aitu/docs/CLAUDE_CODE_BEST_PRACTICES.md

Claude Code 最佳实践指南

本文档基于 Claude Code 之父 Boris Cherny 的 13 条实战技巧，结合 Opentu 项目实际情况进行整理，帮助团队最大化 Claude Code 的开发效率。

目录

• 并行工作流
• 模型选择策略
• 知识沉淀机制
• Plan 模式优先
• 斜杠命令自动化
• Subagents 工作流
• 代码格式化 Hook
• 权限预批准
• MCP 工具链集成
• 长任务自动化
• 验证机制

---

并行工作流

技巧 1: 多实例并行运行

在终端中并行运行多个 Claude Code 实例，开启系统通知，哪个需要输入就跳过去处理。

# 终端 1: 处理功能开发
claude

# 终端 2: 处理测试编写
claude

# 终端 3: 处理文档更新
claude

配置系统通知:

# macOS 系统通知已默认开启
# 确保终端应用有通知权限: 系统设置 → 通知 → Terminal/iTerm2

技巧 2: CLI + GUI 双线作战

使用 & 后台运行和 --teleport 在 CLI/GUI 之间无缝切换会话。

# 在 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 (推荐)
响应速度	快	较慢
准确率	中等	高
纠正次数	多	少
工具调用准确性	一般	高
总体效率	一般	更高

配置方法:

# 在 claude 启动时指定模型
claude --model opus

# 或在 settings.json 中配置默认模型

何时使用 Sonnet:

• 简单的问答查询
• 快速代码片段生成
• 文档格式调整

何时使用 Opus Thinking:

• 复杂功能实现
• 架构设计决策
• 多文件重构
• Debug 复杂问题

---

知识沉淀机制

技巧 4: 团队共享 CODEBUDDY.md

每当 Claude 做错什么就加进去，下次它就知道了，形成飞轮效应。

Opentu 项目 CODEBUDDY.md 结构:

# 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:

# 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 工作流:

# 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

# .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 类型检查并自动修复

# .codebuddy/commands/typecheck-fix.md

# TypeCheck and Fix

运行类型检查并自动修复发现的类型错误。

## 步骤

1. 运行 nx typecheck drawnix
2. 解析错误输出
3. 逐个修复类型错误
4. 重新运行类型检查验证
5. 报告修复结果

示例: /build-test-commit 构建测试提交一条龙

# .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:

# SpecKit Auto Skill

自动执行完整的 SpecKit 工作流。

## 触发条件

当用户描述一个新功能需求时。

## 执行流程

1. 调用 /speckit.specify 生成规范
2. 调用 /speckit.clarify 澄清疑问
3. 调用 /speckit.plan 制定计划
4. 调用 /speckit.tasks 生成任务
5. 调用 /speckit.implement 执行实现

创建自定义 Skill:

# .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:

在项目配置中添加:

// .codebuddy/settings.json (如果存在) 或项目配置
{
  "hooks": {
    "postToolUse": {
      "write": "npm run format:file -- $FILE",
      "edit": "npm run format:file -- $FILE"
    }
  }
}

Opentu 项目格式化脚本:

// 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。

推荐预批准的命令:

# 查看权限设置
/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) 集成示例:

// 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 自动循环改进工作直到完成。

使用方法:

# 启动长任务模式
claude --permission-mode=dontAsk

# 或在会话中配置
/settings permission-mode dontAsk

适用场景:

• 大规模代码重构
• 批量文件处理
• 持续集成修复
• 测试覆盖率提升

安全建议:

1. 确保在版本控制下工作
2. 先创建新分支
3. 设置合理的超时时间
4. 定期检查进度

Opentu 项目长任务示例:

# 示例: 将所有组件迁移到新的 Z-Index 规范
claude --permission-mode=dontAsk

提示词:
"将项目中所有硬编码的 z-index 值替换为 Z_INDEX 常量，
遵循 docs/Z_INDEX_GUIDE.md 规范，完成后运行类型检查确认无误"

---

验证机制

技巧 13: 给 Claude 验证工作的方式 (最重要！)

如果 Claude 能验证自己的工作，最终产出质量能提升 2~3 倍。投入精力把验证机制做扎实，这是回报率最高的投资。

验证机制类型

1. 类型检查验证

# CODEBUDDY.md 中添加

## 验证命令

每次修改 TypeScript 文件后，运行:
\`\`\`bash
nx typecheck drawnix
\`\`\`
确保无类型错误后再继续。

2. 测试验证

## 测试验证

修改代码后运行相关测试:
\`\`\`bash
# 单元测试
nx test drawnix

# 特定文件测试
nx test drawnix --testFile=useImageCrop.test.ts
\`\`\`

3. Lint 验证

## Lint 验证

代码提交前运行:
\`\`\`bash
nx lint drawnix
npm run format:check
\`\`\`

4. 构建验证

## 构建验证

确保代码可以成功构建:
\`\`\`bash
npm run build
\`\`\`

5. 自定义验证脚本

## 自定义验证

### 文件大小检查
\`\`\`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 项目完整验证清单

# 任务完成验证清单

## 代码质量
- [ ] `nx typecheck drawnix` 通过
- [ ] `nx lint drawnix` 通过
- [ ] `npm run format:check` 通过

## 测试覆盖
- [ ] 相关单元测试通过
- [ ] 新功能有对应测试

## 规范遵守
- [ ] 文件行数 < 500 行
- [ ] 使用 Z_INDEX 常量
- [ ] TDesign 组件使用 light 主题
- [ ] 无硬编码敏感信息

## 构建验证
- [ ] `npm run build` 成功
- [ ] 无控制台警告/错误

## 功能验证
- [ ] 本地运行 `npm start` 测试功能
- [ ] 移动端适配正常

在 CODEBUDDY.md 中配置验证

# 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 模板

{
  "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"
    ]
  }
}

验证脚本模板

#!/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 团队