
> AI 编程工程化实践系列 · 卷二 · 建体系 | 第 3 篇 / 共 8 篇
>
> 这个系列只讲一件事：怎么用工程化的方法，把 AI 编程从"碰运气"变成"可预期"。

![image.png](https://developer.qcloudimg.com/http-save/yehe-12408676/0fc89aef96d3c340d195b82dcd4875b7.png)
---

## 一、今天解决"对不对"

上一篇给了那条 30 分钟的一键指令，跑完你手里有五份资产：三张图、两份清单、一份 AGENTS.md。

但"生成出来"和"能用"是两回事。AI 扫你的项目，扫出来的东西一定有误差：图上可能漏了一个模块，接口清单里可能写错一个字段名，AGENTS.md 里的启动命令可能跑不通。这些误差不致命，但会传染。从下一次对话开始，AI 写的每一行代码都以此为地图。

先对一下标题：那"一套规约"说的就是 AGENTS.md，它是地图和索引，不写规矩正文，规矩在 `rules/` 里。这个分工上一篇交代过，后面还会用到。

所以这一篇不重复"怎么生成"（指令上一篇给过了，分步版也附在文末），专门讲三件事：

1. 每份资产**校对时重点看哪里**
2. AI 在生成每份资产时**最容易在什么地方出错**
3. 这五份资产生成完之后，**被谁消费、什么时候消费**

先给一张总图。三张俯视图容易讲成"画三张图"，其实它们是三个不同的视角，互不重复：
![image.png](https://developer.qcloudimg.com/http-save/yehe-12408676/4e06d547c9cd2f6e6d8c05f74af352b0.png)

## 二、为什么先画图，不先写文档

给 AI 建项目认知，有两种路径：写一份详细的架构文档，或者让它先画几张图。

我选后者，理由有两个。

第一，图是 AI 最容易解析的形态。让 AI 读一份 5000 字的架构文档，它要先把文字在"脑内"转成结构；图本身就是结构，SVG 源码里的每个方框、每条箭头都是显式的节点和边，没有转译损耗。

第二，图骗不了人。文档可以写得含糊，"系统采用分层架构，模块间低耦合"这种话谁都会写；图不行，模块之间有没有循环依赖，画出来就是两条箭头互相指着，藏不住。让 AI 画图的过程，等于强迫它把对项目的理解落到明确的节点和边上，糊弄不过去。

还有一层：**画图这个动作本身就是一次架构体检**。哪张图画不出来，或者画出来是一团乱麻，说明问题不在 AI，在项目本身。这种情况下先修架构，再谈让 AI 写代码。

## 三、三张俯视图：各自看哪里

### 第一张：架构图，最容易画废的一张

架构图回答"这个项目长什么样"。听起来最简单，实际最容易画废，废在两个地方。

一是**不分层**。你不明确要求，AI 就把前端、网关、服务、数据库画成一堆平铺的方框，看起来什么都有，实际上没有任何结构信息。所以指令里必须写死："按分层画，前端层 / 后端服务层 / 数据层"。

二是**模块框里只有名字**。AI 默认只写模块名，一个框里俩字"订单"，你看完还是不知道它是干嘛的。要求它每个框里写"模块名 + 一句话职责"，图的信息密度立刻就不一样了。

校对时看两处：分层跟你项目的实际部署结构对不对得上；每个模块的一句话职责，跟你认知里的分工有没有出入。职责描述错了比漏画一个框严重，因为 AI 后面写代码时是按这句话理解模块边界的。

### 第二张：模块图，重点防一个错

模块图看项目内部：controller → service → repository 这些内部模块之间谁依赖谁。

这里 AI 有个高频翻车点：**你让它画模块图，它把 pom.xml 里的依赖全画进来**。Maven 依赖、中间件、第三方 SDK 全成了节点，最后你得到的不是模块图，是一棵依赖树，方框几十个，看不出重点。

所以指令里要有一条硬约束："只画项目内部模块，外部依赖一律不画"。

这张图还有一个额外价值：**循环依赖检查**。要求 AI 发现循环依赖就用红色标出，并在图下方列出清单。人肉 review 代码很难发现 A 依赖 B、B 又依赖 A 这种事，AI 全量扫描反而擅长。我拿自己的项目跑过这一步，确实扫出过循环依赖，都是历史代码里图省事留下的。这种东西平时不疼，一旦要拆模块就是雷。

### 第三张：依赖图，最值钱的一列

前两张看内部，这张看外部：项目靠什么活着。

依赖分三类，用不同颜色标：语言依赖（Spring Boot Starter 这些，编译期就要）、中间件（Redis、MySQL，运行时必须）、外部 API（代码里 FeignClient 调的那些，网络调用）。

分色不是好看。三类依赖的故障模式不同：语言依赖坏了编译不过，问题在构建期就暴露；中间件挂了运行时报错，影响面要看调用链；外部 API 挂了最隐蔽，超时、重试、降级都发生在线上。

这张图上最值钱的一列，是要求 AI 给每个依赖标注"**它挂了，影响什么功能**"。加上这一列，图就从静态清单变成了排障地图：线上出问题时，先看依赖图定位是哪类依赖，再看这列圈出的影响面。

### 三张图的关系

这三张不是同一张图的三种精度，是三个视角：架构图看系统边界，模块图看内部组织，依赖图看外部生命线。校对的时候你会发现它们偶尔“打架”：架构图上画了个消息队列，依赖图的中间件分类里却没有。打架的地方，往往就是文档和现实脱节的地方，顺手修掉。

## 四、两份清单：图是骨架，清单是血肉

图让 AI 看见结构，清单让它在接到具体任务时看清细节：有哪些接口能调、有哪些数据结构能复用。

### 接口清单，四个要素缺一个就废

让 AI 扫所有 Controller 产出 REST 接口清单，拿到手看着挺全，其实缺了四个关键信息，这份清单对 AI 来说接近废纸：

1. **统一返回结构和分页格式**。项目用 `{code, message, data}` 还是别的？分页是 `{total, list}` 还是 `{page, items}`？这条不标注，AI 生成的接口返回格式会五花八门，联调时一个一个改。
2. **Base path 前缀**。不同模块可能挂在 `/console/v1/` 和 `/api/v1/` 两条路径下，这决定 AI 写新接口时路由挂在哪。
3. **按模块分组，不要平铺**。按业务模块分组后，AI 能理解"改这个接口，同模块还有哪些接口要同步改"。平铺一份百十来个接口的大列表，AI 检索得到，关联不到。
4. **核心接口的出入参类型**。对外暴露的主接口必须标。不标，AI 写调用代码时靠猜。

校对重点在第 1 条。AI 扫代码推断返回结构，最容易在字段名上出错，比如把 `message` 推断成 `msg`。差一个字段名，后面每个接口都按错的来。

### 数据模型清单，只列"改了就影响全局"的

接口清单告诉它怎么调，数据模型清单告诉它数据怎么用。

这里有个容易做过头的点：把所有 Entity 的所有字段都列上。没必要。只列那些“改了就影响全局”的核心字段：`status`、`type`、主外键关系这种。一个 Entity 四十个字段，AI 关心的是那五六个有业务含义的，剩下的是数据库的事。

同时让它产出一张 ER 图。实体之间的关系（一对多、多对多）是 AI 写关联查询时最需要的上下文，比字段清单更常用。

### 两份清单之间，藏着一道交叉校对

这是整套流程里我觉得最巧的一步：**让 AI 对照接口清单和数据模型清单，自己找出不一致的地方，自己修到自洽**。

原理很简单：接口清单是扫 Controller 产的，数据模型清单是扫 Entity 和建表 SQL 产的，两次独立扫描，结果之间必然有不一致：接口文档里写着 `userName`，Entity 里叫 `username`；接口返回里有 `deptName`，数据模型里根本没有这个字段。

这些不一致平时散落在两个文件里，谁也不会发现。让 AI 交叉比对一次，全部现形。现形的还不只是文档问题。有些不一致是代码本身留下的历史债，文档说一套、代码做一套。这种地方 AI 修不了，但它会在 summary 里报出来，那就是你该去还的债。

## 五、AGENTS.md：补上篇没讲的两块

AGENTS.md 的五部分结构、200-300 行的地图定位，上一篇讲过了，不重复。这篇补两个上篇没展开的点。补完是六部分，文末的分步指令也按六部分写。比上篇一键版多出来的那一节，就是下面这张表。

### 一块是"AI 加载指引"表格

AGENTS.md 里我建议加一张表，告诉 AI 什么任务读什么文件：

```markdown
## AI 加载指引

| 任务类型 | 启动前必读 | 需要时参考 |
|---------|-----------|-----------|
| 新增/修改接口 | rules/api-spec.md | docs/api-list.md |
| 涉及数据库变更 | rules/db-spec.md | docs/data-model.md |
| 新增页面/组件 | rules/frontend-spec.md | docs/module-deps.svg |
| 排查线上问题 | docs/external-deps.svg | docs/api-list.md |
```

没有这张表，AI 的行为是"全部读一遍"或"凭感觉挑一张读"。有了它，加载行为从概率变成确定。这正好是理解层要交付的东西。

表里没有 `rules/prompt-rules.md`，不是漏了。行为约束那一份每次对话都要读，不按任务类型挑，所以它不进这张表，而是常驻在 AGENTS.md 的"关键约定"里。三层怎么设计是第 4 篇的事，这里你只要知道它归哪一节管。

### 另一块是"关键约定"为什么不直接写规则

上篇样例里，"关键约定"那一节只有四条指向 `rules/` 的链接，一条具体规则都没写。你可能会问：规则直接写 AGENTS.md 里不是更快？

不建议。原因还是那张地图：AGENTS.md 每次对话都全量加载，规则直接写进去，文件会越滚越大，300 行的红线很快就破。放 rules/ 目录、按主题拆文件、靠加载指引按需读取，AGENTS.md 才能一直保持索引的体量。

至于 rules/ 里那三层约束（Always / Ask First / Never）怎么设计，是下一篇的主题。

## 六、这五份资产，生成完只是开始

最后回答"被谁消费"。

五份资产不是生成完就躺在 docs/ 里。整个系列后面讲的六步工作流里，第二步 explore 就是它们的消费方：接到一个需求，AI 启动探索代理，读 AGENTS.md 定位规矩，读三张图建立结构认知，读两份清单知道有哪些接口和数据模型可以复用，然后给出影响面分析：这个需求要动哪些文件、影响哪些模块、有什么风险。

没有理解层，explore 就是"管中窥豹"：你手动贴几个文件给它，它基于这几个文件做判断，其余靠猜。有了理解层，它自己扫，扫出来的是全局。

这也是为什么校对那 10 分钟不能省——你在给后面每一次开发任务修地图。

## 七、校对清单

把每份资产的校对重点汇总成一张表，10 分钟照着过一遍：

| 资产 | 校对重点 | 典型错误 |
|------|---------|---------|
| 架构图 | 分层是否符合实际部署；一句话职责是否准确 | 不分层；职责描述张冠李戴 |
| 模块图 | 是否只含内部模块；循环依赖清单 | 把 pom 依赖全画进来 |
| 依赖图 | 三类是否分清；"挂了影响什么"是否标注 | 外部 API 漏提取 |
| 接口清单 | 返回结构、分页格式、Base path | 字段名推断错误 |
| 数据模型清单 | 是否只含核心字段；ER 关系 | 字段全量罗列，重点淹没 |
| AGENTS.md | 启动命令真跑一遍；加载指引覆盖主要任务类型 | "怎么跑起来"跑不起来 |

最后一行多说一句：AGENTS.md 里"怎么跑起来"写的命令，你必须亲手跑一遍。这是全部校对里唯一没法靠“看”完成的：启动命令跑不通的 AI，后面每次自验证都是空转。

## 八、可带走的三件事

1. **三张图各管一个视角**：架构图防"不分层、没职责"，模块图防"把依赖当模块"，依赖图最值钱的一列是"挂了影响什么"。
2. **两份清单必须交叉校对一次**：两次独立扫描必然不一致，让 AI 自己比对、自己修，现形的不一致里藏着代码的历史债。
3. **AGENTS.md 靠加载指引表保持索引体量**：规则放 rules/ 按需加载，AGENTS.md 永远只当地图。“怎么跑起来”的命令亲手跑一遍，这是唯一不能靠看的校对。
分步版实操指令（与上篇一键版等价，适合想一步步来的同学）已按手册原文整理，直接复制改路径即可：

```text
# ① 架构图
请帮我画一张架构图，保存到 docs/architecture.svg。
要求：
1. 按分层画：前端层 / 后端服务层 / 数据层
2. 每个模块用方框，框内写"模块名 + 一句话职责"
3. 箭头表示调用方向，箭头上方标注调用方式（HTTP/gRPC/消息队列）
4. 用不同颜色区分：你自己写的模块 vs 中间件 vs 外部系统

# ② 模块依赖图
请帮我画一张模块依赖图，保存到 docs/module-deps.svg。
要求：
1. 只画项目内部模块（controller / service / repository / model / client / config）
2. 不画外部依赖（Maven 依赖、中间件、第三方 API 都不画）
3. 箭头表示"依赖于"，箭头上方标注依赖原因（如"调用查询接口"）
4. 如果发现循环依赖，用红色标出，并在图下方列出循环依赖清单
5. 每个模块框内写"模块名 + 一句话职责"

# ③ 外部依赖图
请帮我画一张外部依赖图，保存到 docs/external-deps.svg。
要求：
1. 分三类：语言依赖 / 中间件 / 外部 API，用不同颜色区分
2. 语言依赖：从 pom.xml（或 package.json）提取，标注版本号
3. 中间件：从 application.yml 提取，标注用途
4. 外部 API：从代码里的 RestTemplate / FeignClient 调用提取，标注 API 提供方
5. 标注每个依赖的"如果它挂了，影响什么功能"

# ④ REST 接口清单
请扫描 src/main/java 下所有 Controller 类，产出一份 REST 接口清单，保存到 docs/api-list.md。
要求：
1. 按业务模块分组（如"需求管理模块""用户管理模块"）
2. 每个接口包含：HTTP 方法、路径、入参类型、出参类型、一句话说明
3. 标注项目的统一返回格式（如 ApiResponse<T>）和分页格式（如 PageResult<T>）
4. 标注 Base path 前缀（不同模块可能不同）

# ⑤ 核心数据模型清单
请扫描 src/main/java 下所有 Entity 和 DTO 类，产出一份核心数据模型清单，保存到 docs/data-model.md。
要求：
1. 按实体分组，每个实体只列"改了就影响全局"的核心字段
2. 标注每个字段的类型和含义
3. 同时生成一份 ER 图（保存到 docs/data-model-er.svg），展示实体间的关系

# ⑥ 交叉校对
请对照 docs/api-list.md 和 docs/data-model.md，找出两者不一致的地方，
列出清单并逐项修正，直到两份清单自洽。修不了的在最后标出来。

# ⑦ 生成 AGENTS.md
请基于 docs/ 下的所有产出，生成项目根目录的 AGENTS.md。
包含六部分：项目定位、核心架构、关键模块、关键约定（指向 rules/ 链接）、
AI 加载指引表格、怎么跑起来（含验证方式）。
整体控制在 300 行以内，不要把 docs/ 的内容复制进来。
```

## 下一篇预告

**第 4 篇：《让 AI 听话：Always / Ask / Never 三层约束》**

五份资产让 AI 看见了项目。但“看见”不等于“听话”：它知道了规矩在哪，不代表它会守规矩。下一篇讲约束层：为什么规则要分三级、哪些事必须先问你、哪些事碰都不许碰，以及怎么让"不听话"从靠自觉变成靠机制。

上一篇说过那条标准：每条规则写完，问一句"AI 或 CI 能自动判断它有没有被遵守吗"。下一篇回答的就是——判断完之后，怎么让判断结果真的拦得住它。


这个系列只讲一件事：怎么用工程化的方法，把 AI 编程从"碰运气"变成"可预期"。

让 AI 看见：三张图 + 两份清单 + 一套规约

AI 扫出来的项目文档一定有误差，而误差会传染。这篇讲五份资产怎么校对：三张图各管一个视角，两份清单必须交叉比对一次，AGENTS.md 靠加载指引表保持索引体量。10 分钟照着过一遍，你是在给后面每一次开发任务修地图。

人工智能

编程语言

开发工具

AI编程工程化实践中，通过三张俯视图、两份清单和AGENTS.md建立项目理解层，解决AI生成代码的"对不对"问题。强调交叉校对消除文档不一致，并设计加载指引表实现按需读取，将AI编程从碰运气变为可预期。

消息队列

数据结构

代码解释

中间件

数据库

AI编程

路由

MySQL

Redis

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

让 AI 看见：三张图 + 两份清单 + 一套规约-腾讯云开发者社区-腾讯云

让 AI 看见：三张图 + 两份清单 + 一套规约

让 AI 看见：三张图 + 两份清单 + 一套规约

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