🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉 点击领海量免费额度

很多刚接触 Codex 或 Claude Code 的开发者，在安装配置后，往往急于寻找各种“技能包”或“魔法咒语”来提升 AI 的代码生成能力。然而，真正决定 AI 助手能否与你项目“同频共振”的关键，往往不是某个具体的技能，而是那个看似不起眼的规则文件——AGENTS.md（或CLAUDE.md）。你是否遇到过 AI 生成的代码风格混乱、使用了错误的技术栈，或者完全无视你的项目结构？这些问题，本质上都是规则文件没有配置好。本文将带你深入理解AGENTS.md规则文件，从概念、作用、编写到实战，让你彻底掌握如何“驯服”AI，让它成为你项目得力的、懂规矩的协作者。

1. 什么是 AGENTS.md 规则文件？

1.1 核心概念：持久化的开发规范提示

AGENTS.md（在 Codex、OpenCode 中）或CLAUDE.md（在 Claude Code 中），本质上是一个持久化的、项目级的开发规范与约束提示文件。你可以把它理解为写给 AI 助手的一份“项目开发说明书”或“团队协作章程”。

与单次对话中使用的 Prompt（提示词）不同，规则文件是持久生效的。一旦放置在项目根目录或用户配置目录，AI 助手在后续的所有交互中，都会自动读取并遵循其中的指令。这解决了每次都需要重复说明项目背景、编码风格、技术栈等基础信息的痛点。

1.2 不同工具的规则文件命名

虽然核心思想一致，但不同 AI 编程工具对规则文件的命名和存放位置略有差异：

核心要点：AGENTS.md是 Codex/OpenCode 生态中的标准命名。理解了这个文件，你就能触类旁通，轻松适应 Claude Code 的CLAUDE.md或 Cursor 的规则系统。

1.3 为什么需要它？解决三大核心痛点

1. 代码风格与质量不统一：没有规则时，AI 可能随意使用空格/制表符、混乱的命名（如camelCase、snake_case混用）、缺少必要的注释或文档，导致生成的代码难以阅读和维护。
2. 技术栈与项目约束被忽略：你的项目可能强制使用 React 18+，禁止某个旧库，或者有特定的目录结构（如组件必须放在src/components/下）。没有规则，AI 可能会生成使用旧版本 React 或放错位置的代码。
3. 安全与团队规范缺失：规则可以明确禁止在代码中硬编码 API Keys、数据库密码等敏感信息，强制要求使用环境变量，并遵循团队约定的代码提交、ESLint/Prettier 等检查流程。

简单来说，AGENTS.md就是将你（或团队）的开发习惯、项目约定和最佳实践，系统地、自动化地“灌输”给 AI，让它从“自由发挥”变成“按章办事”。

2. 规则文件的作用域与优先级

一个常见的误解是：规则文件只有一份，要么全局生效，要么项目生效。实际上，现代 AI 编程工具普遍采用“多层规则拼接”的机制。

2.1 规则作用域图解

当你在一个项目中请求 AI 帮助时，它并不是只读取一个文件。相反，它会从多个可能的位置收集规则，并按照一定的优先级进行合并和应用。

（作用域由广到窄，优先级由低到高） ┌─────────────────────────────────────┐ │ 用户级全局规则 │ │ (如：~/.codex/AGENTS.md) │ └───────────────┬─────────────────────┘ │ ┌───────────────▼─────────────────────┐ │ 项目级规则 │ │ (如：/your-project/AGENTS.md) │ └───────────────┬─────────────────────┘ │ ┌───────────────▼─────────────────────┐ │ 目录/路径级规则 (部分工具支持) │ │ (如：.cursor/rules/frontend.mdc) │ └───────────────┬─────────────────────┘ │ ▼ ┌─────────────────────┐ │ 最终生效的规则集合 │ │ (应用于当前上下文) │ └─────────────────────┘

2.2 冲突解决原则：更具体的规则优先

当来自不同作用域的规则发生冲突时（例如，全局规则说“用双引号”，项目规则说“用单引号”），系统遵循一个核心原则：离当前任务更近、作用域更具体的规则优先级更高。

