AI 编程可闭环协作 · 卷二：技术图谱——让 Agent 先看地图再动手

2026-05-28 · 系列《AI 编程可闭环协作》卷二 · 技术图谱与 Agent 读图 系列文稿（Markdown）：github.com/Cyning12/ai-coding-closed-loop-articles 阅读顺序：建议先读卷一「怎样才算做完」，再读本篇。

目录

摘要

若你还没读过 卷一：怎样才算「做完」，建议先看——那里讲清了 图谱 + 协作流程 如何叠放，以及「意图 / 成果 / 验收」怎样算一轮交付。

卷一也点过：技术图谱 负责回答 Agent「改哪里、会影响谁」。本卷只展开图谱这一轨：先 认得仓库里有哪些图谱文件（流程图、表结构说明、入口清单、机器总图等），再讲 第一份图从哪来（新项目 vs 老项目）、流程图为何有 md / ai.md / json 三轨、Agent 默认怎么读（查询子图 + 清单便签，而不是整仓灌 Mermaid）、图谱相关 CI 门禁在合并流程中的作用，以及 怎样验证读图方式是否值得坚持。协作流程与合并签收在 卷三；有地图没签收，照样不敢合并。

8. 技术图谱是什么：流程图、依赖与契约

卷一讲了主图、子图 怎么用。本节先回答三件事：仓库里有哪些图谱文件、各自干什么 → 第一份图从哪来 → Agent 默认怎么读。不必先背文件名，下面命名只是笔者实践中使用示例，并非规范。

8.0 与卷一的衔接

卷一 §2.1 的 主图 + 子图 是本卷锚点。若你还没读过，先扫一眼卷一里的多模块 API 主链路示意，再读下文。

公众版主图（与卷一同构，可另存改模块名）

8.1 仓库里的技术图谱：先认「有哪些文件」

先不要想抽象方法论。技术图谱在工程上就是：仓库里的一个专用文件夹（例如 docs/_tech_graph/，名字可自定），里面放 「帮 Agent 改代码用的地图与清单」——不是产品 PRD 全文，也不是替代 README。

下面用 通俗名 介绍。下表文件名为笔者项目中的命名，并不唯一——你的团队可以自定目录名与编号规则，只要团队内一致即可。

图谱夹里常见几类物件

单独说清楚两个最容易懵的词：

• graph.json（机器总图） 不是让人逐字阅读的文档，而是 「印刷好的大地图集」：由 *.ai.md 经脚本 导出 得到。Agent 默认 不会 把整份 JSON 塞进对话（太大），而是 按入口查一小段——例如「从 RAG 这一节点往下 2 跳」（§8.4 叫 查询子图，§9 用 GPS 比喻）。 改图时：改 *.ai.md（或先从 *.md 改起再同步），再重新导出；不要 直接改 graph.json。
• 01_struct（表结构说明） 就是 「数据库地图」：有哪些表、和业务流程怎么关联。 和 graph.json 不是一回事；不能因为有了总图就删掉它。
• 入口清单 / 契约清单（不同于机器总图） 机器总图 描述 流程与调用关系；入口清单 描述 有哪些对外的「门」（不必是 HTTP）。可以想成：GPS 路网（总图） vs 公交站牌表（入口清单） vs 路口规则（契约清单）。

表结构、契约、机器总图可以 第二步再补。入门时先凑齐下面 最小图谱夹 即可开工。

最小图谱夹示例（笔者项目 · 3 个文件）

文件名 并不唯一；分册名 10_flow_rag 请换成你第一条核心链路（如登录、入库）。

有导出脚本后，再补 *.ai.md 与 graph.json（§8.1 上表「流程原稿 / 机器总图」）。

三类「逻辑信息」（对上表，不必死记文件名）

记一句即可：机器总图 主要管「流程怎么走」；入口清单、表结构说明仍要单独维护。

为何同一套流程图，会有 .md、.ai.md、graph.json？

只对 流程图 这三样容易觉得重复。可以记 三轨（不是三个互相无关的项目）：

人改图（常从 .md 入手）→ 同步 .ai.md → 脚本导出 graph.json → Agent 按任务查其中一截（+ 入口清单等便签，见 §9）

