如何为 Python 项目编写 AGENTS.md 文件指南
- 作者
- 姓名
- Nino
- 职业
- Senior Tech Editor
随着 Cursor、Windsurf 以及基于 LangChain 开发的自定义 AI 智能体（Agents）成为现代开发者的标配工具，我们记录和维护项目文档的方式也在发生深刻的变化。传统的 README.md 文件是为人类开发者编写的，主要包含高层架构、安装步骤和许可证信息。然而，AI 智能体需要的是完全不同的内容：精准的约束条件、严格的编码规范、质量门禁（Quality Gates）以及明确的上下文边界。
为了填补这一空白，开发者社区引入了 AGENTS.md 文件的概念。这个专门的 Markdown 文件扮演着系统提示词（System Prompt）和操作手册的角色，供任何与你的代码库交互的 AI 智能体读取。通过 n1n.ai 平台接入诸如 Claude 3.5 Sonnet 和 DeepSeek-V3 等先进的大语言模型（LLM），开发者可以利用此类文件显著降低幻觉率，防止引入破坏性变更，并确保智能体编写出符合 Python 最佳实践的代码。
在这篇深度指南中，我们将探讨 AGENTS.md 文件的核心结构，分析为什么精简的文件比冗长的文件表现更优，并通过技术测试题检验你的理解程度。
为什么你需要为 Python 项目编写 AGENTS.md 文件
AI 智能体的工作原理是读取你的代码库、解析你的提示词，并结合其训练权重和上下文信息来生成代码。如果没有 AGENTS.md 文件，智能体就必须猜测项目的架构模式、测试策略和代码风格偏好。这通常会导致以下问题：
- 风格漂移（Style Drift）：智能体可能会混合使用面向对象与函数式编程模式，或者在已经使用现代
pyproject.toml的项目里生成过时的setup.py配置文件。 - 依赖混乱：在项目严格依赖 Poetry 或
uv来维护锁文件（Lockfile）完整性时，智能体却尝试使用pip install安装依赖包。 - 质量门禁失效：智能体编写的代码绕过了静态分析工具（如
mypy、ruff、black），导致 CI/CD 流水线构建失败。
通过在项目根目录下放置一个结构化的 AGENTS.md 文件，你为 LLM 提供了一个单一的事实来源（Single Source of Truth）。当借助 n1n.ai 聚合服务来驱动你的自定义智能体工作流时，该文件能帮助你在不同的模型架构之间保持高度的一致性。
AGENTS.md 文件的结构解析
一个生产级别的 AGENTS.md 文件通常被划分为几个不同的功能板块。每个板块针对开发者与智能体协作的特定维度。
1. 项目领域与上下文 (Project Domain & Context)
此部分定义了项目“是什么”以及“为谁服务”。它能防止智能体对应用运行环境做出错误的假设（例如，在一个标准的 Django REST API 项目中误用了 Web3 的上下文）。
2. 环境配置与依赖管理 (Setup & Environment Management)
Python 的包管理生态较为碎片化。你必须明确指出项目是使用 Poetry、uv、Conda 还是标准的虚拟环境（venv）。
3. 编码规范与风格 (Coding Conventions & Style)
定义 Python 的代码标准。是否强制执行 PEP 8？是否使用严格的类型提示（Type Hints）？是否优先使用异步模式（Async）？请在此处详细说明。
4. 项目结构 (Project Structure)
提供目录布局的直观表示，有助于智能体快速定位文件，而无需递归读取每个目录，从而节省 Token 并降低延迟。
5. 质量门禁 (Quality Gates)
列出智能体在提交更改前必须运行的精确命令。如果测试未通过，智能体不应将任务标记为完成。
6. 约束与忽略规则 (Constraints & Ignore Rules)
定义边界。例如，禁止智能体直接修改数据库模式或使用已被废弃的库。
生产级 AGENTS.md 模板
以下是专为现代 Python 项目优化的模板。你可以直接复制并根据自己的代码库进行调整。
# AGENTS.md - AI 开发者操作指南
## 1. 项目领域与上下文
- **项目名称**: FastQuery
- **业务领域**: 基于 `asyncpg` 的高性能 PostgreSQL 异步数据库包装器。
- **目标环境**: Python 3.11+ / 容器化 Linux 环境。
- **核心目标**: 提供类型安全、低延迟的查询执行，并支持自动连接池管理。
## 2. 环境配置与依赖管理
- **包管理器**: Poetry（切勿直接使用 `pip` 或 `requirements.txt`）。
- **虚拟环境激活**: `poetry shell`
- **安装命令**: `poetry install --with dev`
- **锁文件策略**: 除非明确要求，否则切勿运行 `poetry update`。仅使用 `poetry add [package]` 来添加依赖。
## 3. 编码规范
- **格式化**: 代码必须严格符合 Ruff 的格式化规则。运行 `poetry run ruff format`。
- **类型提示**: 所有函数签名必须声明类型。使用 `from typing import ...` 或原生订阅类型（例如，使用 `list[str]` 代替 `List[str]`）。
- **并发处理**: 采用 `async`/`await` 范式。避免在异步循环中执行阻塞性同步调用（例如，不要使用 `time.sleep()`，应使用 `await asyncio.sleep()`）。
- **异常处理**: 必须捕获具体的异常，严禁使用裸 `except:` 语句。
## 4. 项目结构
```text
fastquery/
├── src/
│ └── fastquery/
│ ├── __init__.py
│ ├── pool.py # 连接池逻辑
│ └── client.py # 主 API 客户端接口
├── tests/
│ └── test_client.py # 集成与单元测试
├── pyproject.toml # Poetry 及工具配置
└── AGENTS.md # 本文件
```
5. 质量门禁
在提交任何代码更改之前，你必须运行并通过以下检查：
- 代码风格与格式:
poetry run ruff check .和poetry run ruff format --check . - 类型检查:
poetry run mypy src/（必须返回 0 错误，已启用严格模式）。 - 单元测试:
poetry run pytest tests/（最低覆盖率阈值：90%）。
6. 约束与忽略规则
- 数据库安全: 严禁编写原生 SQL 迁移脚本。所有迁移必须通过 Alembic 进行。
- 文件修改: 请勿修改
tests/fixtures/目录中的任何文件。 - 性能指标: 确保数据库查询延迟保持在 < 50ms。避免出现 N+1 查询模式。
---
## 精简与冗长：上下文窗口的科学
在编写 `AGENTS.md` 文件时，开发者很容易陷入一个误区：试图将每一个细节、错误日志和架构决策记录（ADR）都塞进去。这会导致文件变得极其“臃肿”。
### 上下文膨胀的代价
1. **注意力稀释（Lost in the Middle）**：大语言模型使用自注意力机制（Self-Attention）。当你向 LLM 输入一个庞大的上下文文件时，模型检索位于文档中部指令的能力会显著下降。
2. **延迟与 Token 成本**：发送给 LLM 的每个 Prompt 都会在头部带上 `AGENTS.md` 的内容。一个 5000 字的文件会显著增加响应延迟并推高 API 费用。使用 [n1n.ai](https://n1n.ai) 来测试 Claude 3.5 Sonnet 等模型时，你会发现保持指令精简与更快的响应速度之间存在直接的正相关关系。
3. **指令冲突**：文件越长，引入相互矛盾规则的概率就越高（例如，在某一部分要求严格的类型安全，却在另一部分展示了动态且未声明类型的代码示例）。
### 保持精简的“知情同意”原则
* **控制在 150 行以内**：如果你的 `AGENTS.md` 超过了 150 行，请进行拆分。将核心操作指令保留在 `AGENTS.md` 中，而将深度的架构设计移至独立的 `/docs/architecture.md` 文件中，供智能体在需要时自行读取。
* **使用陈述性列表**：避免长篇大论。使用清晰、祈使性的短句（例如，用“使用 Ruff 进行代码检查”代替“因为我们决定将代码风格标准迁移到 Ruff，所以...”）。
---
## 互动测试：检验你的理解
测试你对为 Python 项目编写 AI 智能体指令的掌握程度。选择你的答案并阅读下方的详细解析。
### 问题 1：上下文管理
**尽管你的 `AGENTS.md` 中指定了使用 Ruff，但智能体仍然不断编写违反格式标准的代码。该文件目前长达 350 行，其中包含详细的项目架构演进历史。解决这个问题最有效的方法是什么？**
* A) 在 `AGENTS.md` 文件中添加更多正确格式化代码的示例。
* B) 删除架构历史记录，将文件精简到 150 行以内，并将格式化命令置于“质量门禁”部分的顶部。
* C) 切换到其他 LLM，因为当前模型无法理解并执行复杂的指令。
* D) 编写一个自定义脚本，在智能体每次保存文件时自动运行 Ruff。
*答案解析：*
正确答案是 **B**。添加更多示例（选项 A）会加剧上下文膨胀，导致“迷失在中间”效应更加严重。虽然自动化脚本（选项 D）很有用，但它只是治标不治本，没有解决智能体指令失焦的底层问题。精简文件可以减少注意力稀释，使智能体能够成功解析并执行格式化约束。
### 问题 2：Python 依赖约束
**你的 Python 项目使用 Poetry 管理依赖。AI 智能体需要添加一个依赖包（`httpx`）来开发新功能。`AGENTS.md` 中的哪项指令能最有效地防止智能体损坏你的锁文件？**
* A) “使用 pip 安装依赖。”
* B) “运行 `poetry update` 以确保所有依赖包都是最新的。”
* C) “仅使用 `poetry add [package]` 添加依赖包。切勿直接运行 `poetry update` 或手动修改 `pyproject.toml`。”
* D) “依赖项是自动管理的。请勿添加任何新包。”
*答案解析：*
正确答案是 **C**。运行 `poetry update`（选项 B）可能会更新与当前任务无关的依赖，从而引入破坏性变更。手动修改 `pyproject.toml` 而不运行锁定命令会导致依赖不一致。明确指示智能体使用 `poetry add` 可以确保安全地更新锁文件。
### 问题 3：格式化与语法安全
**为什么在某些集成了 MDX 解析器的文档或智能体接口中，必须对 `<` 字符进行转义（如 `<`），或者避免直接使用裸大括号 `{}`？**
* A) 防止 Markdown 解析器将这些符号误判为 HTML 标签或 React/JavaScript 组件，从而导致渲染引擎崩溃。
* B) LLM 无法识别 `<` 符号，遇到它会产生幻觉。
* C) 这是 Python 解析 Markdown 元数据时的特有要求。
* D) 这样可以提高 Prompt 的语义密度。
*答案解析：*
正确答案是 **A**。许多现代文档网站和智能体交互界面使用 MDX（Markdown + JSX）。直接使用后跟文本的 `<` 符号或裸大括号 `{}` 会触发编译期错误，因为解析器会尝试将它们作为 JSX 代码进行评估。保持文件清洁并进行适当转义可以确保在各种解析引擎中的兼容性。
---
## 针对 Python 项目的 AGENTS.md 进阶技巧
1. **利用 Pyproject.toml 进行集成**：与其在 `AGENTS.md` 中列出所有详细的静态检查规则，不如直接在 `pyproject.toml` 的 `[tool.ruff]` 和 `[tool.mypy]` 下进行配置。然后在 `AGENTS.md` 中简单地告诉智能体：“运行 `ruff check .` 来验证格式。”这样可以保持 Markdown 文件的清爽，同时充分利用智能体已经读取的配置文件。
2. **动态智能体路由**：不同的任务需要不同的模型。对于代码重构，像 OpenAI o3-mini 或 DeepSeek-R1 这样的推理模型是理想之选；而对于标准的文档编写或样板代码生成，Claude 3.5 Sonnet 则表现优异。使用 [n1n.ai](https://n1n.ai) 可以让你动态地将这些任务路由到最合适的模型，同时将结构化的 `AGENTS.md` 文件作为上下文传递过去。
3. **“智能体自检”步骤**：始终在 `AGENTS.md` 中加入一条规则，要求智能体在返回响应*之前*必须在本地运行质量门禁命令。这会强制智能体在将解决方案呈现给你之前，先在自己的工作区中自我纠正错误。
Get a free API key at [n1n.ai](https://n1n.ai)