How I Use Claude Code | Boris Tane

本文作者分享了使用 AI 编程工具 Claude Code 长达 9 个月后形成的一套独特工作流。其核心原则是在审核并批准书面计划之前，绝不允许 AI 编写任何代码，通过严格分离规划与执行来提升开发质量。

作者的工作流分为三大阶段。首先是研究阶段，作者要求 Claude 深入阅读代码库的相关部分，理解其细节和特异性，并将所有发现写入一个持久的 research.md 文件中，供作者审查。这一步旨在确保 AI 真正理解现有系统，防止后续实现破坏现有功能。第二阶段是规划阶段，作者要求 Claude 基于研究撰写一份详细的 plan.md，包含具体方法、代码片段、待修改文件路径和权衡考虑。随后，最关键的标注循环 开始：作者在编辑器中审阅计划，直接在文档中添加内联注释，以纠正假设、拒绝错误方法或补充领域知识，然后让 Claude 根据这些注释更新计划。这个循环会重复 1 到 6 次，直到计划完美无缺。最后是实施阶段，作者会用一个包含明确指令（如全部实现、标记完成、不停止、维护代码风格、持续运行类型检查）的标准化提示，让 Claude 按照最终确定的计划一次性执行所有任务。作者作为监督者，在实施过程中仅通过简短的指令进行微调或纠正。

这个工作流的关键在于利用 Markdown 文件作为人与 AI 之间的共享可变状态，让作者能够以结构化、渐进的方式注入自己的判断和领域知识，将 AI 的创造力引导至正确的方向。作者认为，这种方法能有效避免因 AI 早期错误假设而导致的无效工作和返工，最终交付更高质量、更贴合项目需求的代码。

核心原则：规划与执行分离

本文作者 Boris Tane 强调，他工作流的核心支柱是一个简单但严格的规则：永远不要让 Claude 在没有书面计划且未经过审核的情况下写代码。他认为，大多数开发者直接输入提示词、让 AI 写代码、再修复错误的方式，对于任何非琐碎的项目都会导致混乱。而市面上流行的各种复杂循环或外部工具，结果也同样糟糕。这个核心原则旨在将“思考”与“打字”彻底分开。

规划阶段是创造性的、需要人类判断的工作，它决定了要“做什么”和“为什么做”。执行阶段则是机械性的，由 AI 负责“怎么做”。这种分离能防止 AI 在错误的假设上浪费算力，让人类开发者始终保持对架构和方向的掌控。作者强调，等到所有决策都在计划中敲定后，执行过程就应该变得“枯燥”，因为真正的创造性工作已经完成。这不仅提升了最终代码的质量，也显著提高了 token 的利用效率，避免了因反复纠正错误而产生的巨大浪费。

三阶段工作流详解

作者的工作流被清晰地划分为三个阶段：研究、规划和实施。每个阶段都有其特定的目标和产出。

1. 研究阶段

任何有意义的任务都从一个“深度阅读”指令开始。作者会让 Claude 彻底理解代码库中相关部分的内容，不仅仅是函数签名层面的阅读，而是深入理解其工作原理、所有细节和特性。为此，作者会使用“deeply”、“in great details”、“intricacies”等关键词来强调深入的程度，防止 AI 只做表面阅读。

研究的结果必须写入一个持久的 research.md 文件，而不是仅停留在对话中。这个文件是供作者审查的界面，通过阅读它，作者可以验证 Claude 是否正确理解了系统，并及早纠正任何误解。作者认为，这是最关键的一步，可以预防最昂贵的失败模式：代码本身能运行，但破坏了周围的系统。例如，一个函数忽略了已有的缓存层，或者一个 API 端点重复了其他地方已有的逻辑。

2. 规划与标注循环

在审核完研究报告后，作者会要求 Claude 为所需的新功能或修改撰写一份详细的 plan.md。这份计划需要包含详细的实现方法、展示实际变更的代码片段、将被修改的文件路径以及相关的考量和权衡。作者倾向于使用自己的 Markdown 文件而非 Claude Code 内置的计划模式，因为这样可以获得完全的控制权，可以在编辑器中直接编辑和添加注释。

这份计划文档本身并非最终产物，真正的关键在于接下来的标注循环。Claude 生成计划后，作者会在编辑器中打开它，并直接在其中添加内联注释。这些注释的形式和目的多种多样：

纠正假设：例如，将 Claude 标记为可选的参数注明“not optional”。
补充领域知识：例如，注明“use drizzle:generate for migrations, not raw SQL”，提供 Claude 不知道的项目规范。
拒绝方案：例如，直接删除关于添加缓存的章节，并注明“remove this section entirely, we don’t need caching here”。
提供正确方向：例如，纠正数据模型的设计，指出“this is wrong, the visibility field needs to be on the list itself”，并重新指导如何构建模式。
解释原因：例如，解释为何某个重试逻辑是多余的，因为队列消费者已经处理了。

完成注释后，作者会再次让 Claude 去阅读这个更新后的文档，并加上明确的指令“address all the notes and update the document accordingly. don’t implement yet”。这里的“don’t implement yet”至关重要，它防止了 Claude 在计划尚未完美时就开始编码。这个“我添加了注释，你去更新计划”的循环会重复 1 到 6 次。

