反思与进阶：AI Agent 时代的开发者

「Claude Code 按你的要求实现了一个功能，测试也绿了。PR review 时，另一个人问：为什么状态放在 middleware，而没有放在 service 层？你忽然发现，代码是 Agent 写的，架构理由却必须由你承担。」

前面 15 章讲了安装、代理循环、Plan Mode、CLAUDE.md、Hooks、Skills、SubAgents、MCP、提示工程、完整工作流和局限性。本章处理最后一个问题：当 Agent 能读仓库、改文件、跑命令、发起验证后，开发者应训练什么能力。

官方文档把 Claude Code 定位为 agentic coding 工具，能读取代码库、编辑文件、运行命令，并接入开发工具。这个事实改变了工作分工，也暴露了一个更硬的问题：如果你说不清目标、边界和验收，Agent 会把不清楚的意图放大成不清楚的改动。

本章不给“未来开发者画像”。那类说法太容易空转。我们只看可观察变量：任务如何被定义，上下文如何被选择，风险如何被约束，输出如何被验证，经验如何沉淀。

参考来源：

Claude Code overview：https://code.claude.com/docs/en/overview
Claude Code memory：https://code.claude.com/docs/en/memory
Claude Code subagents：https://code.claude.com/docs/en/sub-agents
Claude Code hooks：https://code.claude.com/docs/en/hooks-guide

角色变化从一次任务开始

先看一个普通任务：

给后台管理页增加批量禁用用户功能。需要权限校验、操作确认、审计日志、单元测试。不要影响现有单个用户禁用流程。

Claude Code 可以做很多事：搜索相关文件，写计划，修改组件和接口，补测试，运行构建，生成提交信息。开发者看起来少写了很多代码。

但真正决定结果质量的，是下面五个变量。

变量	你要负责什么	失控时的症状
目标	说清用户要完成的动作和系统结果	功能做了，但业务路径不对
上下文	指定关键文件、约束、历史决策	Agent 读了一堆无关文件，遗漏真正入口
边界	说明不能动的模块、权限、数据	diff 扩散，重构变成改写
验收	给出测试、构建、截图、审查标准	看起来完成，实际无法上线
反馈	用 review、日志、失败用例修正方向	同一个错误重复出现

这就是角色变化的具体形态：少做键盘层面的重复操作，多做任务结构、证据和风险的判断。

一个闭合判断：事实、逻辑、经验

使用 Agent 时，最危险的输出往往很顺滑。它语气稳定，代码成片，解释完整。顺滑不等于正确。

每次接受 Agent 产出前，做三项判断。

判断	检查问题	可观察证据
事实是否存在	这个 API、命令、文件、约束真的存在吗	官方文档、本地文件、命令输出
逻辑是否闭合	从问题到方案，中间是否有跳步	计划、调用链、数据流、失败路径
经验能否证伪	这个结论能被什么操作推翻	测试、构建、截图、日志、review

例子：

Agent 说“这个接口没有鉴权风险，因为前端按钮只有管理员可见”。

三项检查会直接暴露问题。

检查	结论
事实	前端按钮可见性不等于后端权限
逻辑	用户仍可直接请求接口
经验	用非管理员 token 调接口即可验证

因此下一条提示应具体到验证：

检查批量禁用用户接口的服务端权限校验。用非管理员身份设计一个失败测试，先证明风险存在，再修复。

新能力一：需求分解

Agent 擅长沿着明确路径执行。模糊需求会让它发明路径。

需求分解的目标，是把一句话拆成对象、动作、规则、异常、验收。

原始需求	拆解后
做一个导出功能	导出什么对象，谁能导出，字段有哪些，数量上限是多少，失败后如何提示
优化登录体验	哪个步骤慢，目标耗时是多少，是否影响安全校验，如何测量
重构订单模块	行为保持不变，先列调用方，先补测试，再分批迁移

可直接使用这个提示：

