> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/agentic_ai_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/agentic_ai_guide/di-wu-bu-fen-fu-lu/12_appendix/12.3_agents_md.md).

# 12.3 AGENTS.md 规范指南

`AGENTS.md`（项目说明文件）是一类面向 AI 编程智能体的项目级说明文档，用于集中存放构建命令、测试入口、代码风格、安全边界与工具权限说明等关键信息。它的定位更接近“给智能体看的 README”：提供上下文与操作约束，但**不是独立的安全边界**。真正的权限控制仍必须由运行时网关、沙箱、凭证代理、CI 策略或人工审批机制执行。不同工具生态可能仍在使用各种前缀名（如 CLAUDE.md、.cursorrules），但理念高度一致，并在长远上正逐渐向通用的 `AGENTS.md` 收敛。

## 12.3.1 什么是 AGENTS.md 与核心概念

`AGENTS.md` 是面向 AI 编程智能体的项目级操作手册，重点回答“能做什么、如何做、不能做什么”。如果说 `README.md` 是给人类开发者看的项目说明，那么 `AGENTS.md` 就是给 AI 编程智能体看的“机器可读说明书”。

> **类比**：
>
> * `README.md` → 人类开发者的项目介绍
> * `AGENTS.md` → AI 编程智能体的工作与合规指南

## 12.3.2 为什么需要项目说明文件

传统的 README.md 存在以下问题：

1. **面向人类**：包含快速入门、项目描述等人类易读但机器难以精确解析的内容
2. **信息分散**：构建命令、测试规则、代码风格等信息可能散落在多个文件中
3. **格式不统一**：每个项目的写法不同，Agent 需要“猜测”

项目说明文件通过标准化格式解决这些问题：

* 给智能体一个 **清晰、可预测** 的上下文与指令位置
* 提供 **精确、步骤化** 的操作指南和风险提示
* 保持 README 简洁，专注人类读者

## 12.3.3 文件结构与基本布局

文件结构通常由根目录主文件、子目录补充文件和可按需引用的扩展文档索引组成。

```mermaid
mindmap
    root((project-root/))
        README.md["README.md<br>(给人类看的项目说明)"]
        AgentDoc["项目说明文件<br>给 AI 智能体看的工作指南"]
        src/
            AgentDocSub["项目说明文件<br>可选：子目录特定指令"]
        tests/
            AgentDocTest["项目说明文件<br>可选：测试目录特定指令"]
```

图 12-1：项目说明文件布局结构

**嵌套规则**：

* 根目录的说明文件适用于整个项目
* 子目录的说明文件可以覆盖或补充父目录的指令
* 适用于 Monorepo 等大型项目

## 12.3.4 推荐内容结构

一个完整的项目说明文件通常包含以下部分：

```markdown

# Project Overview

This is a TypeScript-based web application using Next.js 14.
Architecture: Monorepo with apps/ and packages/ directories.
```

### 构建与测试命令

命令部分要写得能直接复制执行，并标注每条命令各自的适用范围。

```markdown

# Build

npm run build

# Test

npm run test              # 运行所有测试
npm run test:unit         # 仅单元测试
npm run test:e2e          # 端到端测试

# Lint

npm run lint              # ESLint + Prettier
npm run lint:fix          # 自动修复可修复问题
```

```markdown

# Code Style

- Use TypeScript strict mode
- Prefer small, focused modules with descriptive names
- Use named exports for shared modules
- Run `npm run lint` and `npm run format` before handoff
- Let ESLint / Prettier enforce formatting details
```

### 测试规范

测试规范要说明测试放在哪里、怎么命名，以及哪些外部依赖必须被 mock。

```markdown

# Testing Guidelines

- All new features must have unit tests
- Test files should be co-located: `foo.ts` → `foo.test.ts`
- Use `describe` for grouping, `it` for individual tests
- Mock external APIs in tests
```

### 安全考虑

安全部分列出的是硬约束，应该写成智能体可以逐条自查的禁止项。

```markdown

# Security

- Never commit secrets or API keys
- Use environment variables for configuration
- Validate all user input
- Avoid `eval()` and `dangerouslySetInnerHTML`
```

### 权限边界

权限边界要同时写清可以直接动的范围，和必须先问一句的动作。

```markdown

# Permissions

- Allowed paths: `src/`, `tests/`, `docs/`
- Ask before destructive commands or production writes
- Never read or modify undeclared secret stores
```

### Pull Request 指南

这一部分决定智能体如何收尾，因此要给出可量化的规模与内容要求。

```markdown

# Pull Request Guidelines

- Keep PRs focused and small (< 500 lines changed)
- Write meaningful commit messages
- Include tests for new functionality
- Update documentation if needed
```

### 完整示例

把以上各节拼起来，一份完整的项目说明文件大致如下。

````

# 项目说明文件（示例）

# Project Overview

