AI 编程可闭环协作 · 卷五：存量项目怎么落地——案例、误区与渐进路线

## 目录

---

摘要

卷一～四讲的是 框架：意图 / 成果 / 验收、技术图谱、任务单与签收、专题收尾（一轮交付合并后的归档，卷四 §17）。若你的仓库已经跑了很多年，常见状态是：文档与代码分叉、CI 不全、不敢让 Agent 碰核心路由——卷五专门回答：存量项目怎样用「一周量级」试通一条链，而不是两周铺满全仓。

本卷三件事：

1. 两则匿名周记案例（§21 后端横切 · §22 全栈契约）——情节虚构化，只讲机制；
2. FAQ（§23）——含卷三读者常问的 冷/温/热 ≠ 架构三层 对照表；
3. 渐进路线（§25）——阶段 0～3，与卷一 §6 最小起步衔接。

本卷立场（与卷一～四同向，卷五说透）：闭环是为了让 AI Coding 更准确、更敢合——不是在「人本来就能较快做完」的事上强行多走 Agent、多填表、多改图。人把住 关键节点（任务单、合并前检查、签收、高敏复检）；试点链上沉淀 示范性样板（完整 PR 留档，供 Agent 模仿），日常 大部分实现与图谱增量由 Agent 按样板起草、人审 diff（示范性 = 可模仿、可随栈迭代，不是一成不变的标准答案）。

范例栈说明：案例基于笔者在用的 Python 后端 API + 可选 Next.js BFF 双仓组合；不是「React 单体 + Node 一把梭」教程。全栈读者请按自己的仓拆成 契约 + 分栈合并前命令（卷一 §6）。

若你尚无合并前验收（CI 或等价手动门禁），请从 §25 阶段 0 或卷一 §6 开始，不要跳过「验得动」。

---

21. 存量案例：后端横切改动的一周

本节要回答：在 几乎没活图谱、CI 可能不全 的后端仓，如何用 一条非核心链路 跑通卷一～三的最小闭环。

以下情节 **匿名化**；读者不必与任何真实仓库一一对应。

21.1 背景：为什么选「内部工具 API」当第一条链

示例栈：多模块 Python 后端 API（问答、入库、管理类路由并存）；向量检索与业务库在概念上并存，但 本案例不展开 RAG 细节。

存量阻力（常见）：

**试点选链（定稿原则）**：第一条走 **内部工具 / 观测 / 配置类 API**——横切、可测、**不直接碰登录 / 支付**。推广顺序建议：**内部 → 后台 → 登录 → 支付**（先非核心，再碰用户面）。

本案例假设产品要在 内部健康检查接口 上补一项 结构化错误码 与 契约字段对齐（与卷四 §17 同类：门牌号 = 契约/入口清单与代码一致，但本节 不演 CI 红，只走通 happy path + 一条诚实切口）。

21.2 Day 0～1：先「验得动」

目标：合并前必须能回答「敢不敢合」——没有 CI 也要 手动门禁（卷三 §14.1 · 卷一 §6）。

**诚实切口**：该示例仓当时 **尚未** 配齐契约/锚点自动检查；Week 1 只要求 **单测绿 + 书面自勾**。全量 **入口清单** 检查放在 **§25 阶段 2**，不在第一周强上。

21.3 Day 2～3：再「有地图」——70 分即可

按卷二 §8.2～8.3 checklist，只画 一条链：

1. 主图 上标出「内部工具 API」入口方块（不必画满 RAG / 全库）；
2. 一篇分册（子图）展开：该路由依赖哪些模块、改坏会影响谁；
3. 任务单写一行 图谱入口（卷二 §8.3）。

不必 第一周补全全仓子图。主图 + 一篇分册 = 70 分即可开工。

21.4 Day 4～5：敢改 + 签收

任务单（节选 · 虚构）

**实现**：人冻结任务单；Agent 按分册改 handler 与单测。改完对照 **审查自勾表 + CI（或手动等价）**。

签收（本案例 · 小团队）：

本案例动的是 内部工具 API：作者自检 + CI（或手动门禁）+ 自勾表落盘即可，不是「感觉对了」。若改动触及对外 API、核心路由或契约清单，仍须 独立复检（卷三 §12.5 精神）——书面记录不可省。

21.5 一周结束后：刻意不做什么

**一周真正要留下的**：一条可检索的 **示范性样板**（代码 + 最小图 + 任务单 + 签收）；下一轮同类改动让 Agent **按该样板** 改实现与图，人审 diff——**不是**证明「以后每条 API 都靠人手绘全仓图」。

读者可带走的 3 条检查项：

1. 合并前命令是否 写进任务单 且本轮 跑过？
2. 是否 只选一条非核心链 并写清图谱入口？
3. 合并后是否留下 可检索的书面签收（哪怕只有自勾表）？

