这份"AI 维护指南"(AGENTS.md + docs/agents/*)本身也是项目资产,需要随项目演化。
两类人/agent 会触发更新:
- AI agent 完成改动后:回顾"这次改动是不是某个场景的常见漏点?清单是不是漏了什么?"
- 人(开发者)发现新场景:某次维护用不上
docs/agents/现有任何场景文档,新增一份
任何一种情况发生,这份指南就该改:
- ✅ 完成改动后发现"清单里没说,但实际要做"的步骤 → 补到对应场景的必查清单
- ✅ AI 漏了某个文件,review 时被指出 → 补到对应场景的常见漏点
- ✅ 一类改动反复出现且不属于任何已有场景 → 新建场景
- ✅ 项目结构调整(新增
packages/xxx、移动主要目录)→ 改AGENTS.md的项目地图 - ✅ 全局原则调整(如开始支持海外 region、加新的 core/cli 边界规则)→ 改
AGENTS.md的通用约定
- 已有场景 + 新清单项 → 直接加到对应
.md,不要新建 - 一类改动有自己独立的触发条件 + 不重叠的清单 → 新建
判断:如果两个场景的清单重叠 ≥ 80%,说明是同一场景;新增清单项即可。
- 在
docs/agents/下新建<scenario>.md,文件名 kebab-case 描述场景 - 用下方模板填充
- 在
AGENTS.md的"业务场景索引"表格里加一行(按场景频率从高到低排序) - 提 PR 时附 1-2 个真实改动 commit 链接,说明这个场景已经发生过
# <场景中文标题>
## 触发条件
- 何时进入这份文档(2-4 条具体情况)
## 概念图(可选)
若场景涉及多文件协作,画一张简单的层次/数据流图
## 必查清单
### A. <分组名>
- [ ] 具体到文件路径的 action
- [ ] ...
### B. <分组名>
- [ ] ...
## 完成后自查
1-3 条可执行的验证命令
## 常见漏点
基于真实踩坑(初版可空,随实际场景生长)- 文件名:
<topic>-<verb>.md(command-add-remove.md、url-change.md、config-add.md) - 场景标题:3-6 字中文短语(命令增删改、URL / 渠道变更)
- 必查清单分组:用
### A. xxx### B. xxx字母编号,方便引用
两份文档有共同规则时,一处定义、其他引用:
<!-- error-hint-change.md 是定义方 -->
## 不变量
### 1. core 的 hint 必须不含 cli 关切
<!-- url-change.md 是引用方 -->
- ✗ 在 core 的 hint 里写 URL(违反 [error-hint-change.md](error-hint-change.md) 不变量 1)避免同一规则在 N 份文档里复制粘贴,改一处全跟。
AGENTS.md 修改频率应该远低于场景文件,只在三种情况变动:
| 触发 | 改的段落 |
|---|---|
| 加/删一个场景 | 业务场景索引表 |
| 项目结构变化 | 项目地图 |
| 全局原则变化 | 通用约定 |
不要把场景特定的清单往 AGENTS.md 塞 —— 它的设计目标是 AI 加载到上下文里 ~60 行就够,详细内容按需读 docs/agents/。
- 写清晰的 must / must-not / 必查,不写"建议"性语气
- 用 file path + 具体 action 的句式(
packages/cli/src/commands/catalog.ts:增加 import 与 commands 条目) - 在每份场景末尾留常见漏点段,持续累积真实经验
- 在跨场景的不变量上互相引用,不复制
- ❌ 不写前置知识(假设读者会 TS / 会读代码)
- ❌ 不堆砌实现细节(代码改了文档也要改 — 不可持续;清单是"做什么",代码是"怎么做",后者交给代码)
- ❌ 不重复
README.md的内容(README 面向用户,本指南面向维护者) - ❌ 不写反向索引(文件 → 场景)— 双向维护成本高,AI 不需要
- ❌ 不要在场景文件里塞通用约定 — 通用的放 AGENTS.md
这套文档不是一次写完,是随真实工作沉淀的:
- 初版只有触发条件 + 骨架清单 + 空"常见漏点"
- 每完成一次相关改动,补一两条清单或漏点
- 长期未触发的场景文件可以归并或删除(避免文档腐化)