把 Claude Code 用成工程杠杆：落地心得

Sat, 10 Jan 2026 15:00:00 +0800

把 Claude Code 用成工程杠杆：落地心得

我做软件工程 18 年了，在华为和 IBM 做过电信级系统，近四年又一头扎进 AI 工程化，主导过 AI Agent 短视频生成平台和自动化口播剪辑平台。Claude Code 是我最近半年每天都在用的主力工具。它不是替代工程师的魔法，而是一把需要正确握持的杠杆。这篇文章聊聊我怎么把它落地到工程工作流里。

一、先思考，再输入

很多人打开 Claude Code 的第一件事就是开始打字。这往往是最贵的错误。

我现在的习惯是：

写功能前，先想清楚模块边界、数据流、异常路径；
重构前，先定义"目标形态"是什么；
调试前，先列出我已知的事实和假设。

然后按 Shift+Tab 两次进入 Plan 模式，把这些思考丢给 Claude。

Plan 模式不是让 Claude 替我想，而是让它在我已经梳理好的框架里填充细节、发现盲点、提出反例。输入越清晰，输出越可用。这个道理听起来简单，但真正做到的人不多。

如果你觉得自己还不具备独立想架构的能力，我的建议是：先从描述问题开始，和 Claude 反复对话，让它帮你把模糊的想法磨成可执行的方案。对话是双向的，不是单向许愿。

二、架构描述决定代码质量

“给我做一个认证系统” 和 “基于现有 User 模型实现邮箱密码登录，会话存 Redis 24 小时过期，给 /api/protected 加中间件”，得到的结果天差地别。

AI 生成代码的问题，往往不在于模型不够聪明，而在于你给的目标太宽泛。自由度太大，模型就会按照它自己的理解去填补，而这些填补常常和你的工程习惯、团队规范、历史包袱不一致。

我在方糖猫的项目里深有体会。AI Agent 的渲染流水线涉及 Java API 服务、Python Worker、RocketMQ、Remotion 渲染、FFmpeg 后处理多个环节。如果我只说"帮我实现一个视频生成任务调度"，Claude 可能会写出一个看起来合理但完全不符合我们现有架构的方案。但如果我把状态机、消息格式、失败重试策略、SSE 进度推送方式都描述清楚，它就能写出可以直接接入系统的代码。

好的 Prompt 不是文学，是需求文档的浓缩版。

三、CLAUDE.md：给 AI 的入职培训

CLAUDE.md 是 Claude Code 会话启动时自动读取的文件。它的作用很像新员工入职手册，但比那更关键：因为它决定了 Claude 在你项目里的"默认行为"。

我花了点时间打磨自己的 CLAUDE.md，几条原则：

1. 保持简短

Claude 能稳定遵循的指令数量有限，系统提示已经占了一部分。写太多，它只会随机忽略。我的 CLAUDE.md 一般不超过两屏。

2. 只写项目特有信息

不要解释"组件目录是什么"这种通用知识。要写真正影响决策的东西：关键 bash 命令、构建脚本、测试命令、提交规范、技术约束。

3. 写"为什么"，不只是"做什么"

比如：

差：“使用 Java 17”。
好：“使用 Java 17，因为部分依赖在 Java 21 下存在兼容性问题，计划在 Q4 统一升级。”

原因能让 Claude 在你没想到的地方做出正确判断。

4. 持续更新

工作时长按 # 键，Claude 会自动把指令写进 CLAUDE.md。我的标准是：当我第二次纠正同一个问题时，就把它固化为规则。

坏的 CLAUDE.md 像写给新人的文档；好的 CLAUDE.md 像写给"未来失忆的自己"的笔记。

四、上下文窗口不是越用越好

Opus 4.5 的上下文窗口很长，但很多人忽略了一个事实：上下文用到 20%–40% 时，输出质量就开始下降了。

每次消息、每个文件、每段生成代码、每次工具输出都会累积。等会话变得臃肿，即使 /compact 也救不回来，因为能力已经劣化了。

我的做法：

每个任务一个会话：不要在同一会话里既改认证系统又重构数据库。
用外部记忆文件：比如 SCRATCHPAD.md 或 plan.md，把中间结论落地到文件系统。
复制-压缩-清空-粘贴法：重要信息复制出来，/compact 总结，再 /clear，只粘回关键内容。
知道何时清空：会话一旦混乱，直接 /clear。CLAUDE.md 还在，项目规则不会丢。

正确的心智模型是：把 Claude 当成无状态的。状态应该由文件系统、版本控制、外部记忆来维护，而不是由会话历史来维护。

五、提示词是沟通，不是咒语

我反复说的一句话是：提示词不是玄学，是沟通。清晰永远优于模糊。

有效的提示通常包含三层：

要做什么：明确任务目标；
不要做什么：Claude 喜欢过度工程化，必须明确限制；
约束和原因：是原型还是生产代码？性能敏感还是可读性优先？为什么？

