夜雨聆风
TL;DR： 解释代码、修 Bug、补测试、更新文档——四个高频低风险工作流。跑通这四个，等于验证了 CLAUDE.md、测试闭环和模块边界。跑不通就别做复杂任务。
为什么要从这四个工作流开始
团队引入 Claude Code 后最常见的错误：直接甩一个大需求过去，结果改了一堆不该改的文件、没跑测试、引入回归，然后得出结论"AI 不靠谱"。
问题不在 AI。问题在于你没有先验证基础设施。
这四个工作流的共同特征：高频、低风险、可快速验证。它们不是目的，是诊断工具。每个工作流都会暴露一类配置缺陷：
如果这四个工作流都跑不顺，说明你的 CLAUDE.md、Hooks 和权限配置还不支持复杂任务。先把基础诊断能力校准好。
工作流 1：解释代码
目的
新人 onboarding、Code review 前准备、理解不熟悉的模块。解释代码不需要 Claude Code 修改任何文件，是纯只读操作，零风险。
提示词模式
解释 src/services/payment/ 目录的架构。列出每个文件的职责、导出的函数、和调用它的模块。标注哪些函数有测试覆盖，哪些没有。关键约束：只读，不修改。如果 Claude Code 在解释过程中顺手改了代码，说明你的权限或规则配置有问题。
验证方式
人工确认 Claude Code 的解释和实际代码一致。重点检查：
• 文件职责描述是否准确（不是泛泛而谈） • 函数列表是否完整（没有遗漏导出函数） • 调用关系是否正确（确实是被那些模块调用） • 测试覆盖标注是否和实际测试文件对应
暴露的配置问题
如果 Claude Code 解释不准确，原因通常是：
1. CLAUDE.md 缺少项目地图 —— Claude Code 不知道模块之间的依赖关系，只能靠文件名猜。 2. 路径规则缺失 —— monorepo 中，Claude Code 把不同 package 的职责搞混。 3. CLAUDE.md 中的架构描述过期 —— 写的时候是对的，重构后没更新。
验证清单
解释代码验证清单：[ ] 文件职责描述与代码注释一致[ ] 导出函数列表完整（手动 spot check 3 个文件）[ ] 调用关系与 grep 结果匹配[ ] 测试覆盖标注与实际 test 文件对应[ ] Claude Code 没有修改任何文件（纯只读）如果五个都通过，说明项目地图配置有效。如果第二个和第五个失败，优先修 CLAUDE.md 的架构描述段。
工作流 2：修 Bug
目的
小范围行为修复。关键词是"小范围"——一个 bug 最多涉及 2 个文件。超过 2 个文件的修改已经不算简单 bug fix 了。
完整提示词模式
Bug: 用户注册后欢迎邮件没有发送。1. 先定位相关代码：注册逻辑在哪个文件，邮件发送在哪个文件2. 解释当前行为和预期行为的差异3. 提出最小修改方案（只改必要的代码）4. 修改后运行最小相关测试5. 总结：改了什么、为什么、测试结果、剩余风险这个提示词强制 Claude Code 走一条结构化路径：定位 → 诊断 → 方案 → 执行 → 验证。不是让它自由发挥，而是每一步都有可检查的产出。
质量指标
失败诊断树
Bug 修失败了，按这个顺序排查：1. Bug 没修好？ → 诊断错误（Claude Code 定位到了错误的代码） → 上下文不足（Claude Code 不知道关键的调用链） → 修复：补 CLAUDE.md 的架构描述和模块依赖2. 改了太多文件？ → 范围蔓延（Claude Code 觉得"顺便重构一下"） → 边界规则缺失（CLAUDE.md 没有明确哪些模块不能动） → 修复：补 CLAUDE.md 的 Working Rules 和模块边界3. 测试没跑？ → 没有验证习惯（Claude Code 改完就结束了） → CLAUDE.md 没有要求修改后必须运行测试 → 修复：加 PostToolUse Hook 或在 CLAUDE.md Commands 段强调测试4. 引入了回归？ → 没有覆盖原始行为的测试 → 修改影响了其他调用方 → 修复：先补回归测试，再修 bug实战检查
修完 bug 后，对照这个 diff 检查清单：
Bug Fix 验证清单：[ ] 修改文件数 ≤ 2[ ] 每个 hunk 都和 bug 直接相关（无"顺手"改动）[ ] 最小相关测试已运行且通过[ ] Claude Code 解释了 root cause[ ] Claude Code 列出了剩余风险[ ] 没有引入新的 typecheck 或 lint 错误工作流 3：补测试
目的
提高回归保护。补测试和修 Bug 互为镜像：修 Bug 是"测试告诉你行为错了"，补测试是"先写好网，以后改坏了能知道"。
提示词模式
为 src/services/payment/processRefund.ts 补测试。要求：1. 先读源文件，列出所有导出函数和分支2. 列出需要覆盖的场景（正常、边界、异常）3. 写测试，每个测试只验证一个行为4. 确认测试先失败再通过（验证测试本身有效）5. 报告覆盖率第五步"报告覆盖率"容易被忽略，但它是判断测试质量的关键。如果 Claude Code 报告覆盖率从 40% 提升到 65%，你至少知道测试确实在测代码。如果覆盖率没变，说明测试可能测的是无关路径。
质量标准
什么样的测试是有效的：
// 无效测试：测的是 mock 本身，不是业务逻辑it('should work', () => { mockDb.query.mockResolvedValue({ rows: [] }); const result = processRefund('order-123'); expect(result).toBeDefined(); // 永远通过});// 有效测试：测的是具体行为it('拒绝已退款的订单二次退款', async () => { mockDb.query.mockResolvedValue({ rows: [{ status: 'refunded' }] }); await expect(processRefund('order-123')) .rejects.toThrow('ORDER_ALREADY_REFUNDED');});有效测试的判断标准：
• 测试名字描述具体行为，不是 "should work" 或 "test case 1" • 断言具体值，不是 toBeDefined()这种永远通过的断言• 每个测试只验证一个行为，一个 it 块里不要测三件事 • 先失败再通过，确保测试真的能捕获 bug
暴露的配置问题
如果 Claude Code 补的测试跑不起来，通常只有一个原因：CLAUDE.md 里的测试命令是错的。
常见错误：- CLAUDE.md 写的是 npm test，项目实际用的是 pnpm test- CLAUDE.md 写的是 pnpm test，但单测命令是 pnpm test:unit- 测试需要环境变量，CLAUDE.md 没提- 测试框架用的是 vitest，CLAUDE.md 写的是 jest这类问题修一次就好——更新 CLAUDE.md 的 Commands 段。
验证清单
补测试验证清单：[ ] Claude Code 列出了所有导出函数和分支[ ] 场景覆盖了正常路径、边界值和异常情况[ ] 每个测试只验证一个行为[ ] 测试先失败再通过（不是天生就通过）[ ] 覆盖率有提升[ ] 测试命令和 CLAUDE.md 一致工作流 4：更新文档
目的
文档和代码同步。这是最容易被跳过的工作流，但它的诊断价值不低——如果 Claude Code 不知道文档在哪、用什么格式、遵循什么规范，说明 CLAUDE.md 缺少文档规则。
提示词模式
src/services/payment/processRefund.ts 刚修改了退款策略：- 超过 30 天的订单不再支持退款- 新增部分退款逻辑更新所有受影响的文档：1. 找到引用旧退款策略的文档2. 用现有文档风格更新内容3. 更新 API 示例中的请求和响应4. 确认文档内的链接仍然有效验证方式
文档验证比代码验证更难自动化，需要人工检查：
• 位置正确：文档放在项目约定的位置，不是随便找个地方新建 • 格式一致：和现有文档的 markdown 风格、标题层级、代码块格式一致 • 内容准确：示例命令能跑、API 参数和实际代码一致 • 链接有效：文档内引用的其他文档路径仍然可访问
暴露的配置问题
常见问题：- 文档放在 /docs 而不是 /wiki- 用的是中文文档，Claude Code 写了英文- API 文档用 OpenAPI 格式，Claude Code 写了纯 markdown- CHANGELOG 更新规范没写进 CLAUDE.md工作流质量诊断矩阵
四个工作流跑完后，用这个矩阵判断项目配置的健康度：
诊断方法：每个工作流跑两轮。第一轮暴露问题，修复配置后跑第二轮验证。如果第二轮全部通过，基础配置合格。
真实失败案例
背景
一个 6 人团队在支付系统仓库里引入 Claude Code。仓库没有 CLAUDE.md，没有 Hooks，权限完全开放。第一天，后端工程师让 Claude Code 修一个"简单"的 bug：用户登录后偶尔出现 session 过期的提示。
事件经过
Claude Code 的操作：
1. 定位到 auth middleware 中的 session 校验逻辑2. 修改了 auth-middleware.ts —— 修改了 session 过期判断3. 修改了 session-store.ts —— "优化"了 session 刷新逻辑4. 修改了 user-service.ts —— 调整了用户信息查询的缓存策略5. 修改了 logout-handler.ts —— "顺便"统一了错误处理6. 修改了 api-gateway.ts —— 调整了路由匹配顺序5 个文件被修改，原始 bug 只涉及 1 个文件。Claude Code "顺手"做了一些"优化"。
后果
- logout 流程被破坏（用户无法正常退出）- session store 的刷新逻辑和 Redis 配置不兼容（生产环境 session 全部失效）- 没有运行任何测试- 部署后 15 分钟内收到 200+ 用户反馈根因分析
三个配置缺失导致的连锁失败：1. 没有 CLAUDE.md → Claude Code 不知道 session-store.ts 是共享基础设施，不能随便改 → Claude Code 不知道 logout-handler.ts 的错误处理是刻意设计的2. 没有 PostToolUse Hook → 修改文件后没有自动提醒运行测试 → Claude Code 改完就认为任务完成了3. 没有模块边界规则 → Claude Code 的"顺手优化"没有被任何规则约束 → 没有告知哪些文件属于共享层、不能在 bug fix 中修改成本
时间成本：- 4 小时紧急排查和修复- 1 小时回滚部署- 2 小时事后复盘和补写 CLAUDE.md信任成本：- 团队对 Claude Code 的信心从"期待"降到"怀疑"- 两周没人愿意再用 Claude Code修复措施
事后团队做了三件事：
1. 创建 CLAUDE.md，包含： - 模块边界说明（共享层 vs 业务层） - 修改规则（bug fix 最多改 2 个文件） - 测试命令和验证要求2. 添加 PostToolUse Hook： - 修改 src/ 下文件后，自动运行最小相关测试 - 测试失败时提醒 Claude Code 回退修改3. 配置 .claude/rules/ 路径规则： - 共享模块（session-store, cache）需要确认才能修改 - 修改 API 网关需要安全审查如果团队先跑通四个基础工作流，这个失败不会发生。修 Bug 工作流会立刻暴露"改了太多文件"的问题。补测试工作流会暴露"测试没跑"的问题。解释代码工作流会暴露"没有项目地图"的问题。
何时超越基础工作流
四个基础工作流能覆盖日常 60-70% 的任务。但有些任务超出了它们的范围。
复杂度判断矩阵
判断标准很简单：如果你自己也不确定怎么改，就不要让 Claude Code 直接改。先让它调研、解释、列方案，你确认方案后再执行。
从基础到复杂的过渡路径
Level 1: 四个基础工作流（本篇） 解释代码 → 修 Bug → 补测试 → 写文档Level 2: 有结构的复杂任务 先 plan → 拆成多个 Level 1 任务 → 逐个执行验证Level 3: 需要专项角色 调研用 Explorer、安全用 Reviewer、测试用 QA subagentLevel 4: 多角色协作 多个 subagent 并行 + 主会话整合结果不要跳级。Level 1 没跑通就去 Level 3，只会得到更混乱的结果。
进阶提示词工程模式
四个基础工作流的提示词模板可以进一步系统化。以下是每种工作流在不同复杂度下的提示词变体，以及为什么这些变体能引导 Claude Code 产生更好的输出。
解释代码的分层提示词
Level 1 — 快速概览（适合陌生模块首次接触）： 列出 src/services/auth/ 下的所有文件。 每个文件用一句话描述职责。Level 2 — 结构分析（适合理解模块间关系）： 解释 src/services/auth/ 的架构。 列出每个文件的职责、导出的函数、和调用它的模块。 用箭头标注文件之间的调用方向（A → B 表示 A 调用 B）。Level 3 — 深度审计（适合 code review 前准备）： 对 src/services/auth/ 做完整的代码审计准备： 1. 列出每个导出函数的签名、参数类型和返回类型 2. 标注每个函数的测试覆盖状态（有测试/无测试/部分覆盖） 3. 标注错误处理路径（哪些异常被 catch，哪些没有） 4. 标注外部依赖（调用了哪些其他模块、第三方库、API） 5. 列出你注意到的潜在问题（不修改代码，只列出观察）分层的原因：Level 1 消耗约 2000 token 的输出，Level 3 消耗约 8000 token。如果你只需要知道一个模块大概做什么，Level 3 的输出反而增加了审查负担。反过来，如果要做代码审查前的准备，Level 1 的信息不够用。
修 Bug 的结构化提示词变体
基础版适合简单 bug。以下变体处理更复杂的场景：
变体 A — 不确定 bug 所在位置： Bug 报告：[现象描述] 1. 先用 Grep 搜索相关关键词，定位可能出错的代码区域 2. 列出你找到的所有可疑位置，标注可能性（高/中/低） 3. 解释每个位置为什么可疑 4. 等我确认后，再提出修改方案 约束：只做诊断，不做任何修改。变体 B — Bug 涉及多个模块： Bug 报告：[现象描述] 1. 定位 bug 涉及的所有文件 2. 画出调用链：从入口到出错位置，经过哪些文件和函数 3. 在调用链上标注每一步的数据流（输入什么、输出什么、在哪一步出错） 4. 提出最小修改方案，解释为什么改动这些文件就足够 5. 列出调用链上其他可能受影响的调用方 6. 修改后运行所有相关测试，不只是出错的那个文件的测试 约束：修改前先画调用链，确认我同意后再改代码。变体 C — 间歇性 bug（难以稳定复现）： Bug 报告：[间歇性现象描述，复现条件不明确] 1. 搜索代码中所有和该现象相关的代码路径 2. 识别可能导致间歇性行为的代码模式： - 竞态条件（并发访问共享状态） - 时序依赖（setTimeout、事件顺序） - 外部状态（缓存、数据库、第三方 API） - 条件分支中未处理的边界情况 3. 对每个可疑模式，解释为什么它可能导致间歇性行为 4. 建议添加哪些日志或断言来帮助缩小范围 5. 不要修改代码，只输出诊断报告变体 A 增加了一个交互检查点（"等我确认后"），避免 Claude Code 在错误的位置做修改。变体 B 强制画出调用链，这在多文件 bug 中能暴露真正的 root cause。变体 C 的重点是诊断而非修复——间歇性 bug 在没有充分信息时贸然修改，往往引入新问题。
补测试的提示词工程
进阶版 — 带覆盖率分析的测试补充：为 src/services/payment/processRefund.ts 补测试。执行步骤：1. 读源文件，列出所有导出函数2. 对每个函数，列出所有分支（if/else, switch, try/catch, ?. , ??）3. 标注已有测试覆盖的分支（读取现有测试文件对比）4. 只为未覆盖的分支写测试5. 每个测试用 describe/it 结构组织，it 描述具体行为6. 运行测试前报告：新增了几个测试、覆盖了哪些分支7. 运行测试，报告通过率和覆盖率变化输出格式要求：- 测试文件路径：[和源文件对应的测试路径]- 新增测试数量：[N]- 覆盖分支列表：[列出]- 运行命令：[精确命令]- 覆盖率变化：[从 X% 到 Y%]这个变体的关键是步骤 3——"标注已有测试覆盖的分支"。没有这一步，Claude Code 可能重复写已有的测试场景，浪费 token 且不增加覆盖率。
写文档的提示词工程
进阶版 — 变更影响分析驱动的文档更新：刚完成了以下变更：[列出变更内容]请更新所有受影响的文档：1. 搜索阶段 - Grep 搜索所有 .md 文件中引用变更内容的文档 - 列出搜索结果，标注哪些文档确实需要更新2. 更新阶段 - 按现有文档风格更新内容（保持标题层级、代码块格式一致） - 如果涉及 API 变更，更新请求/响应示例 - 如果涉及配置变更，更新环境变量表3. 验证阶段 - 确认文档内链接仍然有效（Grep 检查引用路径是否存在） - 确认示例命令能运行（如果是 shell 命令，验证命令格式正确） - 列出你更新了哪些文件的哪些段落4. 遗漏检查 - 列出可能还需要的文档更新但你不确定的（标注"需要确认"）步骤 4 "遗漏检查" 是这个变体的关键创新。Claude Code 可能无法确定某些文档是否需要更新（比如 CHANGELOG、内部的架构决策记录），让它列出不确定项比让它自己做决定更安全。
工作流失败诊断树（完整版）
前文给出了修 Bug 的失败诊断树。以下是所有四个工作流的完整诊断流程：
┌─ 解释代码失败？│ ├─ 结构描述不准确 → CLAUDE.md 缺少 Structure 段│ │ → 补充：每个顶层目录加一句话描述│ ├─ 调用关系错误 → CLAUDE.md 缺少依赖方向声明│ │ → 补充：Boundaries 段加"谁可以调用谁"│ ├─ 遗漏目录 → CLAUDE.md 的 Structure 段过期│ │ → 触发条件：新增了目录但没更新 CLAUDE.md│ └─ 对生成文件做了描述 → CLAUDE.md 缺少 Off-limits 段│ → 补充：列出所有不应手动修改的路径│├─ 修 Bug 失败？│ ├─ 改了太多文件│ │ ├─ Claude Code "顺手优化" → CLAUDE.md 加 "No unrelated changes" 规则│ │ ├─ 诊断定位错误 → 项目地图不够精确，Claude Code 找错了位置│ │ └─ 模块边界不清 → Boundaries 段需要更明确的约束│ ├─ 测试没跑│ │ ├─ CLAUDE.md 没有要求 → Commands 段补充测试命令│ │ ├─ Hook 缺失 → 添加 PostToolUse Hook 自动运行测试│ │ └─ 测试命令错误 → 修正 Commands 段中的命令写法│ ├─ Bug 没修好│ │ ├─ Root cause 判断错误 → CLAUDE.md 补充调用链和依赖关系│ │ ├─ 只修了表面症状 → 提示词增加"解释 root cause"步骤│ │ └─ 遗漏了相关分支 → 提示词增加"列出所有影响范围"│ └─ 引入回归│ ├─ 没有覆盖原始行为的测试 → 先补回归测试，再修 bug│ ├─ 修改影响了其他调用方 → Boundaries 段补充调用方信息│ └─ 没有跑全量相关测试 → Commands 段补充"影响范围测试"命令│├─ 补测试失败？│ ├─ 测试跑不起来│ │ ├─ 命令不存在 → CLAUDE.md Commands 段的测试命令是错的│ │ │ → 修正：验证命令在终端能跑通再写进 CLAUDE.md│ │ ├─ 环境变量缺失 → CLAUDE.md 补充测试前置条件│ │ └─ 测试框架不匹配 → 修正 Commands 段中的框架名称│ ├─ 测试天生就通过（无效测试）│ │ ├─ 提示词没有要求"先失败再通过" → 加上"确认测试先失败再通过"步骤│ │ ├─ 断言太弱 → 提示词增加"断言具体值，不用 toBeDefined()"要求│ │ └─ Mock 拦截了真实逻辑 → 提示词增加"测试真实行为，不测 mock"│ └─ 覆盖率没提升│ ├─ 测试测的是无关路径 → 提示词增加"列出源文件所有分支"步骤│ └─ 重复已有测试 → 提示词增加"标注已有测试覆盖的分支"步骤│└─ 写文档失败？ ├─ 位置错误 → CLAUDE.md 补充文档目录结构说明 │ → 说明：/docs 放用户文档，/wiki 放内部文档，根目录放 README ├─ 格式不一致 → CLAUDE.md 补充文档格式规范 │ → 或创建 .claude/rules/docs.md 做路径级加载 ├─ 内容不准确 → 提示词增加"验证示例命令能运行"步骤 └─ 遗漏相关文档 → 提示词增加"搜索所有引用旧内容的文档"步骤更多真实工作流案例
案例二：API 版本迁移工作流
场景：后端服务需要把 /api/v1/orders 迁移到 /api/v2/orders，v2 改变了部分响应字段的结构。这是一个跨文件、需要协调前后端的任务，但可以拆成多个基础工作流来执行。
Phase 1 — 解释代码（只读，摸清影响范围）： 列出所有引用 /api/v1/orders 的文件。 区分：前端调用方、后端 handler、测试文件、文档。 标注每个引用的上下文（是请求 URL、测试 fixture、还是文档示例）。Phase 2 — 补测试（先加保护网）： 为 v1 的现有 handler 补充测试（如果覆盖率不足）。 要求：测试必须验证当前 v1 的响应格式。 目的：确保迁移后 v1 的行为不变（向后兼容期）。Phase 3 — 修 Bug（这里是"迁移"而非修 bug，但用同样的约束）： 实现 v2 handler，每个变更控制在 2 个文件以内。 v2 handler 写在独立文件中（不修改 v1 handler）。 路由注册在 routes/index.ts 中添加（这个文件会改，但只加路由，不改现有路由）。Phase 4 — 写文档（更新 API 文档）： 更新 API 文档中的 v2 端点说明。 添加迁移指南（v1 到 v2 的字段映射）。 标注 v1 的废弃时间表。这个案例的关键是按顺序执行四个基础工作流，而不是一次性让 Claude Code "把 v1 迁移到 v2"。顺序执行的好处是每个 phase 都有独立的验证点：Phase 1 的输出是影响范围清单，Phase 2 的输出是测试通过报告，Phase 3 的输出是 diff 和测试结果，Phase 4 的输出是文档更新清单。任何一个 phase 不通过，不会影响前面的成果。
案例三：依赖升级工作流
场景：将项目从 React 17 升级到 React 18。这种任务看起来复杂，但拆成基础工作流后，每一步都是可控的。
Phase 1 — 解释代码（评估影响）： 列出 package.json 中所有 React 相关依赖的当前版本。 Grep 搜索代码中使用 React 17 特有 API 的位置： - ReactDOM.render（React 18 用 createRoot） - componentWillMount 等 deprecated 生命周期 - 依赖 react-scripts 的配置 列出第三方依赖中可能不兼容 React 18 的包。Phase 2 — 补测试（升级前的安全网）： 确认所有现有测试在 React 17 下通过。 如果有组件没有测试，为核心渲染组件补充快照测试。 快照测试的目的是捕获升级后的渲染输出变化。Phase 3 — 修 Bug（分步升级）： 步骤 1：更新 package.json 中的 react 和 react-dom 版本 步骤 2：运行 pnpm install，检查是否有 peer dependency 冲突 步骤 3：修改 ReactDOM.render → createRoot（Grep 逐个修改） 步骤 4：运行测试，确认通过。失败则逐个修复。 约束：每个步骤只做一件事，做完跑测试再进入下一步。Phase 4 — 写文档： 更新项目 README 中的 React 版本说明。 更新 CLAUDE.md 的 frontmatter（如果有 framework 版本声明）。 记录升级过程中遇到的 breaking changes 和解决方案。这个案例的特殊之处在于 Phase 3 被进一步拆分成了多个子步骤。依赖升级的每一小步都可能引入不同的问题，"一次改完"几乎必然导致不可调试的失败。
渐进复杂度决策矩阵
当你拿到一个任务时，用这个矩阵判断应该用哪个级别的提示词：
任务特征 │ 提示词级别 │ 预期交互轮次─────────────────────────────────┼─────────────┼─────────────单文件，行为明确 │ 基础版 │ 1 轮单文件，需要先定位 │ 变体 A │ 2 轮（诊断 + 执行）多文件，调用链清晰 │ 变体 B │ 2-3 轮多文件，影响范围不确定 │ 先解释代码 │ 3-4 轮 │ 再修 Bug │间歇性/难以复现 │ 变体 C │ 2 轮（纯诊断）跨服务/API 变更 │ 拆成多阶段 │ 4-6 轮依赖升级 │ 拆成多阶段 │ 4-6 轮判断的核心逻辑：任务的不确定度越高，提示词中"诊断"部分的权重应该越大，"执行"部分应该越靠后。 如果你在任务描述中用了"可能"、"大概"、"不确定"这类词，说明你应该先用解释代码工作流做诊断，而不是直接让 Claude Code 动手修改。
工作流质量验证检查清单（综合版）
四个工作流全部跑完后，不仅要验证每个工作流的结果，还要验证它们之间的协同是否正常：
单工作流验证：[ ] 解释代码：输出准确，无修改文件[ ] 修 Bug：修改 ≤ 2 文件，无无关变更，测试通过[ ] 补测试：测试先失败再通过，覆盖率提升[ ] 写文档：位置正确，格式一致，链接有效跨工作流验证：[ ] 解释代码识别的问题在修 Bug 中被正确处理[ ] 修 Bug 后的代码在补测试中获得了覆盖[ ] 补测试新增的测试在写文档中被引用（如有必要）[ ] 四个工作流使用的命令全部来自 CLAUDE.md Commands 段基础设施验证：[ ] PostToolUse Hook 正确触发（修改文件后自动跑测试）[ ] .claude/rules/ 中的路径规则被遵守[ ] CLAUDE.md 的项目地图在四个工作流中都没有暴露过期信息[ ] Claude Code 的每个输出都包含 diff、验证结果和剩余风险"跨工作流验证"这个维度容易被忽略。如果解释代码工作流正确识别了模块 A 和模块 B 之间的调用关系，但修 Bug 时 Claude Code 仍然在模块 A 里写了属于模块 B 的逻辑，说明项目地图的 Boundaries 段写对了但 Claude Code 没有遵守——这可能需要在 .claude/rules/ 中加一条路径级的强制规则。
落地清单
四个工作流全部跑通后才算基础配置合格：
基础工作流验证清单：[ ] 解释代码：Claude Code 能准确描述模块结构和调用关系[ ] 修 Bug：每次 bug fix 修改 ≤ 2 个文件，无无关变更[ ] 补测试：测试能跑、先失败再通过、覆盖率有提升[ ] 写文档：文档位置、格式、内容都正确[ ] 修改后自动运行最小相关测试（PostToolUse Hook 或 CLAUDE.md 规则）[ ] Claude Code 每次都报告 diff、验证结果和剩余风险全通过：项目配置有效，可以开始更复杂的任务。有失败：先修配置，再重来。
权衡
这四个工作流看起来不炫，但它们解决的是最实际的问题：你的项目配置到底有没有效。跑通这四个，后面用 subagent、parallel exploration、Hooks 才有基础。跑不通，复杂工作流只会放大混乱。
交叉参考
• 02 - 安装、登录、权限和第一个任务[1]：第一次进入仓库时验证环境 • 04 - CLAUDE.md 项目记忆[2]：工作流暴露的所有问题最终都修到这里 • 12 - Subagents 基础概念[3]：基础工作流跑通后再接触专项角色 • 24 - PostToolUse 自动验证[4]：修改后自动跑测试的 Hook 配置
引用链接
[1] 02 - 安装、登录、权限和第一个任务: 02-setup-permission-first-repo-task.md[2] 04 - CLAUDE.md 项目记忆: 04-claude-md-project-memory.md[3] 12 - Subagents 基础概念: 12-subagents-mental-model.md[4] 24 - PostToolUse 自动验证: 24-posttooluse-stop-verification.md