21.6 与卷四的关系

卷四用 虚构专题 + 契约 CI 红 讲 专题收尾 与失败分支；本节用 更小的存量切口 讲 第一周怎么动起来。两条故事 互补：本节 happy path；卷四 §17.4 主失败分支。

---

22. 存量案例：前端 BFF + 契约类需求

本节要回答：全栈存量里 前端 BFF 如何与 后端契约 / 技术图谱 对齐；与 §21 的差异是 跨端契约同步，不是再讲一条纯后端 RAG 链。

以下情节 **匿名化**；范例为 **Python 后端 API + Next.js BFF** 双仓，**不是** React 单体一把梭教程。

22.1 场景：后端已改，前端还在按旧字段解析

背景：产品要在 统一聊天流 上调整某一 SSE 事件的字段名与错误形状（与卷四 §17.4 同类机制，本节 不重演 CI 红，侧重 双仓怎么分工）。

常见卡点：

### 22.2 任务单：把「跨端」写进非范围

任务单（节选 · 虚构）

**关键**：**非范围** 必须写清 **动哪一端、哪一端冻结**——否则 Agent 会「顺手改后端」导致契约再次分叉。

22.3 串行 PR：先后端，再 BFF（一人团队也适用）

一人团队可以 **同一周串行**，不必假扮「双评审委员会」；但 **两轮都要有书面记录**（§23.5）。

若平台不渲染 Mermaid，可按上表 顺序 1→4 执行即可。

**切勿**：后端 PR 未合就改 BFF 去「凑」旧字段，再在另一个仓开「只改文档」的 PR 等后端——卷四 §17.4 的 **双 PR 死锁** 在跨仓场景同样成立。

22.4 前端合并前检查（概念级）

与卷一 §6 一致，按栈写死，示例：

lint → test → build

有 E2E 再加一步；无 CI 则写入任务单当 手动门禁。BFF 层另可增加 契约测试（消费后端发布的错误形状表），名称因项目而异，公众稿只记 机制。

22.5 与 §21、卷四 §17 怎么分工

读者若只做后端，§21 + 卷四 足够；若全栈，**加上本节** 再对照 §25 阶段 1 的「前后端可并行不同链」。

22.6 诚实切口

---

23. 常见误区 FAQ

本节要回答：存量读者在试框架时最常卡住的 概念与顺序 问题。每条可 单独摘发；若你刚读完卷三又对「冷/温/热」犯迷糊，先看 §23.1 对照表（不改卷三已发正文，以本卷为准）。

### 23.1 冷 / 温 / 热：不是架构三层

卷三 §11.2.1、§14.8 用 冷、温、热 比喻 协作里信息放哪、留多久。不少读者会下意识对齐成「架构分层」或「代码能不能改」——本系列不是这个意思。

**一句收束**：

• 冷层 = 地图（改哪里、从哪进、会影响谁）→ 卷二；
• 温层 = 轨迹（谁定了什么、何时敢合并、收尾后怎么回顾）→ 卷三、卷四；
• 热层 = 事件记忆（可选、远期）→ 本卷不教你怎么搭监控栈。

若团队内部已有「架构冷/温/热」别种说法，请在 README 或术语表 写清映射，避免和本系列混用。

分层示意图（协作记忆，不是架构三层；自下而上为常用叠放顺序）：

23.2 先搭协作流程，还是先画图谱？

不必二选一，但要有顺序感。

**误区**：没 CI、没任务单字段，先画满全仓图谱——图会很快 **和代码分叉**，没人敢用。 **误区**：只有流程、没有图谱入口——Agent 仍易 **改错范围**（卷一 §2.3 叠放）。

23.3 协作留痕会不会越积越厚？

会涨，这是正常现象。 任务单、审查记录、对话导出都会变多。

本系列的应对是 分层，不是「别留痕」：

笔者在后端示例仓做过 **跨轮回顾对照**（字符量降幅、失败样本、**不可外推** 边界）——见卷四 §18.4；**不是**「装了摘要就不用图谱」。降幅度量的是 **回顾同一决策时少翻多少材料**（多为字符量等 **代理指标**），**不是** 代码质量或全行业生产力提升 **61%～77%**（§24.2）。

23.4 不会写导出脚本，图谱怎么起步？

先「表格 + 手画」，再自动化。

1. 用表格列：入口 / 依赖谁 / 改坏会影响谁（卷二 §8.2 新项目 vs 存量）；
2. 挑 一条 核心链，画一张 Mermaid 主图 + 一篇分册；
3. 任务单写 图谱入口 一行；
4. 有精力再接 PR 改图提醒、export/入口清单 检查（卷二 §9.5）。

误区：等「完美工具链」再动手——存量仓往往 永远等不到。

23.5 一人团队，审查和签收怎么做？

