为什么需要 AGENTS.md？

AI 编程助手（如 Claude Code、Cursor、Codex等）越来越普及，但它们每次进入一个项目都像第一次来——没有记忆，没有上下文。代码库越大，Agent 理解项目全貌的成本就越高，越容易做出不符合项目规范的操作。

AGENTS.md 就是解决这个问题的：越来越多 AI Coding Agent会自动发现或优先读取项目中的 AGENTS.md，将其作为理解项目上下文的重要信息来源；部分工具则需要额外配置或采用自己的规则机制。

一个合格的 AGENTS.md 至少应该涵盖以下六个维度：

---

一、项目目标

这是整个说明书的灵魂。Agent 需要理解 这个项目存在的意义 和 当前阶段的核心目标，才能在做决策时不偏离方向。

好的写法

## 项目目标

本项目是一个面向中小团队的内部知识库系统（SaaS），核心目标是：
- 让团队能够用自然语言搜索内部文档，3 秒内返回相关结果
- 支持 Markdown、PDF、Confluence 三种数据源的自动索引
- 当前阶段：MVP 开发，优先保证核心搜索链路跑通，暂不考虑权限系统

写作要点

• 一句话说清产品定位：这是给谁用的，解决什么问题。
• 明确当前阶段：MVP？正式版？重构中？不同阶段 Agent 的决策权重完全不同。
• 列出优先级排序：如果只有三个目标，排个序。Agent 会在冲突时按优先级取舍。

---

二、关键目录

大型项目可能有上百个目录，Agent 不可能一次性读完全部。你需要告诉它哪些目录是核心要点。

好的写法

## 关键目录

src/
├── app/          # Next.js App Router 页面层
│   ├── api/      # API 路由（服务端逻辑入口）
│   └── (main)/   # 用户端页面
├── components/   # 共享 UI 组件
│   └── ui/       # 基础 UI 库（Button, Input, Modal 等）
├── lib/          # 业务逻辑（不要放组件）
│   ├── db/       # 数据库查询层（Prisma）
│   └── search/   # 搜索引擎封装
├── prisma/       # 数据库 Schema 和迁移文件
└── tests/        # 测试文件，与 src 目录结构对应

写作要点

• 用树形结构可视化，一目了然。
• 每个关键目录配一行简短注释，说明 它是什么 和 它不是什么。
• 标出容易混淆的地方（比如 lib/ 不放组件，utils/ 和 helpers/ 的区别）。

---

三、先看这些文件

Agent 不可能一次性读遍整个项目。你需要告诉它：如果要理解核心逻辑，最先应该读哪几个文件。

好的写法

## 先看这些文件

按优先级排列，Agent 应按顺序阅读以理解项目核心：

1. `prisma/schema.prisma` — 数据模型，理解所有实体和关系的第一入口。
2. `src/lib/search/engine.ts` — 搜索核心算法，所有查询最终都走到这里。
3. `src/app/api/search/route.ts` — 搜索 API 入口，理解请求-响应格式。
4. `src/middleware.ts` — 全局中间件，理解认证和路由拦截逻辑。
5. `src/lib/constants.ts` — 全局常量和配置项，理解业务规则边界。

写作要点

• 控制在 5-8 个文件以内，这些文件应该共同画出系统的骨架。
• 给文件排优先级，Agent 通常按顺序阅读。
• 每个文件附一句解释：为什么这个文件重要，读完能理解什么。

---

四、常用命令

Agent 需要跑命令来验证自己的修改是否正确。你必须明确告诉它项目的命令体系，否则它可能会猜测。

好的写法

## 常用命令