不是「有 json 就可以删 md / ai.md」。是：机器总图（json） 来自 .ai.md；人若不读 md，仍要有人维护 ai.md（或能自动生成它），否则总图会过期。

8.2 第一份图谱从哪来？（新项目 vs 老项目）

「我还没有图，第一张怎么画？」——分新老项目，别一刀切。

新项目（推荐）

新仓 先有小地图，再写代码；不必等「全系统架构完美」。

老项目 / 存量

什么样的链路适合当「第一张」？

• 有清晰 HTTP / BFF 入口（一个路由族即可）
• 改完能用 现有或刚补的少量单测 验证
• 先别选 全局配置、横切中间件、多仓胶水

反推怎么画（不写工具名也能做）：从对外路由/handler 起笔 → 跟 2～3 层调用/表 → 主图 5～9 个方块 + 一篇子图。第一版 70 分就够；在真实 PR 里 顺手改图 + 任务单验收 迭代，不追求一次画准。

8.3 怎样选「第一条核心链路」画图

（在 §8.2 选定「画哪条」之后，用本 checklist 落笔。）

1. 写下链路名（例：「AI 问答」「登录」「入库」）。
2. 画 主图 一页：左进右出，分叉写清。
3. 选 一个 最常改的分支，拆 分册子图 一篇。
4. 任务单写 图谱入口：主图 + 子图路径。
5. 合并前跑通卷一 §6 的合并前命令（按栈改）。

8.4 「子图」一词：分册文档 vs 查询裁切

「子图」在协作里有两层意思，都对，别混：

卷一说「打开 RAG 子图」多指 分册；推荐 Agent 默认用的是 查询子图（更省上下文，实验里称 查询子图轨，下文 §9.2）。

不要整仓灌给 Agent：整目录 + 整文件 graph.json + 所有 flow 全文 → 贵、噪声大、仍可能漏关联。

故事线（续卷一）：改 RAG 召回策略 → 主图定位 RAG 召回 → 查询子图（或打开分册对照）→ 看契约/测试锚点 → 改代码。

8.5 与架构图、C4、ADR 的分工

技术图谱（本篇主题）：给 Agent 改代码时的导航与影响面——入口、流程、入口清单、表结构等（见 §8.1）。与 Wiki、ADR 并存：产品语义在 Wiki，设计理由在 ADR，动实现时优先更新图谱。

8.6 存量仓库：图谱不求全仓

勿追求第一周全仓数字孪生；卷五将专讲 存量渐进落地。

9. Agent 默认怎么读图：对照与验收

9.1 为什么要谈「读图方式」

画了图 ≠ Agent 真会用。团队需要约定：默认给模型看什么——否则有人整仓贴 Mermaid，有人只给目录树，结果不可比、也难验收。

9.2 三种读法（通俗对照）

把仓库里的总地图想成 一本厚地图册（导出后的 graph.json，不默认背整本）：

笔者曾在一处 后端 API 示例项目 上做过 读法对照（不是功能测试全集）：在 已建图谱的单仓库 里，用 3 道固定任务 比较不同「喂给模型的地图材料」。在 该有限题集 上观察到：查询子图轨 静态上下文明显小于「精选 Markdown 原文」；部分题 影响面列得更全（未给出具体 token 数字，勿外推）。据此在笔者项目中约定：Agent 改图时默认查询子图，而不是默认灌整段双轨 Markdown——你的团队应 自建题集并重测 后再固化规则。

示例题集（笔者项目 · 3 题，仅说明「比的是什么」）

以下三题仅为笔者仓库的读法对照样例，不是你的团队必须照抄的题目。 请从 真实 PR 抽取 5～10 道自建题集。

题集目的：比较读图方式（整包 / 精选 Markdown / GPS+便签），不是证明三道题做完就等于全仓合格。正式团队宜从 真实 PR 抽出 5～10 道 作自己的题集；上文三题 不能 代表 CLI、纯前端或其它业务形态。

维护仍靠人：.md / .ai.md 照旧更新 → 导出 → 再查询；升级的是读法，不是取消图源。

