外观
第 11 章 · 端到端项目实战
前面每一章都教「单招」：怎么写 Prompt、怎么切模型、怎么派子代理。但真实工作里这些招是连在一起打出来的。本章带你完整走一遍真实项目：从接手一个陌生仓库，到探索、规划、实现、测试、提交、复盘——一镜到底，看清一套拳怎么打。
本章不引入新机制，而是把全书技能按时间顺序编排。建议你边读边在自己的一个真实项目里同步操作。
全章按六个阶段展开：
- 阶段一：接手与建立认知（0–10 分钟）
- 阶段二：探索代码库（派子代理）
- 阶段三：规划与方案审查
- 阶段四：分块实现
- 阶段五：验证、审查与提交
- 阶段六：复盘与沉淀
贯穿案例
为便于讲解，我们虚构一个足够典型的任务：
你刚加入团队，接手一个叫
shorty的开源项目（一个用 TypeScript 写的短链接服务）。组长给你的第一个任务是：「短链接跳转接口偶发返回 500，用户反馈创建短链接后有时打不开。查清楚并修好，顺便补一下缺失的测试。」
这是一个绝佳的综合任务：仓库陌生、问题偶发（难）、要定位根因、要补测试、不能乱改。下面六个阶段就是处理它的完整过程。你在自己的项目中遇到的具体技术细节不同，但阶段结构与决策点完全通用。
阶段一：接手与建立认知（0–10 分钟）
动作 1.1：先不要急着打开 TUI，做三件事
在让 AI 介入前，先用几分钟建立自己的认知——AI 是放大器，你自己零认知时，它放大的是混乱。
- 克隆仓库，自己先读三个文件：
README.md（项目是干什么的）、package.json（技术栈、脚本命令）、目录结构（ls一眼扫过）； - 跑一次项目（按 README），确认能在本地启动；
- 复述任务，把组长的话改写成可验证的目标：
text
现象：短链接跳转接口偶发 500
期望：跳转稳定返回 302，不再 500
附带：补上这个接口缺失的测试动作 1.2：在项目目录启动 TUI，确认开局配置
bash
cd shorty
opencode进 TUI 后先扫两眼状态栏（第 6 章的习惯）：
- 当前模型是什么？这种「偶发 bug 定位」是难任务，确认用的是强模型（不是轻量模型）；
- 当前 Agent 是 build；
- 项目里有没有
AGENTS.md？（侧栏或ls -a可见）有的话它会自动加载。
动作 1.3：先让 AI 给你讲项目，而不是直接修
第一条消息的目的是对齐认知，不是动手：
text
我刚接手这个项目。请先不要改任何代码，先通读项目，
用简洁的方式告诉我：
1. 这个项目整体是做什么的、技术栈；
2. 主要目录和模块的职责；
3. 短链接「创建」和「跳转」分别由哪些文件、函数处理；
4. 项目怎么跑测试。🔍 为什么这么做：让 AI 先做一次「项目导览」，你能在五分钟内补上一小时的背景，且它给出的文件 / 函数清单是接下来探索的地图。明确说「先不要改」，把这一阶段锁成只读。
本阶段要点回顾
- 自己先读 README / package.json，建立最低限度认知；
- 难任务开局确认强模型；
- 第一条消息只读、对齐认知，要「地图」不要「答案」。
阶段二：探索代码库（派子代理）
动作 2.1：让主 Agent 派 explore 子代理追踪跳转链路
定位偶发 500，首先要搞清「跳转接口从请求进入到返回，经过了哪些代码」。这是典型的可派出调查任务：
text
请派 explore 子代理，只做调查、不改代码，追踪短链接跳转接口
的完整调用链：
1. HTTP 请求从哪个路由 / 入口进来；
2. 经过哪些中间件、函数；
3. 在哪里读数据库、在哪里可能抛错；
4. 返回 302 / 500 的分支条件。
请给出每一步对应的文件和行号，并标注「哪些地方最可能产生
未捕获异常导致 500」。🔍 关键点：explore 是 subagent，所以要让主 Agent「派出」它，而不是用 Shift+Tab 去切（那只循环主 Agent）。它的搜索过程不污染主会话，最终只带回一张调用链地图（第 9 章）。
动作 2.2：自己读关键代码，验证子代理的结论
子代理给出地图后，不要全盘照收。用 @文件#行范围 亲自打开它标注的「最可能抛错」的两三个位置，例如：
text
请把 @src/handlers/redirect.ts 的完整逻辑讲给我听，
特别是数据库查询结果为空、或查询本身失败时分别怎么处理。这一步往往立刻露出马脚——比如你可能发现：
text
- 数据库查询可能返回 null，但代码没判空就访问属性；
- 查询失败时异常没有被 try/catch，直接冒泡成 500。动作 2.3：复现问题，把「偶发」变成「可观察」
偶发 bug 最难的是让它重现。让 AI 帮你从代码推断触发条件：
text
根据调用链，什么输入或状态会触发这个 500？
请给出最可能的触发条件（例如：短链接记录不存在 / 数据库
暂时连不上 / 编码字符异常），并说明如何在本地稳定复现。然后按它给的条件本地复现一次（比如请求一个数据库里不存在的短码），观察是否真的返回 500。把偶发问题钉死成一个可重复的请求，后面的修复才有靶子。
阶段三：规划与方案审查
动作 3.1：让 AI 先出根因分析与修复方案，确认前不动手
现在你已经能复现、也读了关键代码。切到 plan Agent（<leader>a，它不编辑项目文件），让它把「根因 + 方案」正式写出来：
text
请基于已经复现的问题，给出：
1. 根因判断：为什么会偶发 500？触发的精确条件是什么？
2. 修复方案：你打算怎么改，涉及哪些文件、哪些分支逻辑；
3. 这个改动可能影响的其它地方（创建接口、其它用到该查询的
位置）；
4. 测试计划：要补哪几个测试用例。
先不要写代码，等我确认。动作 3.2：审查方案——这是你价值最大的时刻
不要看都不看就批准。重点审查四点（第 9 章）：
- 根因对吗？ 它的判断与你亲自读到的代码、复现结果一致吗？
- 是「最小修复」还是「过度改动」？ 警惕方案借机重构一堆无关代码；
- 分支补全了吗？ 比如不仅要处理「记录不存在 → 返回 404」，还要处理「数据库查询本身失败」这两种不同情况；
- 测试覆盖触发条件吗？ 至少要有：正常跳转（302）、记录不存在（应 404 而非 500）、查询异常（应优雅处理）。
如果方案里有需要取舍的点（例如「记录不存在时该返回 404 还是跳转首页」），这是产品决策，应由你拍板，让它把选项列清楚而不是默默选一个。
动作 3.3：确认方案，再切回 build
方案达成一致后，明确确认并切回 build：
text
方案可以。就按「记录不存在返回 404、查询异常记录日志并返回
500 但不暴露堆栈」来做。先补测试，再改实现。🔍 为什么先补测试：先写出能复现 bug 的失败测试，修复后测试转绿——你就有了「修复确实有效」的铁证，且这些测试永久守护这个接口（测试驱动，第 9 章）。
阶段四：分块实现
动作 4.1：把实现拆成两个小提交，而不是一次改完
即使任务不大，也按「先测试、后实现」「先判空、后异常处理」切成小步，每步可独立验证：
text
第 1 步：为跳转接口补测试（正常 302、不存在 404、查询异常），
现在它们应该失败；
第 2 步：修复「记录未判空」的问题，让前两个测试转绿；
请一步步做，每完成一步告诉我，我确认后再继续。动作 4.2：过程中盯紧工具调用与 diff
AI 用 edit / write 改文件时：
- 留意它只动了方案约定的文件，没有顺手「清理」别处；
- 项目开了 formatter 的话，落盘即自动格式化（第 8 章），diff 不会混入风格噪音；
- 如果它开始偏离方案（比如自作主张改了创建接口），及时
Esc打断或 steer 纠偏。
动作 4.3：遇到卡点先分层判断，不乱重试
如果某一步 AI 反复做不对，按第 9、10 章的方法判断瓶颈：
- 是缺证据？（让它把报错和相关文件完整读一遍）
- 是方案有问题？（退回阶段三修订）
- 是模型吃力？（
F2切更强模型）
不要机械重试同一方法。
本阶段要点回顾
- 小步实现、每步确认；
- 盯 diff 防范围蔓延；
- 卡点按证据 / 方案 / 模型分层升级。
阶段五：验证、审查与提交
动作 5.1：跑完整验证，而不只是新增测试
text
现在请：
1. 跑与本次改动相关的全部测试；
2. 跑整个项目的测试套件，确认没有改坏别的地方；
3. 跑类型检查 / 构建（如 tsc、npm run build）；
4. 再用之前复现 500 的那个请求手动验证一次，确认现在返回
正确（404 而不是 500）。🔍 关键点：「新增测试通过」不等于「没改坏别处」。全量测试 + 构建 + 手动复现验证，三重确认才算真的修好（第 9 章）。
动作 5.2：提交前做一次收口 code review
让 AI（或派只读 reviewer 子代理）对照交付清单自查：
text
请对照本次任务做最终自查：
- 500 的根因是否已消除、所有触发分支都处理了？
- diff 是否只包含本次应有的改动，没有调试残留、无顺手重构？
- 测试是否覆盖正常 / 不存在 / 异常三类？
- 是否需要更新文档（如接口行为从 500 变成 404）？你也可以亲自打开 diff 过一遍——这是改动进入主分支前的最后一道关。
动作 5.3：及时 Git commit，把成果固化
确认无误后提交。可以让 AI 生成符合项目约定的 commit message（第 4 章的规则）：
bash
git add -A
git commit # 如：fix(redirect): return 404 for missing short link;
# handle query errors; add tests🔍 为什么提交这一步重要：前面的快照（undo）只覆盖「近期、活动目录」，而一次干净的 commit 是可长期依赖、可推送、可回滚的安全网（第 10 章）。任务一旦验证通过就应及时落袋。
阶段六：复盘与沉淀
动作 6.1：花五分钟做一次简短复盘
任务交付后，别急着立刻跳进下一件事。问自己（也可让 AI 一起）三个问题：
text
1. 这次哪个动作最有价值？（大概率：先复现、先补测试）
2. 哪里走了弯路 / 返工？为什么？
3. 有没有「以后每个类似任务都该做」的经验，值得固化下来？动作 6.2：把可复用的经验沉淀进规则 / 命令，而不是「下次注意」
复盘最有价值的产出是一条会自动生效的新规则。例如你发现项目里所有接口都有「未判空」的通病：
- 在项目
AGENTS.md加一条：「处理数据库查询结果时，必须先判空再访问属性；查询异常要显式捕获，不允许冒泡成裸 500」； - 或做一个
/check-error-handling的自定义 Command，以后一键审查异常处理。
🔍 核心思想（第 4、9 章）：「下次注意」是不可靠的——下个会话的你和 AI 都不会自动记得。写进 AGENTS.md / Command / Agent 的内容，才会在未来每个会话自动加载、自动执行。让一次经验永久增值。
动作 6.3：清理工作区
收尾的小动作：确认没有遗留的调试代码、临时文件；如果探索阶段开了多个 Tabs / Sessions，可关闭或整理（第 2 章），保持环境清爽。
本阶段要点回顾
- 简短复盘：价值点、弯路、可复用经验；
- 经验固化成规则 / 命令，而非寄望记忆；
- 清理工作区。
全章一图流
text
阶段一 接手认知 自己先读 → 确认强模型 → 只读要「地图」
阶段二 探索代码 派 explore 追链路 → 亲自读关键代码 → 复现钉死
阶段三 规划审查 plan 出根因方案 → 审查四点 → 你拍板取舍
阶段四 分块实现 先补失败测试 → 小步修复 → 盯 diff、分层排卡
阶段五 验证提交 全量测试+构建+手动复现 → 收口审查 → commit
阶段六 复盘沉淀 复盘 → 固化规则 / 命令 → 清理结语
这就是一次真实任务的完整生命周期。你会发现：真正动手写代码（阶段四）只占全过程的一小部分，大量价值发生在它之前的「理解、探索、规划」和之后的「验证、复盘」。新手急着让 AI 快改，高手把功夫花在前面和后面——这正是「会用 AI」与「用 AI 系统性交付」的分水岭。
带着这套六阶段框架回到你的真实项目中，完整走两三遍，它就会成为你的肌肉记忆。