把这个需求拆成对象、动作、业务规则、异常路径、验收标准。
不要写实现方案。先指出需求中仍不明确的地方。

需求：<粘贴需求>

如果 Agent 连问题都问不出来，说明上下文不足。补充业务规则，再进入 Plan Mode。

新能力二：上下文管理

Claude Code 的上下文窗口有限。官方 memory 文档说明，CLAUDE.md 和自动记忆会作为上下文加载，具体指令越具体、越简洁，遵守概率越高。它们属于上下文，无法像配置项那样强制执行。

因此，上下文管理要解决两个问题：

让 Agent 看到关键事实。
避免无关材料淹没关键事实。

信息类型	放哪里	原因
长期稳定约定	`CLAUDE.md`	每次会话都需要
本次任务背景	当前提示	只对当前任务有用
大量日志和搜索结果	子代理	主会话只保留结论
固定校验动作	Hooks	到点执行，不靠模型记忆
可复用流程	Skills	按需加载，避免根文件过长

一次真实改动可以这样组织：

阅读 @src/content/docs/claude-code/reflection.md 和 @CLAUDE.md。
目标：把文章改成机制清晰、可执行、带失败模式的教程。
边界：不要改其它章节。
验收：运行 pnpm build，检查是否有破折号、省略号、括号说明。

这个提示给了目标、材料、边界和验收。Agent 能自我收束。

新能力三：验证判断

Agent 能跑测试，但测试范围由你决定。Agent 能解释 diff，但风险权重由你判断。

验证判断至少分三层。

层级	目标	示例
语法层	能否构建、类型是否通过	`pnpm build`、`pnpm check`
行为层	用户路径是否符合预期	单测、集成测试、截图对比
系统层	是否引入长期风险	权限、性能、维护成本、团队约定

一个常见误区是只看语法层。构建通过只能说明代码能被构建，不能说明需求正确。

更好的审查提示：

审查最近改动。按语法层、行为层、系统层列出风险。
每条风险必须给出文件路径、证据和可验证的下一步。
不要修改文件。

当 Agent 给出风险后，再决定是否让它修。审查和修改分开，可以减少自证正确的偏差。

新能力四：工作流设计

成熟的 Agentic Coding 工作流，核心是把可重复判断外置。

组件	适合承载什么	不适合承载什么
`CLAUDE.md`	项目目标、命令、写作标准、硬约束	每次任务的细节
Hooks	格式化、测试、审计、敏感操作拦截	需要大量语义判断的开放问题
Skills	代码审查、文档写作、迁移流程	项目中永远不会复用的一次性提示
SubAgents	大量搜索、日志分析、独立审查	必须持续共享全部上下文的主线任务
MCP	外部系统数据和工具连接	本地源码中已经能读到的信息

官方 hooks 文档把命令式 hook、prompt hook、agent hook 分开。关键区别很简单：固定规则优先用命令式 hook，需要读文件和跑命令时才考虑 agent hook。

一个可落地的个人工作流：

CLAUDE.md 写项目命令、文档标准、禁止项。
review Skill 固化审查模板。
只读 SubAgent 负责大范围搜索和二次审查。
Stop Hook 在任务结束前检查是否运行了指定命令。
每月删除不再有效的规则。

这里的重点是可维护性。规则越多，冲突越多。让少量规则稳定执行，比堆满规则更可靠。

五个训练任务

下面的练习不追求一次做大项目。目标是训练可迁移能力。

任务一：用费曼方式解释一个模块

阅读 src/auth 相关代码。
用高中生能听懂的语言解释登录、刷新、登出三条路径。
每条路径都列出入口文件、关键状态、失败分支。
不要修改文件。

验收标准：你能不看原文复述，并能指出一个真实文件路径。

任务二：用苏格拉底方式拆一个需求

对下面需求提出 8 个澄清问题。
每个问题说明它会影响哪个实现决策。
不要写方案。

