用好 Claude Code 的完整工作流：从“意图架构师”到 AI 自动化工程平台

面向读者：有一定实践经验的开发者、架构师、技术团队负责人，希望系统性掌握 Claude Code 工作流与工程化最佳实践。

https://x.com/eyad_khrais/status/2010076957938188661

---

一、为什么“思考优先”，而不是“编码优先”？

在 AI 编程时代，开发者的角色正在从“写代码的人”转变为“意图架构师”：真正的核心竞争力，不再是你亲手敲了多少行代码，而是你能否把问题拆解清楚、把边界约束讲明白、把系统结构设计好。

传统的“编码优先”模式，在接入 AI 之后会放大原有问题：如果一开始就是模糊需求+随手开干，那么 AI 只会更快地帮你堆砌出难以维护的逻辑碎片，技术债务累积速度呈指数级增长。

1. Plan Mode：把 5 分钟规划变成肌肉记忆

Claude Code 提供了 Plan Mode（计划模式），通过双击 Shift + Tab 进入，这是整套工作流的起点。

在 Plan Mode 中，你应该重点做三件事：

• 明确目标：这次要解决的到底是哪个“具体问题”，而不是一个模糊的大愿景。
• 拉齐约束：技术栈、数据流、性能/安全要求、已有系统边界等。
• 对齐方案：通过来回追问与澄清，确认 Claude 理解到的是与你脑中一致的架构结构。

这个阶段花 5 分钟，能为后续节省数小时调试和返工时间，尤其是在复杂系统或多人协作场景下价值极高。

2. 深度对话：不是“发指令”，而是“共创系统设计”

和 Claude 的交互不应该停留在“帮我写个 X”的命令式，而要变成“我们一起推演这个系统会怎么运转”的深度对话。

一个典型的高质量对话过程，会包括：

• 让 Claude 先反问：它缺少哪些信息、有哪些模糊点；
• 要它提出多种备选设计，并说明权衡点；
• 对每个关键约束（扩展性、性能、合规、安全）明确偏好。

如果你不参与这一层的推演，而是把系统设计完全交给模型，你本质上是在“自我伤残”：久而久之，大脑会失去处理复杂系统的能力，只剩下对模型输出的被动跟随。

---

二、用一份 CLAUDE.md 把项目“喂”清楚

CLAUDE.md 是 Claude Code 在项目级别的“入职手册”，也是所有会话的最高优先级指令来源，你可以理解为：这是你对 AI 的“工程文化注入点”。

1. 指令预算：控制在 100–150 条高价值规则

Claude 在一次会话中能稳定遵守的指令，大致上限是 150–200 条；考虑到系统级提示本身就占掉了约 50 条，你留给项目的空间大约只有 100–150 条。

这意味着：

• 不要把「如何写干净代码」这种教科书内容写进去；
• 不要详细解释常规的目录结构和框架默认约定；
• 要把有限的指令预算，集中在“本项目独有”的东西上。

例如更应该写的是：

• 项目中约定俗成但容易忘记的 Bash 命令；
• 特有的 CI/CD 流程，特殊的代码生成步骤；
• “看起来反直觉、但有历史原因”的设计决定。

2. 写“为什么”，而不仅是“要什么”

高质量的 CLAUDE.md，一定包含大量“为什么”——也就是设计决策背后的上下文。

示例对比：

• 弱规则：使用 TypeScript 严格模式。
• 强规则：使用 TypeScript 严格模式，因为我们曾因隐式 any 在生产上出过严重事故，所以所有新增模块必须在严格模式下通过类型检查。

这种写法的好处是：

• 当你没显式写出某条规则时，模型仍可以依靠这些“价值判断”做出相对合理的折中；
• 同一个 CLAUDE.md，在 Opus 和 Sonnet 之间切换时，也能保证风格和决策一致性。

3. 把 CLAUDE.md 当“活文档”维护

CLAUDE.md 不是一劳永逸写完就放那儿的文档，而是需要持续演进。

实用的更新策略：

• 一条规则如果你在对话中纠正 Claude 两次以上，就应该被提升进 CLAUDE.md；
• 每次出现“模型理解偏差”时，优先思考：这是提示没写清楚，还是 CLAUDE.md 缺少项目级约束；
• 善用编辑器里用 # 触发的自动更新，减少文档维护摩擦。

---

三、Opus 与 Sonnet：深度推理与批量生产的分工

在企业工程实践中，“用对模型”非常关键：不是所有任务都值得用昂贵的深度推理模型去做，也不是所有需求都适合交给快速便宜的模型硬怼。

1. 两个模型的角色画像

