Files
TrueGrowth/docs/CLAUDE_CODE_BEST_PRACTICES.md

793 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Claude Code 最佳实践指南
本文档基于 Claude Code 之父 Boris Cherny 的 13 条实战技巧,结合 Opentu 项目实际情况进行整理,帮助团队最大化 Claude Code 的开发效率。
## 目录
- [并行工作流](#并行工作流)
- [模型选择策略](#模型选择策略)
- [知识沉淀机制](#知识沉淀机制)
- [Plan 模式优先](#plan-模式优先)
- [斜杠命令自动化](#斜杠命令自动化)
- [Subagents 工作流](#subagents-工作流)
- [代码格式化 Hook](#代码格式化-hook)
- [权限预批准](#权限预批准)
- [MCP 工具链集成](#mcp-工具链集成)
- [长任务自动化](#长任务自动化)
- [验证机制](#验证机制)
---
## 并行工作流
**技巧 1: 多实例并行运行**
在终端中并行运行多个 Claude Code 实例,开启系统通知,哪个需要输入就跳过去处理。
```bash
# 终端 1: 处理功能开发
claude
# 终端 2: 处理测试编写
claude
# 终端 3: 处理文档更新
claude
```
**配置系统通知:**
```bash
# macOS 系统通知已默认开启
# 确保终端应用有通知权限: 系统设置 → 通知 → Terminal/iTerm2
```
**技巧 2: CLI + GUI 双线作战**
使用 `&` 后台运行和 `--teleport` 在 CLI/GUI 之间无缝切换会话。
```bash
# 在 CLI 启动后台会话
claude &
# 使用 --teleport 将会话传送到 GUI
claude --teleport
# 从 GUI 返回 CLI 继续工作
# 在 GUI 中使用 /teleport 命令
```
**Opentu 项目应用场景:**
| 实例 | 任务类型 | 示例 |
|------|---------|------|
| 实例 1 | 核心功能开发 | 开发 AI 图像生成功能 |
| 实例 2 | 测试编写 | 为新功能编写单元测试 |
| 实例 3 | 文档/规范 | 更新 API 文档或规范 |
---
## 模型选择策略
**技巧 3: 全程使用 Opus 4.5 Thinking 模式**
虽然单次响应慢一点,但需要纠正的次数少得多,工具调用也更准确,最终算下来反而更快。
**模型对比:**
| 特性 | Sonnet (快速) | Opus 4.5 Thinking (推荐) |
|------|--------------|-------------------------|
| 响应速度 | 快 | 较慢 |
| 准确率 | 中等 | 高 |
| 纠正次数 | 多 | 少 |
| 工具调用准确性 | 一般 | 高 |
| **总体效率** | 一般 | **更高** |
**配置方法:**
```bash
# 在 claude 启动时指定模型
claude --model opus
# 或在 settings.json 中配置默认模型
```
**何时使用 Sonnet:**
- 简单的问答查询
- 快速代码片段生成
- 文档格式调整
**何时使用 Opus Thinking:**
- 复杂功能实现
- 架构设计决策
- 多文件重构
- Debug 复杂问题
---
## 知识沉淀机制
**技巧 4: 团队共享 CODEBUDDY.md**
每当 Claude 做错什么就加进去,下次它就知道了,形成飞轮效应。
**Opentu 项目 CODEBUDDY.md 结构:**
```markdown
# CODEBUDDY.md
## 项目规范
- 文件大小限制: 单文件不超过 500 行
- UI 框架: TDesign React (light 主题)
- Tooltip: 必须使用 theme='light'
## 常见错误记录
### 错误 1: Z-Index 硬编码
❌ 错误: style={{ zIndex: 9999 }}
✅ 正确: 使用 Z_INDEX 常量
### 错误 2: 忘记处理移动端
❌ 错误: 只考虑桌面端交互
✅ 正确: 同时处理触摸和鼠标事件
```
**技巧 5: Code Review 自动更新规则**
使用 `/update-claude-md` 命令让 AI 自动将 Code Review 中发现的问题更新到 CODEBUDDY.md。
**创建自动更新命令:**
参考 `.codebuddy/commands/update-claude-md.md`:
```markdown
# Update CLAUDE.md
分析最近的 Code Review 反馈,提取通用规则并更新 CODEBUDDY.md。
## 步骤
1. 读取最近的 PR review 评论或用户反馈
2. 识别可通用化的模式或规则
3. 检查 CODEBUDDY.md 中是否已有相关规则
4. 如果是新规则,添加到适当的章节
5. 使用统一的格式:
- ❌ 错误示例
- ✅ 正确示例
- 原因说明
```
---
## Plan 模式优先
**技巧 6: 大多数会话从 Plan 模式开始**
先想清楚再动手,好的计划很重要。
**进入 Plan 模式:**
```
Shift + Tab (按两次)
```
**Plan 模式工作流:**
```
1. 描述任务需求
2. Claude 生成实现计划
3. 审查计划,提出修改意见
4. 确认计划后退出 Plan 模式
5. 执行实现
```
**Opentu 项目 Plan 模式示例:**
```
用户: 我想添加一个图片圆形裁剪功能
Claude (Plan 模式):
## 实现计划
### 1. 类型定义
- 创建 CropShape 类型
- 定义 ImageCropPopupProps 接口
### 2. 核心组件
- ImageCropPopup.tsx 裁剪弹窗
- useImageCrop.ts 裁剪逻辑 Hook
### 3. 集成
- 在 PopupToolbar 添加裁剪按钮
- 连接 Plait 节点更新
### 4. 测试
- 单元测试
- E2E 测试
是否确认这个计划?
```
**与 SpecKit 结合使用:**
对于复杂功能,结合 SpecKit 工作流:
```bash
# Plan 模式下先理清思路
Shift + Tab + Tab
# 然后使用 SpecKit 正式规范化
/speckit.specify
/speckit.plan
/speckit.tasks
/speckit.implement
```
---
## 斜杠命令自动化
**技巧 7: 高频重复操作做成斜杠命令**
Claude 自己也能调用这些命令,实现自动化工作流。
**Opentu 项目已有命令:**
| 命令 | 功能 |
|------|------|
| `/auto-commit` | 自动分析变更并提交 |
| `/speckit.auto` | 自动执行完整 SpecKit 流程 |
| `/speckit.specify` | 创建功能规范 |
| `/speckit.plan` | 生成实现计划 |
| `/speckit.tasks` | 生成任务清单 |
| `/speckit.implement` | 执行实现 |
**创建自定义命令:**
`.codebuddy/commands/` 目录下创建 markdown 文件:
**示例: `/commit-push-pr` 一键完成提交推送创建 PR**
```markdown
# .codebuddy/commands/commit-push-pr.md
# Commit, Push, and Create PR
自动完成代码提交、推送和创建 Pull Request。
## 参数
- $ARGUMENTS: PR 标题和描述 (可选)
## 步骤
1. 运行 git status 检查变更
2. 运行 git diff 分析变更内容
3. 生成符合规范的 commit message
4. 执行 git add 和 git commit
5. 推送到远程分支
6. 使用 gh pr create 创建 PR
7. 返回 PR URL
```
**示例: `/typecheck-fix` 类型检查并自动修复**
```markdown
# .codebuddy/commands/typecheck-fix.md
# TypeCheck and Fix
运行类型检查并自动修复发现的类型错误。
## 步骤
1. 运行 nx typecheck drawnix
2. 解析错误输出
3. 逐个修复类型错误
4. 重新运行类型检查验证
5. 报告修复结果
```
**示例: `/build-test-commit` 构建测试提交一条龙**
```markdown
# .codebuddy/commands/build-test-commit.md
# Build, Test, and Commit
确保代码质量后自动提交。
## 步骤
1. 运行 npm run build 构建项目
2. 运行 npm test 执行测试
3. 如果都通过,执行 /auto-commit
4. 如果失败,报告错误并提供修复建议
```
---
## Subagents 工作流
**技巧 8: 使用 Subagents 自动化常见工作流**
把反复做的事情固化下来,让 Claude 自己调用。
**Opentu 项目 Subagent 示例:**
参考 `.codebuddy/skills/speckit-auto.md`:
```markdown
# SpecKit Auto Skill
自动执行完整的 SpecKit 工作流。
## 触发条件
当用户描述一个新功能需求时。
## 执行流程
1. 调用 /speckit.specify 生成规范
2. 调用 /speckit.clarify 澄清疑问
3. 调用 /speckit.plan 制定计划
4. 调用 /speckit.tasks 生成任务
5. 调用 /speckit.implement 执行实现
```
**创建自定义 Skill:**
```markdown
# .codebuddy/skills/code-review.md
# Code Review Skill
自动进行代码审查。
## 检查项
1. TypeScript 类型安全
2. React Hooks 规范
3. 文件大小限制 (< 500 行)
4. Z-Index 规范使用
5. 性能优化建议
## 输出格式
- 问题严重程度: 🔴 Critical / 🟡 Warning / 🟢 Info
- 问题位置: 文件:行号
- 问题描述
- 修复建议
```
---
## 代码格式化 Hook
**技巧 9: 使用 PostToolUse Hook 格式化代码**
Claude 通常能自动生成格式良好的代码Hook 处理最后 10%,避免 CI 格式错误。
**配置 PostToolUse Hook:**
在项目配置中添加:
```json
// .codebuddy/settings.json (如果存在) 或项目配置
{
"hooks": {
"postToolUse": {
"write": "npm run format:file -- $FILE",
"edit": "npm run format:file -- $FILE"
}
}
}
```
**Opentu 项目格式化脚本:**
```json
// package.json
{
"scripts": {
"format": "prettier --write .",
"format:file": "prettier --write",
"format:check": "prettier --check ."
}
}
```
**Hook 工作原理:**
```
Claude 写入文件
PostToolUse Hook 触发
运行 prettier 格式化
文件格式统一
避免 CI 格式检查失败
```
---
## 权限预批准
**技巧 10: 使用 /permissions 预批准常用安全命令**
避免每次都弹确认框,而不是使用 `dangerously-skip-permissions`
**推荐预批准的命令:**
```bash
# 查看权限设置
/permissions
# 预批准常用的安全命令
# 示例配置:
```
**Opentu 项目推荐批准列表:**
| 命令类型 | 示例 | 风险级别 |
|---------|------|---------|
| 读取操作 | `cat`, `ls`, `git status` | 低 |
| 构建命令 | `npm run build`, `nx build` | 低 |
| 测试命令 | `npm test`, `nx test` | 低 |
| Lint 命令 | `nx lint`, `eslint` | 低 |
| Git 查看 | `git log`, `git diff` | 低 |
**不建议预批准的命令:**
| 命令类型 | 示例 | 原因 |
|---------|------|------|
| 删除操作 | `rm -rf`, `git reset --hard` | 破坏性 |
| 推送操作 | `git push --force` | 影响远程 |
| 安装操作 | `npm install <package>` | 引入依赖 |
---
## MCP 工具链集成
**技巧 11: 配置 MCP 让 Claude 使用所有需要的工具**
Claude Code 不只是编程工具,而是能调用整个工具链。
**MCP (Model Context Protocol) 集成示例:**
```json
// mcp.json 配置示例
{
"servers": {
"slack": {
"command": "npx",
"args": ["@anthropic/mcp-server-slack"],
"env": {
"SLACK_TOKEN": "${SLACK_TOKEN}"
}
},
"sentry": {
"command": "npx",
"args": ["@anthropic/mcp-server-sentry"],
"env": {
"SENTRY_AUTH_TOKEN": "${SENTRY_AUTH_TOKEN}"
}
},
"github": {
"command": "npx",
"args": ["@anthropic/mcp-server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
```
**Opentu 项目推荐 MCP 集成:**
| 工具 | 用途 | MCP Server |
|------|------|-----------|
| GitHub | Issue/PR 管理 | @anthropic/mcp-server-github |
| Sentry | 错误日志追踪 | @anthropic/mcp-server-sentry |
| Slack | 团队通知 | @anthropic/mcp-server-slack |
| Figma | 设计稿获取 | @anthropic/mcp-server-figma |
**使用场景:**
```
用户: 查看最近的 Sentry 错误
Claude: [通过 MCP 调用 Sentry API]
发现 3 个未解决错误:
1. TypeError in ImageCropPopup.tsx:45
2. NetworkError in video-api-service.ts:123
3. ...
需要我帮你修复哪个?
```
---
## 长任务自动化
**技巧 12: 长任务使用 --permission-mode=dontAsk**
对于要跑很久的任务,让 Claude 自动循环改进工作直到完成。
**使用方法:**
```bash
# 启动长任务模式
claude --permission-mode=dontAsk
# 或在会话中配置
/settings permission-mode dontAsk
```
**适用场景:**
- 大规模代码重构
- 批量文件处理
- 持续集成修复
- 测试覆盖率提升
**安全建议:**
1. 确保在版本控制下工作
2. 先创建新分支
3. 设置合理的超时时间
4. 定期检查进度
**Opentu 项目长任务示例:**
```bash
# 示例: 将所有组件迁移到新的 Z-Index 规范
claude --permission-mode=dontAsk
提示词:
"将项目中所有硬编码的 z-index 值替换为 Z_INDEX 常量,
遵循 docs/Z_INDEX_GUIDE.md 规范,完成后运行类型检查确认无误"
```
---
## 验证机制
**技巧 13: 给 Claude 验证工作的方式 (最重要!)**
如果 Claude 能验证自己的工作,最终产出质量能提升 2~3 倍。投入精力把验证机制做扎实,这是回报率最高的投资。
### 验证机制类型
#### 1. 类型检查验证
```markdown
# CODEBUDDY.md 中添加
## 验证命令
每次修改 TypeScript 文件后,运行:
\`\`\`bash
nx typecheck drawnix
\`\`\`
确保无类型错误后再继续。
```
#### 2. 测试验证
```markdown
## 测试验证
修改代码后运行相关测试:
\`\`\`bash
# 单元测试
nx test drawnix
# 特定文件测试
nx test drawnix --testFile=useImageCrop.test.ts
\`\`\`
```
#### 3. Lint 验证
```markdown
## Lint 验证
代码提交前运行:
\`\`\`bash
nx lint drawnix
npm run format:check
\`\`\`
```
#### 4. 构建验证
```markdown
## 构建验证
确保代码可以成功构建:
\`\`\`bash
npm run build
\`\`\`
```
#### 5. 自定义验证脚本
```markdown
## 自定义验证
### 文件大小检查
\`\`\`bash
# 检查文件行数是否超过 500 行
wc -l <file> | awk '{if($1>500) exit 1}'
\`\`\`
### Z-Index 规范检查
\`\`\`bash
# 检查是否有硬编码的 z-index
grep -r "z-index:\s*[0-9]" --include="*.scss" --include="*.css"
grep -r "zIndex:\s*[0-9]" --include="*.tsx" --include="*.ts"
\`\`\`
```
### Opentu 项目完整验证清单
```markdown
# 任务完成验证清单
## 代码质量
- [ ] `nx typecheck drawnix` 通过
- [ ] `nx lint drawnix` 通过
- [ ] `npm run format:check` 通过
## 测试覆盖
- [ ] 相关单元测试通过
- [ ] 新功能有对应测试
## 规范遵守
- [ ] 文件行数 < 500 行
- [ ] 使用 Z_INDEX 常量
- [ ] TDesign 组件使用 light 主题
- [ ] 无硬编码敏感信息
## 构建验证
- [ ] `npm run build` 成功
- [ ] 无控制台警告/错误
## 功能验证
- [ ] 本地运行 `npm start` 测试功能
- [ ] 移动端适配正常
```
### 在 CODEBUDDY.md 中配置验证
```markdown
# CODEBUDDY.md 添加
## 自动验证规则
完成任何代码修改后,必须执行以下验证步骤:
1. **类型检查**: `nx typecheck drawnix`
2. **代码规范**: `nx lint drawnix`
3. **测试运行**: `nx test drawnix --passWithNoTests`
4. **构建验证**: `npm run build:web`
如果任何步骤失败,必须先修复问题再继续。
## 验证失败处理
### 类型错误
- 检查类型定义是否完整
- 确认 import 路径正确
- 查看相关 interface/type 定义
### Lint 错误
- 运行 `nx lint drawnix --fix` 自动修复
- 手动修复无法自动修复的问题
### 测试失败
- 分析失败原因
- 更新测试或修复代码
- 确保测试覆盖新功能
```
---
## 快速参考卡片
### 日常开发流程
```
1. 开启 Plan 模式 (Shift+Tab×2)
2. 描述任务,确认计划
3. 退出 Plan 模式开始实现
4. 完成后运行验证命令
5. 使用 /auto-commit 提交
```
### 复杂功能开发流程
```
1. /speckit.specify - 写规范
2. /speckit.clarify - 澄清疑问
3. /speckit.plan - 制定计划
4. /speckit.tasks - 生成任务
5. /speckit.implement - 执行实现
6. 验证 + /auto-commit
```
### 常用命令速查
| 操作 | 命令/快捷键 |
|------|------------|
| Plan 模式 | `Shift + Tab` × 2 |
| 自动提交 | `/auto-commit` |
| 权限设置 | `/permissions` |
| SpecKit 自动流程 | `/speckit.auto` |
| 查看帮助 | `/help` |
---
## 附录: 配置模板
### .codebuddy/settings.json 模板
```json
{
"model": "opus",
"hooks": {
"postToolUse": {
"write": "prettier --write $FILE",
"edit": "prettier --write $FILE"
}
},
"permissions": {
"allow": [
"npm run build",
"npm test",
"nx *",
"git status",
"git diff",
"git log"
]
}
}
```
### 验证脚本模板
```bash
#!/bin/bash
# scripts/validate.sh
echo "🔍 Running validation..."
echo "1. Type checking..."
nx typecheck drawnix || exit 1
echo "2. Linting..."
nx lint drawnix || exit 1
echo "3. Testing..."
nx test drawnix --passWithNoTests || exit 1
echo "4. Building..."
npm run build:web || exit 1
echo "✅ All validations passed!"
```
---
**文档版本:** v1.0
**最后更新:** 2025-01-09
**参考来源:** Boris Cherny - Claude Code 实战技巧
**维护者:** Opentu 团队