Initial TrueGrowth source import

2026-07-07 09:36:36 +08:00
commit 3b6781d695
2283 changed files with 691996 additions and 0 deletions
--- a/docs/CLAUDE_CODE_BEST_PRACTICES.md
+++ b/docs/CLAUDE_CODE_BEST_PRACTICES.md
@@ -0,0 +1,792 @@
+# 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 团队