比如我会这样写：

请为 VideoRenderWorker 添加一个重试机制。要求：

最多重试 3 次，使用指数退避；

只对临时性错误重试，业务逻辑错误直接失败；

不要引入新的依赖，使用现有的 Spring Retry 配置；

这是生产代码，需要单元测试覆盖。

这样的输入，输出基本可以直接进入 Code Review。

另外记住：输出只来自输入。如果你用好模型仍然得到坏结果，问题通常在你——你的提示写法、请求结构、上下文提供方式。

六、模型路由：让合适的模型做合适的事

Claude 的不同模型有明确的分工：

Sonnet：更快更便宜，适合执行明确的编码任务；
Opus：更慢更贵，适合复杂规划、架构设计、深度推理。

我的常用模式是：

用 Opus 做架构规划和复杂方案设计；
用 Sonnet 执行实现、补全代码、跑测试；
用 CLAUDE.md 保证模型切换后仍然遵循相同的项目规则。

这和团队里让资深架构师画蓝图、让工程师写代码是一个道理。Claude Code 里切换模型成本很低，但前提是你知道什么任务该用什么模型。

七、MCP、Hooks、Slash 命令与 Skills

Claude Code 的工具生态值得花时间探索。除了前面提到的 MCP 和 Hooks，Skills（技能） 是我最近用得越来越多的能力，它把常用工作流封装成可复用的指令包。

1. MCP、Hooks 和 Slash 命令

MCP：连接外部服务。如果你还在手动复制粘贴信息进 Claude，很可能 MCP 能帮你自动化。
Hooks：在 Claude 修改代码前后执行操作，比如自动格式化、类型检查、跑 lint。
自定义 Slash 命令：把常用的提示词模板化，避免每次重复输入。

我在项目里配了几个常用 Slash 命令：

/review：让 Claude 按项目规范做 Code Review；
/test：为当前修改生成单元测试；
/doc：为新增接口补全文档。

2. Skills：把个人经验变成团队能力

Skill 是什么？

Skill 是一个 Markdown 文件（通常是 SKILL.md），带有 YAML frontmatter。它描述了一个完整的工作流、判断标准或领域知识。Claude 会在合适的时机自动加载它，或者你可以通过 /skill <name> 手动调用。

你可以把 Skill 理解为"可插拔的专长"：

CLAUDE.md 是项目通用的"入职培训"，始终加载；
SKILL.md 是按需加载的"专项手册"，只在匹配的场景触发。

Skill 放在哪里？

有两种常见位置：

个人级：~/.claude/skills/<skill-name>/SKILL.md，跨项目可用；
项目级：.claude/skills/<skill-name>/SKILL.md，跟随仓库走，团队成员共享。

我推荐项目级 Skill，因为团队规范应该和代码放在一起，而不是依赖每个人的本地配置。

一个最小 SKILL.md 示例：

---
name: spring-api-review
description: 当用户请求对 Spring Boot API 代码进行 Review 时调用此 skill。
---

# Spring Boot API Review 规范

## 检查项

1. 控制器是否只做参数校验和调用服务层？
2. 服务层是否处理业务逻辑，而不是直接操作 HTTP 上下文？
3. DTO 是否有清晰的入参/出参边界？
4. 异常是否统一处理，而不是在每个方法里 try-catch？
5. 是否有对应的单元测试覆盖核心分支？

## 输出格式

对每个问题，按以下结构输出：

- 位置：文件路径 + 行号
- 问题描述
- 风险等级：高 / 中 / 低
- 建议修改

description 字段非常关键。Claude 会根据它判断何时自动加载这个 Skill。描述越具体，触发越准确。

3. 有哪些值得尝试的 Skill？

Claude Code 本身不内置大量固定 Skill，但社区已经沉淀了不少高质量 Skill 包。以下是我觉得对工程团队最有价值的几个方向：

Skill / Skill 包	用途
gstack	比较完整的一套工程 Skill 集合，覆盖 review、qa、investigate、ship、canary、retro 等
`/review`	预着陆 PR 审查，检查 SQL 注入、LLM 信任边界、副作用等结构性问题
`/qa`	系统化 QA 测试，发现 bug 后自动修复并验证
`/investigate`	系统性根因排查，要求"无根因不修复"
`/ship`	合并主分支、跑测试、生成 PR 的发布工作流
`/canary`	部署后监控异常、性能回归、页面失败
`/retro`	基于提交历史做工程复盘
heliohq/ship	更严格的分阶段流水线：spec → dev → E2E → review → QA → refactor → handoff
Cavestack	强调"Hero Six"核心 Skill，包括 office-hours、investigate、plan-eng-review 等

我个人用得比较多的是 /review、/investigate 和 /ship。它们不是替代人的判断，而是把重复性的检查清单和流程自动化，让我把精力放在真正需要决策的地方。

