把 AI 引进真实项目后，我最先补的不是功能，而是仓库入口

最近整理 Sourcelin Blog 这套微服务博客系统时，我越来越确定一件事： AI 真正难的不是“会不会写代码”，而是进了一个真实项目之后，能不能长期保持边界稳定、规则一致、输出不发散。

所以这篇我不聊某个具体功能，而是先聊一个更底层的问题： 为什么我在这个项目里，第一步不是让 AI 写页面、写接口，而是先把仓库入口、规则和执行边界补齐。

我现在看很多项目引入 AI，最容易犯的一个错，就是把 AI 当成“高级补全工具”，一上来就让它写页面、补接口、改样式。

短期看当然能出结果，但只要项目稍微复杂一点，很快就会出现几个问题：

• 这次改法和上次不一样
• 前台、后台、后端的边界开始混
• 接口字段改来改去
• 两周后再接着做，AI 像重新进了一个新项目

我在整理 Sourcelin Blog 的时候，后面越来越确定一件事： AI 进入一个真实项目，第一步不是写代码，而是先读懂仓库入口和长期规则。

项目入口：

• 在线演示：sourcelin.cn
• Gitee：gitee.com/my_lyq/sour…
• GitHub：github.com/SourceLin/s…

这个项目里，入口不是一句话，而是一套文件

Sourcelin Blog 里，我把这层入口拆成了三部分：

• AGENTS.md
• rules/
• skills/

这三层配合起来，AI 才知道：

0. 仓库里有哪些模块
1. 哪些边界不能碰
2. 这类任务应该怎么走流程

举个最直接的例子，仓库根 AGENTS.md 已经把主结构写得很明确：

sourcelin-api/        # Feign 接口与跨服务 DTO
sourcelin-common/     # 公共能力
sourcelin-gateway/    # 网关
sourcelin-auth/       # 认证中心
sourcelin-modules/    # 业务服务
sourcelin-ui/sourcelin-ui-platform/ # 博客前台
sourcelin-ui/sourcelin-ui-admin/    # 管理后台

如果没有这层入口，AI 很容易把本来应该落在 sourcelin-modules/sourcelin-blog 的逻辑塞进公共模块，或者把前台写成后台那一套风格。

我现在会怎么让 AI 先“入场”

我不会再说“帮我做个功能”，而是先给它一个项目级提示：

你现在在 Sourcelin Blog 仓库中工作。
先阅读仓库根目录 AGENTS.md，再按任务读取 rules/README.md 与对应领域规则。
如果是后端任务，读取 rules/backend.md；
如果是博客前台任务，读取 rules/frontend-platform.md；
如果是管理后台任务，读取 rules/frontend-admin.md；
涉及接口或分页时，必须同时遵守 rules/api-contract.md。
​
输出要求：
1. 默认使用中文沟通
2. 只修改与任务直接相关的文件
3. 保持 ApiResponse / PageResult 契约一致
4. 修改后给出实际执行过的验证命令和结果

这段提示词看起来不复杂，但实际效果非常大。 它不是在告诉 AI“写什么功能”，而是在告诉它“先按什么边界工作”。

为什么我觉得 rules/ 比“临时聊天说明”更重要

很多约定如果只放在聊天里，AI 每一轮都可能重新猜一次。

比如这个项目里，rules/api-contract.md 已经把接口约束写死了：

- MUST：对外 REST JSON 成功响应统一为 ApiResponse<T>
- MUST：成功码固定为 0
- MUST：分页字段固定为 items、total、page、pageSize、totalPages
- MUST NOT：前端使用 items ?? list 兼容旧字段

这类规则最大的价值不是“规范”，而是减少 AI 的自由发挥。

我在这个项目里得到的一个结论

一个仓库如果想长期用好 AI，核心不是“提示词写得多花”，而是有没有把这些东西沉淀到仓库里：

• 执行入口
• 长期规则
• 任务流程
• 验证习惯

这也是为什么 Sourcelin Blog 里除了代码本身，我一直在补 AGENTS.md、rules/ 和 skills/。

你可以直接拿去用的步骤

如果你也准备把 AI 引进自己的项目，我建议顺序是：

0. 先写一个仓库入口文件
1. 再把接口、目录、验证规则收口
2. 然后再让 AI 介入真实任务

反过来做，短期可能更快，但中后期返工会明显增加。

代码和目录参考

• AGENTS.md
• rules/README.md
• rules/api-contract.md
• rules/backend.md
• rules/frontend-platform.md
• rules/frontend-admin.md
• skills/README.md

目录结构

这类任务里 AI 最容易跑偏的点

• 只让它“做功能”，不让它先读规则
• 把前台、后台、后端混成一轮任务
• 没有告诉它改完后要怎么验证

我现在更认可的做法是： 先让 AI 学会“不乱动”，再让它开始“动得快”。

如果你现在也在把 Codex、Cursor、Claude Code、OpenCode、Qoder、Trae 这类工具往真实项目里接，这一层入口设计比 prompt 细节更重要。

项目地址再放一次：

• 在线演示：sourcelin.cn
• Gitee：gitee.com/my_lyq/sour…
• GitHub：github.com/SourceLin/s…