这是AI协同方法论系列的最后一篇，这类文章宜精不宜多。后面主要还是以技术积累和经验分享为主。
适用场景：项目已有代码（≥ 10 文件），你要做具体的修改
核心原则：分层装载，按需取用 --- 不要一开始就把代码全塞给 AI
使用前提
- 使用 Claude Code 或类似支持文件工具 + subagent 的 AI 编程环境
- 你已经知道大概 要改什么（需求明确），但可能不知道具体改哪些文件
- 项目根目录有
CLAUDE.md（没有就先写一份，怎么写见文末附录 ）：记录项目级约定、风格、禁区、关键入口。这样后续所有阶段的 prompt 都不用重述项目背景，AI 会自动加载------这是最大的 token 杠杆
阶段 0：需求澄清 + 适配评估（你自己，5 分钟，不耗 token）
A. 需求澄清
在动 AI 前，先写下：
- 一句话描述"要改什么"
- 一句话描述"改完后的预期行为"
- 列出已知约束（不能破坏 X、必须保持 Y）
为什么重要：这三句话是后续所有 prompt 的"根上下文"。写不出就说明需求还没清楚，直接上 AI 会走弯路。
B. 适配评估：这事适合交给 AI 吗？
不是所有改动都适合全交给 AI。快速判断：
- 适合放手让 AI 做：CRUD、文案/模板、UI 样式、已有模式的复刻、迁移重命名、补测试
- AI 做、但你要全程盯：跨多文件的业务逻辑、接口改动、中等复杂度 bug 修复
- AI 只能辅助、你主导：性能调优、并发/锁、架构级重构、安全敏感（认证/加密/注入）、数据迁移
评估结果决定你介入的密度。属于第三类就把方案审阅（阶段 3）和 diff 复查（阶段 5）拉到最严。
阶段 1：定位受影响的文件（让 subagent 探索，不污染主对话）
提示词模板：
我要做这个修改：[你的一句话描述]。
请派一个 Explore subagent 用 Grep/Glob 工具找出哪些文件可能需要改动。
只要求返回：
1. 文件路径 + 一句话说明为什么相关
2. 建议的修改顺序（哪个先改最安全）
只看函数签名/文档注释来判断相关性，不要贴完整实现，也不要写代码。
保持输出在 300 字以内。技巧：
- 强调"派 subagent"，让探索过程的 token 消耗不计入主对话
- 明确限定"只看签名/文档注释，不贴完整实现"，否则 AI 容易越界把全文贴进来
- 主对话里只留下摘要，保住后续阶段的 token 预算
产出：一份"候选修改文件清单"。
阶段 2：精准装载相关文件
提示词模板：
请读取以下文件，理解它们之间的关系：
- path/to/file1.py（函数 foo 是我要改的）
- path/to/file2.py（调用 foo 的上游）
- path/to/file3.py（被 foo 调用的下游）
读完后用 ≤ 5 句话告诉我：
1. 当前的调用链是什么
2. 我的改动会影响哪些地方
3. 有什么必须保持的约束（接口、类型、副作用）技巧：
- 只读 3-5 个关键文件，不要贪多
- 要求 AI 主动输出"约束"，这是它容易忽视的部分
- 让 AI 用简短总结回你，不要在对话里贴完整代码（保留主对话 token）
阶段 3：方案对齐（规划优先，不直接写代码）
推荐做法：进入 Plan Mode
按 Shift+Tab 切换到 Plan Mode。这是 Claude Code 内置能力，系统会强制 AI 先出完整方案、经你批准后再动手，比靠 prompt 里写"不要写代码"可靠得多------靠工具约束，而不是靠 prompt 说服。
提示词模板（Plan Mode 下使用）：
基于上面的理解，给出具体的修改方案：
- 每个文件要改什么（用自然语言描述，不要贴完整代码，
只说"在函数 X 中加入 Y 判断"这种粒度）
- 改动顺序
- 潜在风险和需要验证的点
- 是否涉及依赖/配置/数据库 schema 变更（有就单独列出）技巧：
- Plan Mode 天然阻止直接写代码，你只需专注审方案
- 这一步是核心决策点，你要仔细审阅方案
- 方案不对就重来，成本远低于代码写完再重来
- 如果没用 Plan Mode，必须在 prompt 末尾加粗："不要开始写代码。先等我确认方案。"
阶段 4：执行（动刀）
开始前 ：git checkout -b <feature-branch> 建分支。方向偏了直接丢弃分支比回滚安全。
提示词模板：
方案 OK,请按刚才的方案修改代码。
先用 TodoWrite 把方案拆成逐文件的任务清单,每改完一个就标记 completed,
让我能实时看到进度。
严格约束:
- 不要修改没提到的文件
- 不要"顺手优化"无关代码;但如果发现明显 bug,单独告诉我,不要一起改
- 保持现有代码风格
- 每改完一个文件,用一句话告诉我改了什么技巧：
- TodoWrite 让多文件修改的进度可见，便于随时打断
- "不要顺手优化" 必须明说（AI 的本能倾向是"我看到这里可以改得更好"），但要留个"上报 bug"的口子，否则它可能把发现的问题硬吞下去
- 要求逐文件反馈，方便你实时打断发现方向偏了
- 每完成一批文件就打个 checkpoint commit（后续可用
git rebase --autosquash合并），便于回退到任一中间状态
阶段 5：验证与收尾
A. 运行测试
请跑相关的测试（或我的验证脚本 X），贴出结果。
如果没有测试，请写一个最小的验证脚本来确认改动生效。遗留项目无测试时的增强做法 ：改动前先让 AI 为目标函数写一层 characterization test（捕获当前行为），改完后再跑一次，确认行为变化符合预期。这比事后补测试更能挡住回归。
B. UI / 前端改动必须手动验证
测试通过只是起点。UI 改动要在浏览器里实际点一遍：golden path + 几个边界情况。"测试绿了就收工"是前端回归的重灾区。
C. 对抗式审查
刚才的修改里，最可能引入 bug 的是哪几处？为什么？
还有什么边界情况没考虑到？
这个修改对现有功能有没有潜在的副作用？对抗式问法比"请 review" 更能激发 AI 挑错------AI 不会主动挑自己的错。
D. 收尾（必须自己做）
- 先
git diff --stat扫全景，再逐文件git diff细看，不要让 AI 替你看 - 自己写 commit message（验证你是否真的理解这次改动的试金石）；实在写不出就让 AI "用一句话概括这次改动"作为起点，再自己改
- 如果有不理解的 diff，回头问 AI："这一段为什么这样改？"
迭代与重来
现实中流程很少是单向 0→5。常见的回退路径：
| 在哪里发现问题 | 回到哪一阶段 | 保留什么 | 丢弃什么 |
|---|---|---|---|
| 阶段 2 发现候选清单漏了文件 | 回阶段 1，让 subagent 再挖一轮 | 需求描述 | 旧清单 |
| 阶段 3 发现方案不可行 | 回阶段 2，补读关键文件 | 需求 + 已识别约束 | 错误方案 |
| 阶段 4 发现方案有坑 | 回阶段 3 重做方案 | 已 checkpoint 的 commit | 未提交的改动（git stash 或丢弃分支） |
| 阶段 5 发现漏改了文件 | 回阶段 3 补方案 → 阶段 4 追加 | 已有改动 | 无 |
关键心态：方案推倒重来的成本远低于代码推倒重来。在阶段 3 多改两遍是省钱的。
针对不同修改类型的变体
变体 A：小 bug 修复（单文件）
- 跳过阶段 1，直接说"在 file.py 的 L42 附近有个 bug：[描述]"
- 阶段 2-3 合并为"读 file.py 周围 50 行，告诉我 bug 在哪 + 方案"
- 阶段 4-5 可以合并快速跑完
变体 B：新 feature（跨多文件）
- 阶段 1 要更严格，让 subagent 多挖几轮，防止漏掉受影响的地方
- 阶段 3 的方案评审是最重要的防线，重点看"有没有遗漏的受影响点"
- 建议在新分支上做，便于整体回滚
变体 C：大规模重构
- 先做一次 dry-run：让 AI 改 1-2 个代表性文件，你 review，确认风格和范围都对
- 阶段 4 分批提交，每批独立可回滚
- 每批提交后跑一次完整测试
Token 预算参考
| 阶段 | 相对消耗 | 说明 |
|---|---|---|
| 阶段 1（subagent 探索） | 主对话极少，subagent 内中等 | subagent 内消耗不占主上下文，这是关键收益 |
| 阶段 2（精准装载） | 中 | 取决于文件大小 |
| 阶段 3（方案） | 低 | 纯自然语言 |
| 阶段 4（执行） | 高 | 主要 token 消耗 |
| 阶段 5（验证与收尾） | 中 | 跑测试 + 对抗式审查 |
经验量级：一次典型的中等改动在几万到十几万 token 之间。具体费用按你所用模型的当前定价算。
长对话的上下文管理 ：如果做到阶段 4/5 对话已经很长，让 AI 在阶段末写一份"状态快照"（方案 + 已改文件 + 剩余任务）到一个 .md 文件。必要时 /compact 压缩历史，或开新对话附上该快照续做。
常见陷阱和对策
| 陷阱 | 对策 |
|---|---|
| AI 在阶段 1 顺手读了所有文件 | Prompt 里明确"只看签名/文档，不贴实现" |
| AI 在阶段 3 直接写代码了 | 用 Plan Mode（Shift+Tab），靠工具而非靠 prompt |
| AI 在阶段 4 顺手优化了无关代码 | 明确写"不要顺手优化，但发现 bug 单独上报" |
| 验证阶段 AI 说"看起来没问题" | 用对抗式问题，不要让它做自评 |
| 改完才发现改错了文件 | 阶段 3 的方案必须你仔细过一遍 |
| 多文件改动进度不可见 | 阶段 4 用 TodoWrite 追踪，每个文件独立完成 |
| 改完想回退但 commit 都挤在一坨 | 阶段 4 先建分支，每批末打 checkpoint commit |
| 前端改完测试绿了直接合 | UI 改动必须在浏览器里实际点一遍 |
| 遗留项目没测试不敢改 | 改前先写 characterization test 捕获当前行为 |
| 对话太长 token 吃紧 | 阶段末写状态快照 .md，必要时 /compact 或开新对话 |
核心心法
| 坏习惯 | 好习惯 |
|---|---|
| 把整个项目丢给 AI "你看着改" | 分阶段、逐步装载上下文 |
| 一次到位写完代码 | 先方案、再确认、再动刀 |
| 让 AI 自己验证自己 | 用对抗式问法 + 自己 review diff |
| 所有探索都在主对话做 | 探索性任务派给 subagent |
| 让 AI 一次性搞定 10 个文件 | 分批修改，每批可回滚 |
| 靠 prompt 说服 AI 按步骤来 | 靠工具强制：Plan Mode / TodoWrite / CLAUDE.md |
| 每次 prompt 里重述项目背景 | 一次写入 CLAUDE.md，后续自动加载 |
附录：如何写一份好的 CLAUDE.md
CLAUDE.md 每次对话都会自动加载------写得冗长就是持续白烧 token 。核心原则：越短越好，只写"代码里看不出来的东西"。
混合写最省力
让 AI 写的部分（客观、代码里能看出来的）：
- 项目结构概览、技术栈、关键入口文件
- 常用命令（构建/测试/启动脚本）
- 目录约定（哪些是业务代码、哪些是生成物）
直接用 Claude Code 内置的 /init 命令------它会扫一遍项目出初稿，比从零写快得多。
必须你自己写的部分 （主观、AI 看不出来------这才是 CLAUDE.md 的核心价值）：
- 禁区："不要用 X 库/模式，我们踩过坑"
- 废弃标记："Y 模块即将下线，不要再改"
- 风格偏好："日志不要写中文"、"注释越少越好"、"不要加 try/except 兜底"
- 决策背景："为什么用 A 不用 B"（AI 读代码推不出来）
- 团队约定：提交规范、分支策略、review 流程
写 CLAUDE.md 的流程
- 跑
/init让 AI 出初稿 - 砍冗余：凡是"读代码 2 分钟就能知道"的内容全删------AI 初稿通常要砍掉 50%+
- 补主观：把禁区、约定、踩过的坑加进去------这是 AI 永远写不出的部分
- 持续维护：每次发现自己在 prompt 里重复某条说明，就搬进 CLAUDE.md
⚠️ 坑：/init 默认输出英文
/init 的 skill 模板是英文写的，输出也默认英文。三种解法：
-
临时 ：
/init跑完直接说"把 CLAUDE.md 翻译成中文" -
本项目 ：跑
/init前先手动建一个只写"用中文"的CLAUDE.md，再跑/init -
一劳永逸（推荐） ：在用户级全局
CLAUDE.md（Windows：C:\Users\<你的用户名>\.claude\CLAUDE.md；macOS/Linux：~/.claude/CLAUDE.md）里加一条：- 生成文档、注释、commit message 默认用中文（除非明确要求英文）这个文件所有项目共享 ，一次设置永久生效------以后每次
/init、每次对话都会读到。
一句话：AI 写骨架，你写灵魂。