分步构建 AGENTS.md 文件

AGENTS.md 文件是位于仓库根目录的一个 Markdown 文件。它告诉 AI 编程代理（AI coding agents）如何工作。它涵盖了构建步骤、测试和规则。

请按照以下步骤为 Python FastAPI 项目构建一个。

1. 定义技术栈

用一句话开始。告诉代理所使用的语言、框架和数据库。 示例：一个使用 Python、FastAPI、SQLite 和 pytest 开发的 URL 短链接 API。

2. 提供设置命令

给代理提供可以直接运行的真实命令。不要使用占位符。

• 设置：python -m venv .venv && source .venv/bin/activate
• 运行：uvicorn app.main:app --reload

3. 设定测试标准

这至关重要。代理会使用测试来检查自己的工作。

• 运行 pytest
• 运行 ruff check
• 运行 mypy

4. 映射目录结构

列出你的文件夹，这样代理就不必搜索每个文件。

• app/main.py: 路由处理器
• app/db.py: SQLite 访问
• migrations/: 生成的 SQL（请勿编辑）

5. 定义规范

要具体。模糊的规则是没用的。

• 使用 Pydantic 进行所有输入验证。
• 对客户端错误抛出 HTTPException。
• 为所有内容添加类型标注，以保持 mypy 的整洁。

6. 列出“禁令”

通过设定硬性边界来防止错误。

• 不要手动编辑迁移文件。
• 不要直接提交到 main 分支。
• 绝不要在非本地数据库上运行种子脚本（seed scripts）。

为什么这行之有效

当你给 AI 代理分配一个任务，例如“添加一个 DELETE 端点”时，它会首先阅读此文件。

有了 AGENTS.md 文件，代理可以：

• 准确知道在哪里添加代码。
• 使用你指定的测试工具。
• 无需询问即可遵循你的风格。
• 创建一个分支，而不是破坏你的主代码。

如果没有这个文件，代理就会靠猜测。它可能会使用错误的测试运行器，或者编辑不该触碰的文件。

请像对待代码一样对待此文件。如果你的工作流发生了变化，请立即更新文件。过时的文件会导致错误。

来源: https://dev.to/wolfejam/agentsmd-hands-on-build-one-step-by-step-and-watch-an-agent-use-it-3g27

可选学习社区: https://t.me/GyaanSetuAi