AI 创建 / 审查 AGENTS.md
两种模式：创建一个新的 AGENTS.md 或审查现有的文件是否符合基于研究的质量标准。
模式检测
- 用户提供了现有的 AGENTS.md 或指明了位置 → 审查模式
- 用户要求创建/搭建/生成 → 创建模式
- 不明确 → 询问：
(c) 创建新的 AGENTS.md 还是 (r) 审查现有的？
创建模式
步骤 1：询问放置位置
AGENTS.md 应该放在哪里？
(r)oot — 仓库级基线
(p)ath — 特定目录（提供路径）
对于 monorepo：建议根目录 + 每个包的文件。最近的 AGENTS.md 生效。
如果目标路径已存在 AGENTS.md → 询问：文件已存在。(r) 审查现有 / (o) 覆盖 / (Q) 退出？
步骤 2：专家思考
在编写之前，确定此项目的：
- 什么是不易发现的？ 哪些信息不能从 package.json、配置或目录结构中推断出来？
- 什么是危险的？ 哪些命令或模式会导致静默失败？
- 什么是模糊的？ 哪些地方存在两种有效方法，而智能体会猜错？
- 什么是非标准的？ 哪些约定与框架默认值不同？
如果所有答案都是“没有”——那么该项目可能不需要 AGENTS.md。直接说明。
对于没有 package.json 或构建配置的仓库（仅文档、数据仓库、简单脚本）：只关注使命和判断边界部分——工具链和完成定义部分不适用。
步骤 3：按优先级顺序编写
仅添加通过“不易发现”测试的部分，按以下顺序：
- 使命（2–4 句话）—— 项目目的 + 智能体无法推断的核心约束
- 工具链注册表—— 命令以表格形式呈现，而非工具强制的内容
- 判断边界—— 绝不 / 询问 / 总是 层级
- 完成定义—— “完成” = 特定的退出码
- 升级规则—— 受阻时该怎么做
- 任务组织的部分—— “编写时… / 审查时… / 发布时…”
步骤 4：验证
- 总计 ≤ 150 行（最佳：60–100）
- 每个部分 ≤ 50 行
- 每条指令回答：“什么命令能证明这已完成？”
- 每个“不要”都配有一个“要”
- 不重复 lint 规则（先写工具链）
- 没有不含命令的散文段落
必须——阅读 references/knowledge-base.md 以了解基于研究的模式和证据。
必须——阅读 references/template.md 以获取起步结构。
仅在用户询问完成的 AGENTS.md 是什么样子时，或者仓库是 JS/TS monorepo（它是一个 turborepo + pnpm 工作示例）时，加载 references/example.md——否则跳过。
在审查模式下，如果目标 AGENTS.md 少于 20 行，请勿加载 references/knowledge-base.md —— 对于极短的文件，主体检查清单和反模式列表就足够了。
审查模式
根据基于研究的质量标准评估提供的 AGENTS.md。
评分维度
| 维度 | 权重 | 检查内容 |
|---|---|---|
| 信号密度 | 25% | 不易发现的专家知识行数与通用/冗余行数的比例 |
| 命令优先 | 20% | 每条指令都有可验证的命令或退出码 |
| 完成定义 | 15% | 明确的“完成”标准，包含具体检查项 |
| 边界系统 | 15% | 绝不/询问/总是 层级存在且具体 |
| 长度准则 | 10% | ≤150 总行，≤50 每部分，无臃肿 |
| 反模式排除 | 15% | 无经证明会失败的模式 |
评分指导
- 对于拥有成熟工具链的仓库，在信号密度上严格评分——大多数内容可能是冗余的
- 对于绿场项目，在完成/边界上宽松评分——它们可能还没有 CI 关卡
- 对于 monorepo 根文件，在长度上严格评分——这些文件会在每个包的所有会话中加载
- 如果总分 < 40：建议重写而非增量修复
反模式检查清单
标记以下任何一项（经验证明会损害智能体性能）：
- 不含命令的散文段落
- 模糊指令（“小心”、“尽可能”）
- 没有明确排序的冲突优先级
- lint 配置已强制执行的样式规则
- 架构概览（导致过度探索）
- 15 条以上的警告而没有提供替代方案
- 来自
/init命令的 LLM 生成的模板内容 - 重复工具链已强制的内容
- 粉象违规（长“不要做”列表使禁止的概念保持活跃）
输出格式
## AGENTS.md 审查: <文件名或路径>
**分数**: X/100
**结论**: [生产就绪 / 需要改进 / 建议重写]
### 优点
- ...
### 问题（按严重性排序）
1. [严重] ...
2. [高] ...
3. [低] ...
### 重写建议
1. ...
2. ...
应用
审查本身不是交付物——更好的 AGENTS.md 才是。呈现审查结果后，提供：
应用？(a) 全部 / (s) 按编号选择 / (n) 无
对于 (a) 或 (s)：逐个编辑文件中的编号项，然后重新运行评分维度，并报告新分数与旧分数对比。审查未标记的每一行都原样保留——审查不是重写命令，静默地“改进”未标记的散文会破坏作者的声音和意图。
当用户提供的是内联内容而非文件路径，或者文件不可写时，跳过提供应用的选项。直接说明，而不是报告改进已应用。
必须——阅读 references/knowledge-base.md 以了解每个标准背后的研究证据。
绝不
- 绝不包含智能体可以从仓库结构中发现的内容—— package.json 脚本、目录布局和配置文件是自文档的；重复它们会浪费令牌并产生维护漂移。而是： 引用文件（
见 biome.json）并继续。 - 绝不重复 lint/格式化器规则——工具本身就是约束；重复会导致过时和不必要的要求，严重损害智能体性能。而是： 只列出运行命令（
Lint: \pnpm lint``）。 - 绝不写“不要”而不配对一个“要”——仅含警告的文档会导致过度探索；15 条以上的“不要”而没有替代方案会使智能体变得保守且效率降低。而是： 每个禁止项都配上正确的替代方案。
- 绝不超出 150 行——超过此阈值，收益递减，文件反而会损害质量。而是： 将细节提取到引用的文件中或删除。
- 绝不将 LLM 生成的内容作为最终内容——
/init输出是智能体已知信息的清单；它会降低性能并增加成本。而是： 将其视为草稿清单，然后删除工具链已强制的一切。 - 绝不写散文段落——智能体会跳过它们；使用命令、表格和带可验证结果的要点。而是： 转换为命令 + 退出码 + 一行描述。