AI Coding · Repository Guidance
AGENTS.md 技术教程：
用渐进式披露设计 AI 开发规则
不是给智能体堆更多命令，而是给它恰好足以开始工作的上下文，并让它能在任务需要时找到下一层可靠说明。
基于 AI Hero 的《A Complete Guide To AGENTS.md》提炼、重组与中文实践化改写。
AGENTS.md：项目与智能体之间的配置层
AGENTS.md 是随 Git 提交的 Markdown 指南文件，用来补足“通用模型知识”与“这个仓库的真实工作方式”之间的空白。它不应替代代码、测试或 README；它的职责是让智能体在首次进入仓库时少走弯路。
个人范围
你偏好的协作方式
例如提交信息风格、是否先写测试、偏好的抽象尺度。这类规则应简短且确实会影响实现决策。
项目范围
仓库特有的事实
例如项目目标、实际使用的包管理器、非标准的构建或类型检查入口，以及不可违背的架构约束。
为什么不能把它写成“规则百科”
一个常见循环是：智能体做错一次，团队就往根文件追加一条“永远不要……”；几个月后，规则数量失控、表述相互冲突，并且没人再能判断哪些仍然有效。
三个会直接伤害执行质量的机制
根文件通常会在每个请求中载入。与当前任务无关的规则仍占用注意力，真正关键的约束反而更难被稳定遵循。
不同作者陆续加入偏好后，智能体会面对相互矛盾的“必须”。它未必知道哪一条更新、哪一条优先。
硬编码路径、旧工具链和已迁移的模块会让智能体自信地朝错误方向搜索；这比没有提示更危险。
把“路径说明”换成“能力说明”
| 不稳的写法 | 更耐变化的写法 | 原因 |
|---|---|---|
认证逻辑在 src/auth/handlers.ts | 认证领域由服务端模块负责；先检索 auth、session 与相关测试。 | 重命名或迁移后仍可成立。 |
| 组件必须在某固定目录创建 | UI 组件按领域放置，并沿用相邻组件的导出与测试模式。 | 传达模式，而不是脆弱坐标。 |
| “写干净代码” | 新增公共 API 时补齐单元测试；修改接口时运行类型检查。 | 可验证、可执行。 |
用渐进式披露组织知识
渐进式披露的关键不是隐藏信息，而是将信息放到最适合被加载的时机。根文件给方向，专项文档给约定，局部文件给范围；智能体通过链接和目录逐层进入。
一个可发现的资料树
AGENTS.md # 项目入口与全局工作方式
docs/
├── TYPESCRIPT.md # 仅在修改 TS 时需要
├── TESTING.md # 测试策略、运行器差异与样例
├── API_CONVENTIONS.md # 接口语义、错误模型、版本策略
└── BUILD.md # 非标准构建与发布流程
packages/
└── api/
└── AGENTS.md # 只对 api 包生效的补充约束
skills/
└── release/SKILL.md # 仅在发布任务中调用的工作流链接应该像路标，而不是命令堆叠：关于 TypeScript 约定，参见 docs/TYPESCRIPT.md。 足够让智能体在需要时继续探索。
从最小根文件开始实现
先写一个能够服务于所有任务的版本，再把“仅某类任务需要”的条目移出。对多数仓库，根文件只需覆盖以下三类内容。
| 保留在根文件 | 判断标准 | 示例 |
|---|---|---|
| 一句话项目说明 | 帮助智能体理解所有决策的目标函数 | “这是一个面向无障碍数据可视化的 React 组件库。” |
| 包管理器 | 非默认工具会改变每次安装、执行与工作区命令 | “本项目使用 pnpm workspaces。” |
| 非标准校验命令 | 智能体无法从常规脚本名可靠推断 | pnpm verify 会同时执行类型检查与契约测试。 |
# AGENTS.md
这是一个面向无障碍数据可视化的 React 组件库。
使用 pnpm workspaces 管理依赖；不要用 npm 改写 lockfile。
提交前运行 `pnpm verify`。它包含类型检查与契约测试。
修改 TypeScript 时，参见 [docs/TYPESCRIPT.md](docs/TYPESCRIPT.md)。
新增或修改组件时，参见 [docs/TESTING.md](docs/TESTING.md)。把语言规则移到专题文件
例如 const、类型声明风格、空值策略、lint 例外等，只有在改动对应语言时才有价值。将它们放在 docs/TYPESCRIPT.md，可以让 CSS 排障或依赖升级任务免受干扰。
Monorepo：按目录增加，而不是复制规则
在多包仓库中，可在子目录放置额外的 AGENTS.md。智能体进入某个包时，根级指导与该目录的局部指导一起构成上下文。因此每层只描述自己作用域内新增的事实。
根目录
全局导航
说明仓库由哪些类型的包组成、通用包管理规则，以及“请查看包内 AGENTS.md”。不要写 API 或 CLI 的内部细节。
packages/api/
服务端局部约束
说明 API 的领域、数据库/框架选择、接口规范入口和本包特有的验证命令。它不需要复述根级规则。
# packages/api/AGENTS.md
本包是基于 Node.js 的 GraphQL API，并使用 Prisma 访问数据。
设计或修改接口时，参见 [../../docs/API_CONVENTIONS.md](../../docs/API_CONVENTIONS.md)。
本包的集成测试使用：pnpm --filter @acme/api test:integration重构一个膨胀的 AGENTS.md
不要直接删减。先将现有条目归类、处理冲突、再迁移。尤其是有歧义的规则，应交由项目负责人裁决，而不是让智能体替团队猜测偏好。
推荐的六步迁移法
- 收集每条规则，并标记它覆盖的任务类型与目录范围。
- 找出冲突、重复或过时条目；对冲突规则建立待确认清单。
- 抽取真正的根级最小集：项目目标、工具链关键事实、全局校验。
- 把其余规则按语言、测试、API、Git 工作流等主题迁至独立文档。
- 在根文件和局部文件中留下简洁链接，并检查链接是否可达。
- 用真实任务试跑：让智能体改 TS、改样式、改 API，确认它只读取相关说明。
可交给编码智能体的重构提示词
请将本仓库的 AGENTS.md 重构为“渐进式披露”结构。
1. 列出互相矛盾、重复、含糊或疑似过期的规则；冲突项先向我提问，不要自行选择。
2. 只保留所有任务都需要的根级信息：项目一句话说明、非默认包管理器、非标准构建/类型检查命令，以及真正全局的约束。
3. 将其余内容按主题拆到 docs/ 下，并为每个文件给出清晰标题与适用场景。
4. 生成最小的根 AGENTS.md、各专题文件和建议目录树；根文件仅保留到专题文件的链接。
5. 标记建议删除的内容，并说明原因：模型已知、不可执行、重复或时效性风险过高。
6. 最后校验所有 Markdown 链接和文档内命令是否存在。发布前：用这张清单防止再次失控
- 根
AGENTS.md能在不到一分钟内读完，且每一条都对大多数任务有用。 - 没有把文件路径当作永恒事实；使用了领域词、搜索提示或相邻代码模式。
- 所有“必须 / 永远不要”都具备明确对象、适用范围和可验证结果。
- 语言、测试、接口和发布规则各有可发现的专题入口。
- 子目录只添加局部增量，不复制上级说明。
- 重要说明链接到真正的事实来源：配置、测试、脚本或权威文档。
- 团队知道规则的负责人，并在工具链或架构迁移时同步审查。