A Python REST API.
- Framework: <web-framework>
- Database: <database>
- Authentication: <auth>

# Environment Setup

```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
```

# Build

```bash
python -m compileall app
```

# Run

```bash

# Development mode

uvicorn app.main:app --reload

# Production mode

uvicorn app.main:app --host 0.0.0.0 --port 8000
```

# Test

```bash

# Run all tests

pytest

# Run with coverage

pytest --cov=app --cov-report=html

# Run specific test file

pytest tests/test_users.py
```

# Code Style

- Follow PEP 8
- Use type hints for all function parameters and returns
- Run Ruff/Black before handoff
- Let the formatter enforce line length and import ordering

# File Naming

- API routes: `app/routers/{resource}.py`
- Models: `app/models/{entity}.py`
- Schemas: `app/schemas/{entity}.py`
- Tests: `tests/test_{module}.py`

# Security

- Validate all input with Pydantic models
- Use parameterized queries (SQLAlchemy handles this)
- Never log passwords or tokens
- Rate limit all public endpoints

# Permissions

- Allowed paths: `app/`, `tests/`, `docs/`
- Ask before destructive shell commands or production writes
- Never access undeclared secret stores
````

## 12.3.5 工具支持与配置关系

不同工具生态对项目说明文件的支持程度不同：有的会自动加载指定文件名，有的需要在配置中声明路径。建议以“文件内容结构”作为稳定部分，以“文件名与加载方式”作为可替换的适配层。

项目说明文件旨在 **统一** 而非取代现有的工具特定配置：

| 工具          | 专用配置    | 项目说明文件的作用 |
| ----------- | ------- | --------- |
| IDE / 编辑器插件 | 项目内规则目录 | 提供通用指令    |
| CLI 智能体     | 项目内配置文件 | 提供通用指令    |
| 自动化机器人      | CI 配置   | 提供项目上下文   |

**最佳实践**：将通用指令放在项目说明文件中，将工具特定配置放在各自文件中。

## 12.3.6 高级技巧与最佳实践

**高级技巧：渐进式披露**

不要试图把所有信息都塞进一个项目说明文件。这会消耗 **词元** 并降低智能体的注意力。**推荐结构**：

```
agent_docs/
  ├── architecture.md
  ├── testing_guide.md
  └── database_schema.md
项目说明文件（只包含索引和指针）
```

在项目说明文件中：

> “关于数据库设计细节，请阅读 `agent_docs/database_schema.md`。”

智能体会自行决定何时深入阅读。

```mermaid
graph TD
    A["项目说明文件<br/>AGENTS.md<br/><br/>核心指令与索引"] -->|简洁摘要| B["构建命令"]
    A -->|简洁摘要| C["代码风格"]
    A -->|简洁摘要| D["安全边界"]
    A -->|指针| E["详细架构设计"]
    A -->|指针| F["测试指南"]
    A -->|指针| G["数据库模式"]

    E -.->|引用| E1["agent_docs/architecture.md"]
    F -.->|引用| F1["agent_docs/testing_guide.md"]
    G -.->|引用| G1["agent_docs/database_schema.md"]

    H["智能体读取"] --> A
    H -->|需要时主动调用| E1
    H -->|需要时主动调用| F1
    H -->|需要时主动调用| G1

    style A fill:#e6f7ff,stroke:#1890ff,stroke-width:2px
    style B fill:#f6ffed,stroke:#52c41a,stroke-width:1px
    style C fill:#f6ffed,stroke:#52c41a,stroke-width:1px
    style D fill:#f6ffed,stroke:#52c41a,stroke-width:1px
    style E fill:#fff0f6,stroke:#eb2f96,stroke-width:1px
    style F fill:#fff0f6,stroke:#eb2f96,stroke-width:1px
    style G fill:#fff0f6,stroke:#eb2f96,stroke-width:1px
    style H fill:#fff7e6,stroke:#fa8c16,stroke-width:1px
```

图 12-2：项目说明文件的渐进式披露架构

**核心原则：What / Why / How**

一个好的配置文件应该回答三个问题：

1. **WHAT**: 技术栈、项目结构。
2. **WHY**: 设计决策的背景。
3. **HOW**: 如何运行、测试、验证。

**反模式：不要做 Linter 的工作**

❌ **错误做法**：在 **提示词 (Prompt)** 中详细规定代码风格（空格还是 Tab、换行习惯）。

* **后果**：浪费 Token，执行不稳定。

✅ **正确做法**：使用 ESLint / Prettier / Ruff 等格式化工具。

* 让工具自动修复格式与 Lint 错误。智能体只需要知道 “run `npm run lint:fix`”。

## 12.3.7 逐步采用与验证

**快速开始**