维度	Claude Sonnet	Claude Opus
性格画像	响应快、执行力强、价格便宜	推理深入、擅长复杂权衡和架构思考
上下文容量	约 200k Tokens	约 200k Tokens
典型场景	样板代码、重构、生成测试、重复性任务	初始架构、复杂业务规则、关键风险逻辑
经济属性	适合作为“日常主力生产力”	仅在关键决策阶段介入，控制成本

简单理解：

• 用 Sonnet 做“日常搬砖”和流水线生产；
• 用 Opus 做“总工评审”和高风险决策。

2. 典型的模型切换工作流

一个推荐的工作流如下：

1. 架构决策：
   使用 Opus 做整体系统设计、边界划分、数据建模、错误处理策略等，它在多方案权衡上更可靠。
2. 落地实现：
   在方案定稿后，切到 Sonnet 负责：实现接口、补充测试、整理文件结构、生成重复性样板。
3. 通过 CLAUDE.md 保证“言行一致”：
   所有架构层面的约束都沉淀在 CLAUDE.md 中，从而保证 Sonnet 在执行时不会随意背离 Opus 的设计原则。

这种使用方式既保证了系统设计阶段的深度，又控制了总体 Token 成本，适合团队大规模采用。

---

四、上下文窗口管理：避免“语境衰减”的系统性策略

大模型提供了极大的上下文窗口，但这不意味着“塞得越多越好”。一个非常实用的经验值：当上下文使用率达到 20%–40% 时，输出质量往往开始明显下滑。

1. 压缩陷阱：/compact 不是“后悔药”

在对话越聊越长、文件越贴越多之后，你会感到模型逐渐“迟钝”：它开始忽略早期约束，推理链条也变得摇晃，这就是上下文衰减的表现。

此时很多人会尝试 /compact 指令，但需要注意：

• /compact 只能对“当前已经模糊的状态”做摘要；
• 它不会神奇地恢复模型早已遗忘的精度；
• 如果继续在同一个已“污染”的上下文里对话，只会越聊越糟。

2. 工程化治理准则

建议用一套“工程化的上下文治理”策略，而不是凭感觉：

• 一会话一 Feature：
  不要在同一个会话里又重构数据库，又写权限中间件；一个会话聚焦一个功能，减少上下文干扰。
• 外部记忆：
  在项目根目录维护 SCRATCHPAD.md 或 plan.md，用于记录阶段性结论、TODO 和设计摘要，这些是跨会话共享的“硬盘”。
• 复制-粘贴重置法：
  感到逻辑混乱时执行三步：
  1）/compact 做当前状态摘要；
  2）/clear 清空上下文；
  3）把摘要和关键文件手动重新注入新会话，从干净的上下文重新开始。

在实际项目中，可以把“上下文重置”视作一种常规维护动作，而不是失败的象征。

---

五、提示词工程：从“说不清”到“指令即代码”

在 Claude Code 工作流里，提示词工程不再是“玄学微调”，而是严肃的工程实践：差的输入必然导致差的输出，这是“物理定律”。

1. 高质量提示词的三根支柱

三类关键维度：

1. 精确性：

   • 坏提示：“帮我做个认证系统。”
   • 好提示：明确模型、协议、存储方式、过期策略和保护范围，例如：
     “基于现有 User 模型构建邮件/密码认证，使用 Redis 存储 Session（24 小时过期），并添加中间件保护 /api/protected 下的所有路由。”

2. 负向约束：

   • Opus 倾向于“过度工程化”，如果不加限制，它会自发引入抽象层、组件分层等。
   • 需要显式补充：“保持简单，不要引入我没要求的抽象，尽量单文件完成实现。”

3. 环境补完：

   • 告诉模型当前任务处在怎样的业务约束下，例如：
     “这是一次性原型，不会直接上生产。”
     “这里是高频调用路径，优先考虑性能和内存占用。”

2. 人类工程师仍是最后一道防线

再强的模型，也不能代替“人工代码评审”。高级工程师的核心职责之一，就是识别并清除 AI 引入的技术债务。

实操建议：

• 对生成的代码进行交叉验证：逻辑路径、异常分支、安全与性能；
• 警惕“为解决简单问题却新建一堆文件”的情况；
• 对经常出现的问题模式，反向写入 CLAUDE.md 和提示模板，让系统不断减轻这类错误发生概率。

---

六、从“对话框”到“AI 工程平台”：MCP、Hooks 与自动化

当你把 Claude Code 仅仅当成一个“高级 IDE 帮手”时，你只用到了它的冰山一角。通过 MCP、Hooks、自定义命令和 Headless 模式，它可以升级为一个自动化的工程平台。

1. MCP：把外部系统接入到模型上下文

MCP（Model Context Protocol）是用来把 Claude 接到外部系统（如 Slack、GitHub、数据库等）的通道。

