Claude Code on 方糖猫Blog

把 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 等工具的落地实践，欢迎关注和交流。

Claude Code 是怎么运行的？给新手的 AI 编程代理入门指南

Fri, 09 Jan 2026 10:00:00 +0800

Claude Code 是怎么运行的？给新手的 AI 编程代理入门指南

参考：shareAI-lab/learn-claude-code

你有没有想过，为什么你跟 Claude Code 说“帮我改一下这个网页”，它就能自己打开文件、修改代码、运行测试，然后告诉你结果？

它看起来好聪明，像人一样会“动手”。但其实，它背后的原理并不神秘，甚至可以用几十行简单的代码讲清楚。

这篇文章是给新手的。不管你有没有学过编程，我都会尽量用生活中的例子来解释。读完之后，你会明白：

Claude Code 最核心的部分是什么；
它是怎么“看懂”文件、“动手”改代码的；
它为什么能记住很多事情、做错事能重来；
以及如果你想自己做一个类似的 AI 助手，应该从哪里开始。

一、一句话讲清楚 Claude Code

如果把 Claude Code 拆开，你会发现它只有三个东西：

一个循环 + 一张工具表 + 一个会说话的 AI

部件	作用	生活里的比喻
会说话的 AI（大语言模型）	思考、理解你说的话、决定下一步做什么	一个超级聪明的大脑
工具表	让 AI 能读写文件、运行命令、搜索代码	给大脑装上双手和眼睛
循环	不断重复“思考 → 行动 → 看结果 → 再思考”	机器人一直干活，直到做完

这个“循环”非常重要。没有它，AI 就只能说一次话，没法连续做很多事。

flowchart LR
    subgraph 工具箱["🧰 工具箱（Harness）"]
        读文件["读文件"]
        写文件["写文件"]
        执行命令["执行命令"]
        搜索["搜索代码"]
        权限["权限检查"]
    end

    大脑["🧠 AI 大脑<br/>会思考、会推理"]
    电脑["💻 你的电脑"]

    大脑 -->|我想读文件| 读文件
    读文件 -->|文件内容| 大脑
    大脑 -->|我想运行测试| 执行命令
    执行命令 --> 电脑
    电脑 -->|测试结果| 大脑
    权限 -->|这个能做吗？| 执行命令

二、最核心的 30 行代码

Claude Code 的心脏，是一段很简单的代码。你可以把它理解成“机器人干活的主流程”：

def agent_loop(query):
    # 1. 先把用户的问题记下来
    messages = [{"role": "user", "content": query}]

    while True:
        # 2. 把对话历史发给 AI，告诉它有哪些工具可以用
        response = client.messages.create(
            model=MODEL,
            system=SYSTEM,
            messages=messages,
            tools=TOOLS,
            max_tokens=8000,
        )

        # 3. 把 AI 的回复存进历史
        messages.append({"role": "assistant", "content": response.content})

        # 4. 如果 AI 不再调用工具，就说明它说完了，结束循环
        if response.stop_reason != "tool_use":
            return

        # 5. 执行 AI 要求的工具，并把结果告诉它
        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = run_tool(block.name, block.input)
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })
        messages.append({"role": "user", "content": results})

人话解释

你问了一个问题 → 比如“帮我修一下这个 bug”。
AI 看历史和工具表 → 它想：“我需要先读一下代码文件。”
AI 说“我要用读文件工具” → 程序真的去打开文件。
把文件内容还给 AI → AI 再看，决定下一步。
一直重复，直到 AI 说“我搞定了”。

flowchart TD
    开始([你输入任务]) --> 发给AI[把任务+历史发给 AI]
    发给AI --> AI思考[AI 思考]
    AI思考 --> 判断{AI 想调用工具吗？}
    判断 -->|想| 执行工具[程序执行工具]
    判断 -->|不想| 输出答案[输出最终答案]
    执行工具 --> 返回结果[把结果返回给 AI]
    返回结果 --> 发给AI
    输出答案 --> 结束([结束])

三、20 节课都在讲什么？一张总图看懂

Claude Code 的学习资料里有 20 节课，每节课加一个新能力。它们不是乱排的，而是像打游戏升级一样，一步一步变强。

