核心原则
在审查并批准书面计划之前，绝不让 Claude 编写代码。 将规划与执行分离，可以避免无效劳动，保持对架构决策的控制权，并以更少的 token 消耗获得更好的结果。
整体流程
Research → Plan → Annotate（重复1-6次）→ Todo List → Implement → Feedback & Iterate
第一阶段：Research（调研）
每个有意义的任务都从深度阅读代码库开始。要求 Claude 在执行任何操作前，先彻底理解相关代码，并将调研结果写入持久化的 markdown 文件（如 research.md），而非仅在对话中口头总结。
关键技巧：
- 在 prompt 中使用"deeply"、"in great details"、"intricacies"等强调词，否则 Claude 只会浅层浏览代码
- 书面产物
research.md是审查面——用于验证 Claude 是否真正理解了系统，并在规划开始前纠正误解 - AI 辅助编码中代价最高的失败模式不是语法错误或逻辑错误，而是实现在孤立环境中能工作但破坏周围系统的代码（例如忽略现有缓存层、不遵循 ORM 约定、重复已有逻辑）。调研阶段可以防止这类问题
示例 prompt：
read this folder in depth, understand how it works deeply, what it does and all its specificities. when that's done, write a detailed report of your learnings and findings in research.md
第二阶段：Plan（规划）
审查调研结果后，要求 Claude 在单独的 markdown 文件中编写详细的实施计划。计划应包含：方法说明、代码片段、需修改的文件路径、考量与权衡。
关键技巧：
- 使用自定义
.md文件而非 Claude Code 内置的 plan mode，因为 markdown 文件可在编辑器中自由编辑、添加批注，并作为项目中的真实产物持久保存 - 对于边界清晰的功能，可将开源项目中优秀实现的代码作为参考一并提供。Claude 在有具体参考实现时表现显著优于从零设计
示例 prompt：
the list endpoint should support cursor-based pagination instead of offset. write a detailed plan.md for how to achieve this. read source files before suggesting changes, base the plan on the actual codebase
批注循环（Annotation Cycle）
这是整个工作流中最具特色的环节。
- Claude 生成
plan.md - 在编辑器中打开计划，直接在文档中添加内联批注
- 让 Claude 回去处理批注并更新文档
- 重复此循环 1-6 次，直到满意为止
批注内容示例：
use drizzle:generate for migrations, not raw SQL—— 补充 Claude 不具备的领域知识no — this should be a PATCH, not a PUT—— 纠正错误假设remove this section entirely, we don't need caching here—— 否决某个方案the queue consumer already handles retries, so this retry logic is redundant—— 解释变更原因this is wrong, the visibility field needs to be on the list itself, not on individual items—— 重新定向计划的某个章节
关键约束： 每次让 Claude 处理批注时，必须明确加上 "don't implement yet"，否则 Claude 会在自认计划足够好时直接跳到编码阶段。
为什么有效：
- Markdown 文件充当开发者与 Claude 之间的共享可变状态，可以按自己的节奏思考、精确标注问题位置
- 结构化的计划文档可以整体审查，而聊天记录需要翻阅才能还原决策过程
- 3 轮批注循环可以将一个通用实施计划转化为完美契合现有系统的方案。Claude 擅长理解代码和提出方案，但不了解产品优先级、用户痛点或工程权衡——批注循环就是注入这些判断的途径
Todo List（任务清单）
实施前，要求生成粒度化的任务分解，作为实施过程中的进度追踪器。Claude 在执行时逐项标记完成状态，便于随时查看进展。
第三阶段：Implement（实施）
使用标准化的实施 prompt：
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. do not add unnecessary comments or jsdocs, do not use any or unknown types. continuously run typecheck to make sure you're not introducing new issues.
此 prompt 编码了以下要求：
| 指令 | 含义 |
|---|---|
implement it all | 执行计划中的所有内容，不要挑选 |
mark it as completed in the plan document | 计划文档是进度的唯一真实来源 |
do not stop until all tasks and phases are completed | 不要中途暂停等待确认 |
do not add unnecessary comments or jsdocs | 保持代码整洁 |
do not use any or unknown types | 维持严格类型 |
continuously run typecheck | 尽早发现问题 |
核心理念： 实施阶段应该是机械性的、无趣的。创造性工作已在批注循环中完成。计划确定后，执行应当简单直接。
实施阶段的反馈
实施开始后，开发者的角色从架构师转为监督者，指令变得极为简短：
You didn't implement the deduplicateByTitle function.You built the settings page in the main app when it should be in the admin app, move it.- 前端视觉调整更为简洁：
wider/still cropped/there's a 2px gap - 可附截图说明视觉问题
- 引用现有代码作为参照：
this table should look exactly like the users table, same header, same pagination, same row density. - 方向错误时不要试图修补，而是 revert 后缩小范围重做，效果优于增量修复
保持主导权
虽然执行委托给 Claude，但绝不给予其对构建内容的完全自主权。主要的引导工作在 plan.md 中完成。
具体策略：
- Cherry-picking（逐项筛选）： 对 Claude 提出的多个问题逐一判断，接受、修改或忽略
- Trimming scope（裁剪范围）： 主动删除计划中的 nice-to-have 项，防止范围蔓延
- Protecting existing interfaces（保护现有接口）： 对不应变更的部分设定硬约束
- Overriding technical choices（覆盖技术选择）： 直接指定 Claude 无从知晓的偏好
单一长会话
将调研、规划和实施放在同一个长会话中运行，而非拆分为多个独立会话。到发出"implement it all"时，Claude 已在整个会话中积累了充分理解。上下文窗口填满时，Claude 的自动压缩机制会保留足够的上下文继续工作，而计划文档作为持久化产物可以随时被引用。
一句话总结
深度阅读，编写计划，反复批注直到计划正确，然后让 Claude 不间断地执行全部内容，过程中持续检查类型。
没有魔法 prompt，没有复杂的系统指令，只是一条纪律严明的流水线——三思而后行。
