AGENTS.md 实践指南：让 AI 编码代理从"通用助手"变身"项目专属开发专家"

“README.md 是给人类开发者看的项目介绍，而 AGENTS.md 是专门给 AI 读的、项目专属的’宪法’。”
AGENTS.md 是 AI 编码时代的项目级 System Prompt，目前已被超 6 万个开源项目采用，几乎所有主流 AI 编码工具均原生支持。

本文系统介绍 AGENTS.md 的定义、核心理念、五大实践方案、完整编写模板与项目结构，帮助团队快速落地”一份文件，全工具兼容”的 AI 编码规范。

---

一、AGENTS.md 是什么

AGENTS.md 是一个开放、基于 Markdown 的标准化规范，是专为 AI 编码代理（AI Coding Agent）设计的项目专属操作手册，通常放置在项目根目录（支持子目录嵌套），与 README.md 同级。

对比维度	README.md	AGENTS.md
目标读者	人类开发者	AI 编码代理
核心内容	项目介绍、使用说明、贡献指南	编码规范、开发命令、权限边界
维护频率	低（核心信息稳定）	高（持续迭代优化）
格式	自由描述	结构化、指令化

本质：仓库级的标准化 System Prompt，用于统一 AI 在项目内的编码行为、规范、流程与权限边界。

发展历程：2025 年由 OpenAI、Google、Cursor、Factory 等厂商与社区联合提出；2025 年 12 月被捐赠给 Linux 基金会旗下的 Agentic AI Foundation（AAIF）进行中立开源治理。

🔗 参考资料：AGENTS.md 官方市场

---

二、没有 AGENTS.md 的核心痛点

在没有 AGENTS.md 的日子里，AI 辅助开发面临五大共性困境：

#	痛点	具体表现
1	配置碎片化，维护成本极高	不同 AI 工具都有专属配置文件（如 .cursorrules、CLAUDE.md、.copilotrules），同一项目需维护多套规则
2	AI 行为不可控，返工成本高	没有统一指令约束，AI 生成的代码风格、架构设计与项目规范严重脱节
3	上下文冗余，模型效率下降	每次对话都要重复投喂项目架构、规范、命令等信息，占用大量上下文窗口
4	大型项目协作混乱	Monorepo/多模块项目中，单靠对话无法让 AI 精准适配，跨模块开发极易出现规则冲突
5	团队标准不统一	不同开发者给 AI 的 Prompt 风格不一，AI 输出代码质量参差不齐

---

三、核心理念：六大设计原则

AGENTS.md 的设计围绕以下六大核心理念：

#	理念	说明
1	人机文档分离	README.md 面向人类，AGENTS.md 专供 AI，互不干扰
2	标准化与互操作性	统一开放格式，”一份文件，全工具兼容”
3	轻量无依赖	纯 Markdown 语法，无复杂配置语法和额外依赖
4	最小必要上下文	只给 AI 提供必须的可执行指令，拒绝哲学化描述
5	分层优先级设计	支持”根目录全局规则 + 子目录专属规则”的嵌套模式
6	可执行性优先	所有指令必须具体、可落地、可直接执行

---

四、五大核心实践方案

🗂️ 实践一：仓库聚合（Monorepo）

问题：前后端或相关项目分仓，导致 AI 编码时上下文割裂。

方案：将项目重构为 monorepo（单一代码仓库），使 AI 能在同一上下文中进行全栈开发。

# 存量项目的过渡方案：聚合脚本
project-root/
├── src/                 # 主项目源码
├── reference-projects/  # 聚合的子仓库（通过脚本同步，.gitignore 排除）
│   ├── backend-api/     # 后端 API 子仓库
│   └── shared-utils/     # 公共工具子仓库
└── AGENTS.md            # AI 全局规则

---

⚙️ 实践二：统一环境配置

问题：本地环境配置不统一，AI 无法自主启动和验证项目。

方案：

1. 将环境变量统一置于 ~/.<project>_env 文件，由启动脚本自动加载
2. 提供封装好的一键启动脚本（如 ./scripts/start-server.sh），处理构建、进程管理、健康检查等复杂逻辑

# 一键启动脚本示例
#!/bin/bash
source ~/.<project>_env    # 加载环境变量
make build                  # 构建项目
make start                  # 启动服务
curl -f http://localhost:8080/health || exit 1  # 健康检查

---

✅ 实践三：验证闭环

目标：让 AI 的工作产出从”代码可编译”升级为”功能可运行”。

方案：定义严格的验证规范，特别是为 API 测试设计标准化的 curl 命令模板：

# 标准化 curl 模板（命令独立执行，使用临时文件中转数据）
curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d @/tmp/user_payload.json

# user_payload.json 内容
{
  "username": "test_user",
  "email": "test@example.com"
}

关键原则：命令独立执行 + 临时文件中转，避免 Shell 环境差异。

---

🔍 实践四：自动化检查

理念：写在 AGENTS.md 中的规则必须有自动化检查来保障执行力。