1. 在项目根目录创建项目说明文件。可先下载 [AgentGo](https://github.com/yeasy/AgentGo)（原名 agentrc）提供的最佳实践模板：`curl -fsSL https://raw.githubusercontent.com/yeasy/AgentGo/main/AGENTS.md -o AGENTS.md.new`
2. 如果项目已存在 `AGENTS.md`，先用 `diff -u AGENTS.md AGENTS.md.new` 对比，再手工合并；确认无本地规则被覆盖后再替换
3. 根据项目实际情况调整内容
4. 优先补全 **Build / Test / Lint / Permissions**，再补充 **Code Style** 与 **Security**

**逐步完善**

* 第一周：基础构建、测试、Lint 与权限边界
* 第二周：代码风格和命名规范
* 第三周：安全规则和 PR 指南
* 持续：根据智能体表现调整和补充

**验证效果**

使用 AI 编程 Agent 进行以下测试：

1. “请添加一个新的 API 端点”——检查是否遵循文件命名规范
2. “请为这个函数添加测试”——检查测试是否放在正确位置
3. “请修复这个 bug”——检查是否运行了测试套件

## 12.3.8 CI 持续集成与 Linter 检查

`AGENTS.md` 不能仅仅是一份被遗忘在根目录的纯文档，**必须加入 CI/CD 流程以防止其随时间发生“沉默腐烂”**。

**1. 目录强制校验 (Linter)**

通过编写一段简单的 CI 脚本（例如 `scripts/lint_agents_md.py`）并挂载到 Actions：

```python
import sys

def lint_agents_md():
    try:
        with open("AGENTS.md", "r") as f:
            content = f.read()
    except FileNotFoundError:
        print("❌ 错误: 必须在根目录提供 AGENTS.md")
        sys.exit(1)

    required_sections = ["# Build", "# Test", "# Lint", "# Permissions"]
    recommended_sections = ["# Code Style", "# Security"]

    for sec in required_sections:
        if sec not in content:
            print(f"❌ 错误: AGENTS.md 缺失核心要求章节 '{sec}'")
            sys.exit(1)

    for sec in recommended_sections:
        if sec not in content:
            print(f"⚠️ 警告: 建议补充章节 '{sec}'")

    # 避免占用过长上下文
    if content.count('\n') > 500:
        print("❌ 错误: AGENTS.md 太长，请使用子文件并在主文件引用")
        sys.exit(1)

    print("✅ AGENTS.md 结构校验通过")

if __name__ == "__main__":
    lint_agents_md()
```

**2. 将权限声明接入运行时策略 (Permission Constraints)**

可以把 `AGENTS.md` 中的权限段落作为**策略输入**，由系统网关、工具代理或 CI 检查转译成可执行的 allowlist / denylist。关键边界是：自然语言文件本身只负责说明意图，不能替代真正的访问控制。

```markdown

# Permissions

- allowed_mcp_servers: ["db-readonly", "github-repo-read"]
- allowed_fs_paths: ["src/", "tests/", "docs/"]
- blocked_shell_commands: ["rm -rf", "docker push", "npm publish"]
```

要实现“代码化安全边界 (Security-as-Code)”，还需要至少三件事：

1. **运行时强制**：工具网关或沙箱在执行前读取策略并硬拦截越权调用。
2. **默认拒绝**：未声明的文件路径、外部域名、MCP server、发布命令和生产写入默认不可用。
3. **可审计性**：每次放行、拒绝和人工批准都记录 trace，避免把 `AGENTS.md` 误当成不可绕过的安全机制。

## 12.3.9 其他资源与配置对比

**相关资源**

建议查阅大模型工具链（如 Cursor、Cline、Aider 等）的最新官方文档，确认其支持的规则加载机制。

**与其他配置文件的对比**

| 维度   | 项目说明文件       | 工具专属配置文件         |
| ---- | ------------ | ---------------- |
| 标准化  | 目标是跨工具通用     | 工具专属             |
| 适用范围 | 尽量跨工具复用      | 仅特定工具            |
| 层级位置 | 根目录 + 子目录    | 根目录 + 父目录 + 用户目录 |
| 核心内容 | 构建命令、测试、代码风格 | 工作流、工具连接相关特化配置   |
| 加载方式 | 工具主动读取或声明路径  | 随工具原生机制自动加载      |

两者的互补结构图如下：

```mermaid
mindmap
    root((project-root/))
        AgentDoc["项目说明文件<br>通用智能体指令"]
        ToolCfg["工具专属配置<br>例如 CLAUDE.md"]
        .cursor/
            rules["rules<br>IDE 专属配置"]
        src/
            AgentDocSub["项目说明文件<br>子目录特定指令"]
```

图 12-3：项目说明文件与工具专属配置共存结构

> **提示**：最佳实践：项目说明文件应随项目演进持续维护，重点关注：构建/测试入口、代码规范、安全边界、回归样例集。

***

**下一节**: [案例模板与检查清单](/agentic_ai_guide/di-wu-bu-fen-fu-lu/12_appendix/12.4_case_templates.md)