目标：建立高效的 Claude Code 工作流程，避免常见陷阱
预计时间：30 分钟
对应官方文档：Best Practices

工作流程模板

日常开发流程

1. 启动
   claude --name "feature-xxx"

2. 了解上下文
   > 请介绍这个项目的架构和当前任务

3. 编写代码
   > 实现 [功能描述]，要求：...

4. 验证
   > /test
   > /lint

5. 提交
   > /git diff
   > /git commit -m "feat: xxx"

6. 收尾
   > /exit

Bug 修复流程

1. 复现问题
   > 测试失败了：[错误信息]
   > 请分析原因

2. 定位根因
   > 请详细说明第 X 行的逻辑问题

3. 修复
   > 请修复并运行测试验证

4. 回归测试
   > 运行全量测试，确保没有破坏其他功能

代码审查流程

1. 加载变更
   > /add [修改的文件]

2. 请求审查
   > 请审查这些更改，关注：安全性、性能、可维护性

3. 处理反馈
   > 请修复第 X 条问题

4. 最终确认
   > 所有问题已修复，请最终确认

黄金法则

✅ Do（要做）

用 Git
- 每次重要操作前 git commit
- 方便随时回退
小步快跑
- 每次请求聚焦一个任务
- 验证通过后再下一步
明确约束
- "不要修改 API 接口"
- "保持向后兼容"
- "测试覆盖率不下降"
验证一切
- 代码：运行测试
- 配置：检查语法
- 文档：确认准确
定期压缩
- /compact 保持上下文高效
- 长会话适时新建

❌ Don't（不要做）

不要盲信
- AI 会犯错，必须审查
- 特别是安全相关代码
不要一次给太多任务
- 容易遗漏或混乱
- 拆分多个步骤
不要忽视错误
- 测试失败要深入分析
- 不要 "再试一次" 蒙混
不要在生产环境直接用 Auto 模式
- 重要操作要确认
- 使用 Ask 或 Auto Edits
不要泄露敏感信息
- API Key、密码不要粘贴
- 使用环境变量或 MCP

环境配置检查清单

项目级（.claude/）

项目/
├── .claude/
│   ├── CLAUDE.md           ✅ 项目规范
│   ├── settings.json       ✅ 项目配置
│   ├── skills/             ✅ 自定义命令
│   └── prompts/            ✅ 提示词模板

用户级（~/.claude/）

~/.claude/
├── settings.json           ✅ 全局配置
├── memory/                 ✅ 自动记忆
└── mcp.json               ✅ MCP 配置

团队协作规范

共享配置

# 团队共享的 CLAUDE.md
git clone [email protected]:company/claude-configs.git
ln -s claude-configs/team-a .claude

代码审查清单

## AI 生成代码审查表
 
- [ ] 是否理解业务逻辑？
- [ ] 是否有安全风险？
- [ ] 测试是否充分？
- [ ] 性能是否符合要求？
- [ ] 是否有副作用？
- [ ] 文档是否更新？

性能优化

加速响应

# 开启 Fast Mode（Opus 模型下）
claude config set fast_mode true
 
# 限制并行度（低配置机器）
claude config set max_parallelism 2
 
# 禁用不需要的功能
claude config set enable_telemetry false

减少卡顿

# 大项目排除不需要的目录
cat > .claudeignore << EOF
node_modules/
dist/
build/
*.min.js
*.lock
EOF

补充：完整工作流与项目初始化

高效开发工作流全景图

完整配置与脚本

示例 1：新项目初始化脚本（一键配置 Claude Code）

#!/bin/bash
# init-claude-project.sh - 为新项目初始化 Claude Code 配置
 
PROJECT_DIR="${1:-.}"
PROJECT_TYPE="${2:-generic}"  # generic | python | node | rust
 
cd "$PROJECT_DIR" || exit 1
 
# 创建目录结构
mkdir -p .claude/prompts
mkdir -p .claude/skills
mkdir -p .claude/subagent-templates
 
echo "✅ 创建 .claude/ 目录结构"
 