方案：为关键架构约束（如分层依赖规则）编写检查脚本，并通过 Makefile 提供统一入口：

# Makefile 示例
.PHONY: lint-arch
lint-arch:
    @scripts/check_arch.sh || { \
        echo "=== WHAT ==="; cat /tmp/arch_error/what.txt; \
        echo "=== WHY ==="; cat /tmp/arch_error/why.txt; \
        echo "=== HOW ==="; cat /tmp/arch_error/how.txt; \
        exit 1; }

检查脚本失败时，必须输出 WHAT（什么错了）+ WHY（为何不允许）+ HOW（如何修复），让 AI 能直接根据指引修复问题。

---

📚 实践五：参考项目引入

问题：AI 不认识私域组件、内部项目或特定开源代码的细节。

方案：通过 git submodule 直接将相关项目的源码引入到本地的 reference-projects/ 目录，同时为每个参考项目配一份架构说明文档：

reference-projects/
├── legacy-auth-system/     # 通过 git submodule 引入
│   ├── ref-auth-system.md  # 架构说明文档
│   └── src/
└── internal-lib/           # 内部工具库
    ├── ref-internal-lib.md
    └── src/

---

五、四大实践场景

场景 1：中小型单体项目（最常用）

根目录放置唯一的 AGENTS.md 文件，覆盖项目全量核心规则，适配 90% 以上的单体项目。

关键原则：所有规则必须量化，而非模糊表述。

模糊表述 ❌	量化表述 ✅
“编写高质量代码”	“函数行数不超过 50 行”
“代码要简洁”	“圈复杂度上限为 10”
“注意代码风格”	“注释率不低于 20%”

迭代闭环：每次 AI 出现错误、踩坑后，将对应约束规则补充到 AGENTS.md 中，持续优化。

---

场景 2：大型 Monorepo / 多模块项目

采用”全局 + 局部”的分层嵌套式管理，实现细粒度管控。

monorepo-project/
├── AGENTS.md                    # 根目录全局规则：安全合规底线、通用工具链规范
├── apps/
│   ├── web-admin/
│   │   └── AGENTS.md           # 管理后台专属规则（优先级 > 根目录）
│   └── h5-mobile/
│       └── AGENTS.md           # H5 移动端专属规则（优先级 > 根目录）
├── packages/
│   ├── components/
│   │   └── AGENTS.md           # 公共组件库规则
│   └── utils/
│       └── AGENTS.md           # 工具库规则
└── docs/
    └── AGENTS.md               # 文档目录专属规则

行业案例：OpenAI 主仓库使用 88 个 AGENTS.md 文件，分别对应不同业务模块，实现极致精准的 AI 行为控制。

---

场景 3：团队协作

将 AGENTS.md 纳入项目标准化流程，作为代码仓库的必备文件，由团队共同维护。

• 统一标准：所有开发者使用 AI 时，都遵循统一的项目规则，避免个人 Prompt 带来的输出差异
• 新人入职：新成员可通过 AGENTS.md 快速让 AI 适配项目，降低项目熟悉成本

---

场景 4：安全与权限

• 写保护机制：所有兼容工具均支持 AGENTS.md 写保护，AI 无法擅自修改核心规则
• 三级权限边界：

权限等级	行为	示例
✅ 可直接执行	读取代码、执行标准命令	读取 src/、执行 pnpm dev
⚠️ 需用户确认	修改配置文件、核心架构	修改 .eslintrc.js
❌ 绝对禁止	高危系统命令、未经审核依赖	rm -rf /、引入未审核的 npm 包

---

六、为什么选择 AGENTS.md

#	优势	说明
1	极致降本提效	一次编写，全工具兼容，减少重复上下文投喂
2	标准化 AI 开发流程	统一项目内 AI 的行为规范，降低 Code Review 和返工成本
3	零门槛快速接入	纯 Markdown 格式，只需新增一个文件即可接入所有兼容工具
4	全场景适配	从个人项目到超大型企业级 Monorepo 都能完美适配
5	中立开源无厂商锁定	Linux 基金会 AAIF 中立治理，不被单一厂商专有格式绑定
6	安全可控	自带写保护机制 + 权限边界定义，精准管控 AI 操作范围

---

七、完整编写模板（可直接复用）

以下模板适用于大多数项目，可根据实际技术栈调整：

# AGENTS.md - [项目名称] AI 编码代理操作手册

## 1. 项目核心概览
- **项目类型**：[例如：企业级中后台管理系统 / 前端组件库 / 后端微服务框架]
- **核心功能**：[一句话说明项目的核心用途与业务目标]
- **技术栈**：[例如：Vue3 + TypeScript + Vite + Pinia / Spring Boot 3 + Java 17]
- **架构说明**：[例如：前后端分离架构 / Monorepo 多包架构]
- **项目底线约束**：[例如：必须兼容 Node.js 18+ / 禁止引入未经安全审核的依赖]

## 2. 项目结构与核心目录说明

