mirror of
https://github.com/modelstudioai/cli.git
synced 2026-09-14 19:49:23 +08:00
若麒
131 lines
4.2 KiB
Markdown
131 lines
4.2 KiB
Markdown
# 维护本指南
|
|
|
|
这份"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
|
|
|
|
## 文档生长的节奏
|
|
|
|
这套文档**不是一次写完**,是随真实工作沉淀的:
|
|
|
|
- 初版只有触发条件 + 骨架清单 + 空"常见漏点"
|
|
- 每完成一次相关改动,补一两条清单或漏点
|
|
- 长期未触发的场景文件可以归并或删除(避免文档腐化)
|