Vibe Coding 不是随便写：给 AI Agent 的项目治理上手指南#

(以下文章内容是以React、Nextjs、Supabase、Better auth、SEO/GEO全栈架构项目为模板）

很多人第一次使用 AI Agent IDE 时，都会经历同一个阶段：看起来什么都能改，实际上改完哪里都可能坏。

它可以很快生成页面、接口和脚本，却未必知道项目为什么这样组织、哪些文件不能碰、改完以后应该如何验证。于是，真正拉开效率差距的，不是“会不会写 Prompt”，而是有没有把项目治理规则交给 Agent。 Vibe coding 的核心不是让 AI 随便写，而是让 AI 在清晰的边界内持续交付。

一、先建立一个共识：Agent 缺的不是能力，而是上下文#

一个新加入项目的人，通常需要先了解四件事：项目做什么、代码放在哪里、如何启动和验证、哪些约束必须遵守。

AI Agent 也一样。只不过人可以通过几天的沟通慢慢补齐上下文，Agent 每次打开任务时都需要一个稳定、可读、可执行的入口。

这个入口通常就是项目根目录下的 AGENTS.md。它不是“给 AI 看的 README”，而是项目的协作协议：

• 说明项目目标和技术栈；
• 规定开发、测试、构建和发布命令；
• 记录代码风格、目录边界和不可违反的规则；
• 指向认证、国际化、UI、API 等领域文档；
• 告诉 Agent 修改后必须同步哪些文档。

如果一个规则只存在于某个人的记忆里，它就无法稳定地约束 Agent，也无法稳定地约束团队。

二、AGENTS.md 应该写什么#

一份能真正发挥作用的治理文件，不需要写成百科全书，但应该覆盖下面这条最短路径：认识项目 → 执行任务 → 修改代码 → 验证结果 → 更新知识。

1. 项目概览：让 Agent 先知道“为什么”#

不要只写“这是一个前端项目”。应该交代产品目标、主要用户、核心页面和当前阶段。

例如：

# Project Overview

这是一个面向开发者的内容站点，使用 Astro 构建，内容以 Markdown/MDX 管理。
新增文章优先放入对应的 content collection，并遵循现有 frontmatter schema

这几句话看似简单，却能减少大量错误决策：Agent 不会把内容站点当成后台管理系统，也不会在不必要的地方引入数据库或状态管理。

2. 技术栈和命令：把“怎么做”写成可执行信息#

技术栈要写版本敏感、行为敏感的部分；命令要写可以直接复制执行的部分。

## Development Commands

- 安装依赖：`pnpm install`
- 本地开发：`astro dev --background`
- 类型与 Astro 检查：`pnpm check`
- 生产构建：`pnpm build`
- 格式检查：`pnpm format`

尤其要写清楚开发服务器的启动方式、停止方式和日志查看方式。对 Agent 来说，“启动项目”不是一句口号，而是一个必须能被验证的动作。

3. 代码边界：明确哪些事情绝对不能做#

治理文件最有价值的部分，往往不是建议，而是禁令。

例如：

• 不要为了修复一个页面问题重写整个布局系统；
• 不要绕过现有 schema 直接添加未定义的 frontmatter 字段；
• 不要手动修改生成目录和依赖目录；
• 不要在没有验证的情况下声称任务完成；
• 不要删除已有标题大纲，除非用户明确要求；
• 不要为了“看起来更完整”擅自增加新的依赖或基础设施。

好的规则应该能帮助 Agent 做取舍。规则不是越多越好，而是要足够具体，能在冲突发生时给出答案。

三、不要把所有知识塞进一个文件#

AGENTS.md 适合做入口和索引，不适合承载所有实现细节。随着项目变大，应该把领域知识拆成独立文档：

AGENTS.md
docs/
├── AUTHENTICATION.md
├── INTERNATIONALIZATION.md
├── UI_DESIGN.md
├── BACKEND_API.md
└── STRUCTURED_DATA.md

根规则只需要说明“什么时候必须读哪份文档”：

### ALWAYS Read These Files Before:

- 修改认证流程前，阅读 `docs/AUTHENTICATION.md`
- 修改语言和路由前，阅读 `docs/INTERNATIONALIZATION.md`
- 修改 UI 组件前，阅读 `docs/UI_DESIGN.md`
- 修改 API 前，阅读 `docs/BACKEND_API.md`

这样做有两个好处。

第一，Agent 可以按任务加载上下文，不必每次读取整个项目。第二，领域文档可以独立演进，避免根目录规则文件变成没人敢修改的“知识垃圾场”。

四、把任务流程写成闭环，而不是一句“帮我改一下”#

一个可靠的 AI 协作任务，至少包含五个动作：

1. 理解：先检查相关文件和现有实现，不凭空设计。
2. 计划：列出准备修改的文件、原因和风险。
3. 实现：只修改任务范围内的内容，保留无关改动。
4. 验证：运行与改动匹配的检查、测试或构建命令。
5. 交付：说明改了什么、验证了什么、还有什么已知限制。

五、文档也要进入变更闭环#

最常见的治理漏洞是：代码改了，规则没改；新页面加了，项目结构没改；认证逻辑变了，认证文档还是旧的。

因此，AGENTS.md 应该明确文档同步关系：

这张表的作用，是把“顺手更新文档”变成明确的交付条件。否则，文档更新永远会排在“下次再说”。

结语：把项目规则写下来，才是真正的自动化#

AI Agent 能把代码生产速度提高很多，但速度只会同时放大秩序和混乱。

没有治理时，Agent 是一个高产但不稳定的实习生；有了清晰的上下文、边界和验证闭环，它才会逐渐变成一个可靠的协作者。

项目治理不是限制 AI 的护栏，而是让 AI 能放心加速的路面。

如果你正在维护一个 vibe coding 项目，你可以直接下载这份 AGENTS.md 项目治理模板，复制到项目根目录后，再根据真实项目的架构结构补充/修改内容。

然后你可以这样给一组Prompt给AI agent

请完善AGENTS.md内容,我的要求是: 尽量指出风格和方向性的内容以及绝对不能出现的规则
1. 以AGENTS-example.md的大纲为基准, 更新到项目中, 切勿删除任意一个标题大纲
2. 然后结合现有的AGENTS.md内容以及当前项目的架构方案, 完善大纲内容

**注意: 缺少的功能或文档, 需要你分析项目已有的结构和架构方案, 然后来决定是否需要创建相应功能的独立文档, 如果创建了文档,需要在AGENTS.md引用, 如有不明确的疑问可以询问我**

模板不是最终答案。它的价值在于提供一套不会漏掉关键问题的检查清单；真正有效的内容，必须来自当前项目的代码、命令和团队约定。