flowchart LR
    subgraph 第一阶段["🌱 第一阶段：让 AI 动起来"]
        s01["s01 循环"]
        s02["s02 工具"]
        s03["s03 权限"]
        s04["s04 钩子"]
    end

    subgraph 第二阶段["🛠️ 第二阶段：做复杂任务"]
        s05["s05 计划"]
        s06["s06 子代理"]
        s07["s07 技能"]
        s08["s08 压缩记忆"]
    end

    subgraph 第三阶段["🧠 第三阶段：记得住、错得了"]
        s09["s09 记忆"]
        s10["s10 系统提示"]
        s11["s11 错误恢复"]
    end

    subgraph 第四阶段["⏳ 第四阶段：长时间运行"]
        s12["s12 任务图"]
        s13["s13 后台任务"]
        s14["s14 定时任务"]
    end

    subgraph 第五阶段["👥 第五阶段：团队协作"]
        s15["s15 队友"]
        s16["s16 团队协议"]
        s17["s17 自治"]
        s18["s18 目录隔离"]
    end

    subgraph 第六阶段["🔌 第六阶段：扩展组装"]
        s19["s19 MCP 插件"]
        s20["s20 完整系统"]
    end

    第一阶段 --> 第二阶段 --> 第三阶段 --> 第四阶段 --> 第五阶段 --> 第六阶段

下面拆解核心部分。

四、第一阶段：让 AI 动起来

s01 Agent Loop：一个循环就够了

这是所有东西的基础。就像你骑自行车，核心是“踩踏板 → 车轮转 → 车前进”这个循环。Claude Code 的核心就是：

AI 思考 → 调用工具 → 看结果 → 再思考 → 再调用工具 → …… → 完成

没有循环，AI 只能说一句话。有了循环，它就能连续做很多步。

s02 Tool Use：从一把螺丝刀到整套工具箱

最早的 AI 只有一个工具：执行终端命令（bash）。但这样很不方便，就像你修自行车只能用一个螺丝刀。

后来 Claude Code 给 AI 配了一整套工具：

read_file：读文件
write_file：写文件
edit_file：改文件中的一部分
glob：按名字找文件
grep：在文件里搜索文字

这些工具是“分发表”管理的。程序不用写一堆 if/else，而是查一个字典：

TOOL_HANDLERS = {
    "read_file":  read_file_function,
    "write_file": write_file_function,
    "edit_file":  edit_file_function,
}

# AI 说想用 read_file，就找到对应的函数执行
handler = TOOL_HANDLERS["read_file"]
result = handler(path="main.py")

好处：加新工具就像往工具箱里多放一把扳手，不用改主流程。

s03 Permission：先问能不能做，再让它做

这是 Claude Code 很重要的一课：自由要有边界。

AI 能力很强，但它不能想删啥就删啥、想改啥就改啥。权限系统就像家长给孩子定规矩：

读文件可以；
修改重要文件要问一下；
删除整个文件夹？不行。

flowchart TD
    AI想做事[AI 想执行命令] --> 查权限{权限系统检查}
    查权限 -->|允许| 直接执行
    查权限 -->|需要确认| 问用户[弹窗问用户]
    查权限 -->|禁止| 拒绝[拒绝执行]
    问用户 -->|同意| 直接执行
    问用户 -->|不同意| 拒绝

这教会我们一个工程原则：先设边界，再给自由。

s04 Hooks：在循环边上挂“挂钩”

Hook 中文叫“钩子”。想象你在书包上挂很多小挂件：钥匙扣、饭卡、耳机。主书包不变，但你可以加东西。

Claude Code 的 Hook 系统也是这样：

工具执行前，可以检查一下（PreToolUse）；
工具执行后，可以记录日志（PostToolUse）；
会话开始/结束时，可以做初始化或清理。

flowchart LR
    AI决定[AI 决定调用工具] --> 前钩子["PreToolUse 钩子<br/>检查/拦截"]
    前钩子 --> 执行工具
    执行工具 --> 后钩子["PostToolUse 钩子<br/>记录/通知"]
    后钩子 --> 返回AI

核心思想：主循环不要改来改去，把扩展功能挂到钩子上。

五、第二阶段：做复杂任务

s05 TodoWrite：先做计划，再动手

如果你要写一篇大作文，你会先列提纲，对吧？Claude Code 也是这样。