这意味着：

• 项目级规则会覆盖用户级全局规则中的冲突项。
• 目录/路径级规则（如果支持）会覆盖项目级规则中的冲突项。
• 非冲突的规则会同时生效，共同约束 AI 的行为。

这种设计非常灵活。你可以在全局规则中定义所有项目的通用底线（如“永远不要写死密码”），然后在具体项目中定义技术栈细节（如“本项目使用 TypeScript 和 Tailwind CSS”）。

3. AGENTS.md 文件内容详解

理解了概念和作用域，接下来我们看看一个有效的AGENTS.md文件里到底应该写什么。内容可以大致分为几个核心板块。

3.1 项目背景与目标

这是规则的“开场白”，帮助 AI 理解它正在参与一个什么样的项目。

# 项目规则 (AGENTS.md) ## 项目概述 - **项目名称**: MyAwesomeApp - **类型**: 全栈 Web 应用 (Next.js + FastAPI) - **核心目标**: 构建一个高性能、可维护的内部管理仪表盘。 - **当前阶段**: 功能开发与迭代。 ## 技术栈约束 - **前端**: Next.js 14 (App Router), React 18, TypeScript 5, Tailwind CSS - **后端**: FastAPI, Python 3.11+, SQLAlchemy 2.0, PostgreSQL - **禁止使用的库/模式**: 禁止使用 `any` 类型 (TypeScript)，禁止使用 `eval`，禁止使用已弃用的 API。

3.2 编码标准与风格指南

这是确保代码一致性的核心部分。写得越具体，AI 产出越符合预期。

## 代码风格与规范 ### 通用原则 - **最小改动原则**: 除非明确要求，否则只修改与当前任务直接相关的文件。保持更改范围聚焦。 - **先验证后提交**: 生成或修改代码后，应思考并描述如何验证其正确性（例如，运行哪个测试、检查哪个端点）。 ### 前端 (TypeScript/React) - **命名**: - 组件: `PascalCase` (如 `UserProfile.tsx`) - 函数、变量、属性: `camelCase` - 常量: `UPPER_SNAKE_CASE` - 接口/类型: `PascalCase`，并以 `I` 为前缀（可选，但需统一），如 `IUserData` - **导入顺序**: 第三方库 -> 项目内部模块 -> 相对路径导入 -> 类型导入。使用 `import/order` ESLint 规则。 - **组件**: - 默认使用函数组件和 React Hooks。 - 复杂组件需使用 `React.memo` 进行性能优化。 - Props 必须明确使用 TypeScript 接口定义类型。 - **状态管理**: 优先使用 React Context 或 Zustand，仅在必要时使用 Redux Toolkit。 ### 后端 (Python/FastAPI) - **命名**: 遵循 PEP 8。函数、变量 `snake_case`，类 `PascalCase`。 - **类型注解**: 所有函数、方法必须包含完整的类型提示 (Type Hints)。 - **API 设计**: - 路径使用 `snake_case`。 - 使用 Pydantic 模型进行请求/响应验证。 - 错误响应统一格式：`{"detail": "错误信息"}`，并包含合适的 HTTP 状态码。 - **数据库**: 使用 SQLAlchemy 2.0 声明式映射，异步会话。

3.3 项目结构与文件约定

告诉 AI 你的项目是如何组织的，避免它把文件生成在错误的位置。

## 项目文件结构 - `src/app/`: Next.js App Router 页面和布局。 - `src/components/`: 可复用的 React 组件。按领域分类子文件夹，如 `ui/`, `forms/`。 - `src/lib/`: 工具函数、API 客户端、配置。 - `src/types/`: 全局 TypeScript 类型定义。 - `backend/app/`: FastAPI 应用主目录。 - `backend/app/api/v1/`: API 路由端点。 - `backend/app/models/`: SQLAlchemy 数据模型。 - `backend/app/schemas/`: Pydantic 模式。 - **重要**: 不要直接在 `src/app/api/` 下创建后端逻辑，那是 Next.js 的 API Routes，本项目后端独立。

3.4 安全与最佳实践

设定安全红线，防止 AI 生成有风险的代码。