需求：<粘贴需求>

验收标准：问题能改变实现路径，不能只是补充描述。

任务三：用西蒙方式做一次渐进实现

把这个功能拆成 3 个最小可交付组块。
每个组块给出输入、输出、验证命令、失败回滚方式。
等我批准后再实现第一组块。

验收标准：每个组块都能单独验证，失败时不会拖垮全局。

任务四：建立双会话审查

会话 A 写代码：

按计划实现用户批量禁用功能，并运行相关测试。

会话 B 审代码：

只读审查这次改动。重点看权限绕过、审计日志遗漏、测试空洞。
输出问题清单，不要修改文件。

验收标准：会话 B 至少能指出一个可验证风险，或明确说明未发现风险和剩余测试空洞。

任务五：把经验沉淀进配置

复盘本次任务中我纠正过你的地方。
判断哪些适合写入 CLAUDE.md，哪些适合做 Hook，哪些只应留在本次会话。
先给分类理由，不要直接改文件。

验收标准：沉淀的是稳定规则，临时事实不进入长期记忆。

失败模式

失败模式	表现	下一步检查
把 Agent 当自动执行器	一句话下发大任务，直接接受大 diff	先要求计划和文件清单
把提示当魔法咒语	收藏大量模板，但不定义验收	给每条提示加可验证完成标准
把上下文塞满	提供一堆文档，关键约束反而丢失	删除无关材料，只保留决策事实
把审查交给同一轮上下文	Agent 倾向解释自己刚写的代码	新会话或只读子代理审查
把 `CLAUDE.md` 写成百科	每次会话加载大量低频信息	控制长度，低频内容改用链接或 Skill
把 Hooks 写成语义判断机器	固定流程中塞入不稳定自然语言判断	固定动作交给命令，语义审查交给人工或子代理

决策边界

Agent 更适合处理：

入口清楚、验收清楚的功能。
大范围搜索、机械迁移、测试补齐。
有明确命令可验证的任务。
可由子代理隔离的研究和审查。

人必须主导：

需求取舍。
架构边界。
安全和权限决策。
上线风险判断。
团队协作规则。

若一个决策失败后会造成数据、资金、权限、合规风险，Agent 可以辅助查证和生成方案，最终判断必须落在人身上。

个人进阶路径

用 30 天建立一个小循环。

周期	动作	产物
第 1 周	每天让 Claude Code 解释一个真实模块	模块路径、调用链、失败分支
第 2 周	每个需求先拆问题和验收	需求清单、测试标准
第 3 周	所有改动都做双会话审查	风险清单、修复记录
第 4 周	把高频纠正沉淀到配置	精简后的 `CLAUDE.md`、一个 Skill、一个 Hook

每周只问三个问题：

哪个错误重复出现。
哪个规则可以外置。
哪个验证仍然依赖肉眼猜测。

答案会告诉你下一次该改提示、改文档、加测试，还是加自动化。

最后检查清单

结束一个 Agentic Coding 任务前，过一遍这张表。

需求是否被拆成对象、动作、规则、异常、验收。
关键事实是否来自本地文件、官方文档或可复现命令。
计划是否说明要改哪些文件和不改哪些文件。
验证是否覆盖语法层、行为层、系统层。
审查是否和实现分离。
高频纠正是否沉淀到 CLAUDE.md、Skill 或 Hook。
临时事实是否避免写入长期记忆。

这套检查的目的，是给速度加刹车。Agentic Coding 的收益来自循环：定义目标，提供上下文，执行改动，验证反馈，沉淀规则。循环越清楚，Agent 越像工具；循环越含混，Agent 越像噪声放大器。

回到漫游指南可以按需重读前面章节。下一章：/goal 与跨轮持续目标——设定可验证终点，让 Claude 跨轮自主续跑；再进入 Routines 与定时自动化与调试与错误恢复等第九部分实践章。