做复杂任务前，AI 会先写一个待办清单（Todo）：

1. 读 README 了解项目      [待做]
2. 找到 bug 所在的文件     [进行中]
3. 修改代码                [待做]
4. 运行测试确认修好        [待做]

每完成一步，就更新状态。如果 AI 太久没更新，系统还会“唠叨”它：“喂，你忘了更新待办清单啦！”

这个机制让 AI 不容易“跑偏”。

s06 Subagent：雇一个小助手

有时候一个任务需要查很多东西。比如“这个项目的测试框架是什么？”AI 可能要读 10 个文件才能确定答案是 pytest。

如果让主 AI 自己读 10 个文件，它的“脑子”会塞满东西，又慢又贵。

解决办法是：雇一个临时小助手（子代理）。小助手用全新的对话去读那 10 个文件，最后只把答案“pytest”告诉主 AI。

flowchart LR
    主AI["主 AI"] -->|派任务| 子AI["子 AI<br/>新开一个对话"]
    子AI -->|读10个文件| 文件["项目文件"]
    文件 -->|内容| 子AI
    子AI -->|只返回结论：pytest| 主AI

主 AI 的脑子很干净，只记住了最重要的结论。

s07 Skill Loading：需要哪本字典，就翻哪本

想象你要学数学、物理、化学三科。你不会每次上课都把三本书全背上，而是上什么课带什么书。

Claude Code 也是这样。它有很多“技能书”（比如 git 用法、测试规范、API 文档），但不会一次性全塞给 AI。

它是两层加载：

先给目录：告诉 AI 有哪些技能书；
需要时再翻开：AI 说“我要查 git 那本书”，系统才把完整内容给它。

这样就省了很多“脑容量”。

s08 Context Compact：脑子塞不下时怎么办？

AI 一次能看的文字是有限的，就像你的作业本只有那么多页。如果写得太多，就要翻页或者撕掉旧的。

Claude Code 有三种“翻页”方法：

micro_compact：把很久以前的工具结果换成一句话摘要，比如“之前用过 read_file”；
auto_compact：当文字太多时，自动让 AI 写个总结，用总结替换原来的长对话；
compact 工具：AI 自己决定什么时候该“翻页”。

flowchart TD
    subgraph 第一层["第一层：micro_compact"]
        旧结果["旧工具结果"] --> 占位符["换成占位符<br/>[之前读过 main.py]"]
    end

    subgraph 第二层["第二层：auto_compact"]
        太多文字["对话太长"] --> 写总结["AI 写摘要"] --> 替换历史["用摘要替换历史"]
    end

    subgraph 第三层["第三层：compact 工具"]
        AI判断["AI 觉得该压缩了"] --> 手动触发["调用 compact 工具"]
    end

    第一层 --> 第二层 --> 第三层

六、第三阶段：记得住、错得了

s09 Memory：AI 也要记笔记

AI 没有真正的记忆。每次对话结束，它就忘了。如果想让它长期记住东西（比如你喜欢什么代码风格、项目有什么规矩），就需要一个“记忆系统”。

记忆系统通常分三步：

选择：哪些东西值得记住？
提取：把重要信息摘出来；
固化：存到文件或数据库里，下次对话再读出来。

flowchart LR
    对话["一段对话"] --> 选择["选择重要信息"]
    选择 --> 提取["提取关键事实"]
    提取 --> 存储["存到记忆文件"]
    存储 --> 下次对话["下次启动时读取"]

比如 AI 记住了：“这个用户喜欢用 2 个空格缩进。”下次写代码时它就会自动用 2 个空格。

s10 System Prompt：提示词不是写死的

System Prompt 就是告诉 AI“你是谁、该怎么做事”的那段话。

Claude Code 的 System Prompt 不是一次性写死的，而是运行时拼接的：

基础身份部分；
当前项目规则；
加载的技能书；
用户的偏好记忆。

就像你写作文时，老师给的题目要求 + 你自己的提纲 + 参考资料，组合在一起。

s11 Error Recovery：做错事能重来

AI 也会犯错。比如它调用了一个不存在的文件，或者写的代码运行报错。这时候怎么办？

Claude Code 有几种“重来”策略：