### 开发环境
```bash
npm run dev          # 启动开发服务器 (localhost:3000)
npm run db:studio    # 启动 Prisma Studio 查看数据库
npm run db:push      # 将 schema 变更同步到开发数据库

测试

npm test             # 运行所有测试（Vitest）
npm run test:watch   # 监听模式
npx vitest src/lib/search  # 只运行搜索模块测试

类型检查与构建

npm run typecheck    # TypeScript 类型检查（与构建分离，更快）
npm run lint         # ESLint 检查
npm run build        # 生产构建（会自动跑 typecheck + lint）

代码格式化

npm run format       # 格式化代码（如 Prettier）
cargo fmt            # Rust
gofmt ./...          # Go

写作要点

• 分类写：开发/测试/构建/部署，按场景分组。
• 写完整命令，不要省略参数，Agent 需要精确复制。
• 写注释说明每个命令的作用，尤其是自定义脚本。
• 如果在 CI 中有额外的检查步骤，也写在这里。

---

五、验证要求（Verification Requirements）

每次修改代码后，Agent 需要跑什么来确保没搞坏东西？这不是"建议"，是强制要求。

好的写法

## 验证要求

Agent 在完成任何代码修改后，必须依次通过以下验证，全部通过才算完成任务：

1. **类型检查**：`npm run typecheck` 必须零错误。
2. **Lint 检查**：`npm run lint` 必须零警告。
3. **测试通过**：`npm test` 必须全部通过。
4. **构建成功**（涉及生产代码时）：`npm run build` 必须成功。

### 特殊情况
- 修改数据库 Schema 后，必须同时运行 `npm run db:push`。
- 新增 API 路由后，必须确认返回类型与前端调用一致（参考 `src/lib/api-types.ts`）。
- 修改搜索引擎后，必须跑 `npm run test:search` 专项测试。

写作要点

• 用"必须"而不是"建议"，给 Agent 明确的硬性要求。
• 列出具体命令，不要模糊描述。
• 按顺序排列，快的放前面（typecheck 比测试快，先跑能快速失败）。
• 补充特殊情况下的额外验证步骤。

---

六、禁区

这是最有 AGENTS.md 特色的部分。人类开发者会靠常识避开坑，Agent 不会。你必须把"绝对不能做"的事情明确写出来。

好的写法

## 禁区

以下操作在任何情况下都不允许：

1. **禁止直接修改数据库迁移文件**：
   - `prisma/migrations/` 目录下的文件由 `prisma migrate` 自动生成，只能通过命令修改 Schema 后重新生成。
   - 绝不能手动编辑 `migration.sql`。

2. **禁止引入新的后端依赖**：
   - 新增 npm 包前必须确认是否为已有依赖，优先复用 `package.json` 中已有的库。
   - 如需新增，必须先询问确认。

3. **禁止删除或修改测试文件**：
   - 如果测试失败，只能修改实现代码来让测试通过。
   - 只有在你新增了功能并编写了对应测试时，才能新增测试文件。

4. **禁止在组件中直接调用数据库**：
   - 所有数据库操作必须通过 `src/lib/db/` 中的封装函数。
   - 组件和页面只能通过 API 路由获取数据。

5. **禁止修改 ESLint/Prettier 配置**：
   - `.eslintrc.*`、`.prettierrc.*` 配置文件不可更改。
   - 如果 lint 规则导致代码报错，修改代码而非规则。

写作要点

• 每条禁区用"禁止"开头，语气强硬，不留模糊空间。
• 解释为什么禁止：Agent 理解了原因会更可靠地遵守。
• 给出正确做法：不只说不能做什么，还要说应该怎么做。
• 覆盖面从大到小：依赖管理 → 文件操作 → 代码规范。

---

完整模板

将以上六部分组合起来，就是一个完整的 AGENTS.md 模板：

# AGENTS.md — 给 AI 的说明书

> 本文档为 AI 编程助手（Claude Code、Cursor 等）提供项目上下文和操作规范。
> 请在每次代码修改前阅读本文档，确保理解项目目标和约束。

## 项目目标

<!-- 一句话描述项目做什么 + 当前阶段 + 优先级排序 -->

## 关键目录

<!-- 树形结构 + 每个目录一行注释 -->

## 先看这些文件

<!-- 5-8 个文件，排序，每个文件说明为什么重要 -->

## 常用命令

<!-- 分类列出：开发 / 测试 / 构建 / 部署，附完整命令 + 说明 -->

## 验证要求

<!-- 修改代码后的强制性检查清单，快速的在前面 -->

## 禁区

<!-- 绝对不能做的事 + 原因 + 正确做法 -->

---

实践建议

1. 先写再迭代：不用追求一次完美。写一个初版，在 Agent 使用过程中发现遗漏了就补上。
2. 团队维护：AGENTS.md 应该随项目演进同步更新。建议在 PR 模板里加入"是否更新 AGENTS.md"的检查项。
3. 保持简洁：Agent 每次都会读这个文件，太长会影响效率。控制在 200 行以内。
4. 测试你的指令：让 Agent 执行一个中级复杂的任务，看它是否会违反你的禁区或跳过验证要求。

---

不建议写进 AGENTS.md 的内容

AGENTS.md 的目标是帮助 Agent 快速理解项目，而不是替代所有项目文档。因此，不建议把以下内容直接写进去：

• 完整 API 文档
• 数据库设计文档
• 系统架构设计说明
• 产品需求文档（PRD）
• README 的完整复制版

更好的做法是，在 AGENTS.md 中告诉 Agent 这些文档在哪里，需要时再去阅读。

写在最后

一个好的 AGENTS.md 并不会提升模型本身的能力，但能够显著降低上下文缺失带来的决策成本，让 Agent 更快理解项目、更少犯错、更稳定地遵循团队规范。