可以没有第二个人点 Approve，但不能没有「验收 + 书面落盘」。

§21 案例：内部路由可自检；§22 强调 **跨端契约** 时更要写清 **非范围**。

附册 B（规划）将收 Blocking 三行模板、双轨 PR 等可复制清单；正文 不展开 内部编号。

23.6 图谱会不会过时？要不要「半自动」？

会过时；目标是降漂移，不是归零维护，更不是「全仓人手永久绘图」。

试点之后的三层分工

「示范性」表示 **可模仿的节奏**，不是唯一金牌模板；换栈、换仓应 **重定或重审** 样板。

常见做法对照

**勿误解**：卷二说的「PR 顺手改图」，在存量阶段 1 之后应读成 **「同 PR、按示范性样板更新图与清单」**——维护量主要在 **试点建样板**，不是每条需求都从零画主图。

稳态维护预算大约 10%～15%（2～5 人团队；≤2 人目标 ≤10%），前提是 只维护试点链与按需补分册，非全仓手绘、非 KPI、非对读者的承诺；>20% 应减项或加强自动化（§25.4、§24）。样本口径（笔者示例仓）：约 3 名后端、每周约 5～8 个任务、2 条 试点链上的任务单/签收/局部图维护（非 KPI，勿外推团队规模或栈类型）。

量法（粗估，答辩用）：在任务单或周记里把「改 export/入口、对齐契约、补分册」与「写业务功能」分开粗记占比——不是审计级工时；可迁移的是 「有维护成本、过高要减项」 的纪律，不是 抄具体百分比。

23.7 契约检查绿了，是不是就算对了？

不一定。门牌号（契约/入口清单）对了，具体行为逻辑仍可能错。

卷四 §17.4 主失败分支：**契约检查红** → 同 PR 修文档+代码+测试；**契约绿了、pytest 仍红** → 回到实现与失败路径（卷四 §17 副分支一句）。

23.8 和 Jira / 飞书工单冲突吗？

叠加，不替换。

习惯做法：工单号可以写在任务单 **背景** 一行；**合并门禁** 仍是 **机器绿 + 书面签收**，不是「工单关了就算交付」。

23.9 Auto / 换模型，靠什么稳住输出？

卷一 §0 写过：Cursor Pro + Auto、预算有限、模型会切——因此更信 流程 + 机器验收 + 任务单字段，而不是赌某次 Prompt。

### 23.10 可以不做跨轮回顾摘要吗？

可以。 新需求开工仍靠 图谱 + 任务单；跨轮回顾摘要（卷四 §18 的编译式回顾页）服务 跨很多轮之后 的复盘，不是开工必读。

若你 连任务单与 CI 门禁都还没跑通，请先 §25 阶段 0 或卷一 §6，不要 先上 摘要编译入库 / LLM Wiki 类方案。

与 Andrej Karpathy 提出的 LLM Wiki 相比：同样强调 编译原始材料、而非每次从长对话重新理解；本系列的 跨轮回顾摘要 定位更窄——工程专题归档与决策摘要（Epic / 专题 合之后），不是 通用领域百科；敢不敢合并 仍只看 规格、合并前检查、书面签收，不看摘要写得多漂亮。可与图谱（冷）、任务单（温）互补。

23.11 一定要装 OpenSpec、ast-grep 吗？

不必。 公众稿只承诺本系列已反复用的 能力等价物：

• 任务单字段（验收、非范围、失败路径、测试策略）；
• 合并前 pytest / lint 类检查；
• 契约/锚点 清单 + CI（机制名即可，不绑某一文件名）。

其它工具若你团队已成熟，可自行 映射 到上述能力；不要 把未普及工具写成本文标配（§24 展开）。

23.12 读完卷三仍懵：下一步读哪？

### 23.13 和业界说法（Harness / SDD / 效能指标）怎么对齐？

本节把 方法论地图 §3.1 / §5 / §9 与卷四 §18.4 收成 存量读者 FAQ；更全外链对照由系列维护者在仓库 Issue / 讨论区补充（公众稿以本节表为准）。

**与 George Hotz 类「Agent 灾难论」**：他常批评 **无约束 Agent**；本系列问的是 **有闸协作下能否稳定交付**，且 **不主张** 全自动替代程序员（§24.2）。**不同层面**，可并存。

---

24. 诚实边界：不能外推成什么

本节要回答：卷一 §5「诚实边界」的 展开版——哪些话本文 没有 说、读者 不应 自行外推。

### 24.1 卷一已说 · 卷五补什么 ### 24.2 不能外推清单（公众版） ### 24.3 换模型、换仓库、个人与团队 ### 24.4 与独立篇、附册的边界