## 安全规范 - **绝对禁止**在源代码中硬编码以下任何信息： - API 密钥、令牌、密码、数据库连接字符串。 - 个人身份信息 (PII)。 - 内部服务器地址或未公开的端点。 - **必须**使用环境变量 (`.env` 文件) 来管理配置，并在 `.gitignore` 中忽略 `.env` 文件。 - 所有用户输入在用于数据库查询或系统命令前**必须**进行验证或参数化。 - 涉及文件操作时，必须检查路径遍历漏洞。

4. 编写高质量规则的实战技巧

知道了写什么，更要懂得怎么写才有效。以下是来自开源社区和实战总结的最佳实践。

4.1 规则编写核心约束

1. 短小、具体、可执行：避免模糊的指令。将“写出高质量的代码”改为“函数长度不超过 50 行，必须包含 JSDoc/文档字符串”。
2. 避免空泛表述：不要写“遵循最佳实践”，而是写具体的实践，如“使用async/await处理异步，避免回调地狱”。
3. 拆分与组合：不要试图在一个AGENTS.md里塞进所有规则。参考best-rules项目的思路，按层次拆分：
   • 全局规则 (global.md)：所有项目通用的底线原则（如安全、最小改动）。
   • 技术栈规则 (stacks/*.md)：针对特定技术栈的约束（如react.md,python.md）。
   • 场景规则 (scenarios/*.md)：针对特定任务的指导（如bugfix.md,feature.md）。
4. 避免冲突与重复：同一件事只在一个地方定义。如果“使用 TypeScript”在全局规则中定义了，技术栈规则中就无需重复。

4.2 利用 Frontmatter 限定作用域（高级）

一些工具（如 Cursor、GitHub Copilot）支持在规则文件中使用 YAML Frontmatter 来精确控制规则的生效范围，这能极大提升规则的针对性和效率，避免无关规则干扰。

--- # 这是一个 Frontmatter 区块，用于定义规则的元数据 applyTo: - "src/**/*.ts" - "src/**/*.tsx" # 此规则仅对 src 目录下的 .ts 和 .tsx 文件生效 language: typescript # 指定此规则针对 TypeScript 语言 --- # 以下是规则正文 ## TypeScript 特定规则 - 严格模式 (`strict: true`) 必须开启。 - 使用 `interface` 而非 `type` 定义对象形状。 - 泛型参数使用单大写字母，如 `T`, `K`, `V`。

4.3 一个完整的 AGENTS.md 示例

结合以上所有要点，这里是一个面向一个简单 Node.js API 项目的AGENTS.md示例，它位于项目根目录。

# 项目规则 - Node.js API 服务器 ## 项目背景 这是一个基于 Express.js 和 TypeScript 构建的 RESTful API 服务器，用于用户管理。数据库使用 PostgreSQL。 ## 技术栈 - **运行时**: Node.js >= 18 - **语言**: TypeScript 5.x - **框架**: Express.js 4.x - **ORM**: Prisma - **测试**: Jest & Supertest - **代码风格**: ESLint + Prettier (配置已存在) ## 编码规范 ### 通用 - 使用 `async/await`，避免回调函数和 `.then()`。 - 所有导出的函数、类、接口必须包含 JSDoc 注释。 - 错误处理：使用集中式错误处理中间件。业务逻辑中抛出 `AppError` 类（已定义）的实例。 - 环境变量通过 `config.ts` 统一加载，禁止直接使用 `process.env`。 ### TypeScript - 开启 `strict` 模式。 - 使用 `interface` 定义对象和函数类型。 - 禁止使用 `any`。如果必须使用，需添加 `// eslint-disable-next-line @typescript-eslint/no-explicit-any` 并说明理由。 - 模块导入使用 ES6 语法 (`import/export`)。 ### 项目结构 - `src/controllers/`: 请求处理逻辑。 - `src/services/`: 业务逻辑层。 - `src/routes/`: Express 路由定义。 - `src/middlewares/`: 自定义中间件。 - `src/utils/`: 工具函数。 - `src/types/`: 全局类型定义。 - `prisma/`: Prisma 架构和迁移文件。 - **新文件**必须放在正确的目录下。 ### API 设计 - RESTful 风格。资源使用复数名词（如 `/api/v1/users`）。 - 响应格式统一为： ```json { "success": true, "data": { ... }, // 成功时的数据 "message": "操作成功", // 可选的成功信息 "error": null }

或（错误时）：

{ "success": false, "data": null, "message": "错误描述", "error": { "code": "ERROR_CODE", "details": { ... } // 可选的错误详情 } }

• 使用 HTTP 状态码：200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error。

安全

• 所有路由（除登录/注册）必须通过authMiddleware进行 JWT 令牌验证。
• 用户密码在存入数据库前必须使用bcrypt哈希。
• 对所有用户输入（req.body, req.query, req.params）使用 Joi 或 Zod 进行验证。
• 严禁在日志或响应中泄露敏感信息（密码、令牌、SQL 错误详情）。

任务流程

1. 理解需求：先复述你理解的任务。
2. 规划变更：列出需要修改/创建的文件。
3. 实现：生成或修改代码，遵循上述所有规范。
4. 验证建议：提供验证代码正确性的步骤（例如，运行哪个测试命令，或用 curl 测试哪个端点）。

## 5. 如何应用与测试规则 ### 5.1 放置规则文件 对于 Codex/OpenCode： 1. **项目级**：将编写好的 `AGENTS.md` 文件直接放在你的项目根目录。 2. **用户级全局**：将通用规则放在 `~/.codex/AGENTS.md`（Linux/macOS）或 `C:\Users\<你的用户名>\.codex\AGENTS.md`（Windows）。这样，所有没有项目级规则的项目都会继承这些规则。 ### 5.2 在 Codex 中验证规则生效 放置好 `AGENTS.md` 后，打开你的 IDE（如 VS Code）并确保 Codex 插件已激活。然后，你可以通过以下方式测试： 1. **直接提问**：在聊天框中问一个与项目相关的问题，例如：“请为这个项目创建一个新的用户注册端点。” 观察 AI 的回复是否遵循了你在规则中定义的框架（Express）、目录结构（`src/controllers/`）、响应格式和安全要求（密码哈希、输入验证）。 2. **代码生成**：在编辑器中对一个文件提出代码生成或补全请求。例如，在 `src/services/` 目录下新建文件时，AI 应该能自动建议符合项目约定的服务层代码结构。 3. **检查细节**：特别关注那些你在规则中明确指定的细节，比如： - 是否使用了正确的命名约定？ - 生成的代码是否放在了正确的目录？ - 是否包含了必要的 JSDoc？ - 是否避免了使用 `any` 类型？ ### 5.3 调试规则不生效的问题 如果发现 AI 似乎没有遵守你的规则，可以按以下步骤排查： 1. **文件位置与名称**：确认 `AGENTS.md` 文件确实位于**项目根目录**，并且文件名拼写正确（区分大小写）。 2. **规则冲突**：检查是否存在用户级全局规则与项目级规则冲突的情况。记住，项目级规则优先级更高，会覆盖全局规则。 3. **规则过于模糊**：检查你的规则指令是否足够具体。“写出好代码”是无效指令，“函数行数不超过30，并包含错误处理”是有效指令。 4. **上下文长度限制**：极长的 `AGENTS.md` 文件可能会被截断，导致部分规则未被 AI 读取。尽量保持规则简洁、聚焦核心约束。对于复杂项目，采用拆分规则文件（如 Cursor 的 `.cursor/rules/` 目录）是更好的选择。 5. **工具支持度**：确认你使用的 AI 编程工具版本是否支持 `AGENTS.md` 文件。查阅官方文档获取最新信息。 ## 6. 进阶：规则的组织与管理策略 对于个人或小型项目，一个 `AGENTS.md` 文件可能就够了。但对于大型项目或团队协作，更需要科学的规则管理。 ### 6.1 分层规则策略 借鉴 `best-rules` 项目的思路，建议采用以下结构：

your-project/ ├── .codex/ # 可选，Codex特定配置 ├── .cursor/ # 可选，Cursor规则目录 │ └── rules/ │ ├── global.mdc # 项目级全局规则 │ ├── stacks/ │ │ ├── react.mdc │ │ └── node.mdc │ └── scenarios/ │ ├── bugfix.mdc │ └── feature.mdc ├── AGENTS.md # 基础项目规则 (Codex/OpenCode主入口) ├── CLAUDE.md # Claude Code项目规则 └── .github/ └── copilot-instructions.md # GitHub Copilot规则

**如何工作**： - `AGENTS.md` 作为主入口，可以只包含最核心的项目概述和通用原则，并引用或说明其他规则文件的位置。 - 将技术栈细节（React、Node、Python）剥离到 `stacks/` 目录下。 - 将任务方法论（如何修复 Bug、如何开发新功能）剥离到 `scenarios/` 目录下。 - 这样，AI 在处理不同文件（`.tsx` vs `.py`）或不同任务（修复 Bug vs 写新 API）时，可以动态加载最相关的规则子集，减少上下文负担，提高准确性。 ### 6.2 规则的生命周期与维护 规则不是一成不变的。随着项目演进，规则也需要更新。 1. **定期审查**：每个季度或主要技术栈升级后，回顾规则是否仍然适用。 2. **问题驱动更新**：当 AI 反复犯同一类错误时，不要只是手动修正代码，而应该思考：是否缺少一条规则来防止这个错误？然后将这条规则补充进去。 3. **团队同步**：在团队中，`AGENTS.md` 应该被纳入版本控制（如 Git）。规则的修改需要经过讨论和评审，就像代码一样。 4. **精简原则**：定期删除过时、无效或很少用到的规则。保持规则集的精炼和高效。 ## 7. 常见问题与解决方案 | 问题现象 | 可能原因 | 解决方案 | | :--- | :--- | :--- | | AI 完全无视我的 `AGENTS.md` | 1. 文件放错位置或命名错误。<br>2. 使用的 AI 工具不支持该文件。<br>3. 规则文件语法错误（如格式混乱）。 | 1. 确认文件在项目根目录且名称正确。<br>2. 查阅工具官方文档确认支持性。<br>3. 检查文件是否为纯文本 Markdown 格式。 | | 部分规则生效，部分不生效 | 1. 规则描述模糊、矛盾。<br>2. 上下文长度限制，尾部规则被截断。<br>3. 规则与其他层级（全局）规则冲突。 | 1. 重写模糊规则，使其具体、可执行。检查并解决矛盾。<br>2. 精简规则，或拆分到多个文件按需加载。<br>3. 明确项目级规则的优先级，必要时调整全局规则。 | | AI 生成的代码风格仍不一致 | 规则未覆盖所有细节，或者 AI 的“默认行为”与项目习惯不同。 | 在规则中补充更具体的风格指南，例如直接提供 `.prettierrc` 或 `.eslintrc` 的关键配置片段，让 AI 模仿。 | | 规则太多，感觉拖慢了 AI 响应 | 过长的规则文件占用了大量上下文 Token，挤占了分析代码本身的空间。 | 实施分层和拆分策略。将不常用的、场景特定的规则移出主文件，放到按需触发的子规则文件中。 | | 团队成员对规则理解不一致 | 规则是文本文件，缺乏强制性和可视化。 | 将关键规则（如目录结构、命名规范）也写入项目的 `README.md` 或 `CONTRIBUTING.md`。在团队会议中定期 review 规则的有效性。 | 掌握 `AGENTS.md` 规则文件的编写与应用，是解锁 AI 编程工具全部潜力的关键一步。它让你从被动的代码审查者和修正者，转变为主动的规则制定者和引导者。一个好的规则文件，就像一份清晰的蓝图和一本详尽的开发手册，能让 AI 助手真正理解你的项目语境、技术偏好和团队规范，从而生成出更高质量、更符合预期、更少需要返工的代码。 > 🚀 30+款热门AI模型一站整合，DeepSeek/GLM/Qwen 随心用，限时 5 折。 👉[点击领海量免费额度](https://taotoken.net/models/detail/chat?modelId=deepseek-v4-pro&utm_source=tt_blog_mr)