仓库指令
仓库指令是供编码 Agent 读取的项目说明文件，常见名称有 AGENTS.md 和 CLAUDE.md。它保存命令、目录职责和代码约定等稳定信息，让 Agent 少一些重复摸索。
本文先说明应该记录哪些内容，再讲文件的组织、维护和加载范围，最后说明怎样验证规则有效。不同工具支持的文件名、层级和加载方式不同，需要按实际工具确认。
1. 面试核心
先记住这几条，再读正文- 长期项目约定。 仓库指令保存反复使用的构建与测试命令、目录职责、代码约定和验收要求。卡 · 指令内容
- 指令加载。 指令文件的发现范围、加载时机和优先级由具体工具决定。卡 · Codex 指令发现与范围
- 指导与强制约束。 规则文件指导模型执行任务，CI 检查与运行时权限控制负责强制约束。
- 规则评测。 指令变更需要在固定任务和环境中对照评测，同时比较任务结果、规则遵守情况与成本。卡 · 组织与维护
- 团队协作。 多工具协作通过共享项目约定、接口和验收标准，保持开发与评审要求一致。卡 · 组织与维护
2. 指令内容
指令要告诉 Agent 项目特有的做法，让它知道在哪里修改、用什么命令验证。下面以 TypeScript 订单服务为例，给出一份简短说明。
# 项目说明
TypeScript 订单服务，入口 src/server.ts。
## 命令
- 单测：pnpm test
- 类型检查：pnpm typecheck
## 结构
- src/api：参数校验与 service 调用。
- src/service：业务逻辑。
- src/repo：数据库访问。
## 约定
- 金额用整数分，避免浮点舍入误差。
- 接口变化需要验证兼容性。
- 迁移文件通过新增版本演进。
项目还可以按实际情况补充以下执行约定：
- 写明运行版本与安装命令。比如，项目使用 Node 20 时应注明版本，安装命令可以写成
pnpm install。 - 写明测试范围。比如，
pnpm test -- <文件>运行指定测试，pnpm test运行全量测试。 - 写明交付要求。比如，提交前通过
pnpm typecheck，新接口必须在tests/api/补充集成测试。 - 写清目录职责的边界。比如，只有
src/repo允许写 SQL，src/api只负责 HTTP 参数校验和调用 service。 - 写清禁止事项与替代做法。比如，已有迁移文件保持不变，通过新增迁移演进数据库。代码中禁止写入密钥，改由
config/读取环境变量。
“运行 pnpm typecheck”给出了可执行命令，比“保证类型正确”更容易验证。规则还应说明原因，比如金额用整数分，是为了避免浮点舍入误差。知道原因后，Agent 在相似场景中也更容易作出正确判断。
内容优先保留项目特有约定和容易出错的地方。代码中直接可见的结构细节可以按需读取，大段背景则放到独立文档，并写明何时去读。规则越长，每次加载占用的上下文就越多，关键要求也更容易被忽略。
临时错误、当前待办和修改进度另存任务状态。把它们与长期约定分开，可以减少过时信息。目录或命令变化时，再同步更新对应规则。
3. 组织与维护
规则需要随代码演进，否则旧命令和旧约定会误导后续任务。维护时重点处理以下四件事：
- 分层放置：工具支持多级文件时，用户级放个人偏好，仓库根目录放共同约定，子目录放模块规则。具体发现范围和覆盖顺序仍由工具决定。
- 保留真实需求：新增规则应对应已经出现的问题，说明它要避免什么错误。反复出现的问题尤其值得记录；一次明确且影响大的错误，也能成为补充规则的依据。
- 跟随版本评审：规则和代码一起纳入版本管理与评审，使约定变化可以追溯。过时或重复的内容及时合并、删除，减少上下文占用。
- 验证修改效果：使用代表任务比较新旧规则，确认目标问题改善，并检查常规任务是否退化。文件长度增加带来的执行成本也要计入。
多人使用不同工具时，可以维护共同的项目规则，再按各工具支持的方式引用或生成入口文件。这样能减少多份内容分别修改后产生的分歧。入口文件存在后，还需要验证工具实际读到了什么。
只在特定任务中使用的流程，可以写成 Agent Skills，按需加载。
必须执行的格式检查可以放入持续集成（CI），命令和路径限制则交给运行时权限控制。Hook 是按事件触发的处理器，其阻断条件见 Agent Harness。
3.1 Codex 指令发现与范围
文件写好后，还需要确认它位于工具会搜索的路径中。Codex 的启动目录、文件名和大小限制都会影响发现结果。
Codex 按以下发现顺序组合指令：
- 先读取全局指令，同层优先采用
AGENTS.override.md，其次是AGENTS.md。 - 再从项目根目录走到当前工作目录，逐层查找文件。每层先检查
AGENTS.override.md，再检查AGENTS.md，随后检查配置的备用文件名。 - 每层最多采用一份非空文件，再按全局到项目、由浅到深的顺序组合。更深目录中的项目约定覆盖上层的冲突项。
项目文档合计受 project_doc_max_bytes 限制，默认上限为 32 KiB。超过限制的内容会影响加载，所以需要保持规则简洁，并检查关键要求是否完整进入上下文。
修改后，可以在目标目录启动新会话，核对实际加载的文件与规则。上下文压缩后的保留和重载由宿主实现，也就是承载模型与工具的程序负责。因此，恢复任务时还要检查关键约束，确认它们仍然可用。
4. 常见问题
理解加载范围后，还需要区分项目规则与工具本身的指令。两者都影响模型行为，但来源和职责不同。
4.1 仓库指令和系统提示有什么区别？
仓库指令描述当前项目，系统提示描述 Agent 工具的通用行为和能力。前者由项目维护者编写，后者由应用开发者编写。
宿主决定仓库指令如何进入上下文，以及它与其他指令的优先级。文件中的文字仍受运行时权限约束。例如，规则要求执行某个命令，实际执行还要通过工具权限检查。
5 · 面试题卡片
本页题目与参考回答
5.1 项目规则文件中应该保存哪些信息？哪些信息不能在上下文压缩时丢失？
考察重点
- 区分长期项目约定和当前任务状态，并说明各自保存在哪里。
- 解释指令文件怎样加载，以及压缩后为什么仍需核对关键约束。
参考回答
规则文件应保存反复使用的项目约定，压缩后仍需保留关键约束、验证要求和当前任务进度。
长期约定包括常用命令、目录职责、代码规则及其原因。比如，写出提交前要运行的检查，说明金额为什么用整数分，以及数据库迁移和密钥怎样处理。规则要有具体适用范围，命令要能直接执行。
当前进度、改动文件和未解决错误属于临时状态，写入进度文件或压缩摘要。指令文件可以由宿主独立加载，但压缩后保留和重载的方式取决于工具实现。因此，恢复时要核对关键约束及任务状态，确认文件内容实际生效。
5.2 更新 AGENTS.md 或 Skills 后，怎样验证效果确实提升？
考察重点
- 用目标问题和常规任务对照新旧规则，区分改善与回归。
- 比较任务结果、规则遵守情况、执行成本和人工修正量。
相关内容：组织与维护、编码 Agent 评测。
参考回答
规则效果需要用代表任务对照新旧版本，同时检查目标问题是否改善、常规任务是否退化。
任务集既包含这次要解决的问题，也包含与修改无关的常规工作。固定模型、工具、代码版本和预算后，分别使用新旧规则，每个任务运行多次。
比较时记录以下结果与成本指标：
- 记录任务成功率和违反规则的次数。
- 比较执行步数与 Token 消耗。
- 统计人工修正量，并检查文件变长带来的额外成本。
能自动判断的输出用评价脚本检查，其他输出使用明确的评分细则。模型评审再通过人工抽查校准。目标问题改善且常规任务满足回归要求后，保留这次修改。
5.3 多人使用不同 AI 工具开发同一个功能时，怎样协作？
考察重点
- 说明怎样共享项目规则、接口约定和验收标准。
- 解释不同工具产生的改动怎样进入共同的版本管理与评审流程。
相关内容：组织与维护。
参考回答
多人协作需要共享项目约定、接口和验收标准，让不同工具产生的改动遵循同一套要求。
仓库规则纳入版本管理，写清命令、目录职责和禁止事项。不同工具可以保留各自入口，共享同一份规则内容，再确认引用方式被工具实际加载。
功能开始前约定接口与数据结构，并按模块明确负责人，减少同时修改同一文件。所有改动采用共同的分支管理、CI 和代码评审流程，以测试和类型检查等作为验收依据。反复出现的问题进入共享规则或自动检查，供其他开发者复用。
5.4 AGENTS.md 已存在但没有生效，应检查哪些加载条件？
考察重点：根据发现路径、覆盖文件和大小限制，判断目标规则是否被加载。
相关内容：Codex 指令发现与范围。
参考回答
应检查实际使用的宿主、启动目录、文件优先级和大小限制，再验证目标规则是否进入上下文。
Codex 先读全局指令，再沿项目根目录走到当前目录。同层 AGENTS.override.md 优先于 AGENTS.md，之后才检查备用文件名，每层最多采用一份非空文件。还要检查 project_doc_max_bytes，项目文档默认合计上限为 32 KiB。
修正路径或文件后，在目标目录启动新会话，核对实际发现的指令，再运行能检验该规则的任务。这样才能区分文件已加载和模型执行效果两类问题。