• 冷/温/热 协作分层 vs 架构三层：以 §23.1 为准；更深探讨计划以独立短文连载（非 本系列卷号）。
• 附册 A–C（术语 / 模板 / 延伸阅读）：随系列 附册 连载（§26），不 占卷五正文篇幅。

---

25. 存量项目渐进落地

本节要回答：老项目 先做什么、后做什么、做到哪一步可以停——收成可执行路线，与卷一 §6、§21 案例、§23 FAQ 对齐。

**新项目** 可从卷一 §6 直接试；**本节默认** 你已有多年代码、文档分叉、CI 可能不全。

落实原则：阶段 1 的目标是 示范性样板 + 敢合并；不是给团队加一套「比人手写更累」的文书运动。若某步 明显 比资深工程师直接改更慢、更乱，应 缩范围或先不用 Agent（任务单与门禁仍可按风险保留），见摘要「本卷立场」。

25.1 先排阻力：跳过哪步会白做

**口诀**：**能合 → 能闭环一条链 → 有入口图 → 再谈优化与摘要**。

25.2 四阶段路线（0 → 3）

阶段 0：验得动（无 CI 也能开始）

目标：任何一轮合并前，都能说出 「跑过哪些命令、谁勾了验收」。

**时间**：通常 **1～2 天** 能定稿清单；不必等「先把 CI 搭完美」。

阶段 1：一条试点链 + 一轮闭环 + 示范性样板

目标：证明 框架在存量仓能跑通一次，并留下 示范性样板（供 Agent 模仿），而不是画满全仓图。

**时间**：**约一周**（与 §21 周记同量级）；团队小可拆成两周，但 **范围勿扩** 成「顺便改五条链」。

阶段 2：图谱检查与对照（可选增强）

目标：把 门牌号 与代码绑紧，降低文档漂移。

**诚实边界**：**不是**「上了检查就零维护」；日常改图以 **Agent 起草、人审** 为主（§23.6），人全手绘全仓 **不是** 目标态。

阶段 3：新需求默认闭环；老代码按需补图

目标：新活 走任务单 + 图谱入口 + 合并前检查；老代码 不追求一次铺满数字孪生。

### 25.3 双轨并存：旧流程和新闭环共存多久？

存量仓几乎总有 「老需求仍走口头 + diff 瞄一眼」。建议：

这样既不让团队窒息，也能让 **证据** 说话（「这条链确实更稳」）。

25.4 维护成本：稳态大概占多少工程时间？

上述比例为 **稳态持续维护** 的增量工程时间，**不含** 第一条试点链建 **示范性样板** 的一次性投入（约一周，§21 / 阶段 1）。

不是「一次建好永久归零」，也 不是「全仓人手维护」的预算。若负责人把图谱当 无人认领的文档坟场，或 无样板却强迫每条需求重画主图，任何比例都会失控——需要 Owner（哪怕兼职）。

25.5 何时不要追求「全仓图谱」

出现以下 任一 情况，宜 暂停铺图，只维护试点链：

• 对外入口 >20 且半年无人愿意改图；
• 业务方明确 不要 工程地图，只要排期；
• 链路已下线或极少调用，补图 无消费者；
• 团队连阶段 0 都未做到（合并前命令都说不清）。

这与卷一 §5「纸上谈兵」边界一致：先一条链跑通，再谈推广。

25.6 全栈 / 双仓：前后端可以不同步阶段

范例栈为 **Python 后端 + Next.js BFF** 双仓，**不是** 单体 React 教程；合并前命令按 **分栈** 写（卷一 §6）。

25.7 阶段自检清单（可复制）

## 存量落地自检（当前阶段：0 / 1 / 2 / 3）

- [ ] 合并前命令已写入任务单且本轮跑过
- [ ] 试点链路已命名且非核心用户面
- [ ] 主图 + 至少一篇分册 / 或表格版入口清单
- [ ] 最近一轮有书面签收（含一人团队自勾表）
- [ ] （阶段 2+）契约/锚点检查与 PR 同改纪律已试过
- [ ] （阶段 3）新需求默认挂图谱入口

---

26. 结语（系列收束）

五卷一条线：在预算与模型不稳定的现实下，用「地图 + 交接单」把 AI 改动做成可验收的交付。

### 从哪里开始读 ### 系列之后

• 附册（术语、Blocking 模板、模型自检等）将 另行连载，不 占用卷六编号。
• 方法论（对外无卷号）：建议应聘 / 评审岗 先读框架 再进卷一～五：从「更会写」到「敢合并」。
• 正文与连载稿：GitHub · ai-coding-closed-loop-articles（卷一～五链见该仓 README；腾讯云已发见各卷文首）。

欢迎 Issue / 讨论与 fork；实践反馈会反哺 附册与勘误，卷三正文 不因 单条评论而改版。

---

许可：CC BY 4.0 · 署名可转载与改编 · 系列文稿：ai-coding-closed-loop-articles