AGENTS.md 手把手教程：一步步构建，看 AI 编码助手如何用起来
在入门指南中，我介绍了什么是 AGENTS.md 以及里面应该放什么。本篇是实战跟进：我们将为一个真实项目逐一编写完整的 AGENTS.md，然后让 AI 编码助手来使用它，亲眼见证它的效果。到最后你将拥有一份可用的文件——并且亲眼看到它的回报。
还不了解 AGENTS.md？它是一个放在仓库根目录的 Markdown 文件，告诉 AI 编码助手如何在这个项目中工作——构建步骤、测试、规范、护栏。每个部分背后的"为什么"请参考入门指南。
我们使用的项目
我们将为一个小型但真实的服务编写 AGENTS.md：一个Python 编写的 URL 缩短器 API——FastAPI、SQLite、pytest。几个端点、一层薄薄的数据层、一套测试。你可以跟着做，也可以换成自己的仓库——步骤完全一样。
项目结构：
linkshort/
app/
main.py # FastAPI routes
db.py # SQLite access
models.py # Pydantic models
migrations/ # generated SQL — not hand-edited
tests/
requirements.txt
第 0 步——从一个空文件开始
在仓库根目录：
touch AGENTS.md
就这步。我们将逐段填充，构建出一个助手能在 30 秒内读完的文件。
第 1 步——方向：一句话
告诉助手它面对的是什么。添加：
# AGENTS.md
A URL shortener API in Python — FastAPI, SQLite, pytest.
一句话就设定了助手的先验知识：它在读第一行代码之前就知道了语言、框架和存储。
第 2 步——安装和运行
助手如果连项目都启动不了就无法帮忙。添加真实的、可复制粘贴的命令：
## Setup
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
## Run
uvicorn app.main:app --reload # http://localhost:8000
使用你仓库中实际能用的命令——不要用占位符。
第 3 步——测试：助手的反馈循环
这是最重要的部分，因为测试是助手检查自己工作的方式。添加：
## Test — all must pass before a change is done
pytest
ruff check .
mypy app
现在助手知道如何验证修改，也知道必须达到什么标准。知道 pytest 的助手会运行它；不知道的助手会给你一个坏掉的分支。
第 4 步——地图：文件在哪
一份简短的地图，让助手无需探索整个目录结构就能定位：
## Structure
- app/main.py route handlers
- app/db.py SQLite access (parameterized queries only, never string-built SQL)
- app/models.py Pydantic request/response models
- migrations/ generated SQL — do not hand-edit
- tests/ pytest, mirroring app/
注意我们已经在相关位置融入了规范——"只允许参数化查询"和护栏"不要手动编辑"。
第 5 步——规范：代码风格
你希望遵循的模式。要具体——模糊的规则只是噪音：
## Conventions
- Validate all input with Pydantic models at the route boundary.
- Raise HTTPException for client errors; never return raw dicts on failure.
- Type everything; mypy must stay clean.
- Match the style of the surrounding file.
"给所有内容加上类型标注；mypy 必须保持干净"明确告诉了助手该怎么做。"写出好代码"则不会。
第 6 步——提交和 PR
如果你的助手会开 PR，给它内部规则：
## Commits & PRs
- Conventional Commits (feat:, fix:, chore:).
- One logical change per PR; update CHANGELOG.md.
第 7 步——护栏：雷区
那些"不要做"的规则，可以防止代价高昂的错误：
## Don't
- Don't hand-edit migrations/ — they're generated.
- Don't commit directly to main — branch and open a PR.
- Never run the seed script against a non-local database.
你的完整 AGENTS.md
把以上内容拼在一起，你就得到了一份完整的、可复制粘贴的文件：
# AGENTS.md
A URL shortener API in Python — FastAPI, SQLite, pytest.
## Setup
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
## Run
uvicorn app.main:app --reload # http://localhost:8000
## Test — all must pass before a change is done
pytest
ruff check .
mypy app
## Structure
- app/main.py route handlers
- app/db.py SQLite access (parameterized queries only, never string-built SQL)
- app/models.py Pydantic request/response models
- migrations/ generated SQL — do not hand-edit
- tests/ pytest, mirroring app/
## Conventions
- Validate all input with Pydantic models at the route boundary.
- Raise HTTPException for client errors; never return raw dicts on failure.
- Type everything; mypy must stay clean.
- Match the style of the surrounding file.
## Commits & PRs
- Conventional Commits (feat:, fix:, chore:).
- One logical change per PR; update CHANGELOG.md.
## Don't
- Don't hand-edit migrations/ — they're generated.
- Don't commit directly to main — branch and open a PR.
- Never run the seed script against a non-local database.
三十秒就能读完。现在来看看它是否管用。
第 8 步——验证：让助手来试试
这才是关键部分。在你的代码编辑助手中打开仓库——Claude Code、Cursor、Codex，随便你用哪个——然后给一个真实的任务：
"添加一个 DELETE /links/{code} 端点，可以删除链接，并附带测试。"
观察有了 AGENTS.md 后它会怎么做：
- 它先读取文件——它知道了技术栈和路由的位置。
- 它在
app/main.py中添加处理器，按照你的规范要求验证输入。 - 它在
tests/中编写 pytest 测试，镜像项目结构。 - 它运行
pytest、ruff和mypy——因为你告诉它这是标准——并修复失败的问题。 - 它不会动
migrations/，也不会提交到 main——它会开一个新分支。
现在想象一下没有这个文件做同样的任务。助手只能猜：用什么测试框架？路由写在哪？有 lint 步骤吗？于是它来问你，或者猜错，或者编辑了一个生成文件让你不得不回退。AGENTS.md 就是一个打断你的助手和一个直接交付的助手之间的区别。
这就是全部的回报——你可以实时看到它发生。
保持更新
养成一个习惯：把这个文件当代码来维护。当测试命令变了，或者你添加了目录，或者你发现自己反复告诉助手同样的事情——顺手更新 AGENTS.md。过时的文件比没有更糟，因为助手会信任它。
这就是循环
你从一个空文件开始，添加了八个简短的部分，然后亲眼看到一个助手用它们每一个来完成一个正确、经过测试的修改，全程无需手把手指导。写一次，每个进入你仓库的助手都会收到同样的简报。
以上就是实战构建部分。关于每个部分背后的原则——应该放什么、反模式、为什么短小胜过完整——请参考入门指南。