适合用 MCP 的典型场景：

• 需要频繁查看/同步的外部数据源，比如线上配置、运营报表；
• 重复的“查资料→贴给模型→要结果”的工作流；
• 跨团队协作的通知和状态流转，例如在合并 PR 时自动同步到团队频道。

一旦频率足够高，就应该为该数据源开发一个 MCP 服务，把上下文注入自动化，而不是依靠人工复制粘贴。

2. Hooks：自动执行格式化和静态检查

Hooks 可以理解为“绑定在 Claude 操作上的自动任务”，比如在每次修改代码后自动运行 Prettier 或类型检查。

这带来两个好处：

• 在问题刚出现时就被捕获，而不是堆到后期；
• 把“纠正 AI 格式/类型错误”的工作交给工具链，让人类专注业务逻辑。

从团队视角看，Hooks 是防止 AI 生成代码在质量上“滑坡”的关键一环。

3. 自定义 Slash 命令与 Headless 模式

• 自定义 Slash 命令：
  将高频任务固化在 .claude/commands 中，例如：

  • /review-pr：按团队规范审查 PR；
  • /debug-api：按照统一格式分析某个接口问题。

• Headless Mode（命令行模式，-p 参数）：
  在 CI/CD 或脚本中调用 Claude 完成 PR 审查、日志分析、自动生成变更说明等任务，无需手动打开界面。

可以搭建起“错误日志 → 更新 CLAUDE.md → 行为改进”的自反馈闭环，让系统随时间持续进化。

---

七、当 AI 卡死、乱回答时，怎么“救场”？

在实际使用中，你一定会遇到：模型在一个坑里反复打转，或者信誓旦旦地给出错误方案的情况。

1. 三振出局原则：不要无止境解释

如果你已经从多个角度解释了三次，Claude 仍然无法对齐你的意图或修正错误，那么继续解释通常只会让上下文更混乱。

这时的正确做法是：

• 停止在当前会话里“死磕”；
• 果断做上下文重置（/clear）；
• 用更简洁、更抽象的方式重新描述问题，甚至换一种比喻或模型（如有限状态机）。

2. 示样法：让模型“照着做”

大模型的模仿能力往往强于抽象理解。遇到理解障碍时，不妨：

• 自己写出一个最小可行示例（Minimal Example），哪怕只有几十行；
• 标明这是“示范模板”，要求“按这个模式扩展到其他场景”。

对于复杂状态机、权限矩阵、报表生成等问题，这种做法尤其有效。

3. 重置与重构视角

最后是两种常用“重启”手段：

• 彻底重置上下文：
  使用 /clear，并只注入最必要的上下文（如接口定义、关键业务规则），避免历史垃圾干扰新推理。
• 改变问题表述：
  比如从“如何处理一堆 if-else 状态”换成“如何设计一个有限状态机”，让模型有机会在新的抽象层面重新组织解法。

---

八、如何在团队内落地这套工作流？

从个人到团队，采用 Claude Code 的完整工作流，大致可以划分为三个阶段。

1. 个人层面：建立“思考优先”的习惯

• 每个任务先在 Plan Mode 花 5 分钟澄清意图；
• 主动维护自己项目的 CLAUDE.md，并将高频错误写进去；
• 对提示词和结果进行“事后复盘”，找出可以模板化的高效对话模式。

2. 小团队层面：对齐规范与工具链

• 将 CLAUDE.md 提升为“项目必需文件”，由 Tech Lead 维护结构，成员共同补充；
• 将 Hooks（格式化、类型检查、lint）纳入必跑流程；
• 约定模型使用策略：什么时候必须用 Opus，什么时候默认用 Sonnet。

3. 中大型团队：建设 AI 驱动的工程平台

• 逐步引入 MCP，把关键外部系统纳入统一上下文；
• 用 Headless 模式嵌入 CI/CD，构建自动化 PR 审查、变更总结、日志分析流程；
• 为团队整理最佳实践手册，包括提示模板、常见故障应对策略、成功范例等。

---

九、结语：真正决定产出质量的，是输入质量

高产出的 AI 开发不是运气，而是一套有纪律的系统性方法论。

当我们从“随手让 AI 写点东西试试”，走向“用 AI 作为严肃的工程基础设施”，就必须同时升级自己的思考方式、工具链设计和团队实践——而其中最根本的一条，是永远牢记：如果产出质量不佳，根源几乎总在于输入不够清晰、不够完整、不够专业。

只要养成思考优先、上下文可控、提示精确、持续回顾的工作习惯，Claude Code 不只是一款“写代码的工具”，而是一个可以和你一起成长的自动化工程搭档。