AGENTS.md 实战指南：如何让 AI 编程助手真正遵循项目规范
在使用 Cursor、Codex、Claude Code 等 AI 编程工具时，经常会遇到一个问题：
AI 能写出功能正确的代码，却不一定能写出符合项目规范的代码。
例如，你的项目明明已经有统一的技术栈和开发约定，但 AI 仍然可能：
- 使用项目中没有引入的第三方依赖。
- 直接在组件中调用接口，绕过现有的请求封装。
- 使用
any类型，破坏 TypeScript 类型约束。 - 随意创建新的目录或文件，忽略现有架构。
- 修改自动生成的代码，导致下次构建覆盖修改。
- 修改与当前需求无关的文件，扩大变更范围。
这些问题并不完全是模型能力不足造成的。
更常见的原因是：AI 没有获得足够明确、稳定且符合当前项目的上下文。
AGENTS.md 正是解决这一问题的一种方式。
它可以将技术栈、目录结构、编码规范、执行约束和验证要求统一记录下来，让 AI 编程助手在执行任务时有明确的项目级指导。
本文从实际开发出发，介绍 AGENTS.md 的作用、编写方法、推荐模板，以及如何把它融入日常 AI 辅助开发流程。
一、AGENTS.md 是什么？
AGENTS.md 是面向 AI 编程代理（Coding Agent）的项目指导文件，通常放置在项目根目录。
它使用 Markdown 格式，记录项目中需要 AI 理解并遵守的开发约定。
可以把它看成一份专门写给 AI 的项目开发手册。
传统开发工具已经有各自的配置文件：
| 配置文件 | 主要作用 |
|---|---|
eslint.config.js |
JavaScript / TypeScript 代码质量和风格检查 |
.prettierrc |
代码格式化规范 |
tsconfig.json |
TypeScript 编译与类型检查配置 |
package.json |
项目依赖、脚本与元数据 |
AGENTS.md |
为 AI 提供项目背景、开发约定和任务执行指导 |
两者的区别在于：
ESLint、Prettier 和 TypeScript 编译器主要通过确定性规则检查代码。
而 AGENTS.md 主要影响 AI 的代码生成和操作决策。
比如下面两条规则：
- 所有 API 请求必须统一放在 src/services/ 目录。
- Never 直接修改 src/generated/ 下的自动生成文件。
它们并不是普通的格式化规则，而是项目级的架构约束和操作边界。
需要注意，AGENTS.md 并不等同于强制执行的安全策略。AI 是否正确读取和遵循规则，取决于具体工具、上下文以及模型行为。
因此，AGENTS.md 负责提供指导，测试、Lint、代码审查和权限控制负责进一步验证与约束。
二、为什么 AI 编程需要项目规范？
我们先看一个简单的例子。
假设项目技术栈如下：
- React 19
- TypeScript
- Ant Design
- Less + CSS Modules
- 统一封装的 API 请求模块
现在要求 AI 实现一个复制文本按钮。
1. 没有项目规范时
AI 可能生成这样的代码：
export default function CopyBtn({ text }: any) {
return (
<button
style={
{ color: 'blue', padding: '4px 8px' }}
onClick={() => navigator.clipboard.writeText(text)}
>
Copy
</button>
)
}
这段代码可以完成基本复制功能，但存在一些项目规范问题：
- 使用
any，缺少明确的 Props 类型。 - 使用内联样式，没有复用项目的 CSS Modules。
- 组件命名为
CopyBtn，与团队命名约定可能不一致。 - 缺少复制失败处理。
- 没有使用项目现有的消息提示组件。
这些问题不一定会导致代码无法运行，但会增加后续维护和代码审查的成本。
2. 加入 AGENTS.md 之后
假设我们已经明确告诉 AI：
## Coding Style
- React 组件使用 TypeScript。
- Props 使用 interface 定义。
- 组件名称使用 PascalCase。
- 样式统一使用 Less + CSS Modules。
- 用户操作结果使用 Ant Design message 提示。
- 禁止使用 any 类型。
- 组件放在 src/components/ 目录下。
此时，期望 AI 生成的代码更接近项目实际风格：
// src/components/CopyButton/index.tsx
import { message } from 'antd'
import styles from './index.module.less'
interface CopyButtonProps {
text: string
onSuccess?: () => void
}
export default function CopyButton({
text,
onSuccess,
}: CopyButtonProps) {
const handleCopy = async () => {
try {
await navigator.clipboard.writeText(text)
message.success('复制成功')
onSuccess?.()
} catch {
message.error('复制失败')
}
}
return (
<button
className={styles.copyButton}
onClick={handleCopy}
>
复制
</button>
)
}
这里的改进不仅是代码风格上的区别。
更重要的是：
- 类型定义符合约定。
- 组件目录和命名一致。
- 样式方案与项目保持统一。
- 复用了已有 UI 组件库。
- 增加了必要的异常处理。
当然，这只是用于说明规则作用的示例，并不意味着添加 AGENTS.md 后，AI 每次都能完全遵守要求。
AGENTS.md 的价值，是减少 AI 在项目实现方式上的不确定性，而不是代替工程质量保障。
三、一份完整的 AGENTS.md 应该包含什么？
对于常见的前端、后端和全栈项目，可以从以下六个方面组织规则。
1. Project Overview：项目背景与技术栈
首先告诉 AI 当前项目是什么，以及应该采用哪些技术。
例如：
# AGENTS.md
## Project Overview
这是一个基于 React 19 + TypeScript 的 Web 应用。
技术栈：
- React 19
- TypeScript
- Vite
- pnpm
- Ant Design
- Less + CSS Modules
开发约定：
- 优先复用已有依赖。
- 不得随意引入新的 UI 组件库。
- 新增依赖前说明原因。
- 优先沿用现有代码模式。
这里建议明确技术栈的版本以及依赖管理工具。
否则 AI 可能会使用与当前项目不兼容的 API，或者给出错误的依赖安装命令。
技术栈信息应以项目实际配置为准，不要仅凭历史文档填写。
2. Project Structure：目录结构
接下来明确项目的目录职责。
src/
├── components/ # 可复用组件
├── pages/ # 页面组件
├── hooks/ # 自定义 Hooks
├── services/ # API 请求封装
├── stores/ # 全局状态管理
├── utils/ # 工具函数
├── types/ # 公共类型定义
├── constants/ # 常量
└── assets/ # 静态资源
在 AGENTS.md 中进一步约定：
## Project Structure
- 通用组件放在 src/components/。
- 页面组件放在 src/pages/。
- 所有 API 请求封装在 src/services/。
- 自定义 Hooks 放在 src/hooks/。
- 公共类型定义放在 src/types/。
- 通用工具函数放在 src/utils/。
新增文件前，先查找是否存在可复用实现。
不要为简单功能重复创建新的目录层级。
这一部分可以有效减少 AI 随意组织代码的问题。
但不需要把整个项目的文件树全部复制进去。
对于大型项目，记录主要目录的职责以及需要特别注意的模块即可。
3. Coding Conventions：编码规范
编码规范应该尽可能明确、可执行。
不推荐这样的写法：
- 遵循最佳实践。
- 保持代码整洁。
- 注意可维护性。
这些描述过于抽象，不同开发者和模型可能有不同理解。
更好的做法是：
## Coding Conventions
### TypeScript
- 新增代码必须提供明确的类型。
- Props 优先使用 interface。
- 不得使用 any 绕过类型检查。
- 类型转换必须有合理依据。
### React
- 使用函数组件和 Hooks。
- 组件名使用 PascalCase。
- 自定义 Hooks 使用 use 前缀。
- 列表渲染必须提供稳定的 key。
- 避免在渲染过程中执行昂贵计算。
### Styling
- 使用 Less + CSS Modules。
- 禁止随意添加内联样式。
- 颜色和间距优先引用设计变量。
- 不得引入与现有技术栈冲突的样式方案。
### API
- API 请求统一封装在 services 目录。
- 优先使用项目现有的 HTTP 客户端。
- 不在页面组件中重复实现请求逻辑。
- 正确处理加载、失败和空状态。
这里有一个重要原则：
规范不应只是描述结果，还应该明确实现路径。
例如，与其要求“接口调用要规范”，不如直接要求“所有请求统一通过 services 模块调用”。
这样更容易在生成代码和 Code Review 阶段进行检查。
4. Build & Verification：构建和验证命令
AI 完成代码修改后，应该知道如何验证结果。
例如：
## Build & Verification
项目使用 pnpm。
常用命令：
- pnpm dev：启动开发服务器
- pnpm build：执行生产构建
- pnpm lint：执行代码检查
- pnpm test：运行单元测试
完成代码修改后：
1. 检查修改涉及的文件。
2. 优先运行相关测试。
3. 运行适用的 Lint 或类型检查。
4. 涉及构建配置时，执行生产构建。
5. 汇总验证结果和未解决的问题。
这里的脚本仅作为示例，需要与 package.json 中实际存在的命令对应。
不要要求 AI 在每次修改后无条件运行所有命令。
例如，仅修改文档时，通常不需要执行完整的生产构建。
更合理的原则是：
验证范围应与变更影响范围相匹配。
5. Never Rules：禁止事项
这一部分通常是 AGENTS.md 中最值得重点维护的内容。
前面的规则告诉 AI 应该怎么做，Never 规则则明确哪些行为不应该发生。
例如：
## Never Rules
- Never 修改 node_modules/。
- Never 直接修改 dist/ 构建产物。
- Never 修改自动生成的代码，除非任务明确要求更新生成流程。
- Never 在源代码中硬编码密码、Token 或 API Key。
- Never 使用 any 绕过 TypeScript 类型检查。
- Never 在没有必要时新增第三方依赖。
- Never 删除与当前需求无关的代码。
- Never 在未获得明确授权时执行破坏性 Git 操作。
- Never 为了通过测试而删除测试用例。
- Never 在未经验证的情况下声称测试通过。
Never 规则的重点并不是数量，而是可判断性。
例如：
Never 修改 dist/
这是一个明确的禁止事项。
而：
Never 写低质量代码
则缺少可以客观判断的标准。
建议优先记录容易造成真实工程风险的操作，包括：
- 数据与密钥泄露。
- 自动生成代码被直接修改。
- 非预期依赖升级。
- 破坏性 Git 操作。
- 越权修改文件。
- 通过跳过检查掩盖错误。
另外，Never 规则也不应该无限扩大。
比如“永远不能修改 lock 文件”就不适合所有项目，因为新增或升级依赖时，锁文件通常需要同步更新。
更合理的约束是：
- 未涉及依赖变更时，不得修改 lock 文件。
- 如果需要更新依赖，应同步更新对应锁文件。
- 不得无故批量升级现有依赖。
好的规则应该保护正常开发流程，而不是阻碍正常开发。
6. Collaboration：任务执行与协作规范
AI Coding Agent 与普通代码补全工具的一个重要区别是：
它不仅能生成代码，还可能读取文件、执行命令、修改工程配置，甚至操作 Git。
因此，除了代码风格，还需要明确任务执行边界。
## Collaboration
### Before Changes
- 修改前先阅读相关代码。
- 优先复用现有实现。
- 复杂任务先给出简要修改计划。
- 不得随意扩大需求范围。
### During Changes
- 只修改完成当前任务所需的文件。
- 尽量保持改动范围最小。
- 避免无关重构。
- 不覆盖其他开发者或 Agent 的改动。
### After Changes
- 总结修改内容。
- 说明影响范围。
- 列出实际执行的验证命令。
- 如存在未完成事项，明确说明。
### Git
- 不得擅自执行 git reset --hard。
- 不得擅自执行 git clean -fd。
- 未经授权不得切换分支。
- 不得提交与当前任务无关的文件。
- 提交信息遵循 Conventional Commits。
在多人开发或多个 Agent 并行工作时，这类规则尤其重要。
AI 不仅需要知道如何完成任务，还应该知道哪些操作超出了当前任务的权限范围。
四、可直接使用的 AGENTS.md 模板
把前面的规则整合起来，就可以得到一份适合大多数 TypeScript 前端项目的基础模板。
根据项目实际情况调整技术栈、路径和验证命令后，放到项目根目录即可。
# AGENTS.md
## 1. Project Overview
本项目为 React + TypeScript Web 应用。
技术栈：
- Framework: React
- Language: TypeScript
- Build: Vite
- Package Manager: pnpm
- UI: Ant Design
- Styling: Less + CSS Modules
基本原则：
- 遵循现有项目架构。
- 优先复用已有组件和依赖。
- 不引入无关技术方案。
- 保持修改范围最小。
## 2. Project Structure
- src/components/：通用组件
- src/pages/：页面
- src/hooks/：自定义 Hooks
- src/services/：API 请求
- src/stores/：状态管理
- src/utils/：工具函数
- src/types/：公共类型
- src/constants/：常量
新增文件前先检查现有实现。
## 3. Coding Conventions
### TypeScript
- 使用明确的类型定义。
- Props 优先使用 interface。
- 禁止无理由使用 any。
- 保持类型声明可复用。
### React
- 使用函数组件和 Hooks。
- 组件命名采用 PascalCase。
- Hooks 使用 use 前缀。
- 列表渲染使用稳定的 key。
### Styling
- 使用 Less + CSS Modules。
- 优先复用设计变量。
- 避免硬编码样式。
- 不引入新的 CSS 方案。
### API
- 所有 API 请求放在 services/。
- 使用项目已有请求封装。
- 处理加载、错误和空状态。
## 4. Build & Verification
使用 package.json 中已有的脚本。
常用命令：
- pnpm dev
- pnpm build
- pnpm lint
- pnpm test
代码修改后：
- 优先执行相关测试。
- 执行适用的静态检查。
- 必要时进行构建验证。
- 汇报实际验证结果。
## 5. Never Rules
- Never 修改 node_modules/。
- Never 直接修改构建产物。
- Never 硬编码敏感信息。
- Never 无故引入新依赖。
- Never 删除无关代码。
- Never 擅自执行破坏性 Git 操作。
- Never 跳过检查来掩盖错误。
- Never 声称未运行的测试已通过。
- Never 擅自覆盖其他人的改动。
## 6. Collaboration
执行任务前：
- 先理解需求和相关代码。
- 必要时给出修改计划。
- 确认涉及的文件和影响范围。
执行过程中：
- 优先采用最小改动。
- 不进行无关重构。
- 遵循现有架构和命名规范。
任务结束后：
- 总结变更文件和内容。
- 说明执行的验证步骤。
- 列出失败项和剩余风险。
## 7. Git Conventions
提交信息格式：
type(scope): description
常用类型：
- feat
- fix
- refactor
- docs
- test
- chore
未经明确要求，不主动创建提交。
这份模板的重点并不是覆盖所有工程情况，而是先建立一组稳定的基础规则。
实际应用中可以从较短的版本开始，随着项目复杂度增加，再补充特定模块的约定。
五、AGENTS.md 与 DESIGN.md 如何配合？
在前端项目中，除了代码组织和技术规范，视觉一致性同样重要。
即使 AI 能正确使用 React、TypeScript 和组件库，生成的页面仍然可能出现：
- 配色与现有品牌不一致。
- 不同页面的圆角、阴影、间距不统一。
- 随意使用颜色值。
- 重复设计已经存在的 UI 组件。
这时可以考虑将设计约定单独维护在 DESIGN.md 中。
二者职责不同：
| 文件 | 主要职责 |
|---|---|
AGENTS.md |
开发规范、目录结构、编码要求、执行边界 |
DESIGN.md |
设计变量、布局、颜色、字体和视觉约定 |
例如：
# DESIGN.md
## Colors
- Primary: #1677ff
- Success: #52c41a
- Warning: #faad14
- Error: #ff4d4f
## Typography
- 正文大小：14px
- 次级说明：12px
- 页面标题：24px
- 字重优先使用 400 / 500 / 600
## Spacing
使用 8px 基础间距体系：
- xs: 4px
- sm: 8px
- md: 16px
- lg: 24px
- xl: 32px
## Components
- 优先复用现有 Ant Design 组件。
- 统一使用项目约定的主题变量。
- 不随意新增按钮、表单或弹窗样式。
这里的配置只是演示格式，实际项目应以已有设计系统为准。
随后在 AGENTS.md 中增加一条引用：
## UI Development
- 开发或修改 UI 前，先阅读 DESIGN.md。
- 优先使用项目现有 Design Tokens。
- 不得自行创建与设计系统冲突的视觉规范。
这样就形成了两层上下文：
AGENTS.md 负责开发行为，DESIGN.md 负责视觉约束。
需要注意，DESIGN.md 并不是所有 AI 编程工具都会自动识别的标准入口。
只有当工具读取了该文件，或项目规则明确引导其读取时，其中的设计约定才可能发挥作用。
六、多个 AI 编程工具如何使用 AGENTS.md？
不同 AI 编程工具的项目指令机制并不完全相同。
常见规则入口如下：
| AI 编程工具 | 规则配置方式 |
|---|---|
| OpenAI Codex | AGENTS.md |
| Cursor | 项目 Rules，例如 .cursor/rules/ |
| Claude Code | CLAUDE.md |
| GitHub Copilot | 仓库指令文件，例如 .github/copilot-instructions.md |
| Windsurf | Workspace Rules / 项目规则机制 |
具体的文件发现、作用范围及优先级，应以对应工具当前版本的官方说明为准。
不要假设所有工具都能直接、完整、自动读取项目根目录中的 AGENTS.md。
如果团队同时使用多种 AI 工具，可以采用统一维护规则，再通过各工具支持的入口进行引用或同步的方式。
例如：
project/
├── AGENTS.md
├── DESIGN.md
├── CLAUDE.md
├── .cursor/
│ └── rules/
└── .github/
└── copilot-instructions.md
其中 AGENTS.md 可以作为核心项目规范，其他配置文件根据工具能力复用相关内容。
这样可以减少多个规则文件分别维护带来的不一致问题。
七、让 AGENTS.md 真正发挥作用的几个技巧
1. 不要写成一份超长的项目文档
AGENTS.md 的主要职责是提供开发决策所需的关键信息，而不是替代完整的项目文档。
可以优先保留：
- 技术栈和核心架构。
- 主要目录职责。
- 编码约定。
- 关键禁止事项。
- 构建与验证命令。
- 任务协作边界。
复杂模块的详细说明可以放到独立文档，再按需引用。
规则不是越多越有效。过长、重复或相互冲突的规则反而可能增加上下文负担。
2. 将常见错误转化为明确规则
AGENTS.md 不必一次写完。
更实用的方式是从实际开发问题中持续完善。
例如：
某次 AI 直接修改了自动生成的 API 类型文件，导致下一次代码生成覆盖修改。
就可以补充：
- Never 直接修改 src/generated/ 下的文件。
- 如需调整生成类型，应修改对应的 Schema，
然后重新执行代码生成命令。
这比简单地要求“不要破坏现有功能”更有效，因为它明确指出了错误行为和正确处理路径。
3. 规则发生冲突时，优先保证一致性
随着规则增长，可能出现这样的冲突：
- 禁止修改 lock 文件。
- 新增依赖后必须同步更新 lock 文件。
两条规则分别看似合理，但放在一起会导致执行歧义。
因此，规则需要明确适用条件。
例如：
- 未发生依赖变更时，不修改 lock 文件。
- 依赖发生变更时，必须同步更新 lock 文件。
同时要避免在多个配置文件中重复维护相互矛盾的要求。
4. 对高风险操作建立额外保护
涉及数据删除、数据库迁移、生产部署、敏感配置和 Git 历史修改时，仅依靠文本规则并不充分。
建议结合：
- 命令执行权限。
- 人工审批机制。
- CI 检查。
- 自动化测试。
- 最小权限原则。
例如，即使在 AGENTS.md 中写明不得修改生产数据库，也不应该向普通开发 Agent 提供不必要的生产数据库写入权限。
5. 定期更新项目规则
AGENTS.md 最大的维护风险之一，就是规则与实际项目脱节。
假设项目已经由 Redux 迁移到 Zustand，但 AGENTS.md 仍然要求使用 Redux。
AI 可能会遵循过时规则，继续生成旧架构代码。
因此，当项目发生以下变化时，应同步检查规则：
- 技术栈升级。
- 目录结构调整。
- 新增或替换基础组件。
- 请求层或状态管理方案迁移。
- 构建、测试和部署流程变化。
可以将 AGENTS.md 的维护纳入相关 Pull Request 的检查项。
八、如何判断 AGENTS.md 是否有效？
不能仅仅因为 AI 生成的代码看起来更规范，就认定规则已经发挥作用。
更可靠的方法是使用相同任务进行对照测试。
例如准备一组固定开发任务：
- 新增一个 React 组件。
- 新增一个 API 请求。
- 修改现有页面。
- 修复一个 TypeScript 类型错误。
- 对指定模块进行小范围重构。
分别在提供和不提供 AGENTS.md 的条件下执行，观察以下指标：
| 评估指标 | 说明 |
|---|---|
| 规范遵循率 | 生成结果满足明确项目规则的比例 |
| 一次通过率 | 不经人工修复即可通过预定验证的比例 |
| 无关文件修改数 | 是否出现任务范围外的变更 |
| 人工修正次数 | 开发者需要纠正 AI 的次数 |
| 验证通过率 | Lint、类型检查和相关测试的结果 |
为了让评估更可信，应该尽量控制模型版本、输入任务、初始代码状态等变量，并采用多次运行而不是单次对比。
对于实际开发团队而言，不一定需要复杂的评测平台。
从固定任务集和人工检查表开始，就能判断当前规则是否真正减少了重复修正。
九、常见问题
Q1：AGENTS.md 应该放在哪里？
通常放在项目根目录，与 package.json 等文件同级。
部分工具还支持子目录级的指令文件，具体作用范围依赖工具本身的规则发现机制。
Q2：AGENTS.md 需要提交到 Git 吗？
团队共享的项目规范建议提交到 Git，与代码一起进行版本管理。
这样所有开发者和支持相应规则的 AI 工具都可以使用相同的规范。
个人偏好可以使用工具提供的用户级配置，不必全部写入团队共享规则。
Q3：AGENTS.md 写多长比较合适？
没有统一的最佳行数。
建议先从最必要的内容开始，保证每条规则清楚、有效、没有重复。
当规则逐渐增长时，可以按模块拆分文档，避免把所有实现细节塞进单个文件。
Q4：加入 AGENTS.md 后，还需要 ESLint 和测试吗？
需要。
AGENTS.md 是自然语言指导文件，不是确定性验证工具。
ESLint、类型检查、测试和 CI 仍然是工程质量保障的重要组成部分。
Q5：AGENTS.md 只能用于前端项目吗？
不是。
Java、Python、Go、Node.js、AI Agent 等项目都可以使用相同思路。
例如 Java Spring Boot 项目可以约定：
## Java Conventions
- 使用项目当前 JDK 版本。
- Controller 只负责参数接收和响应处理。
- 业务逻辑放在 Service 层。
- 数据访问放在 Repository 或 Mapper 层。
- 使用项目现有的异常处理机制。
- 不直接返回包含敏感信息的实体。
- 不修改已上线且不可变更的数据库迁移脚本。
Python 项目则可以增加：
## Python Conventions
- 使用项目指定的 Python 版本。
- 遵守现有代码格式化和类型检查配置。
- 优先复用当前虚拟环境中的依赖。
- 不修改原始数据文件。
- 不在代码中硬编码密钥。
- 涉及模型评测时记录数据集、参数和版本。
核心思想完全一致：把项目中隐含的开发约定显式化。
十、总结
AI 编程助手已经能够完成大量代码编写和工程修改任务，但项目规范、架构决策和操作边界仍然需要明确传达。
AGENTS.md 提供了一种简单的解决方案：使用 Markdown 将分散在项目中的开发约定组织成 AI 可以参考的指导文件。
一份有价值的 AGENTS.md，应该回答几个关键问题：
- 项目是什么？ 使用什么技术栈和架构。
- 代码放在哪里？ 目录和模块如何划分。
- 代码怎么写？ 使用什么编码约定和复用策略。
- 哪些操作不能做？ 明确修改边界与高风险行为。
- 如何验证结果？ 使用哪些检查、测试与构建流程。
- 如何协作？ 避免无关修改和破坏其他开发者的工作。
它不需要写得复杂，也不必一开始就覆盖所有规则。
更重要的是让规则足够准确、具体，并随着项目演进持续维护。
AGENTS.md 的真正价值，不是让 AI 记住更多规则，而是让它在理解项目约束的前提下，做出更符合工程实际的决策。
当项目规范、自动化验证和合理的操作权限结合起来时，AI 辅助开发才能从“快速生成代码”，逐步走向更加稳定、可控的工程化协作。