日常 vs 进阶：上面「GPS + 便签」指 Agent 每次按任务现场查询——日常开发不需要「按题打包」。若要做 读法对照实验、或 冻结某一任务的上下文 以便复跑，才把 §9.2 题集里某一题所需的查询子图 + 站牌/警示便签 预先收成一袋 Prompt 材料（§9.6）。

9.3 GPS 与便签：谁是谁

9.4 收到任务：该不该读图谱？

很多人问：「图谱夹文件不少，是不是每次对话都要通读？」——不必。 团队应约定 读图决策，避免 Agent 要么整仓灌图、要么完全不看。

下面用与 §9.3 同一套比喻（GPS / 便签 / 表结构+规约）；文件名仅为笔者项目示例。

怎么读这张图：菱形 = 判断（是/否）；矩形 = 动作（去读什么、去做什么）；从左到右沿箭头阅读。

怎么读这张图：

推荐读序（改代码时）：

GPS 查询子图 → 站牌/路口规则便签 → 按需 表结构+规约 → 不足时 分册流程图片段 → 锚点代码

两种常见误解：

1. 「不改业务代码就用不到图谱」——对 Agent 是否开图 大体成立；但 提 PR 合并时，CI 仍会校验图谱是否与代码一致（见 §9.5），与 Agent 当轮读没读无关。
2. 「任务很小也要通读图谱夹」——若任务单已写明「改某表的某字段」，即使改动行数少，也应打开 表结构说明（及必要时 实现规约）对照，而不是跳过图谱。

卷四将展开 经验文档库 与图谱的分工；本卷只强调：默认读图姿势是 GPS+便签，不是每次复印整本图册。

9.5 图谱与 CI：门禁在流程里干什么

卷一 §6 讲过 合并前必绿：单测、lint、构建等。技术图谱再补一层——文档与代码别悄悄分叉。它和「Agent 这一轮 Prompt 里带了什么」是 两条线：

人/Agent 改代码 + 顺手改图（.md / .ai.md）
        ↓
    导出机器总图（若已有脚本）
        ↓
    提 PR → CI 自动跑图谱相关检查 + 常规测试
        ↓
    全绿 → Review → 合并

CI 在这里的角色：不是替 Agent 读图，而是 在合并前拦住「图已过期」——相当于地图出版社的 校对车间。

因此：即使某次对话 Agent 没打开图谱夹，只要改动了入口/流程/表，PR 仍可能因图谱 CI 变红——这是在保护全团队的下一位读者（人或 Agent），不是惩罚「没读图」。

入门团队：任务单写清入口 + 合并前跑通卷一 §6 的命令；有精力再逐步加上述图谱门禁。

卷三预告：合并前的 完整协作流程、任务单字段与签收 在卷三展开；本卷只解决「图是什么、怎么读、CI 如何防图过期」。

9.6（进阶）按题打包：何时需要「一袋行李」

§9.2 已说明：日常开发用 现场 GPS + 便签 即可。本节只给 要做读法对照、或要冻结复现 的团队。

先分清两步，别和「导出总图」混了：

按题打包 ≠ 再 export 一份总图。 它是 「这道题出发时的行李」；没有基准题集、不做 A/B 读法实验时 可以不做。

无对照实验时，任务单 + §9.5 的 CI + 人工 Review 已够闭环。按题打包 仅在做读法 A/B 或冻结复现时需要；日常改需求不必做。

9.7 诚实边界

• 读法对照指标只代表 已建模仓库 + 声明题集（如 §9.2 三题）；比的是 读法，不是业务全覆盖；换仓、换模型应 重测。
• 验收的是 读图策略是否值得坚持，不是「有图谱就零 bug」。
• CI 保证的是文档与实现不漂移；Agent 读图姿势 要靠团队约定与任务单——二者互补，见 §9.5。

10. 结语

你不必一次建完美数字孪生。新项目：先画一条链路；老项目：选一条链路反推或对照文档。 维护 **人读 .md + 导出源 .ai.md**，Agent 默认 查询子图 + 清单便签。再配合 任务单、图谱 CI 与合并前验收（§9.5；卷三展开协作流程），才能把「猜仓库」变成 按图施工。