每次使用 Codex 都要重复说明技术栈、目录结构、代码规范和测试命令？本文通过一个真实项目，讲清楚 `AGENTS.md` 的作用、编写方式、分层规则和常见误区，让 Codex 从“临时写代码”升级为真正理解仓库约定的开发助手。

前言：Codex 缺的不是更长的提示词

不少开发者第一次使用 Codex 时，会尝试把所有要求都塞进任务描述：

请使用 TypeScript，不要新增依赖，保持现有代码风格，
接口返回格式不能变，修改后运行 lint 和测试，
不要修改数据库迁移文件……
 

这段提示词本身没有问题，但如果每个任务都要重复一次，很快会出现三个麻烦：

1. 团队成员使用的规则不一致；
2. 提示词越来越长，真正的任务目标反而不突出；
3. 一旦项目规范变化，旧提示词仍在继续传播。

更合适的做法，是把稳定、长期、与仓库相关的约定写进 `AGENTS.md`，把当前需求留在任务提示词中。

一句话理解：

> 任务提示词回答“这次做什么”，`AGENTS.md` 回答“在这个仓库里应该怎么做”。

一、AGENTS.md 到底解决什么问题？

`AGENTS.md` 是 Codex 用来读取项目指导信息的文件。它适合记录仓库结构、开发约定、禁止事项、验证命令和交付标准。

例如，当你让 Codex 新增一个接口时，它不仅要知道业务需求，还需要理解：

- 项目使用 Express、NestJS 还是 Spring Boot；
- 业务逻辑应该放在 Controller、Service 还是 Repository；
- 是否允许安装新的依赖；
- 哪些生成文件不能直接编辑；
- 修改完成后应该运行什么命令；
- 测试失败时应该继续修复还是只汇报问题。

这些信息不会因为一次需求结束而失效，因此适合沉淀为仓库规则。

二、从零编写一份 AGENTS.md

下面以一个 Node.js + TypeScript 服务为例。在项目根目录创建 `AGENTS.md`：

# Project Guidelines

## Project Overview
- This is a Node.js REST API written in TypeScript.
- Source code is under `src/` and tests are under `tests/`.
- Keep controllers thin; business logic belongs in services.

## Coding Rules
- Use TypeScript strict mode.
- Reuse existing utilities, error classes and response types.
- Do not add a dependency unless the task explicitly requires it.
- Do not edit generated files under `src/generated/`.
- Do not modify existing database migration files.

## Testing
- Add tests for new behavior and regression fixes.
- Run `npm run lint` after editing.
- Run `npm test` before reporting completion.
- If a command fails, report the command and the relevant error output.

## Delivery
- Summarize changed files and behavior.
- Include the verification commands and results.
- Call out remaining risks or checks that could not be completed.

这份配置有四个明显特点：

- 规则简短，不解释大段背景；
- 每条内容都会影响一次工程决策；
- 验证命令可以直接执行；
- 最终交付格式清晰可检查。

三、一份高质量 AGENTS.md 应包含什么？

1. 项目概况

只写与开发决策有关的信息，不需要复制 README。

## Project Overview
- Backend: Java 21 and Spring Boot 3.
- Database: PostgreSQL with Flyway migrations.
- Modules follow controller, service and repository layers.

项目概况的目标，是帮助 Codex快速定位正确模块，而不是介绍产品历史。

2. 代码与架构约定

把团队经常在 Code Review 中指出的问题写进去：

## Architecture
- Controllers only validate input and map responses.
- Domain logic belongs in `domain/`.
- Database access must go through repositories.
- Do not call third-party APIs directly from controllers.

相比“请写高质量代码”，这些规则具有明确的判断标准。

3. 修改边界

编码智能体能够同时修改多个文件，因此边界尤其重要：

## Change Boundaries
- Keep changes scoped to the requested feature.
- Do not perform unrelated refactors.
- Do not modify `.env`, production credentials or deployment secrets.
- Ask before changing a public API or database schema.

边界不是为了限制 Codex 的能力，而是降低一次任务的影响面。

4. 验证命令

“请确保代码没有问题”几乎无法验收，应该替换成项目真实存在的命令：

## Verification
- Frontend changes: run `npm run lint` and `npm run test`.
- Backend changes: run `./gradlew test`.
- Before completion, run the narrowest relevant test first.

如果完整测试需要半小时，可以明确要求先运行相关模块测试，再根据修改范围决定是否运行全量测试。

5. 输出与交付标准

Codex 完成修改后，不应只回复“已经处理好了”。可以明确要求：

## Completion Report
- List modified files.
- Explain the user-visible behavior change.
- Report every verification command and its result.
- Mention unverified assumptions and remaining risks.

这样可以快速判断它是否真正完成了任务。

四、AGENTS.md 与提示词应该如何分工？

很多人会把临时需求也写进 `AGENTS.md`，最终文件越来越混乱。可以使用下面的判断标准：

内容	放置位置	示例
当前任务目标	本次提示词	新增订单导出功能
仓库长期规则	AGENTS.md	禁止直接修改生成代码
可复用任务流程	Skill	代码审查、缺陷修复流程
Codex 项目设置	.codex/config.toml	模型、沙箱或 MCP 配置

一个配合 `AGENTS.md` 的任务提示词，可以非常简洁：

```text
为订单列表新增按创建时间导出 CSV 的功能。

要求：
1. 先阅读 AGENTS.md 和现有订单模块；
2. 保持当前权限检查和字段命名；
3. 覆盖正常导出、空结果和无权限场景；
4. 按项目规则完成验证并汇报结果。
```

