AI 编码代理能不能写出符合项目习惯的代码，往往不只取决于模型能力，还取决于它是否拿到了正确的上下文。AGENTS.md 就像放在代码库入口处的一份工程协作说明：它告诉代理项目如何运行、代码应该放在哪里、测试如何执行，以及哪些边界不能碰。
文件写得太短，代理只能猜；写成几十页的规范手册，又很难持续维护。对 Python 项目来说，好的 AGENTS.md 应该是一份短而具体的操作指南，让代理在开始修改前就知道最重要的事实。
先写代理最需要的工程事实
一份实用的 AGENTS.md 通常应覆盖以下内容：
- 项目如何安装依赖和启动本地环境
- 测试、静态检查和格式化命令
- 主要目录的职责
- 配置文件、环境变量和外部服务的边界
- 修改代码时需要遵守的局部约定
- 完成任务前必须验证的检查
关键是写出可以执行的指令，而不是抽象口号。
例如，不要只写“请确保代码质量”，可以明确写成：
提交 Python 代码前运行：
uv run pytest
uv run ruff check .
uv run ruff format --check .
新增业务逻辑时，测试放在 tests/ 下，并优先使用 pytest fixture。
前一种写法无法帮助代理做决定，后一种写法则可以直接转化为行动。命令也应尽量与项目真实使用的工具保持一致。如果项目使用 Poetry、PDM 或传统的 venv，不要为了示例整齐而改写成另一套命令。
用目录说明减少错误改动
Python 项目经常同时包含 API、领域逻辑、数据库访问和脚本。代理如果不知道目录边界，很容易把业务规则塞进路由函数，或者在测试中重复实现生产代码。
可以在 AGENTS.md 中给出一张简短的地图：
## Repository map
- `src/acme/api/`: HTTP routes and request/response schemas
- `src/acme/services/`: application use cases
- `src/acme/models/`: persistence models
- `tests/unit/`: isolated unit tests
- `tests/integration/`: tests requiring the database
- `scripts/`: one-off operational scripts; do not import them from the app
Keep business rules in `services/`, not in FastAPI route handlers.
这类信息不需要解释整个系统，只要告诉代理“这个目录负责什么”和“什么不应该放在这里”。对于经常变动的架构细节，宁可写得少一些，也不要留下过期的长篇描述。
如果某个子目录有特殊规则，还可以放置更靠近代码的 AGENTS.md。例如，根目录文件描述全局命令，src/acme/api/AGENTS.md 只补充 API 层的响应格式和兼容性要求。实际采用这种层级结构时，应明确团队使用的代理如何发现和合并这些文件，并避免在不同层级重复写同一条规则。
一份可直接改造的模板
下面的模板适合作为 Python 项目的起点。运行命令、目录名和规则需要替换成项目自己的内容。
# AGENTS.md
## Project
This is a Python 3.12 service managed with uv. The application code lives in
`src/acme/`, and tests live in `tests/`.
## Setup
Install dependencies and create the local environment with:
uv sync
Copy `.env.example` to `.env` for local development. Never commit `.env` or
real credentials.
## Validation
Run the focused test before broader checks:
uv run pytest tests/unit/path/to/test_file.py -q
Before completing a change, run:
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy src
## Code layout
- `src/acme/api/`: FastAPI routes and schemas
- `src/acme/services/`: application and domain logic
- `src/acme/repositories/`: database access
- `tests/`: tests grouped by unit and integration scope
Keep route handlers thin. Put business decisions in `services/`. Do not access
the database directly from an API route.
## Change rules
- Prefer small, focused changes.
- Preserve the public API unless the task explicitly requests a breaking change.
- Add or update tests for behavior changes.
- Use existing helpers before introducing a new abstraction.
- Do not modify migrations, CI configuration, or deployment manifests unless
the task requires it.
## Completion checklist
- Tests cover the changed behavior.
- Formatting and lint checks pass.
- No secrets, local files, or generated artifacts were added.
- The final summary names the files changed and checks executed.
这份文件的价值不在于模板本身，而在于它把“完成任务”的定义变得可检查。代理可以根据 Validation 和 Completion checklist 自主完成一轮验证，开发者也能快速审查它是否真的做过这些检查。
让规则可执行、可维护
规则要能指导选择
“遵循项目风格”通常不够具体。更有效的规则会说明优先级和例外：
## Dependencies
Use the Python standard library when it is sufficient. Before adding a third-party
dependency, check whether an existing package in `pyproject.toml` already solves
the problem. A new dependency requires a test and a short reason in the change
summary.
这条规则会影响代理的实际行为：它会先查看 pyproject.toml，而不是立即安装一个新包。
命令要覆盖不同反馈速度
把检查分成“快速反馈”和“完整验证”通常更适合日常工作。修改一个解析函数时，代理可以先运行单文件测试；准备结束时，再执行完整测试、类型检查和 lint。这样既不会把每次小改动都变成漫长流程，也不会遗漏最终验证。
写清楚危险边界
如果项目存在高风险操作，应直接写出限制。例如：
## Sensitive areas
- Do not run destructive database commands against shared environments.
- Do not edit files under `vendor/` or generated client code manually.
- Treat authentication and authorization changes as security-sensitive and add
tests for both allowed and denied cases.
这些限制比“谨慎处理数据库和安全代码”更有用，因为代理知道哪些操作需要停下来确认，哪些文件不应直接修改。
常见失败方式
把 AGENTS.md 写成公司规章全文。 过长的文档会稀释最重要的命令和边界。保留高频决策所需的信息，详细架构文档放到专门的文档目录，并在这里提供入口。
只写工具名称，不写实际命令。 “使用 pytest 和 Ruff”仍然需要代理猜测参数、工作目录和检查范围。尽量提供能复制执行的命令。
描述理想状态，而不是当前仓库。 如果文档说项目使用 Poetry，但仓库实际由 uv.lock 管理，代理会从第一步开始走偏。AGENTS.md 应和 pyproject.toml、CI 配置及实际目录保持一致。
忽略局部上下文。 一个根目录文件无法表达每个模块的特殊约束。对确实存在不同规则的子目录，可以增加局部说明，但要控制层级和重复内容。
没有定期验证文档。 当测试命令、Python 版本或目录结构变化时，AGENTS.md 很快会变成误导。可以把文档检查纳入代码审查，或者在 CI 中验证其中的关键命令仍然有效。
落地时的检查清单
把文件提交到 Python 项目前，可以逐项确认：
- 新开发者能否只看这份文件就启动测试？
- 代理是否知道最重要的源码和测试目录？
- 每条规则是否会影响一个具体的工程决策？
- 命令是否能在当前仓库中直接运行？
- 是否说明了密钥、生成文件和生产环境的边界？
- 是否列出了完成任务前必须执行的验证？
- 文档是否足够短，能够随着项目变化持续维护？
AGENTS.md 不是自动保证代码质量的魔法配置。它的作用是降低上下文缺失带来的猜测，让 AI 编码代理更快进入项目的工作方式。最好的版本通常不长，但每一段都能让代理少犯一个具体的错误。