How to Write AGENTS.md

以下是一份由 AI 生成的、针对 Codex 编写的 AGENTS.md 模板和指南。当作一个备忘录，希望有帮助。

随着 AI 编程代理（如 Codex）的兴起，越来越多的开发者开始使用它们来辅助代码修改、功能实现和问题修复。但由于这些代理是基于语言模型的，它们在理解项目上下文、工程规范和安全边界方面存在局限。因此，编写一份清晰、具体的 AGENTS.md 成了确保 AI代理能够正确、有效地为你的项目服务的关键。

如何为 Codex 编写 AGENTS.md

本文是给仓库维护者的实操指南：你可以把 AGENTS.md 看成“给 AI 编程代理的项目协作手册”。

写得好的 AGENTS.md 可以让代理：

• 更快进入状态（少问问题、少走弯路）
• 按你的工程规范做事（测试、风格、提交流程）
• 避免高风险行为（误删文件、错误发布、越权操作）

---

1. AGENTS.md 是什么

AGENTS.md 是放在仓库中的约定文件，告诉 Codex（或其他代理）在这个项目里应该如何工作。

你可以把它理解为以下内容的组合：

• 项目背景与目标
• 本地开发与测试命令
• 代码修改范围和边界
• 质量门槛（测试、Lint、类型检查）
• 交付标准（提交信息、PR 说明、变更记录）

---

2. 推荐放置位置

通常放在仓库根目录：

• ./AGENTS.md

如果你有多模块仓库，也可以：

• 根目录放“全局规则”
• 子目录放局部 AGENTS.md（覆盖该子项目特殊约束）

示例：

• AGENTS.md（全局）
• services/api/AGENTS.md（API 子项目规则）
• web/AGENTS.md（前端子项目规则）

---

3. 一份好 AGENTS.md 的结构

建议按下面顺序组织：

1. 项目简介（做什么、技术栈、运行环境）
2. 快速开始（安装依赖、启动命令）
3. 必跑检查（test/lint/typecheck/build）
4. 修改边界（哪些可改、哪些不能动）
5. 编码规范（风格、命名、注释）
6. 提交流程（分支、commit、PR 模板）
7. 安全与敏感操作（禁止项、需确认项）
8. 参考资料（关键文档路径）

---

4. 编写原则（非常关键）

原则 A：给“可执行指令”，不要写口号

差的写法：

• “请保证质量”

好的写法：

• “每次改动后必须执行 pnpm test && pnpm lint && pnpm typecheck，失败不得提交。”

原则 B：约束要具体到命令和路径

差的写法：

• “不要改核心模块”

好的写法：

• “未明确要求时，不得修改 infra/、scripts/release/、.github/workflows/。”

原则 C：区分“必须”和“建议”

建议使用关键词：

• MUST（必须）
• SHOULD（建议）
• MUST NOT（禁止）

原则 D：写清失败处理策略

例如：

• 测试失败怎么办
• 依赖安装失败怎么办
• 遇到脏工作区怎么办

---

5. 常用内容模板（可直接复用）

5.1 任务执行策略

## Execution Policy
- MUST 先阅读与任务相关的目录和测试用例，再改代码。
- MUST 优先做最小改动，避免无关重构。
- SHOULD 把复杂改动拆成多个可审阅提交。

5.2 测试与质量门槛

## Quality Gates
- MUST 运行：`pnpm lint`
- MUST 运行：`pnpm test`
- MUST 运行：`pnpm typecheck`
- MUST 在提交说明里记录测试结果摘要。

5.3 风险控制

## Safety Rules
- MUST NOT 执行破坏性命令（如 `rm -rf`, `git reset --hard`），除非用户明确要求。
- MUST NOT 修改生产环境配置文件：`deploy/prod/*`。
- MUST 在执行数据库迁移前先征求确认。

---

6. 你可以直接填写的骨架

把下面保存为 AGENTS.md，按需替换尖括号内容：

# AGENTS.md

## Project Overview
- Name: <项目名>
- Stack: <语言/框架>
- Goal: <项目目标>

## Setup
- Install: `<安装命令>`
- Dev: `<启动命令>`
- Build: `<构建命令>`