4. 怎么创建自己的 Skill？

创建 Skill 的步骤很简单：

新建目录：
```
mkdir -p .claude/skills/my-skill
```
写 SKILL.md：包含 name、description、用途、步骤、输出格式、示例和约束。
测试触发：开一个新会话，描述一个匹配的场景，看 Claude 是否自动加载。如果没加载，调整 description 让它更具体。
迭代优化：使用一段时间后，把新发现的问题和约束补充进去。和 CLAUDE.md 一样，Skill 也是需要持续维护的。

我的建议是：不要一开始就写很多 Skill。先观察团队里哪些工作流是重复的、哪些判断标准是大家口头传颂的，把最常见的两三个固化成 Skill。质量比数量重要。

5. Skill、CLAUDE.md、Hooks 的分工

能力	作用	触发方式
CLAUDE.md	项目通用规则，始终加载	每次会话启动
SKILL.md	专项工作流，按需加载	匹配描述时自动加载，或 `/skill` 手动调用
Hooks	代码修改前后的强制检查	触发编辑操作时
MCP	连接外部系统的能力	需要外部数据或操作时

这几层叠加起来，才能把 Claude Code 从一个"聊天工具"变成符合团队工程规范的"协作系统"。

这些小投入会不断复利。模型每周都在变好，但你的工具链、Skill 库和流程才是属于自己的护城河。

八、当 Claude 卡住时，换策略

Claude 有时会陷入循环：改了 A 导致 B 错，改了 B 又导致 A 错。这时候继续补充说明往往没用。

我常用的策略：

清空会话：从头开始，减少污染；
拆分任务：把大问题拆成几个独立的小问题；
给示例而不是解释：“参考 UserService.java 里的错误处理模式” 比 “请优雅地处理异常” 有效得多；
换种表述方式：同一个需求用不同结构说一遍，有时能绕过模型的固化模式。

关键技能不是让 Claude 永远不出错，而是尽早识别循环，并及时切换策略。

九、构建系统，而不是一次性工具

Claude Code 最大的价值，不在于帮你完成单次任务，而在于把它嵌入工程系统。

它支持 headless 模式（-p），可以脚本化、自动化、串联命令。企业已经在用它做：

自动审 PR；
处理支持请求；
更新文档；
批量重构；
生成测试用例。

我们的飞轮是：

Claude 出错 → 改进 CLAUDE.md 或工具链 → 下次更好。

几个月后，即使模型没变，整个系统也会显著提升。这就是复利。

如果你只把 Claude Code 当成一个交互式聊天工具，你正在浪费它的大部分价值。

十、写给老工程师的话

用了 Claude Code 一段时间后，我发现一个有意思的现象：

经验丰富的工程师反而更容易用好它。

因为你知道什么是好的架构，什么是坏的妥协，什么是可以自动化的重复劳动，什么是必须人工把关的关键决策。Claude Code 不会替你承担责任，但它能把你的判断力和工程经验放大很多倍。

对我来说，它最大的帮助不是写代码更快，而是：

把重复性工作交给它，我腾出时间思考架构；
用它快速验证想法，减少原型阶段的沉没成本；
通过 CLAUDE.md 和工具链，把个人经验沉淀为团队能力。

总结

把 Claude Code 用好，核心就几句话：

先思考，再输入；
架构描述决定代码质量；
CLAUDE.md 是杠杆点；
上下文在用到 30% 时就开始劣化；
提示词是沟通，输出来自输入；
让 Opus 规划，让 Sonnet 执行；
善用 MCP、Hooks、Slash 命令，更要善用 Skills；
卡住时换策略；
构建系统，而不是只做一次性任务。

现代 AI 工具已经强得离谱。你是在和工具对抗，还是顺势而行，往往取决于这些细节。

我在 ftmao.com/blog 持续记录 AI 工程、Agent 设计与 Claude Code 等工具的落地实践，欢迎关注和交流。

开发工具 on 方糖猫Blog

把 Claude Code 用成工程杠杆：落地心得

把 Claude Code 用成工程杠杆：落地心得

一、先思考，再输入

二、架构描述决定代码质量

三、CLAUDE.md：给 AI 的入职培训

1. 保持简短

2. 只写项目特有信息

3. 写"为什么"，不只是"做什么"

4. 持续更新

四、上下文窗口不是越用越好

五、提示词是沟通，不是咒语

六、模型路由：让合适的模型做合适的事

七、MCP、Hooks、Slash 命令与 Skills

1. MCP、Hooks 和 Slash 命令

2. Skills：把个人经验变成团队能力

3. 有哪些值得尝试的 Skill？

4. 怎么创建自己的 Skill？

5. Skill、CLAUDE.md、Hooks 的分工

八、当 Claude 卡住时，换策略

九、构建系统，而不是一次性工具

十、写给老工程师的话

总结