--- title: "别让 AI 乱写代码：从方法论到实战，我的 Claude Code 工作流" author: deletexiumu pubDatetime: 2026-02-17T01:00:00+08:00 featured: false draft: false tags: - Claude Code - AI 编程 description: "从 Boris Tane 的方法论到 get-shit-done 工具，再到飞书 Webhook 实战案例，三层递进讲透 Claude Code 的正确打开方式。" --- 多数人用 Claude Code 的方式是：一句话描述需求，让它直接写。结果经常是——前三轮惊艳，第五轮开始跑偏，第十轮已经不知道它在改什么。 问题不在模型。问题在于你没有流程。 你不会让一个新来的工程师看了一眼 Jira 标题就动手写代码，却天天这样对 AI。 我这半年摸索出一套稳定打法：**方法论给方向，工具给效率，案例给信心。** 这篇文章把三层全讲透。 --- ## 一、方法论：先计划，再编码 这套方法论来自 Boris Tane 的博客 *"How I Use Claude Code"*（链接附在文末）。我反复读了好几遍，核心观点一句话： **在你审阅并确认书面计划之前，不要让 Claude 写一行代码。** 这不是"建议"，这是纪律。 ### 三个阶段 **Research：先让 AI 把代码读透** 不是随口问"这个文件干什么"，而是要求 Claude 深读整个模块，写出一份 `research.md`。用词要有压力：deeply、in great detail、go through everything。 写出来的不是聊天记录，是一份你能审阅的文档。审阅它，你才知道 AI 到底理解了多少。 很多翻车项目的根因，就是 AI"看起来懂了"，但实际忽略了现有的缓存层、ORM 约定、或者其他模块已经实现的逻辑。Research 阶段把"感觉它懂了"变成"我能确认它懂了"。 **Plan：写计划，反复批注** 让 Claude 写 `plan.md`，包含实现方案、代码片段、文件路径、取舍分析。然后你在编辑器里直接批注——这里不对、那个方案我不要、这个约束你漏了。 发回给 Claude：**"I added a few notes to the document, address all the notes and update the document accordingly. don't implement yet."** 这个循环叫 **Annotation Cycle**，通常走 1-6 轮。关键词是最后那句 **don't implement yet** ——这句话把"思考"和"执行"彻底分开了。 为什么用 Markdown 文件而不是在对话里讨论？因为文档是共享的可变状态。你可以按自己的节奏思考，精确地在出问题的地方批注，不会被对话流冲走。 批注收敛后，再让 Claude 在计划里补一个 todo 清单，分阶段、分任务。依然附上那句 **don't implement yet**。 **Implement：一口气执行** 计划确认后，才进入实现阶段。给 Claude 的指令是： > implement it all. when you're done with a task or phase, mark it as completed in the plan document. do not stop until all tasks and phases are completed. continuously run typecheck to make sure you're not introducing new issues. 让它一口气跑完，不要中途停下来征求意见。计划已经反复确认过了，实现阶段的工作是机械执行。 实现过程中如果需要纠偏，用简短指令： - "这个函数你没实现。" - "这个页面应该在 admin app，不是 main app，挪过去。" - 视觉问题："wider"、"still cropped"、"there's a 2px gap"。 方向偏大了就回滚重来，别在错误基础上打补丁。 ### 最关键的一条 guardrail 整个方法论里最重要的，不是 Research 也不是 Plan，而是那句 **don't implement yet**。 AI 的默认倾向是：拿到问题就开写。你不拦它，它就会写。一旦写了，你就陷入"改还是不改"的沉没成本陷阱。 先想清楚，再动手。这条规则对人也适用，对 AI 尤其致命。 --- ## 二、工具化：get-shit-done 把纪律变成流水线 Boris 的方法论很好，但有个问题：靠手动执行。 你得自己记着"先写 research"、"别让它实现"、"批注完了再发回去"。做一个项目没问题，连做三个，纪律就松了。 这就是 get-shit-done（简称 GSD）解决的问题：**把方法论产品化，变成一套命令系统。** ### 它解决的核心问题：Context Rot GSD 的设计出发点是一个被多数人忽视的问题——**上下文腐烂（Context Rot）**。 Claude 的上下文窗口有 200k tokens。听起来很大，但在一个复杂项目里，研究文档、计划、代码变更累积起来，窗口很快就满了。满了之后，AI 的输出质量会明显下降：它开始忘记前面的约束，重复已有逻辑，或者生成和已有代码风格不一致的实现。 GSD 的策略是：**每个执行任务用独立的上下文窗口**。规划者和执行者分离，执行者拿到的是精简的计划文档，不是整个对话历史。这样每个任务都在"干净"的上下文里跑。 ### Boris 流程 → GSD 命令的对应关系 | Boris 流程 | GSD 命令 | 产物 | |---|---|---| | Research | `/gsd:plan-phase N`（内置研究） | `RESEARCH.md` | | Plan + Annotation | `/gsd:discuss-phase N` + `/gsd:plan-phase N` | `CONTEXT.md` + `*-PLAN.md` | | Coding | `/gsd:execute-phase N` | `*-SUMMARY.md` + 原子提交 | | Test/UAT | `/gsd:verify-work N` | `*-UAT.md` | | 修复闭环 | `/gsd:plan-phase N --gaps` + `/gsd:execute-phase N --gaps-only` | gap plans + 修复结果 | ### 5 步核心工作流 **Step 1：`/gsd:new-project`** GSD 会问你一系列问题：目标是什么、约束是什么、技术偏好是什么、边界在哪里。然后生成： - `PROJECT.md`（项目定义） - `REQUIREMENTS.md`（需求清单） - `ROADMAP.md`（路线图，拆成多个 Phase） - `STATE.md`（决策记录，持续累积） 如果是已有代码库，先跑 `/gsd:map-codebase`，让 GSD 分析现有架构、技术栈、代码风格。 **Step 2：`/gsd:discuss-phase N`** 针对当前 Phase 的具体实现，GSD 会识别灰色地带然后问你。比如做 UI 功能会问布局和交互偏好，做 API 会问错误处理和返回格式。 你的回答写入 `CONTEXT.md`，成为下游所有 agent 必须遵守的约束。这一步对应 Boris 的 Annotation Cycle 的"输入侧"——把你的判断变成硬约束。 **Step 3：`/gsd:plan-phase N`** 这一步内置了完整的 Research → Plan → Verify 循环： 1. 4 个研究 agent 并行出动（技术栈研究员、特性研究员、架构研究员、**陷阱研究员**），产出 `RESEARCH.md` 2. 规划 agent 基于研究结果写计划 3. 检查 agent 验证计划是否满足需求 4. 不过就循环，直到验证通过 **Step 4：`/gsd:execute-phase N`** 计划按依赖关系分成 wave： - 独立任务 → 同一 wave → 并行执行 - 有依赖的任务 → 后续 wave → 等前置完成 每个任务在独立的 200k 上下文窗口里执行，执行完产出原子提交和 `SUMMARY.md`。 **Step 5：`/gsd:verify-work N`** 不是"跑一遍测试"就结束。GSD 做对话式 UAT——逐条确认预期行为。有问题自动诊断，生成 gap 修复计划。然后 `/gsd:plan-phase N --gaps` + `/gsd:execute-phase N --gaps-only` 只修复问题，不动其他。 ### 三个设计亮点 **11 个专业 agent 分工协作。** 研究员、规划师、检查器、执行器、验证器、调试器——每个角色只干一件事。不是一个"万能 AI"从头聊到尾，而是流水线上的工位。 **上下文预算控制。** 编排层维持在约 30-40% 的上下文占用，而不是用到 80% 才换窗口。这保证了规划和协调始终在清醒状态下运行。 **波次执行（Wave Execution）。** 独立任务并行跑，有依赖的串行等。垂直切片（一个功能端到端）比水平分层（先写所有 model，再写所有 controller）更适合并行。 --- ## 三、实战案例：飞书 Webhook 机器人开发全记录 方法论和工具都讲了。你可能在想：实际跑起来什么感觉？ 我拿一个真实项目来走一遍——**ClawdBot Bridge 飞书 Webhook 模式开发**。这个项目我用 GSD 全程管理，从 Research 到 Verify 完整闭环。完整的 `.planning/` 目录、研究文档、计划文档、审计报告都在开发分支上，文末有链接，建议对照着看。 ### 项目背景 ClawdBot Bridge 是一个 Go 写的桥接服务，连接飞书 IM 和 ClawdBot AI Agent。v1.0 用 WebSocket 模式，但生产环境长连接不稳定——断线时正在执行的任务直接中断，无感知。 v1.1 的目标：**给已有的 WebSocket 模式加上 Webhook 模式**，让用户可以按需切换。 技术栈：Go 1.23 + 飞书 SDK + Prometheus 监控。 ### `.planning/` 目录：项目的"大脑" GSD 生成的 `.planning/` 目录是整个项目的决策中心（可以直接在 GitHub 分支上浏览每个文件的完整内容）： ``` .planning/ ├── PROJECT.md # 需求定义 + 显式 Out of Scope ├── STATE.md # 累积决策记录（为什么这样做） ├── ROADMAP.md # 4 阶段路线图 ├── research/ │ ├── ARCHITECTURE.md # 现有架构分析 │ └── PITFALLS.md # 10 个已识别陷阱 ├── codebase/ # 代码库静态分析 └── phases/ # 每个阶段的计划和总结 ├── 01-PLAN.md ├── 01-SUMMARY.md ├── 02-PLAN.md └── ... ``` ### Research 阶段：陷阱识别是最大的价值 `PITFALLS.md` 列出了 10 个潜在陷阱，其中 3 个标记为 Critical： **陷阱 1（Critical）：飞书 3 秒超时** 飞书要求 Webhook 回调在 3 秒内返回 HTTP 200，否则判定失败。连续失败会自动禁用 Webhook。 这意味着：收到消息后必须立即返回 200，然后异步处理。不能同步等 AI 生成回复。 如果没有在 Research 阶段识别到这一点，你会怎样？实现一个同步处理的 handler，部署后发现飞书不停禁用你的 Webhook，然后开始排查——这就是典型的"事后 debug"。 **陷阱 3（Critical）：Challenge 验证** 飞书首次配置 Webhook 时会发送 Challenge 请求验证地址可达性。这个请求的格式和正常消息不同，必须单独处理。 GSD 的建议：把 Challenge 验证做成第一个测试用例。先确保握手通过，再做消息处理。 **陷阱 4（Critical）：签名验证** Webhook 请求需要验签防止伪造。自己手写签名验证容易出错——时间戳格式、编码方式、哈希算法都是坑。 GSD 的建议：直接用飞书官方 SDK 的验签方法，不手写。 **一句话总结：陷阱前置识别 >> 事后 debug。** 10 个陷阱里有 3 个 Critical，全部在写第一行代码之前就识别并制定了应对策略。 ### Plan 阶段：ROADMAP 拆成 4 个 Phase | Phase | 内容 | 核心产出 | |---|---|---| | 1 | 接口抽象 | FeishuSender/Receiver 接口分离 | | 2 | Webhook Server + 安全 | Worker Pool + 签名验证 + 3 秒超时处理 | | 3 | 配置模式切换 | CLI 参数 + 配置文件双入口 | | 4 | 测试 + 文档 | 集成测试 + 部署文档 | 4 个 Phase 对应 4 个开发日。每个 Phase 在 discuss → plan → execute → verify 的完整循环里跑。 ### Execute 阶段：STATE.md 记录关键决策 执行过程中碰到的设计决策，全部写入 `STATE.md`。举三个例子： **决策 1：用 event_id 而非 message_id 去重** 飞书在 Webhook 超时时会重试，同一条消息可能收到多次。去重用什么 key？ `message_id` 看起来合理，但飞书重试时 `event_id` 保持一致，`message_id` 不一定。所以用 `event_id` 去重。 这个决策如果没记录，三个月后你看到代码里用 `event_id` 去重会困惑——为什么不用更直觉的 `message_id`？ **决策 2：闭包模式解决循环依赖** Bridge 需要同时持有 Sender 和 Receiver 的引用，但两者在初始化时互相依赖。用闭包延迟绑定，避免了循环依赖。 **决策 3：Panic recovery 放在 job 执行层** Worker Pool 里单个 job panic 不能把整个 worker 打崩。recovery 放在 job 执行层，worker 继续处理队列里的下一个 job。 ### Verify 阶段：全部通过 最后跑 `/gsd:audit-milestone`，产出 `v1.1-MILESTONE-AUDIT.md`： - Requirements 10/10 ✅ - Phases 4/4 ✅ - Integration 12/12 接线验证 ✅ - E2E Flows 2/2 端到端流程 ✅ ### 关键数据 - **20 个结构化 Git 提交**（feat/test/docs 前缀，GSD 自动生成） - **最终代码**：约 1500 行 Go + 350 行文档 - **0 技术债、0 功能缺口** ### 案例启示 **1. Out of Scope 要显式声明。** `PROJECT.md` 里明确写了"不做云函数部署"、"不做 WebSocket 和 Webhook 同时运行"。不写清楚，AI 会"好心"帮你做，然后你花时间拆。 **2. 陷阱前置识别远胜事后 debug。** 飞书 3 秒超时这种问题，调试阶段碰到会浪费半天。Research 阶段识别，10 分钟搞定策略。 **3. STATE.md 让后人能理解"为什么这样做"。** 代码告诉你 what，注释告诉你 how，`STATE.md` 告诉你 why。三个月后回来维护，不用考古。 --- ## 四、我的实践总结 ### 三层价值 - **方法论（Boris）给方向**：先想清楚再动手，don't implement yet。 - **工具（GSD）给效率**：把纪律变成命令，把命令变成流水线。 - **案例（飞书 Webhook）给信心**：跑完一个完整闭环，你会知道这套流程不是纸上谈兵。 ### 什么项目适合 中等以上复杂度、需要多步实现的项目。 如果只是改个按钮颜色、加个 console.log，直接写就行。但如果你的项目有多个模块、需要做架构决策、或者涉及外部系统集成，这套流程会显著减少返工。 ### 三条防偏建议 **1. 不要跳过 discuss-phase。** 很多"计划不贴业务"的问题，根源是约束没前置。discuss-phase 把你的判断变成硬约束，不是可选项。 **2. 不要把 plan 做太大。** 一个 Phase 塞 15 个任务，计划本身就成了负担。宁可多 plan 小步跑——每个 Phase 2-5 个任务刚好。 **3. 不要把 verify 当形式流程。** 你最贵的 bug，往往在"看起来都对"但真实交互出错的地方。verify 是真的验收，不是打个勾。 ### 最后一句 AI 编程的上限，不是模型能力，是你有没有流程系统。 --- ## 参考资源 - Boris Tane, *How I Use Claude Code*：[How I Use Claude Code](https://boristane.com/blog/how-i-use-claude-code/) - get-shit-done GitHub：[get-shit-done](https://github.com/gsd-build/get-shit-done) - ClawdBot Bridge 飞书 Webhook 开发分支：[feat/v1.1-webhook-mode 分支](https://github.com/deletexiumu/moltbotCNAPP/tree/feat/v1.1-webhook-mode) --- ## 相关阅读 - [同样的话跟 Claude Code 说了八遍，是时候让它自己记住了](/posts/claude-code-memory-rules/) — 把工作流规则写进 CLAUDE.md，不用每次重复交代 - [从单兵作战到团队协作：Claude Code Agent Team 深度解析](/posts/claude-code-agent-team/) — 有了好的工作流，下一步是多 Agent 并行 - [从需求到自动化：Claude Code Skill 工具链完整实战](/posts/claude-code-skill-toolchain/) — 工作流方法论的实战延伸，把采集流程固化成可复用 Skill