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

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

## 一、上一篇留了一个问题

上一篇说，Vibe Coding 的三个致命问题指向同一个根因：缺少工程化基础设施。

那这基础设施从哪来？

看到这个结论，第一反应大概是：这是团队的事。要开规范评审会，要拉齐技术选型，要等领导点头，最好还要有个专项。等这套流程走完，你用 AI 的热情早就凉了。

这篇想说的正好相反：这事你一个人就能开始。

不需要立项，也不需要说服任何人。你在自己的开发环境里用 AI，交出去的是代码本身。代码质量变好、效率提上去，这些变化是自然发生的，不用向谁证明。

规范是写给 AI 看的，不是写给领导看的。想通这一点，后面的事就简单了。

还有一个更实际的理由：等团队拉齐这件事，通常等不到结果。会开一次不够，开到第三次，人的热情已经凉了，文档还是空的。而你自己先把项目摸一遍，今天就能出东西。

## 二、30 分钟怎么花

先纠正一个预期。一听"建立规范"，脑子里浮现的通常是对着空文档憋一下午。实际不是。30 分钟里，你只动手两次，中间 20 分钟是 AI 的。
![image.png](https://developer.qcloudimg.com/http-save/yehe-12408676/bc15498f3b6ca096b703e9b553f7afb1.png)

### 前 5 分钟：发一条指令

把这段话发给 AI：

```text
帮我完整摸清当前这个项目，产出一整套 AI 协作基础设施。
整个过程你自主推进，遇到问题自己修、自己 review、自己决定下一步，不要每一步都问我。

请按以下顺序执行：

第一步：画三张全景图，保存到 docs/
- architecture.svg（分层架构图，核心模块写一句话职责）
- module-deps.svg（内部模块依赖，循环依赖红色标出）
- external-deps.svg（语言依赖 + 中间件 + 外部 API 三类，不同颜色标注）

第二步：梳理接口和数据模型
- docs/api-list.md（REST 接口清单，按模块分组）
- docs/data-model.md 和 docs/data-model-er.svg（含 ER 图）

第三步：对照以上两份清单，列出不一致的地方并修正，直到自洽

第四步：基于 docs/ 下的所有产出，生成项目根目录的 AGENTS.md
- 包含五部分：项目定位、核心架构、关键模块、关键约定、怎么跑起来
- 整体控制在 300 行以内，不要把 docs/ 的内容复制进来

自主原则：
- 每一步跑完自己 review 输出质量，不合格自己重跑
- 图里有漏、有错、有不清晰的，主动补充或重画
- 有判断不清的地方，先做一个合理选择，在最后的 summary 里标出来
- 全部跑完后，生成一份 summary：列出每个产出文件、内容概括、
  以及你认为还需要人工确认的地方
```

这段指令的关键不是"让它干活"，是最后那几行：别来问我。每一步自己检查自己重跑，拿不准的先做选择再标记，最后一次性汇报。你如果中途它问一句你答一句，30 分钟就变成 3 小时了。

### 中间 20 分钟：AI 自己跑

它产出五份资产，各管一件事：

- **三张图**：架构图看系统边界，模块图看项目内部，依赖图看它靠什么活着
- **两份清单**：接口清单告诉 AI 怎么调，数据模型清单告诉它数据怎么用
- **AGENTS.md**：项目常识手册，规矩放在哪儿也标在里面

这 20 分钟你去干别的。它会自己 review，不合格自己重跑，最后交一份 summary。summary 里标出它拿不准的地方。那几个地方，就是给你的校对清单。

### 最后 10 分钟：校对，这段不能省

AI 自己扫出来的东西一定有误差。回来只查三处：

1. 三张图里的模块职责，跟你认知里的架构对不对
2. 接口清单的统一返回格式、分页格式，跟项目实际的信不对
3. AGENTS.md 里"怎么跑起来"那一节，按它写的命令真跑一遍，能不能起来

为什么不省？从下一次对话开始，AI 写的代码都以这五份资产为地图。地图错一处，后面跟着错一片，而且往往要到联调才暴露。

举个真实的错法。你的项目统一返回体是 `{code, message, data}`，AI 扫代码时标成了 `{code, msg, data}`——就差一个字段名。之后它写的每个接口都按错的来，你要到联调的时候才会发现，然后一个一个改回来。校对 10 分钟，省的是这种事。

## 三、AGENTS.md 长什么样

校对完，你手里就有了一份 AGENTS.md。它是 AI 的项目常识手册，放在项目根目录，每次对话自动加载。长这样：

```markdown
# AGENTS.md —— AI 编程项目常识手册

## 项目定位
本项目是 XXX 管理系统，基于 Spring Boot 2.x + MySQL 5.7 构建。

## 核心架构
（引用 architecture.svg 的关键结论，1-3 句话）

## 关键模块
| 模块 | 职责 | 备注 |
|------|------|------|
| controller | 接口层 | 禁止在此层写业务逻辑 |
| service | 业务逻辑层 | 事务边界在此层 |
| repository | 数据访问层 | 禁止在此层写业务逻辑 |

## 关键约定
规则按主题放在 rules/ 目录，AI 按任务类型读需要的那一份：
- rules/prompt-rules.md：AI 行为约束（今天可以先空着）
- rules/api-spec.md：统一响应体、分页格式、错误码
- rules/db-spec.md：表设计规范、SQL 禁令
- rules/frontend-spec.md：组件与样式约定

## 怎么跑起来
1. 安装 JDK 1.8
2. 执行 mvn clean install
3. 启动主类 Application.java
4. 健康检查：GET /actuator/health 返回 UP
```

写法上有两条讲究，决定这份文件好不好用。

第一，它是地图，不是手册。控制在 200-300 行。判断标准很简单：**AI 不知道就会写出错误代码的信息**，放进来；AI 不知道只会写得不够好的信息，放 docs/ 详细文档，这里放个链接。把所有东西都塞进去，AI 的注意力被稀释，真正要紧的规则反而被淹没。

第二，"怎么跑起来"要写到 AI 能自己验证。健康检查端点、核心接口的 curl 范例、自检脚本。这样它改完代码能自己跑验证，而不是停下来等你测。

还有一处你可能注意到了：上面样例里"关键约定"那一节，我只放了一组指向 `rules/` 的链接，一条具体的规则都没写。

这么安排是有理由的。AGENTS.md 是地图，告诉 AI 项目长什么样；规则放在另一个目录里，告诉它代码该怎么写。地图一次就能画完，规则画不完。

那规则什么时候写？

## 四、rules/ 目录今天可以先空着

答案是：今天不写，也不在这 30 分钟里。

这是整篇最反直觉的一条。一次写全看起来最省事，写出来一下午，然后那份文件再也没被打开过。

先说清楚 `rules/` 是什么。它是一个目录，不是一份文件。规矩按主题拆成几份，AI 按任务类型读它需要的那一份：行为上的约束放 prompt-rules.md，接口格式放 api-spec.md，表设计和 SQL 放 db-spec.md，前端组件放 frontend-spec.md。今天你不需要知道每份里面写什么，只需要知道规矩往这儿放。

为什么不直接写进 AGENTS.md？地图每次对话全量加载，正文塞进去，300 行红线很快就被撑破。具体怎么按需加载是第 3 篇的事，这里你只要记住分工：AGENTS.md 放指针，rules/ 放正文。

那正文从哪来？等第一个 bug。

AI 写了一条没有 traceId 的日志，你补一条：日志必须携带 traceId。它想直接改表结构，你补一条：改表结构先问我。

这两个例子都属于行为约束，落在 prompt-rules.md 里。等后面接口格式、SQL 写法上踩了坑，再往 api-spec.md、db-spec.md 补。归置的事不用你现在操心，先记下来就行。

写的时候有一条标准，今天就能用：**每条规则写完，问一句"AI 或 CI 能自动判断它有没有被遵守吗？"** 能，才算规则；不能，那只是愿望。

拿上面那个 traceId 举例，同一个意思有两种写法：

```markdown
# 愿望
- 日志要规范

# 规则
- 日志必须携带 traceId，格式：log.info("[{}] 操作描述", traceId)
```

下面那条，AI 改完自己就知道有没有做到，CI 扫一遍也知道。上面那条，你跟它较劲三天也不会有结果。

攒到三五条，你的 rules/ 里就有十来行真正会被执行的东西了。至于这些规则怎么分成必须执行、先问再动、绝对禁止三层，那是第 4 篇的主题，今天不展开。

我自己的经验是，规则只能一点点长出来。头一个星期可能只攒五条，但每条都在真实任务里验证过，比一次写五十条从没被执行过的强得多。

## 五、三个你可能想问的

**我的项目很老很乱，AI 摸得清吗？**

我的看法是，越老的项目越该先摸一遍。摸不清是常态，但这恰恰是做这件事的理由。让 AI 画图这件事本身是一次架构体检：哪张图画不出来，或者画出来一团乱麻，说明架构本身有问题。这种情况下先修架构，再让 AI 写代码。AI 会在 summary 里告诉你它哪里拿不准，那几个地方就是你架构里最糊的地方。

**团队没人用这套，我一个人搞有什么用？**

你不需要任何人批准，因为产出是代码本身。效率差是攒出来的，攒到肉眼可见的时候，同事会来问你怎么做到的。那时候才轮到推广，那是第 8 篇的事。现在操心推广，属于还没学会走先想跑步姿势。

**校对完还要不要人工看代码？**

要。这 30 分钟让 AI 不用猜。至于查得准不准，那是自动化验证的活，第 5 篇专门讲。今天先把地图立起来。

## 六、可带走的三件事

1. **30 分钟你只动手两次**：开头发指令，结尾校对三处。中间 20 分钟是 AI 的，summary 里它标"拿不准"的地方就是你的校对清单。
2. **AGENTS.md 只当索引用**：200-300 行，放"AI 不知道就会写错代码"的信息，其余给链接。"怎么跑起来"要写到 AI 能自己验证。
3. **rules/ 先占位，规则等第一个 bug 再补**：每条必须能自动判断对错。判断不了的，不是规则，是愿望。

那条一键指令可以直接复制。建议先原样发一次，再按你项目的实际情况改。

## 下一篇预告

**第 3 篇：《让 AI 看见：三张图 + 两份清单 + 一套规约》**

今天只讲了怎么在 30 分钟里把这五份资产生成出来。第 3 篇把它们逐一拆开：每份资产长什么样、校对时重点看哪里、AI 在画图和扫清单时最容易在什么地方出错。今天的 30 分钟解决"有没有"，下一篇解决"对不对"。至于 rules/ 那个今天还空着的目录，什么时候往里填、填什么，第 4 篇讲。


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

一个人也能开始：30 分钟建立你的第一份 AI 编程规范

一个人 30 分钟就能建立第一份 AI 编程规范：发一条指令，AI 自主产出五份资产，你只需校对三处。规则不必一次写全，等第一个 bug 来了再补。

人工智能

编程语言

开发工具

从“碰运气”到“可预期”，30分钟搭好AI编程工程化基础设施。无需团队，个人即可用一键指令生成架构图、接口清单及AGENTS.md，通过校对与规则积累实现代码质量可控，提升AI协作效率。

代码解释

中间件

AI编程

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

一个人也能开始：30 分钟建立你的第一份 AI 编程规范-腾讯云开发者社区-腾讯云

一个人也能开始：30 分钟建立你的第一份 AI 编程规范

一个人也能开始：30 分钟建立你的第一份 AI 编程规范

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