Factory AGENTS.md 规范：为 Droid 构建持久化指令与安全护栏
原文：AGENTS.md | 作者：Factory | 日期：2026-10-26
📝 摘要
本文档是 Factory 为其自主编程智能体 Droid 制定的官方 AGENTS.md 编排规范。文章详细阐述了如何通过根目录与嵌套指令文件，为 Agent 提供在每个会话中持久生效的项目上下文、构建验证命令与安全边界。核心内容包括：五种正交指令载体（AGENTS.md、DESIGN.md、SKILL.md、自定义命令与设置文件）的分工原则；自底向上的动态发现机制与四层继承优先级；严格的上下文预算上限（初始加载 80k 字符、动态发现 40k 字符）；以及可直接落地的根目录与子项目标准模板和常见排错策略。
📋 术语表
| 英文 | 中文 | 说明 |
|---|---|---|
| Droid | Droid | Factory 推出的自主编程智能体（AI Coding Agent） |
| harness | 编排框架 / 接入层 | 围绕模型构建的运行时环境，负责工具调用、上下文加载与指令分发 |
| context budget | 上下文预算 | 允许指令文件在单次会话上下文窗口中所能占据的最大字符上限 |
| dynamic discovery | 动态发现 | Agent 在逐层读取文件路径时，动态探测并加载局部指令文件的机制 |
| instruction surface | 指令载体 / 指令界面 | 暴露给 Agent 的不同持久化指令通道（如 AGENTS.md、DESIGN.md、SKILL.md 等） |
| nested instructions | 嵌套指令 | 位于 Monorepo 子目录或特定服务包内部的局部规则文件 |
| personal directory | 个人指令目录 | 位于用户家目录下跨项目共享的个人默认偏好配置（如 ~/.factory/） |
| standing instructions | 常驻指令 | 只要进入对应项目或目录树就会自动加载生效的基线规则 |
| verbatim | 逐字 / 原生 | 未经压缩或摘要提取的原样文本与代码内容 |
正文
使用 AGENTS.md 为 Droid 提供持久生效的项目指令、执行命令与安全护栏。
AGENTS.md 为 Droid 提供了它在每次会话中都应随身携带的项目简报：如何安装依赖、运行服务、执行测试、修改代码、核验证据，以及如何严格遵守代码库的边界约束。
它专门用于承载那些在 Droid 着手编写代码前就必须加载的指导原则。请务必保持其短小精悍、具体明确且易于验证。
创建你的第一个 AGENTS.md
- 创建单个根文件：在仓库根目录添加
AGENTS.md。先从一个根文件开始，仅当某个软件包、应用或服务确实需要差异化规则时，才补充嵌套文件。 - 命令置顶：清晰列出 Droid 应当运行的精确命令，涵盖依赖安装、本地开发、测试运行、类型检查、代码规范检查与打包构建。当全量命令耗时过长时，应附带具体的命令行参数或包过滤器。
- 明确规范与安全规则：收录仓库目录骨架、生成代码维护规则、安全隔离边界、代码归属权限，以及 Droid 在宣告任务完成前必须出具的验证凭据。
- 将文件提交至版本控制：项目级指令必须检入 Git 仓库，确保每位人类队友与自动化任务会话都能获得完全一致的操作上下文。
# 仓库操作指南
## 命令清单
- 安装依赖：`pnpm install`
- 启动本地开发服务：`pnpm dev`
- 运行单元测试：`pnpm test`
- 运行类型检查：`pnpm typecheck`
- 运行代码检查：`pnpm lint`
## 项目目录布局
- `apps/web/`：主应用程序
- `packages/ui/`：跨项目共享的 UI 组件库
- `packages/config/`：共享工具集与通用配置
## 编码规范
- 使用严格模式下的 TypeScript。
- 优先声明明确类型，避免使用 `any`。
- 改动保持克制，专注于当前请求的任务范围。
## 验证流程
在收工前，必须依次执行：
1. `pnpm test`
2. `pnpm lint`
3. `pnpm typecheck`应该包含哪些内容
| 章节名称 | 优秀示例的标准 |
|---|---|
| 项目概览 (Project overview) | 一段简短文字，清晰解释产品定位、整体架构或软件包功能。 |
| 命令清单 (Commands) | 给出确切的依赖安装、本地启动、测试、Lint、类型检查、构建以及代码重新生成命令。 |
| 仓库地图 (Repository map) | Droid 在动笔修改前必须掌握的核心目录职责划分。 |
| 编码惯例 (Conventions) | 无法单凭浏览代码直观推导出的项目专属设计模式与习惯。 |
| 测试规则 (Testing rules) | 针对性单测命令、全量发布门禁命令，以及何时必须补充测试用例。 |
| 生成文件 (Generated files) | 标明哪些文件属于自动生成、真正应该修改的源文件位置，以及重新生成的命令。 |
| 安全规则 (Security rules) | 机密信息处理规范、生产环境隔离底线、权限审批机制与数据库迁移安全。 |
| PR 交付标准 (PR expectations) | 必须出具的运行凭据、截图、变更日志记录或代码审查前置检查项。 |
优先编写能够切实改变 Droid 操作行为的具体规则：
## 测试规范
- 针对局部修改，运行针对性单测：`pnpm test -- path/to/file.test.ts`。
- 在完成大范围重构前，必须执行全量测试：`pnpm test`。
- 只要条件允许，每次 Bug 修复都必须补充对应的回归测试用例。坚决避免无法被机械核验的空洞套话：
## 测试规范（反面示例）
- 请务必小心。
- 确保所有东西都能正常工作。选用恰当的指令载体
秉持“最小特权”原则，为特定职责挑选最精简、最持久的指令通道。
| 指令载体 | 适用场景 | Droid 的处理机制 |
|---|---|---|
AGENTS.md 及其兼容文件名 | 常驻生效的编码指令、常用命令、仓库惯例与安全规则。 | 在会话启动与动态文件发现过程中，作为编码准则全量载入。 |
DESIGN.md（含大小写变体） | 常驻生效的设计系统、UX 交互、视觉元素与版式规范。 | 作为独立的设计指南通道单独载入。 |
SKILL.md | 可复用的工作流、检查清单或专业领域知识，仅在命中时按需载入。 | 识别为技能（Skill），仅在被显式调用或上下文匹配时才展开载入全文。 |
.factory/commands/* | 由用户手动触发的提示词模板或可执行命令快捷方式。 | 作为自定义斜杠命令（Slash Commands）暴露给用户。 |
.factory/settings.json | Droid 的偏好配置、默认模型选型与策略权限。 | 作为结构化配置参数直接解析，不作为自然语言提示词处理。 |
避免把 AGENTS.md 当成垃圾场
严禁将冗长的排错运维手册全量粘贴进
AGENTS.md。要么只保留指向单一真实事实来源的链接，要么将可复用的操作流程迁移到 Skills 中，确保额外的上下文仅在真正需要时才被按需拉取。
发现机制与继承优先级
当检测到 Git 根目录时，Droid 会从当前工作目录（CWD）一路自底向上递归搜索至 Git 根目录。在每一级路径中，它都会依次检查当前目录本身以及以下专用的上下文配置目录：
| 专用上下文目录 | 常见用途 |
|---|---|
.factory/ | Factory 平台专属的项目级指令配置。 |
.agents/ | 兼容社区通用的复数形式跨 Agent 共享目录约定。 |
.agent/ | 兼容单数形式的 Agent 目录约定。 |
与此同时，Droid 还会检查位于用户家目录（Home Directory）中的个人级指令目录：
| 个人指令目录 | 常见用途 |
|---|---|
~/.factory/ | 跨所有项目通用的个人 Droid 偏好设置。 |
~/.agents/ | 跨工具兼容的个人指令目录（复数命名）。 |
~/.agent/ | 跨工具兼容的个人指令目录（单数命名）。 |
当多个指令文件同时命中生效时，请遵循以下分层心智模型：
- 用户即时请求：用户在当前对话中发出的即时请求，优先级永远高于任何常驻静态指令。
- 嵌套细化覆盖：子目录中嵌套的项目文件，专门用于针对特定目录树细化或覆盖根目录项目规则。
- 项目优先于个人：项目级配置文件应当始终覆盖个人全局默认偏好。
- 个人偏好不打架：个人全局文件只应描述个人通用偏好，绝不能声明与具体仓库规则相冲突的强硬要求。
兼容的文件命名
为新项目编写指南时，请一律优先采用标准的 AGENTS.md。此外，Droid 也完全兼容以下历史命名，确保从其他编码工具迁移而来的既有指令文件能够无缝运行：
| 文件名称 | 适用条件 |
|---|---|
AGENTS.md | 强烈推荐：所有新建项目指南的标准命名。 |
agents.md | 全小写格式的向下兼容变体。 |
Agents.md | 首字母大写格式的兼容变体。 |
CLAUDE.md | 兼容既有针对 Claude Code 编写的指令文件。 |
Claude.md | 针对 Claude 文件的首字母大写兼容变体。 |
这是一份用于向后兼容的候选文件清单，绝不是要求你把每个文件都创建一遍。在同一个项目中同时创建多个兼容文件来重复堆砌相同规则，只会白白消耗宝贵的上下文预算，而不带来任何有效信息增量。
嵌套指令
当某个子目录树拥有差异化的运行命令、特殊编码惯例、独立的代码生成产物或不同的代码归属职责时，嵌套文件能发挥巨大价值。
repository/
AGENTS.md
apps/
web/
AGENTS.md
src/
page.tsx如果 Droid 的初始会话启动于 repository/ 根目录，它会首先载入根目录的全局指南。随着任务推进，当 Droid 随后读取 apps/web/ 目录下的源文件时，它会自动探测并动态加载 apps/web/AGENTS.md，从而将更精细的专用规则应用到该子目录树中。
请仅针对真正的本质差异引入嵌套文件：
- 某个子模块采用了不同的包管理器（如 pnpm 与 cargo 混用）或不同的测试运行框架。
- 某个微服务包含严禁手动修改、必须通过工具重新生成的特定代码。
- 前端专区拥有一套不适用于后端其他目录的设计系统规范。
- 涉及生产部署脚本或数据库迁移的路径，需要额外的确认与审批机制。
切忌在嵌套文件中机械复制粘贴根目录已有的通用规则。
上下文预算
所有指令文件都会计入会话的上下文 Token 开销中。请务必将 Droid 最核心、最亟需严格遵守的规则高密度置顶。
| 加载阶段 | 字符数硬顶上限 |
|---|---|
| 初始全局准则载入 (Initial AGENTS-style load) | 80,000 字符 |
| 动态读取路径指令发现 (Dynamic Read-path discovery) | 40,000 字符 |
请注意：上述数字是防爆仓的安全上限，绝非你的编写目标。在绝大多数情况下，文件体积越紧凑，模型的遵循质量越好。
根目录标准模板
# 仓库总览指南
## 项目定位
用一到两句话简要说明本产品、服务或软件包的核心职责。
## 常用命令
- 依赖安装：`REPLACE_ME`
- 本地启动：`REPLACE_ME`
- 运行测试：`REPLACE_ME`
- 类型检查：`REPLACE_ME`
- 代码检查：`REPLACE_ME`
- 打包构建：`REPLACE_ME`
## 目录骨架
- `REPLACE_ME/`：存放……
- `REPLACE_ME/`：存放……
- `REPLACE_ME/`：存放……
## 编码惯例
- 在引入全新模式前，优先遵循现有代码的设计风格。
- 改动范围严格限定在用户明确要求的任务之内。
- 优先复用现有的工具函数和第三方依赖库。
- 当改变业务行为逻辑时，必须同步新增或更新自动化测试。
## 验收门禁
在宣告工作完成前，必须先执行针对性验证，然后再运行全量项目门禁：
1. `REPLACE_ME`
2. `REPLACE_ME`
3. `REPLACE_ME`
## 安全红线
- 严禁将密码、私钥、API 令牌等机密凭据检入版本控制。
- 未经用户明确许可，严禁执行具备破坏性的不可逆命令。
- 严禁手动修改自动生成的文件。请通过运行 `REPLACE_ME` 命令重新生成。子项目嵌套模板
# 子项目指南
本文件仅在当前目录树范围内生效。除非此处声明了更具体的专属规则，否则一律遵循根目录 `AGENTS.md`。
## 局部命令
- 运行本包专属测试：`REPLACE_ME`
- 运行本包专属 Lint：`REPLACE_ME`
- 重新生成本模块本地工件：`REPLACE_ME`
## 局部惯例
- 针对……场景，使用 `REPLACE_ME`。
- 严禁使用 `REPLACE_ME`；当前子模块统一改用 `REPLACE_ME`。
- 对外公开的导出内容统一维护在 `REPLACE_ME`。
## 局部验证
对当前子目录树引入修改后，必须运行：
1. `REPLACE_ME`
2. `REPLACE_ME`应当坚决避免的反模式
切忌将 AGENTS.md 当成无节制倾倒信息的垃圾场。严禁包含以下内容：
- 密码凭证、API 访问令牌、私钥或内网私有主机名。
- 完整复制粘贴早已在其他文档中存在的大部头参考资料。
- 未及时维护、与代码库实际结构严重脱节的陈旧目录清单。
- 与项目集体共识相互抵触的个人独占偏好。
- 理应记录在 Issue、Pull Request 或临时需求规格说明中的阶段性任务笔记。
- 缺乏明确合理依据、要求 Agent 盲目跳过测试和校验的懒惰指令。
如果某项指导仅在特定工作流中生效，请将其沉淀为一个 Skill（技能）；如果它仅适用于某个局部功能模块，请将其拆分放入嵌套的 AGENTS.md 中。
常见排错与疑难解答
Droid 没有遵守项目规则
请将规则具体化。用确切的执行命令、文件路径以及客观的验收标准，替代诸如“请测试你的工作”这类含糊建议。同时，请将最重要的核心规则置顶到文件的头部。
嵌套的 AGENTS.md 没有被调用
请确认该文件使用了受支持的文件名，且确实位于 Droid 所探测的目录树路径中。如果整个会话是从代码库更高层级的根目录启动的，Droid 通常只有在真正读取该子目录树下的文件时，才会动态触发嵌套指令的发现机制。
个人指令与仓库规则发生冲突
请将个人指令改写为“兜底默认项”。必须确保项目级规则以及用户在对话中的明确指令，拥有覆盖个人偏好的最高裁量权。
指令文件体积过长
请在 AGENTS.md 中仅保留长期稳定、信息密度极高的高价值规则。对于冗长的大篇幅参考文档应改为提供超链接；将多步可复用操作流程迁移到 Skills 体系中；并将针对特定子系统的局部指引拆解到嵌套的子目录文件中。