AI 编码代理能补全函数、拆分模块、编写测试，但它默认不了解你的仓库习惯：包管理器、代码风格、测试命令、分层边界，甚至哪些文件绝不能改。AGENTS.md 的作用，是把这些隐含规则写成代理在每次任务开始前都能执行的项目说明，减少看似正确却无法合并的改动。
把工程约定变成可执行指令
一份有效的 AGENTS.md 不应是团队文化介绍，而应回答代理完成任务必须解决的问题：
- 从哪里安装依赖，使用哪个 Python 版本。
- 怎样运行格式化、静态检查和测试。
- 业务代码、HTTP 层、数据访问层各自放在哪里。
- 新功能应采用哪些已有模式。
- 哪些目录、生成文件或迁移文件需要额外确认。
抽象要求例如“保持代码干净”通常无法指导具体决策。相比之下，“新增 FastAPI 路由放入 src/app/api/，路由只负责请求校验，数据库访问经由 src/app/services/”可以直接影响代理生成的文件和依赖方向。
从仓库事实出发，而不是罗列偏好
编写前，先检查项目中已经存在的权威配置。pyproject.toml、测试目录、CI 工作流和贡献指南通常比口头约定更可靠。可以这样快速收集信息：
find . -maxdepth 3 -type f \( -name 'pyproject.toml' -o -name 'pytest.ini' -o -name 'ruff.toml' -o -name 'conftest.py' \) -print
sed -n '1,220p' pyproject.toml
find tests -maxdepth 2 -type f -name 'test_*.py' -print 2>/dev/null
观察现有测试如何命名、fixture 放在哪里、异步函数怎样测试，再将结论写进指南。这样代理是在延续仓库现状，而不是把另一套通用 Python 风格硬塞进项目。
一个可直接改造的 Python 项目模板
下面假设项目采用 src/ 布局、uv 管理依赖、Ruff 做检查、pytest 跑测试。请将命令和目录名替换为仓库的真实情况，再保存为根目录的 AGENTS.md：
# AGENTS.md
## Project
- Python version: 3.12
- Package manager: uv
- Source code: `src/acme/`
- Tests: `tests/`
## Setup and validation
Run these commands from the repository root:
```bash
uv sync --all-groups
uv run ruff format --check .
uv run ruff check .
uv run pytest
Before finishing a change, run the narrowest relevant test first, then run the full test suite when shared behavior changes.
Code conventions
- Add production modules under
src/acme/; do not import fromtests/. - Keep public functions fully type annotated.
- Use
pathlib.Pathfor filesystem paths. - Raise domain-specific exceptions from
src/acme/errors.py; do not expose database-driver exceptions from service functions. - Keep HTTP handlers thin: parse input, call a service, map expected errors to responses.
Tests
- Name test files
test_<module>.pyand test functionstest_<behavior>. - Use pytest fixtures for setup. Do not make real network calls in unit tests.
- Add a regression test for every bug fix.
Boundaries
- Do not edit lock files manually. Use
uv addoruv remove. - Do not change database migrations or CI workflows unless the task explicitly requires it.
- Ask before introducing a new runtime dependency. ```
这个模板的关键不在于使用了哪种工具，而在于每条规则都能被验证。代理知道命令，就能在修改后自行检查；代理知道边界，就不容易为了解决局部问题跨层重构。
为常见任务补充局部规则
根目录的规则应保持稳定、简短。对于容易出错的子系统，可以在对应目录加入更具体的 AGENTS.md，例如 API 目录强调错误响应格式，数据层目录强调事务和迁移限制。局部文件只写该目录特有的约束，避免复制根文件后逐渐失效。
还应把“完成”的标准说清楚。一个新增接口不只是有路由和实现，还可能需要输入校验、错误映射、单元测试和文档更新。对高风险操作，明确要求代理先说明影响范围或先请求确认，比笼统地要求“谨慎修改”更有效。
维护时关注准确性，而非篇幅
AGENTS.md 是工程接口的一部分，应随工具链和目录结构演进。每次升级 Python、替换包管理器、迁移 lint 工具或调整测试布局后，都应更新相关命令。过期命令会让代理浪费时间，也会降低团队对指南的信任。
可以用下面这份检查清单审视现有文件：
- 新成员能否仅凭文件完成安装、检查和测试？
- 规则是否对应仓库中真实存在的脚本、目录和配置？
- 是否说明了新增代码、测试和依赖的落点？
- 高风险或不应自动修改的区域是否明确？
- 每个命令是否仍能在 CI 或本地环境运行？
从一份覆盖构建、验证、目录边界和测试习惯的短文档开始，比写一篇面面俱到但无人维护的规范更有价值。随着代理反复在同一类任务上犯错，再把具体教训沉淀为可执行规则，AGENTS.md 才会真正提高首轮改动的可用性。