用 Claude Code 最佳实践重塑工作流：代理循环与四阶段方法论
这篇文章记录了我阅读 Claude Code 官方最佳实践后，将其应用到个人博客重构项目中的完整过程。核心收获是理解了”代理循环”的本质，以及如何在 context window 的约束下，设计高效的四阶段工作流。
一、代理循环：Claude Code 的本质
Claude Code 与普通的聊天机器人最大的区别在于：它是一个代理式编码环境。
不是等你逐条下达指令后才继续，而是可以自行读取文件、运行命令、根据结果进行修改，自主解决问题。只要方向没有走偏，你可以让它自主运行，自己只需要在关键节点做决策。
官网文档对此的概括很精准：与其自己编写代码并要求 Claude 审查，不如描述你想要什么，让 Claude 弄清楚如何构建它——Claude 会探索、规划和实现。
这种自主性对应的工作流，我将其概括为三个阶段：
1
探索规划 → 执行编码 → 验证结果
但实际操作中，我发现需要把”探索”和”规划”拆开，形成更精细的四阶段工作流。
二、Context Window：一切实践的约束前提
在深入工作流之前，必须理解一个核心约束：Claude 的 context window 填充速度很快，随着填充，性能会下降。
Context window 保存着整个对话的历史——每条消息、读取的每个文件、每个命令输出。单个调试会话或代码库探索就可能生成并消耗数万个 token。当 context 接近满载时，Claude 会开始”遗忘”早期指令或犯更多错误。
这意味着：context window 是最重要的资源，所有工作流设计本质上都是在用有限的 context 换取最大的输出质量。
理解这一点后，很多最佳实践就顺理成章了：为什么频繁纠正后要开新 session？为什么要把探索和执行分开？为什么要用 subagents？都是为了保护 context 的纯净和高效利用。
三、四阶段工作流
基于 context window 约束，我实践的工作流分为四个阶段：
1
探索项目 → 推理规划 → 执行编码 → 验证结果
阶段一：探索项目
目标：为 Claude Code 补充干净的 context。
这是最容易被跳过的阶段。普通人听到需求后，往往马上让 Claude 开始写代码。但官方文档明确警告：”让 Claude 直接跳到编码可能会产生解决错误问题的代码。”
探索阶段的正确做法是：让 Claude 了解项目全貌——梳理项目结构、各个模块的绑定关系、现有漏洞和改进空间。这个阶段我的理解是为 Claude 补充干净的背景资料，了解项目的大大小小的细节，减少后续幻觉的出现。
模糊提示在探索阶段是有效的。像 “你会改进这个文件的什么？” 这类开放性问题，可以表面你不会想到要问的东西。但当探索完成后，后续阶段就需要精确指令了。
博客项目实践：在重构个人博客时，我首先让 Claude 了解基于 jekyll-theme-chirpy 7.5 的现有结构。通过探索，Claude 梳理出 11 处对比度、响应式、信息架构与视觉层次问题，并识别出 chirpy 主题的
tail_includes插槽、script_includeshook、_data覆盖机制等关键扩展点。这些背景信息为后续规划提供了准确的事实基础。
阶段二：推理规划（Plan Mode）
目标：需求对齐，形成可执行的完整方案。
Claude Code 提供了 Plan Mode，用于将探索与执行分开。这一步的核心价值是：根据 Claude 上阶段了解的全貌，进行需求上的对齐，并让 Claude 在 plan 中确定哪些需求是合理的、哪些是不能的、需要调整的。这样就形成了一个完整的推理编码方案。
但 Plan Mode 增加了开销，不是所有任务都需要。官方建议：范围明确且修复很小的任务（如修复拼写错误、添加日志行或重命名变量），可以直接执行。当你对方法不确定、更改修改多个文件或你不熟悉被修改的代码时，规划最有用。如果你能用一句话描述 diff，跳过计划。
博客项目实践：我向 Claude 提供了”加强而非推翻”的基调约束，Claude 据此提出了四种重做方案（墨水经典精修 / 推翻重写 Tufte 风格 / 仅改首页 / 强动效方案）。我最终选择了”墨水经典精修 + 全站重做 + 保留 light/dark 双模式 + 中度动效”。这个决策过程正是 Plan Mode 的价值体现——在编码前先把方向对齐，避免后续大规模返工。
阶段三：执行编码
目标：按照规划方案实施。
方案规划好后，就可以进行编码任务。这里的关键原则是：指令越精确，需要的更正就越少。
Claude 可以推断意图，但它不能读心术。需要引用特定文件、提及约束、指出示例模式。在所有过程中，你都可以随时打断 Claude 正在做的事，及时纠正和补充正确的信息，将其作为干净的 context 补充。
当需要对项目引入新的内容，但 context 中不存在时，可以使用 @ 引用文件、粘贴屏幕截图或者管道数据来提供。
博客项目实践：由于前期探索和规划阶段方向正确，执行编码阶段我没有过多干涉，Claude 自主完成了 8 个 commit，从对比度与中文排版修复，到动效层、Hero 组件、作品集网格，再到 5 个 bug 修复。
阶段四：验证结果
目标：提供成功标准，让 Claude 自检。
这是官方文档列为最高杠杆的事情：”包括测试、屏幕截图或预期输出，以便 Claude 可以检查自己。当 Claude 能够验证自己的工作时，例如运行测试、比较屏幕截图和验证输出，它的表现会显著提高。”
没有明确的成功标准，Claude 可能会产生看起来正确但实际上不起作用的东西。你成为唯一的反馈循环，每个错误都需要你的关注。
| 策略 | 低效做法 | 高效做法 |
|---|---|---|
| 提供验证标准 | “实现一个验证电子邮件地址的函数” | “编写 validateEmail 函数。示例测试用例：user@example.com 为真，invalid 为假。实现后运行测试” |
| 以视觉方式验证 UI | “让仪表板看起来更好” | “[粘贴屏幕截图] 实现此设计。对结果进行屏幕截图并与原始设计进行比较。列出差异并修复它们” |
| 解决根本原因 | “构建失败” | “构建失败，出现此错误：[粘贴错误]。修复它并验证构建成功。解决根本原因，不要抑制错误” |
博客项目实践：验证阶段调用了 Playwright 工具去获取博客的截图，验证了 UI 的实现效果，并反过来检查编码出现的问题。最终形成了完整的验证矩阵：首页（light/dark）、文章详情页、作品集页、分类页、标签页、归档页、关于页全部通过；响应式断点覆盖 768px、1024px、1280px 三个视口。这种”截图验证 → 发现差异 → 修复问题”的循环，正是”给 Claude 一种验证其工作的方式”的实践体现。
四、Context 管理与 Session 策略
及时纠正与 Session 重置
官方文档强调：”一旦你注意到 Claude 偏离轨道，立即改正它。”最好的结果来自紧密的反馈循环。
但如果在同一个会话中对同一问题纠正了 Claude 两次以上，context 就充满了失败的方法。此时官方建议运行 /clear 并使用更具体的提示重新开始。干净的会话与更好的提示几乎总是优于长会话与累积的改正。
这与我的实践完全吻合：如果出现了两次以上的改正，就需要新开一个任务/session。频繁更改后，上下文已经被污染，不如重新开始。context window 有容量限制，最接近上限时获得的上下文越丰富，但早期的指令会模糊。
避免”厨房水槽会话”
官方将”厨房水槽会话”列为常见失败模式：你从一个任务开始，然后问 Claude 一些不相关的东西，然后回到第一个任务——Context 充满了无关的信息。修复方法是在不相关的任务之间 /clear。
博客项目实践：我没有频繁切换任务方向，而是从”探索项目结构”一直推进到”验证 UI 效果”，保持了 context 的连贯性。
积极管理 Context
官方提供了多种 context 管理工具：
| 工具 | 用途 |
|---|---|
/clear | 在任务之间完全重置 context window |
/compact <instructions> | 按需压缩对话历史，保留关键内容 |
/rewind 或双击 Esc | 从选定的消息进行总结，恢复之前状态 |
/btw | 快速提问，答案不会进入对话历史 |
| Subagents | 在单独的 context 中探索，为主对话保持干净 |
Subagents 尤其值得关注。当 Claude 研究代码库时，它读取许多文件，所有这些都消耗你的 context。Subagents 在单独的 context windows 中运行并报告摘要，是保护主 context 的最强大工具之一。
五、精确指令与环境配置
提示要具体
官方给出的策略对比：
| 策略 | 模糊提示 | 精确提示 |
|---|---|---|
| 限定任务范围 | “为 foo.py 添加测试” | “为 foo.py 编写测试，涵盖用户已注销的边界情况。避免 mock” |
| 指向来源 | “为什么 ExecutionFactory 有这样奇怪的 api？” | “查看 ExecutionFactory 的 git 历史并总结其 api 是如何形成的” |
| 参考现有模式 | “添加日历小部件” | “查看主页上现有小部件的实现方式以了解模式。HotDogWidget.php 是一个很好的例子。按照模式实现一个新的日历小部件” |
| 描述症状 | “修复登录错误” | “用户报告会话超时后登录失败。检查 src/auth/ 中的身份验证流程，特别是 token 刷新。编写一个失败的测试来重现问题，然后修复它” |
配置 CLAUDE.md
/init 可以根据项目结构生成启动 CLAUDE.md 文件。这是 Claude 在每次对话开始时读取的特殊文件，包括 Bash 命令、代码风格和工作流规则。
核心原则：保持简洁。对于每一行，问自己：”删除这个会导致 Claude 犯错吗？”如果不会，删除它。膨胀的 CLAUDE.md 文件会导致 Claude 忽略你的实际指令。
| ✅ 应该包括 | ❌ 应该排除 |
|---|---|
| Claude 无法猜测的 Bash 命令 | Claude 可以通过读取代码弄清楚的任何东西 |
| 与默认值不同的代码风格规则 | Claude 已经知道的标准语言约定 |
| 测试指令和首选测试运行器 | 详细的 API 文档（改为链接到文档） |
| 存储库礼仪（分支命名、PR 约定） | 经常变化的信息 |
| 特定于你的项目的架构决策 | 长解释或教程 |
六、常见失败模式
官方文档总结了五个常见失败模式，我在博客项目中有意识地规避了其中几个：
- 厨房水槽会话：未在博客项目中穿插无关任务，保持了 context 的专注。
- 一次又一次地改正：由于前期探索充分，博客项目执行阶段纠正次数极少。
- 过度指定的 CLAUDE.md：未使用复杂的 CLAUDE.md，而是通过 Plan Mode 和对话中的精确指令来传递需求。
- 信任然后验证的差距：通过 Playwright 截图和多页面验证矩阵，避免了”看起来正确但实际不起作用”的问题。
- 无限探索：探索阶段有明确目标（”梳理项目结构、识别问题”），未让 Claude 无限制地读取文件。
七、总结
Claude Code 的最佳实践核心在于：理解代理循环的本质，尊重 context window 的约束，将探索、规划、执行、验证四个阶段分离，并给 Claude 提供验证其工作的手段。
在博客项目中，这一工作流被完整落地：探索阶段补充了干净的 context，规划阶段对齐了需求方向，执行阶段凭借精确指令高效推进，验证阶段通过 Playwright 截图确保了交付质量。
对于项目的构建，不要频繁更改方向，会造成 Agent 的 context 混乱。对于 skill、mcp 工具，在博客项目中用到的比较少，主要是设计和获取网页截图时用到。
如果你也在使用 Claude Code 处理项目，建议从”慢下来，把 Claude 当作助手”开始，走完完整的四阶段工作流，而不是一上来就要求写代码。最终的效果会证明，前期多花的时间是值得的。