[项目根目录]/
├── AGENTS.md # 本文件，AI代理全局规则（禁止AI擅自修改）
├── README.md # 项目人类可读说明文档
├── src/ # 核心源码目录
│ ├── api/ # 接口请求封装
│ ├── components/ # 公共通用组件
│ ├── pages/ # 业务页面代码
│ ├── utils/ # 通用工具函数
│ └── assets/ # 静态资源文件
├── tests/ # 单元测试/集成测试目录
└── scripts/ # 构建和部署脚本

- **目录读写权限**：[例如：仅可直接修改 src/pages/、src/components/，修改配置文件需用户手动确认]

## 3. 标准开发与执行命令
> 所有操作必须使用以下指定命令，禁止使用其他替代命令

- **安装依赖**：`[例如：pnpm install]`
- **本地启动开发服务**：`[例如：pnpm dev]`
- **生产环境构建**：`[例如：pnpm build]`
- **运行全量单元测试**：`[例如：pnpm test]`
- **运行代码格式检查**：`[例如：pnpm lint]`
- **代码自动格式化**：`[例如：pnpm format]`
- **其他核心命令**：[例如：pnpm db:migrate 数据库迁移]

## 4. 代码规范与编写约束
- **语言与语法**：[例如：强制使用 TypeScript 严格模式，禁用 any 类型]
- **命名约定**：[例如：组件使用 PascalCase，函数/变量使用 camelCase]
- **代码质量约束**：[例如：单个函数行数不超过 50 行；圈复杂度上限为 10]
- **异常处理规范**：[例如：所有异步请求必须有 try/catch 异常捕获]

## 5. Git 与提交规范
- **分支管理规则**：[例如：feature/xxx 开发分支，bugfix/xxx 修复分支，禁止直接提交到 main 分支]
- **Commit 提交格式**：[例如：`<type>(<scope>): <subject>`，type 可选值：feat/fix/docs/style/refactor/test/chore]
- **PR/MR 规则**：[例如：提交 PR 前必须完成全量测试与 Lint 检查]

## 6. AI 代理行为准则与权限边界
### 核心工作原则
1. 所有操作必须严格遵循本文件定义的规则，优先适配本项目的专属约定
2. 代码编写必须先理解现有项目的架构与风格，保持与现有代码的一致性
3. 执行任何修改前，必须先读取相关文件，充分理解上下文，禁止凭空生成代码
4. 完成代码编写后，必须先执行 Lint 检查与相关测试，确保无报错、无警告，方可提交

### 权限边界
- ✅ 可直接执行：读取项目内所有代码文件；执行本文件定义的标准开发命令
- ⚠️ 需用户确认后执行：修改项目配置文件；修改核心架构代码
- ❌ 绝对禁止执行：擅自修改/删除本 AGENTS.md 文件；执行高危系统命令

## 7. 异常处理与兜底规则
- 当遇到本文件未定义的规则时，优先参考项目内已有的代码风格与约定
- 当执行命令报错时，优先查看项目内的错误日志与已有解决方案，无法解决时及时向用户反馈
- 当用户需求与本文件规则冲突时，优先向用户确认，以用户的明确指令为准

---

八、项目结构全景图

单项目结构（中小型项目）

your-project/
├── AGENTS.md          # 根目录主文件（推荐全大写命名，唯一主入口）
├── AGENT.md           # 备用兼容文件，单数形式，优先级低于 AGENTS.md
├── README.md          # 面向人类的项目说明文档
├── src/               # 项目核心源码
├── tests/             # 测试用例
└── package.json       # 项目依赖配置

Monorepo 结构（大型项目）

monorepo-project/
├── AGENTS.md                    # 根目录全局规则：组织级通用规范、安全合规底线
├── README.md                    # 项目整体说明
├── package.json                 # 全局依赖配置
├── pnpm-workspace.yaml          # monorepo 工作空间配置
├── apps/
│   ├── web-admin/
│   │   └── AGENTS.md           # 管理后台子项目专属规则（优先级 > 根目录）
│   └── h5-mobile/
│       └── AGENTS.md           # H5 移动端子项目专属规则（优先级 > 根目录）
├── packages/
│   ├── components/
│   │   └── AGENTS.md           # 公共组件库专属规则
│   └── utils/
│       └── AGENTS.md           # 工具库专属规则
└── docs/
    └── AGENTS.md               # 文档目录专属规则

---

九、价值总结

AGENTS.md 的本质是用最小的上下文成本，让 AI 获得最大的项目理解。

维度	价值
对 AI	提供精准上下文，让 AI 从”通用助手”变身”深度适配项目的专属开发专家”
对团队	沉淀隐性知识（编码规范、架构约束、开发流程），形成标准化的 AI 辅助开发流程
对项目	构建”打开即理解、改完即验证”的高效开发反馈回路

AGENTS.md 不是一个简单的配置文件，而是 AI 编程时代的项目协作事实标准，是跨厂商、跨工具的互操作性协议，是把开发者从重复人机沟通中解放出来的核心载体。