# 根据项目类型生成 CLAUDE.md
case "$PROJECT_TYPE" in
  python)
    cat > .claude/CLAUDE.md << 'EOF'
# Python 项目开发规范
 
## 技术栈
- Python 3.11+
- FastAPI / Django（根据实际选择）
- pytest + coverage
- Ruff（lint + format）
 
## 编码规范
- 类型注解覆盖率 100%
- 函数长度 <= 40 行
- 使用 Pydantic 做数据校验
- 异步代码优先用 async/await
 
## 常用命令
```bash
pytest tests/ -v --cov=src --cov-report=term-missing
ruff check src/ && ruff format src/

禁止事项

不要硬编码密钥/密码
不要在循环中查询数据库
不要直接返回 ORM 对象（用 Pydantic Schema） EOF ;; node) cat > .claude/CLAUDE.md << 'EOF'

Node.js 项目开发规范

技术栈

Node.js 20+ / TypeScript 5+
pnpm 优先
Vitest / Jest
ESLint + Prettier

编码规范

严格模式 strict: true
优先 const，少用 let，禁用 var
异步优先 async/await，禁用回调
类型导出显式使用 export type

常用命令

pnpm install
pnpm dev
pnpm test
pnpm lint
pnpm typecheck

EOF ;; *) cat > .claude/CLAUDE.md << 'EOF'

项目开发规范

通用约定

每次提交前运行测试
代码风格保持一致
复杂逻辑必须写注释

常用命令

# 请根据实际项目填写

EOF ;; esac

echo "✅ 生成 .claude/CLAUDE.md (${PROJECT_TYPE})"

生成 .claudeignore

cat > .claudeignore << 'EOF' node_modules/ dist/ build/ *.min.js *.lock vendor/ .git/ coverage/ .log .env !.env.example EOF

echo "✅ 生成 .claudeignore"

生成项目级 settings.json

cat > .claude/settings.json << 'EOF' { "model": "sonnet", "maxParallelism": 4, "enableTelemetry": false, "preferredEditor": "vscode" } EOF

echo "✅ 生成 .claude/settings.json"

echo "" echo "🎉 项目初始化完成！请根据实际需求修改 .claude/CLAUDE.md"


使用方式：
```bash
chmod +x init-claude-project.sh
./init-claude-project.sh ~/projects/my-api python

示例 2：团队共享配置仓库结构

company-claude-configs/
├── README.md
├── base/
│   ├── CLAUDE.md              # 公司级通用规范
│   ├── settings.json          # 推荐全局设置
│   └── .claudeignore          # 通用忽略模式
├── teams/
│   ├── backend/
│   │   ├── CLAUDE.md          # 后端团队规范
│   │   └── prompts/
│   │       ├── api-design.md
│   │       └── db-review.md
│   └── frontend/
│       ├── CLAUDE.md          # 前端团队规范
│       └── prompts/
│           ├── component-review.md
│           └── e2e-scenario.md
├── skills/
│   ├── deploy.yaml
│   ├── lint-check.yaml
│   └── release.yaml
└── install.sh                 # 一键安装脚本

install.sh 示例：

#!/bin/bash
TEAM="${1:-backend}"
PROJECT_DIR="${2:-.}"
 
# 复制基础配置
cp base/CLAUDE.md "$PROJECT_DIR/.claude/CLAUDE.md"
cp base/settings.json "$PROJECT_DIR/.claude/settings.json"
cp base/.claudeignore "$PROJECT_DIR/.claudeignore"
 
# 合并团队特定配置（追加到末尾）
echo "" >> "$PROJECT_DIR/.claude/CLAUDE.md"
echo "---" >> "$PROJECT_DIR/.claude/CLAUDE.md"
cat "teams/$TEAM/CLAUDE.md" >> "$PROJECT_DIR/.claude/CLAUDE.md"
 