重试：可能是网络抖动，再试一次就好了；
换条路：这个方法不行，换另一个工具试试；
清理空间：上下文太满导致看不清，先压缩一下再试；
换个小模型/大模型：简单任务用小模型省钱，复杂任务换大模型。

flowchart TD
    出错[工具执行出错] --> 重试{重试有用吗？}
    重试 -->|有用| 再试一次
    重试 -->|没用| 换方法[换工具/换思路]
    换方法 -->|还不行| 清空间[压缩上下文]
    清空间 -->|再试| 再试一次

重要道理：错误不是终点，而是调整的起点。

七、第四阶段：长时间运行

s12 Task System：把大目标拆成小任务

复杂项目不能靠一个简单的 Todo 清单。任务之间有依赖关系：

A 做完了，B 才能开始；
C 和 D 可以同时进行；
E 要等 C 和 D 都做完。

Claude Code 用任务图来管理。每个任务存成一个文件，记录自己的状态、依赖谁、被谁依赖。

flowchart LR
    A["设计登录页面"] --> B["写前端代码"]
    A --> C["写后端接口"]
    B --> D["联调测试"]
    C --> D

s13 Background Tasks：慢活放后台

有些命令要跑很久，比如 npm install 可能要几分钟。如果 AI 停下来等，就太浪费了。

Claude Code 会开一个新的后台线程去跑这些慢命令，主 AI 继续思考别的事。等后台跑完了，再通知 AI。

s14 Cron Scheduler：定时任务

Cron 就是“定时器”。比如你可以让 AI 每天早上 8 点检查一遍代码仓库，看看有没有需要更新的依赖。

“到点了就干活，不用人喊。”

flowchart LR
    时间到[时间到了] --> Cron[Cron 触发器]
    Cron --> 任务[执行预设任务]
    任务 --> 结果[把结果发给 AI]

八、第五阶段：团队协作

s15 Agent Teams：多个 AI 一起干活

一个 AI 干不完的大项目，可以叫一群 AI 一起干。每个 AI 有自己的身份和“收件箱”（mailbox）。

它们通过 JSONL 文件收发消息：

{"from": "leader", "to": "alice", "content": "你去写登录页面"}
{"from": "alice", "to": "leader", "content": "我做好了"}

每行一条消息，追加写入，像写日记一样简单。

s16 Team Protocols：队友之间要讲规矩

多人协作不能乱说话。Claude Code 的团队协议规定：

每个重要请求都要带一个 request_id（像快递单号）；
回复时要引用同一个 request_id；
请求状态是 pending（等待中）、approved（同意）或 rejected（拒绝）。

这样就不会搞混谁同意了什么。

s17 Autonomous Agents：AI 自己会找活干

更高级的团队里，AI 不需要等领导分配任务。它会自己去看任务板，认领还没人做的、并且前置条件满足的任务。

如果 60 秒没活干，它就自动“下班关机”。

s18 Worktree Isolation：各干各的，不打架

两个 AI 同时改同一个文件，会互相覆盖。Claude Code 用 git worktree 给每个任务一个独立目录和独立分支：

任务 A → 目录 auth-refactor/ → 分支 wt/auth-refactor
任务 B → 目录 ui-login/     → 分支 wt/ui-login

大家互不干扰，最后再把代码合并。

九、第六阶段：扩展组装

s19 MCP Plugin：不够用时，插更多工具

MCP 是“模型上下文协议”。你可以把它理解成“USB 接口”：

Claude Code 本身带了一些工具；
如果你需要连数据库、查浏览器、操作 Slack，可以通过 MCP 插进来；
这些外部工具和自带工具一样，AI 都能调用。

flowchart LR
    Claude["Claude Code"] --> MCP["MCP 接口"]
    MCP --> 数据库["数据库工具"]
    MCP --> 浏览器["浏览器工具"]
    MCP --> Slack["Slack 工具"]
    数据库 -->|结果| Claude
    浏览器 -->|结果| Claude
    Slack -->|结果| Claude

s20 Comprehensive Agent：把所有东西拼起来

最后一节课，就是把前面 19 节课的所有机制都装进同一个循环里：

一个循环 + 工具 + 权限 + 钩子 + 计划 + 子代理 + 技能 + 记忆 + 压缩 + 任务图 + 后台任务 + Cron + 团队 + 自治 + Worktree + MCP = 完整的 Claude Code

