约 5 分钟3 张卡

仓库指令

仓库指令是放在代码仓库中、供编码 Agent 在每次会话开始时自动读取的说明文件，例如 AGENTS.md、CLAUDE.md。它保存构建和测试命令、目录结构、代码约定、禁止事项等稳定信息，让 Agent 不必每次重新摸索项目。本文讲应该写什么、不该写什么、如何组织与维护，以及如何验证修改有效。不同工具支持的文件名、层级和加载规则不同，具体以所用工具的文档为准。

1. 面试核心

先记住这几条，再读正文

仓库指令保存稳定、每次任务都可能用到的信息：常用命令、项目结构、代码约定、验证方式和明确的禁止事项。卡 · 写什么
不写临时任务状态、可以从代码直接看出的内容和大段文档；内容越长，每次占用的上下文越多，重点越容易被稀释。
指令文件在会话开始时加载，不依赖对话历史，因此上下文压缩后仍然有效；必须长期遵守的约束应写在这里，而不是只在对话中说一次。
修改指令后用代表任务对比修改前后的结果，确认确实改善，而不是凭感觉增加规则。卡 · 组织与维护
团队共用一份纳入版本管理的指令，可以让使用不同工具的开发者得到一致的约定。卡 · 组织与维护

2. 写什么

卡 · 项目规则文件中应该保存哪些信息？哪些信息不能在上下文压缩时丢失？

# 项目说明

Node 20 + TypeScript 的订单服务，入口 src/server.ts。

## 常用命令
- 安装：pnpm install
- 单测：pnpm test -- <文件>；全量 pnpm test
- 类型检查：pnpm typecheck（提交前必须通过）

## 结构
- src/api：HTTP 路由，只做参数校验和调用 service
- src/service：业务逻辑
- src/repo：数据库访问，唯一允许写 SQL 的目录

## 约定
- 金额使用整数分，不使用浮点数。
- 新接口必须有对应的集成测试（tests/api/）。

## 禁止
- 不修改 migrations/ 中已有的迁移文件，新增迁移代替。
- 不在代码中写入密钥，使用 config/ 读取环境变量。

写作要点：

具体可执行：“运行 pnpm typecheck”比“保证类型正确”有用。
说明原因：“金额用整数分，因为浮点数会产生舍入误差”让 Agent 在相似场景也能正确判断。
只写例外：通用的良好实践模型已经知道，写项目特有的约定和容易出错的地方。
保持简短：详细文档放在其他文件中，指令里写明在什么情况下去读哪个文件。

3. 组织与维护

卡 · 更新 AGENTS.md 或 Skills 后，怎样验证效果确实提升？卡 · 多人使用不同 AI 工具开发同一个功能时，怎样协作？

层级：多数工具支持多级文件，例如用户级（个人偏好）、仓库根目录（全项目约定）、子目录（模块特有约定），离修改位置越近的文件通常越具体。
来源：Agent 犯了一次可以通过规则避免的错误，就是增加一条规则的时机；规则不再适用时删除。
版本管理：和代码一起提交、评审，变更有记录。
防止膨胀：定期合并重复规则、删除过时内容。很长的规则文件会挤占上下文，也会让真正重要的规则被忽略。
与其他机制分工：只在特定任务需要的流程写成 Agent Skills；必须保证执行的检查（格式化、禁止的命令）用 Hook 或 CI 强制，不能只依赖文字规则。