## Quality Gates
- MUST run: `<lint命令>`
- MUST run: `<test命令>`
- MUST run: `<typecheck命令>`

## Scope
- Editable paths: `<可修改目录>`
- Restricted paths: `<限制目录>`

## Coding Rules
- Style: `<风格规范>`
- Naming: `<命名规范>`
- Comments: `<注释要求>`

## Git Workflow
- Branch: `<分支策略>`
- Commit: `<提交规范>`
- PR: `<PR要求>`

## Safety
- MUST NOT: `<禁止行为>`
- Ask before: `<需确认操作>`

## References
- `<文档路径1>`
- `<文档路径2>`

---

7. 完整示例：一个可落地的 AGENTS.md

下面是一份完整示例（Node.js + TypeScript + Monorepo 场景）：

# AGENTS.md

## Project Overview
- Repository: acme-platform
- Architecture: pnpm monorepo (`apps/*`, `packages/*`)
- Main apps:
  - `apps/web`: Next.js frontend
  - `apps/api`: Fastify backend
- Shared packages:
  - `packages/ui`
  - `packages/config`
  - `packages/utils`

## Environment
- Node.js: 20.x
- Package manager: pnpm 9.x
- Database: PostgreSQL 15
- Copy `.env.example` to `.env` before local run.

## Setup & Run
- Install dependencies:
  - `pnpm install`
- Start all apps in dev mode:
  - `pnpm dev`
- Start single app:
  - `pnpm --filter @acme/web dev`
  - `pnpm --filter @acme/api dev`

## Required Quality Gates
Before any commit, agent MUST run all of:
- `pnpm lint`
- `pnpm typecheck`
- `pnpm test`

If task touches build config or dependency graph, also run:
- `pnpm build`

If a command fails:
- Include failure summary in final response.
- Do not claim success.

## Code Change Policy
- MUST keep changes minimal and task-focused.
- MUST preserve public API compatibility unless task explicitly requests breaking changes.
- SHOULD add or update tests for behavioral changes.

### Editable by default
- `apps/**`
- `packages/**`
- `tests/**`
- `docs/**`

### Restricted (need explicit user request)
- `.github/workflows/**`
- `infra/**`
- `scripts/release/**`
- `deploy/prod/**`

## Coding Standards
- TypeScript strict mode must pass.
- Prefer explicit types on exported functions.
- Avoid introducing new dependencies unless necessary.
- Keep functions small and cohesive.
- Add comments only for non-obvious logic.

## Testing Rules
- For unit logic changes:
  - update/add unit tests near changed module.
- For API contract changes:
  - update integration tests under `apps/api/test`.
- For UI behavior changes:
  - add/update React Testing Library tests.

## Git & PR Rules
- Branch naming:
  - `feat/<short-topic>`
  - `fix/<short-topic>`
  - `chore/<short-topic>`
- Commit convention:
  - `feat: ...`
  - `fix: ...`
  - `chore: ...`
  - `test: ...`
  - `docs: ...`
- PR description MUST include:
  - What changed
  - Why changed
  - Risk/impact
  - Test evidence (commands + key results)

## Safety Constraints
- MUST NOT run destructive commands (e.g. `rm -rf`, `git reset --hard`) unless explicitly requested.
- MUST NOT modify secrets or real credentials files.
- MUST ask for confirmation before:
  - DB schema migrations
  - production config changes
  - mass file deletion or renaming

## Collaboration Behavior
- If workspace is dirty, do not revert unrelated changes.
- If unexpected external edits appear during task, pause and report.
- Prefer `rg` for search and `rg --files` for file discovery.

## Reference Docs
- `README.md`
- `docs/architecture.md`
- `docs/contributing.md`
- `docs/testing.md`

---

8. 自检清单（写完后检查）

在你提交 AGENTS.md 前，确认：

• 规则是否可执行（都能落到命令/路径）
• 禁止项是否明确（尤其破坏性操作）
• 质量门槛是否闭环（失败时如何处理）
• 是否区分必须/建议
• 是否覆盖了该仓库的真实技术栈

如果这些都满足，这份 AGENTS.md 基本就能稳定指导 Codex 做出可控改动。