这个循环之所以高效，是因为 Markdown 文件作为人和 AI 之间的共享可变状态。作者可以以自己的节奏思考，在问题出现的精确位置进行标注，并在不丢失上下文的情况下重新与 AI 交互。这比通过冗长的聊天信息来引导 AI 要清晰和结构化得多。通过几轮这样的循环，一个通用的实现计划可以被重塑为完美适配现有系统的精确方案。

在实施开始前，作者还会要求 Claude 在计划中添加一个细粒度的任务分解清单，列出完成计划所需的所有阶段和单个任务。这个清单在实施过程中充当进度追踪器，Claude 每完成一项就会在计划文档中将其标记为完成，让作者可以随时了解进展。

3. 实施与监督

当计划文档最终敲定后，作者会用一个标准化的提示词命令 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. 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.” 这个提示词包含了所有关键要求：实现全部内容、更新计划作为进度源、不间断执行直到完成、保持代码整洁、维护严格类型、并持续运行类型检查。

进入实施阶段后，作者的角色从架构师转变为监督者。他的提示变得非常简短，通常只是一句话的修正，例如“You didn’t implement the deduplicateByTitle function.” 或 “wider”（针对前端样式）。对于视觉问题，他有时会附上截图。他也经常引用现有的代码作为参考，例如“this table should look exactly like the users table”，这比从头描述设计要精确得多。当 Claude 走向错误方向时，作者不会尝试修补，而是通过丢弃 Git 更改来彻底回退，然后缩小范围重新开始。

在整个过程中，作者始终坐在驾驶位上。即使在实施阶段，他也会通过选择性接受、修改或拒绝 Claude 的提议，来行使自己的判断。例如，他会从 AI 识别出的多个问题中，决定哪些需要简化，哪些值得提取成函数，哪些应该忽略以控制范围。他会主动削减计划中的非必需功能，防止范围蔓延，并设定硬性约束来保护现有接口不被意外修改。Claude 处理机械执行，而作者则做出所有关键的判断决策。

保持对项目的掌控

作者强调，尽管将执行权委托给了 Claude，但他从未赋予 AI 对构建内容的完全自主权。所有的主动引导都发生在 plan.md 文档的标注循环中。Claude 可能会提出技术上正确但对项目不合适的方案，例如过度设计、意外修改了被其他部分依赖的公共 API，或在简单方案可行时选择了更复杂的选项。作者拥有关于更广泛系统、产品方向和工程文化的背景知识，而这些是 Claude 所不具备的。

在实施过程中，作者通过以下几种方式持续保持掌控：

从提案中精选：当 Claude 提出多项修改时，作者会逐项评估，决定接受、修改或忽略。
主动裁剪范围：当计划中包含非核心功能时，作者会主动将其移除，以防止范围蔓延。
保护现有接口：当作者知道某些东西不应更改时，会设置硬性约束，例如函数签名不能改变，调用方必须适应被调用方。
覆写技术选择：当作者有特定偏好时，会直接给出指令，例如使用某个模型或库的内置方法，而不是让 Claude 编写自定义代码。

Claude 负责机械执行，而作者则做出所有判断决策。计划捕获了前期的大决策，而在实施过程中，作者通过有选择性的指导来处理那些浮现出来的小问题。这种分工确保了项目始终沿着正确的方向前进。

关于长对话的实践

作者倾向于在一个长的、连续的会话 中完成研究、规划和实施，而不是将它们分成多个独立的会话。一个长会话可能从深入阅读一个文件夹开始，经历几轮计划标注，然后执行全部实施，所有这些都在一个连贯的对话中完成。

作者并没有遇到很多人提到的，在上下文窗口使用超过 50% 后性能下降的问题。相反，他认为当进入实施阶段时，Claude 已经通过整个会话积累了深厚的理解：在研究阶段阅读文件，在标注循环中精炼其心智模型，并吸收了作者通过注释注入的领域知识。当上下文窗口填满时，Claude 的自动压缩功能能够保留足够的上下文以继续工作。而作为持久化产物的计划文档，即使在压缩后也能完整保留其全部内容，作者可以在任何时候指引 Claude 参考它。这使得长对话不仅可行，而且更加高效。

问答

问：作者工作流的核心原则是什么？ 答：核心原则是“永远不要让 Claude 写代码，直到你审核并批准了一份书面计划”，即严格分离规划与执行。

问：为什么在研究阶段，必须将发现写入 research.md 文件？ 答：这个文件是供作者审查的界面，他可以验证 AI 是否正确理解了系统，并纠正任何误解。这是防止后续实现破坏现有系统的关键步骤。

问：什么是“标注循环”，它为什么有效？ 答：“标注循环”是作者在 Claude 生成计划后，直接在计划文档中添加内联注释，然后让 AI 根据注释更新计划的迭代过程。它之所以有效，是因为 Markdown 文件作为人与 AI 之间的“共享可变状态”，允许作者以结构化的方式精确注入自己的判断和领域知识。

问：在实施阶段，作者使用的标准化提示词中包含了哪些关键指令？ 答：关键指令包括：实现所有内容、在计划文档中标记完成进度、不中断直到全部完成、不添加不必要的注释、不使用 any 或 unknown 类型、以及持续运行类型检查。

问：作者如何在实施阶段保持对项目的掌控？ 答：作者通过从 AI 的提案中精选、主动裁剪非核心功能、保护现有接口不被修改以及直接覆写技术选择等方式，确保 AI 的执行始终符合项目的大方向和具体约束。