# 维护本指南

这份"AI 维护指南"(`AGENTS.md` + `docs/agents/*`)本身也是项目资产,需要随项目演化。

## 谁来维护

两类人/agent 会触发更新:

1. **AI agent 完成改动后**:回顾"这次改动是不是某个场景的常见漏点?清单是不是漏了什么?"
2. **人(开发者)发现新场景**:某次维护用不上 `docs/agents/` 现有任何场景文档,新增一份

## 何时更新

任何一种情况发生,这份指南就该改:

- ✅ 完成改动后发现"清单里没说,但实际要做"的步骤 → 补到对应场景的**必查清单**
- ✅ AI 漏了某个文件,review 时被指出 → 补到对应场景的**常见漏点**
- ✅ 一类改动反复出现且不属于任何已有场景 → 新建场景
- ✅ 项目结构调整(新增 `packages/xxx`、移动主要目录)→ 改 `AGENTS.md` 的**项目地图**
- ✅ 全局原则调整(如开始支持海外 region、加新的 core/cli 边界规则)→ 改 `AGENTS.md` 的**通用约定**

## 新增一份场景文档

### 何时新增 vs 扩展现有

- 已有场景 + 新清单项 → 直接加到对应 `.md`,**不要新建**
- 一类改动有自己**独立的触发条件 + 不重叠的清单** → 新建

判断:如果两个场景的清单重叠 ≥ 80%,说明是同一场景;新增清单项即可。

### 步骤

1. 在 `docs/agents/` 下新建 `<scenario>.md`,文件名 kebab-case 描述场景
2. 用下方模板填充
3. 在 `AGENTS.md` 的"业务场景索引"表格里加一行(按场景频率从高到低排序)
4. 提 PR 时附 1-2 个真实改动 commit 链接,说明这个场景已经发生过

### 文件模板

```markdown
# <场景中文标题>

## 触发条件

- 何时进入这份文档(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` 字母编号,方便引用

### 跨场景引用

两份文档有共同规则时,**一处定义、其他引用**:

```markdown
<!-- 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` 修改频率应该**远低于**场景文件,只在三种情况变动:

| 触发          | 改的段落       |
| ------------- | -------------- |
| 加/删一个场景 | 业务场景索引表 |
| 项目结构变化  | 项目地图       |
| 全局原则变化  | 通用约定       |

**不要把场景特定的清单往 AGENTS.md 塞** —— 它的设计目标是 AI 加载到上下文里 ~60 行就够,详细内容按需读 `docs/agents/`。

## 文档应该是什么样

### Do

- 写清晰的 **must / must-not / 必查**,不写"建议"性语气
- 用 file path + 具体 action 的句式(`packages/cli/src/commands.ts:增加产品命令 map 条目`)
- 在每份场景末尾留**常见漏点**段,持续累积真实经验
- 在跨场景的不变量上互相引用,不复制

### Don't

- ❌ 不写前置知识(假设读者会 TS / 会读代码)
- ❌ 不堆砌实现细节(代码改了文档也要改 — 不可持续;清单是"做什么",代码是"怎么做",后者交给代码)
- ❌ 不重复 `README.md` 的内容(README 面向用户,本指南面向维护者)
- ❌ 不写反向索引(文件 → 场景)— 双向维护成本高,AI 不需要
- ❌ 不要在场景文件里塞通用约定 — 通用的放 AGENTS.md

## 文档生长的节奏

这套文档**不是一次写完**,是随真实工作沉淀的:

- 初版只有触发条件 + 骨架清单 + 空"常见漏点"
- 每完成一次相关改动,补一两条清单或漏点
- 长期未触发的场景文件可以归并或删除(避免文档腐化)