这是一篇factory.ai介绍agent.md的文章。
agent.md基本上就是claude.md或者cursorrules，不过他是个通用标准，很多ai coding工具都支持。在当前ai coding工具大乱战的情况下是个不错的选择
使用单一的 Markdown 文件向代理传授他们需要了解的关于您项目的一切。
1 · 什么是 AGENTS.md？
AGENTS.md 是一个存在于您的代码仓库（或主目录）中的 Markdown 文件，它充当 AI 编码代理的简报包。
为什么需要 AGENTS.md？
README.md 文件是为人类准备的：快速入门、项目描述和贡献指南。 AGENTS.md 则通过包含编码代理需要的额外、有时是详细的上下文来补充这一点：构建步骤、测试和约定，这些内容可能会使 README 变得混乱，或者与人类贡献者无关。
我们有意将其分开，以便：
- 为代理提供一个清晰、可预测的指令存放位置
- 保持 README 的简洁性，专注于人类贡献者
- 提供精确的、专注于代理的指导，以补充现有的 README 和文档
它包含的内容：
描述如何构建、测试和运行您的项目 解释架构模式和约定 列出外部服务、环境变量或设计文档 提供特定领域的词汇和代码风格规则
代理在规划任何更改之前都会阅读 AGENTS.md，让他们获得资深工程师已经掌握的相同团队知识。
2 · 一个 AGENTS.md 适用于多个代理
您的 AGENTS.md 文件与不断增长的 AI 编码代理和工具生态系统兼容，包括：
- Factory Droid - Factory 的 AI 编码代理
- Cursor - AI 驱动的代码编辑器
- Aider - 终端中的 AI 结对编程
- Gemini CLI - Google 的命令行 AI 助手
- Jules - Google 的编码助手
- Codex - OpenAI 的代码生成模型
- Zed - AI 增强编辑器
- Phoenix - AI 开发平台
- 以及许多新兴工具
与其引入另一种专有文件格式，AGENTS.md 使用了在整个 AI 开发生态系统中都适用的标准。
3 · 文件位置和发现层次结构
代理按以下顺序查找 AGENTS.md（找到第一个匹配项即停止）：
- 当前工作目录中的 ./AGENTS.md
- 最接近的父目录，直到仓库根目录
- 代理正在工作的子文件夹中的任何 AGENTS.md
- 个人覆盖：~/.factory/AGENTS.md
多个文件可以共存。距离正在编辑的文件更近的那个具有优先权。
4 · 文件结构和语法
AGENTS.md 是普通的 Markdown；标题提供语义提示。
markdown
# Build & Test ← 编译和测试的精确命令
# Architecture Overview ← 主要模块的简短描述
# Security ← 认证流程、API 密钥、敏感数据
# Git Workflows ← 分支、提交约定、PR 要求
# Conventions & Patterns ← 命名、文件夹布局、代码风格代理识别：
- 顶级标题 (#) 作为章节
- 用于命令或规则的项目符号列表
- 内联代码 (`) 用于精确命令、文件名、环境变量
- 指向外部文档的链接（GitHub、Figma、Confluence...）
5 · 常见章节
| 章节 | 目的 |
|---|---|
| Build & Test | 编译和运行测试套件的精确命令。 |
| Architecture Overview | 主要模块和数据流的单段摘要。 |
| Security | API 密钥、端点、认证流程、速率限制、敏感数据。 |
| Git Workflows | 分支策略、提交约定、PR 要求。 |
| Conventions & Patterns | 文件夹结构、命名模式、代码风格、lint 规则。 |
只包含未来的您会关心的内容------简洁胜于百科全书长度的文件。
6 · 模板和示例
Factory 风格的综合示例
markdown
# MyProject
这是 My Project 的概述。这是一个用于突出 AGENTS.md 文件实用性的示例应用程序。
## 核心命令
• 类型检查和 lint：`pnpm check`
• 自动修复样式：`pnpm check:fix`
• 运行完整测试套件：`pnpm test --run --no-color`
• 运行单个测试文件：`pnpm test --run <path>.test.ts`
• 启动开发服务器（前端 + 后端）：`pnpm dev`
• 生产构建：`pnpm build` 然后 `pnpm preview`
所有其他脚本都包装这六个任务。
## 项目布局
├─ client/ → React + Vite 前端
├─ server/ → Express 后端
• 前端代码**仅**存在于 `client/` 中
• 后端代码**仅**存在于 `server/` 中
• 共享的、环境无关的辅助函数属于 `src/`
## 开发模式和约束
### 编码风格
• TypeScript 严格模式，单引号，尾随逗号，无分号。
• 100 字符行限制，制表符缩进（YAML/JSON/MD 使用 2 空格）。
• 公共 API 使用接口；避免 `@ts-ignore`。
• 修复逻辑错误时测试先行。
• UI 调整使用视觉差异循环。
• 未经 PR 描述解释，绝不引入新的运行时依赖。
## Git 工作流程要点
1. 使用描述性名称从 `main` 分支：`feature/<slug>` 或 `bugfix/<slug>`。
2. 在提交**之前**本地运行 `pnpm check`。
3. **仅允许**在您的功能分支上使用 `git push --force-with-lease` 进行强制推送。绝不强制推送 `main`。
4. 保持提交的原子性；偏好检查点（`feat: ...`、`test: ...`）。
## 每个 PR 所需的证据
当 PR 包含以下内容时可以审查：
- 所有测试通过（`pnpm test`）
- Lint 和类型检查通过（`pnpm check`）
- 差异限制在约定路径内（见第 2 节）
- **证明工件**
• 错误修复 → 首先添加失败的测试，现在通过
• 功能 → 展示行为的新测试或视觉快照
- 一段式提交/PR 描述，涵盖意图和根本原因
- 覆盖率不下降，无未解释的运行时依赖Node + React 单一仓库
markdown
# Build & Test
- Build: `npm run build`
- Test: `npm run test -- --runInBand`
# Run Locally
- API: `npm run dev --workspace=api`
- Web: `npm run dev --workspace=web`
- Storybook: `npm run storybook`
# Conventions
- 所有后端代码在 `packages/api/src`
- React 组件在 `packages/web/src/components`
- 使用 `zod` 进行请求验证
# Architecture Overview
API 是 GraphQL (Apollo)。Web 使用带 SSR 的 Next.js。
# External Services
- Stripe 用于支付（`STRIPE_KEY`）
- S3 用于上传（`AWS_BUCKET`）
# Gotchas
- 测试快照路径是绝对的------重构后运行 `npm run test -- --updateSnapshot`。Python 微服务
markdown
# Build & Test
- Build: `pip install -e .`
- Test: `pytest`
# Run Locally
- `uvicorn app.main:app --reload`
# Conventions
- 通过 Pydantic 设置进行配置（`settings.py`）
- CELERY 任务存在于 `tasks/` 中7 · 最佳实践
保持简洁 使用具体命令 与代码同步更新 单一真实来源 让请求精确 合并前验证
8 · 代理如何使用 AGENTS.md
-
摄取 任务开始时，代理将最近的 AGENTS.md 加载到他们的上下文窗口中。
-
规划 构建/测试命令用于形成执行计划（例如，编辑后运行测试）。
-
工具选择 文件夹和命名约定引导诸如 edit_file 和 create_file 等工具的使用。
-
验证 陷阱和领域词汇改善推理并减少幻觉。
9 · 当出现问题时
像任何开发工作一样，当范围蔓延或假设被证明错误时，代理任务有时需要方向修正。与人类合作者相同的迭代模式在这里也适用。
代理漂移的警告信号：
- 计划在执行过程中自我重写
- 在声明路径之外的编辑
- 声称修复但没有失败的测试来证明它们有效
- 充满不相关更改的差异
恢复手册：
- 收紧规格：缩小代理可能接触的目录或测试范围
- 拯救好的部分：保留有效的工件，如失败的测试；恢复嘈杂的编辑
- 重新启动：使用改进的指令启动新的会话
- 接管：当您能判断代理正在失败时，结对编程最终更改
10 · 开始使用
-
规格模式 规格 + AGENTS.md = 新功能的即时上下文。
-
自动运行 可靠的自动化依赖于准确的构建和测试命令。
总结
- 在您的仓库根目录添加 AGENTS.md（以及子模块可选）。
- 记录构建/测试命令、约定和陷阱------简洁且可操作。
- 代理自动读取；无需额外标志。
- 从您的待办事项列表中选择一个小错误或小功能。写三个清晰的句子，说明从哪里开始，如何重现问题，以及什么证据表示完成。让代理通过 Explore → Plan → Code → Verify 运行，审查证据，然后合并。
以更少的意外更快地交付------为您的代理提供它需要的行动手册！