# 复制团队 Prompts 和 Skills
cp -r "teams/$TEAM/prompts/"* "$PROJECT_DIR/.claude/prompts/" 2>/dev/null || true
cp skills/*.yaml "$PROJECT_DIR/.claude/skills/" 2>/dev/null || true
 
echo "Installed team '$TEAM' config into $PROJECT_DIR/.claude/"

示例 3：项目级 `.claude/settings.json` 完整配置

{
  "model": "sonnet",
  "contextWindow": {
    "maxFiles": 20,
    "maxTokensPerFile": 4000
  },
  "caching": {
    "enablePromptCaching": true
  },
  "costControl": {
    "sessionBudgetAlert": 3.0
  },
  "behavior": {
    "autoRunTests": false,
    "askBeforeLargeEdits": true,
    "preferredShell": "bash"
  },
  "ignorePatterns": [
    "node_modules/",
    "dist/",
    "build/",
    "*.min.js",
    "*.lock",
    ".git/",
    "coverage/",
    "*.log",
    ".env.local",
    ".env.production"
  ],
  "skills": {
    "autoEnable": ["git", "github"]
  },
  "subagentDefaults": {
    "mode": "ask",
    "timeoutMinutes": 30
  }
}

实战场景

场景一：新功能开发（从需求到 PR 的完整流程）

背景：产品经理提出"添加用户邀请功能"，需要后端 API、前端页面、数据库迁移。

步骤：

初始化：确认在项目目录，git checkout -b feature/user-invite，启动 claude --name feature-user-invite
需求对齐：向 Claude 描述需求，明确约束：
- 不要修改现有用户表结构（新增 invite 表）
- 邀请链接 7 天过期
- 管理员和普通用户权限不同
任务拆分：由于涉及前后端 + DB，使用子代理并行：
- subagent-db：设计 invite 表 migration 和模型
- subagent-api：实现 POST /invites 和 GET /invites/:token 接口
- subagent-fe：实现邀请页面和链接复制功能
编码与验证：每个子代理完成后，主会话合并代码，运行全量测试
审查与提交：使用 /prompt security/audit 审查新 API 的安全性，确认后 git commit

结果：

从需求到完整 PR 耗时 3 小时，传统方式通常需要 1.5 天
由于 CLAUDE.md 中规定了权限校验和输入验证的强制要求，AI 自动在接口中实现了防暴力破解和 XSS 防护
子代理并行让 DB、API、前端同时推进，无等待时间
代码风格与团队现有代码 100% 一致，Review 时几乎无风格类意见

场景二：生产事故应急响应

背景：凌晨 2 点生产环境订单服务报错率突增，值班工程师需要快速定位并修复。

步骤：

快速启动：工程师 SSH 到服务器，启动 claude --name incident-20250618-orders
加载上下文：/add logs/production/order-service.error.log src/orders/（只加载相关文件，控制 token）

诊断：将错误日志粘贴给 Claude，要求分析根因：

> 订单服务报错率突增，以上是最近 50 条错误日志。
> 相关代码：@src/orders/service.py
> 请分析根因并给出修复方案。

修复与验证：Claude 定位到是数据库连接池耗尽，建议增加连接池大小并优化慢查询。工程师确认后，AI 生成修复代码和配置变更。
记录与复盘：修复后 /export 导出整个诊断过程，发送给团队用于次日复盘。

结果：

从接到报警到修复上线用时 25 分钟（以往类似事故平均 1.5 小时）
工程师无需在凌晨 2 点独自面对大量日志，AI 快速提取关键模式和关联代码
导出的诊断记录成为后续自动化监控规则的基础（如"连接池使用率 > 80% 告警"）
由于使用了独立命名会话，次日团队成员可通过 --continue 复盘完整过程

中级教程完成！

你已经掌握了：

✅ CLAUDE.md 定制
✅ 会话管理
✅ 高效提示词
✅ Skills 扩展
✅ MCP 工具连接
✅ 子代理协作
✅ 成本控制
✅ 最佳实践

下一步

→ 进入高级教程，学习 Agent SDK、Hooks、插件开发和企业部署

或继续实践，在真实项目中应用所学！

评论

相关文章

OpenTelemetry 监控与可观测性

CI/CD 集成：GitHub Actions / GitLab

安全加固与沙箱配置