听起来很多，但你已经一个个看过了。它们都是围绕最初那个简单循环加上的“配件”。

十、给新手的 5 个开发小技巧

这些技巧来自 Claude Code 的源码，平时写程序也能用到。

1. 用“查表”代替一堆 if/else

# 不推荐
if name == "read": read_file()
elif name == "write": write_file()

# 推荐
HANDLERS = {"read": read_file, "write": write_file}
HANDLERS[name]()

加新功能只要加一行。

2. 修改列表要小心

如果你想在一个函数里修改外面的列表，要用切片赋值：

messages[:] = new_list  # 正确：改原来的列表
# messages = new_list   # 错误：只是让局部变量指向新列表

3. 用 `**kwargs` 接受任意参数

def handler(**kw):
    print(kw["path"])

handler(path="main.py", limit=10)

(**kw) 表示“不管什么参数名，都装进字典 kw 里”。

4. 守护线程做后台任务

import threading

t = threading.Thread(target=download_file, daemon=True)
t.start()

主程序退出时，守护线程会自动结束，不会卡住。

5. JSONL 比 JSON 更适合追加写入

# 写：每行一条
with open("inbox.jsonl", "a") as f:
    f.write(json.dumps(msg) + "\n")

# 读：逐行解析
for line in open("inbox.jsonl"):
    msg = json.loads(line)

追加写入很安全，不会因为同时写入而损坏文件。

十一、总结

Claude Code 看起来很厉害，但它的核心其实非常朴素：

一个 while 循环 + 一张工具表 + 一个会说话的 AI。

真正让它变强的，是围绕这个循环一层层加上的“配件”：权限、计划、子代理、技能、记忆、压缩、任务图、后台任务、团队、自治、目录隔离、MCP……

这些配件都是为了解决一个核心问题：

怎么让一个只会说话的 AI，真正能在现实世界里连续、安全、高效地干活。

理解了这个骨架之后，你再回头看 Claude Code，就不会觉得它是黑魔法了。它就是一个被精心设计的“机器人工作台”，而我们看到的聪明，来自那个会思考的大脑，加上一套会执行的 harness。

大脑负责想，工作台负责做。把工作台造好，大脑就能发挥全部实力。

本文是学习 shareAI-lab/learn-claude-code 的笔记整理。如果你想动手，可以从 s01_agent_loop/code.py 开始，一课一课跟着做。

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 卡住时，换策略

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

十、写给老工程师的话

总结

Claude Code 是怎么运行的？给新手的 AI 编程代理入门指南

Claude Code 是怎么运行的？给新手的 AI 编程代理入门指南

一、一句话讲清楚 Claude Code

二、最核心的 30 行代码

人话解释

三、20 节课都在讲什么？一张总图看懂

四、第一阶段：让 AI 动起来

s01 Agent Loop：一个循环就够了

s02 Tool Use：从一把螺丝刀到整套工具箱

s03 Permission：先问能不能做，再让它做

s04 Hooks：在循环边上挂“挂钩”

五、第二阶段：做复杂任务

s05 TodoWrite：先做计划，再动手

s06 Subagent：雇一个小助手

s07 Skill Loading：需要哪本字典，就翻哪本

s08 Context Compact：脑子塞不下时怎么办？

六、第三阶段：记得住、错得了

s09 Memory：AI 也要记笔记

s10 System Prompt：提示词不是写死的

s11 Error Recovery：做错事能重来

七、第四阶段：长时间运行

s12 Task System：把大目标拆成小任务

s13 Background Tasks：慢活放后台

s14 Cron Scheduler：定时任务

八、第五阶段：团队协作

s15 Agent Teams：多个 AI 一起干活

s16 Team Protocols：队友之间要讲规矩

s17 Autonomous Agents：AI 自己会找活干

s18 Worktree Isolation：各干各的，不打架

九、第六阶段：扩展组装

s19 MCP Plugin：不够用时，插更多工具

s20 Comprehensive Agent：把所有东西拼起来

十、给新手的 5 个开发小技巧

1. 用“查表”代替一堆 if/else

2. 修改列表要小心

3. 用 **kwargs 接受任意参数

4. 守护线程做后台任务

5. JSONL 比 JSON 更适合追加写入

十一、总结

3. 用 `**kwargs` 接受任意参数