任务目标清楚，项目约定也不需要重复。

五、Monorepo 如何使用分层规则？

大型仓库可能同时包含前端、后端和基础设施代码。把所有规则塞进根目录文件，会导致不同技术栈相互干扰。

可以按目录分层放置：

my-platform/
├─ AGENTS.md
├─ apps/
│  ├─ web/
│  │  └─ AGENTS.md
│  └─ api/
│     └─ AGENTS.md
└─ packages/
   └─ shared/

根目录保存全仓库规则：

# Repository Rules
- Use conventional commit messages.
- Do not edit lockfiles unless dependencies change.
- Keep changes within the requested workspace.
```

`apps/web/AGENTS.md` 保存前端规则：

```md
# Web App Rules
- Use React and the existing component library.
- Do not add inline SVG icons; use the installed icon package.
- Run `pnpm --filter web test` after modifying components.
```

`apps/api/AGENTS.md` 保存后端规则：

```md
# API Rules
- Keep route handlers thin.
- Validate input with the existing schema library.
- Run `pnpm --filter api test` after backend changes.

Codex 会根据工作目录读取适用的指导信息，更接近目标文件的规则用于处理对应子目录。分层时应避免父级和子级规则互相矛盾；如果必须覆盖，应把差异写得明确。

六、三个真实使用场景

场景 1：新增接口

`AGENTS.md` 可以固定接口分层、校验库、错误格式和测试要求。任务提示词只需描述业务输入、输出和验收条件。

场景 2：修复线上缺陷

可以加入回归测试要求：

## Bug Fixes
- Reproduce the bug before changing code when feasible.
- Add a regression test that fails before the fix.
- Avoid broad refactors during an urgent bug fix.

这会促使 Codex 证明问题已经被覆盖，而不是只修改一处看起来可疑的代码。

场景 3：代码审查

可以明确审查优先级：

## Review Priorities
- Prioritize correctness, security and regressions.
- Report findings with file and line references.
- Check tests for changed behavior and failure paths.
- Ignore unrelated formatting preferences.
```

这样得到的审查结果通常比泛泛的“帮我看看代码”更有价值。

七、最常见的错误写法

错误 1：使用空泛要求

- Write clean code.
- Follow best practices.
- Make sure everything works.

 

这些规则无法验证，也无法帮助 Codex 在两个实现方案之间做选择。

可以改成：

- Reuse existing service and repository layers.
- Do not add a new dependency without approval.
- Run `npm test` and report the result.

 

错误 2：文件过长

把架构设计、部署手册和业务文档全部复制进来，会稀释真正重要的规则。推荐只保留高频、稳定、能够改变行为的内容，详细资料用路径引用。

md
- For payment state transitions, read `docs/payment-state-machine.md`.
 

错误 3：命令与项目实际不一致

从网上复制模板后，最容易留下不存在的 `npm test` 或错误工作目录。提交 `AGENTS.md` 前，应由开发者亲自运行其中的命令。

错误 4：写入密钥和敏感信息

`AGENTS.md` 通常会进入版本库，不应包含 API Key、生产账号、内部 Token 或客户数据。只描述凭据应该从哪里读取，不要写具体值。

错误 5：把临时需求永久化

“本周先跳过测试”“临时修改某个用户数据”不属于仓库长期规则。这类要求应该留在当前任务中，并在执行前确认风险。

八、如何验证 AGENTS.md 是否有效？

不要只看文件写得是否漂亮，可以用一个小任务进行验证：

```text
先阅读当前目录适用的 AGENTS.md，不修改文件。
总结你必须遵守的架构约定、禁止事项、验证命令和完成标准。
```

检查 Codex 的总结是否准确，再给出一个范围较小的真实任务。完成后重点观察：

- 是否修改了正确的模块；
- 是否避免了禁止修改的文件；
- 是否运行了指定命令；
- 是否按要求汇报失败和剩余风险；
- Git Diff 是否只包含相关改动。

如果某条规则经常被忽略，先判断它是否过于抽象、与其他规则冲突，或者藏在过长的段落中。通常把规则改得更具体，比反复强调“必须遵守”更有效。

九、可直接使用的精简模板

# Repository Guidelines

## Structure
- Source code: `src/`
- Tests: `tests/`
- Documentation: `docs/`

## Development
- Follow existing patterns before introducing new abstractions.
- Keep changes scoped to the requested behavior.
- Do not add dependencies without approval.
- Do not edit generated files or existing migrations.

## Verification
- Run the narrowest relevant tests first.
- Run `npm run lint` after editing.
- Run `npm test` before completion.
- Report commands that could not be run and explain why.

## Completion
- Summarize modified files and behavior.
- Include test and lint results.
- Mention remaining risks and assumptions.

 

使用时不要原样照搬。先删除不适用的内容，再替换成仓库中真实存在的目录、命令和规则。

总结

`AGENTS.md` 不是万能提示词，也不是项目文档的替代品。它更像是提供给编码智能体的仓库工作说明：内容不必多，但必须稳定、具体、可执行。

一份好的 `AGENTS.md` 应做到：

- 帮助 Codex快速理解仓库结构；
- 明确代码应该放在哪里；
- 限制不相关修改和高风险操作；
- 给出真实可运行的验证命令；
- 定义完成任务时必须提交的信息。

当这些规则稳定下来后，开发者可以把注意力放回需求本身，而不是每次重新解释项目。对于准备长期使用 Codex 的团队，`AGENTS.md` 往往是成本最低、收益最直接的一项配置。