AGENTS.md：AI 编码代理的“项目宪法”
在 AI 辅助开发工具（如 Cursor、WorkBuddy、TraeWork等）日益普及的背景下，如何让 AI 准确理解项目背景、遵循团队规范、避免“瞎搞”，成为一个现实问题。AGENTS.md 正是在这种需求下形成的社区约定——它是一份存放在项目根目录的 Markdown 文件，专门用于指导和约束 AI 编码代理的行为。
它的核心定位是：项目级系统提示词，相当于给当前代码仓库“量身定制”的 AI 使用说明书或“项目宪法”。
一、专业术语
根据文件中的讨论，AGENTS.md 在专业领域有以下几个标准称呼：
1. AGENTS.md 文件 / AI 代理行为规范文件 现代 AI 辅助开发工具会自动识别该文件名，并将其内容作为系统级上下文注入 AI 的对话或代码补全中。 2. 项目级系统提示词（Project-level System Prompt） 相当于给当前工作区专属定制的“AI 宪法”，优先级高于 AI 的通用默认设定。 3. 项目上下文注入文件（Project-level Context Injection File） 一种开放格式的 Markdown 文件，专用于指导 AI 编码代理理解项目上下文与规则。
二、AGENTS.md 的核心作用
它就像一个“AI 实习生入职手册 + 操作红线清单”，从四大维度对 AI 进行硬性约束：
1. 环境锁定（Environment Locking） • 强制锁定 Git 提交身份，避免因本地默认用户名导致推送失败 • 明确锁定后端/前端的绝对路径和对应远程分支，防止 AI 改错目录 2. 操作安全红线（Operational Safeguards） • 禁止危险命令（如 git add -A、git push） • 强制按需提交，避免误传配置文件到远程仓库 3. 可追溯性规范（Traceability Mandate） • 强制“改前先备份”和“改后记日志” • 定义增量包存放规范，确保交付内容结构化 4. 边界隔离（Boundary Isolation） • 严格限定操作范围在项目目录内 • 禁止 AI 误操作到其他项目或外部系统文件
三、AGENTS.md 与 SKILL.md 的区别
在文件中，讨论者还明确区分了 AGENTS.md 与 SKILL.md 的职责：
| 维度 | AGENTS.md | SKILL.md |
|---|---|---|
| 性质 | 声明式（Declarative） 告诉 AI “世界是什么样的” | 过程式（Procedural） 告诉 AI “遇到故障怎么干” |
| 核心内容 | 静态知识图谱（目录、分支映射、禁止条款） | 动态决策树（如果报错 X，则执行方案 B） |
| 生命周期 | 每次对话自动加载，常驻后台 | 按需加载（仅当识别到特定意图时才触发） |
| 类比 | 公司规章制度 | 员工手中的专用工具箱 |
简单来说：AGENTS.md 确保 AI “不闯祸”，SKILL.md 教会 AI “干脏活”。两者共同构成了 AI 编码代理的完整治理体系。
四、执行机制
当你在这个项目根目录下启动 AI 工具时，AGENTS.md 会以“硬约束”形式加载到 AI 的短期记忆中。AI 在生成命令（如 git add、mkdir、rm）前，会优先比对这份规则清单；如果违反规则，AI 会主动阻止自己执行或向用户报错。
简而言之，这份文件将你隐性的开发管理经验——如“别动配置文件”、“记得备份”、“别乱推代码”——转化为了 AI 显性必须遵守的规则逻辑。
说明：
• AGENTS.md 是一种社区约定，并非强制性标准，但已被主流 AI 编码工具广泛支持。
• 部分工具（如 Cursor 旧版）使用 .cursorrules 作为等效文件。
• AGENTS.md 为静态约束文本，不包含可执行代码。
• 如需定义可执行工作流，应使用 SKILL.md 或类似机制。