134 lines
7.8 KiB
Markdown
134 lines
7.8 KiB
Markdown
请审查并整理 `openspec/specs/` 下的稳定规范，使其成为可搜索、边界清晰、无冗余、与当前业务一致的能力索引，按以下流程执行。
|
||
|
||
## 约束
|
||
|
||
- `openspec/specs/` 描述长期稳定的业务能力、规则和外部行为，不记录变更过程、迁移说明、实现路径、内部类型名、组件 props、样式数值、层级分层等实现细节
|
||
- 用户可感知或对外暴露的契约可以保留：公开 API 路径、请求/响应字段、协议名、错误码、数据约束、交互结果
|
||
- `Requirement` 和 `Scenario` 应描述业务能力、外部行为或稳定约束，不以“使用某层/某组件/某库实现”作为标题或核心表述
|
||
- 不把当前代码自动视为唯一真相；若代码、README、现有 spec 冲突且无法判断应以哪边为准，列入待确认清单，不直接改写规范
|
||
- 仅删除内容已被其他规范完整覆盖且无独立检索价值的规范；非冗余内容仅迁移、合并、拆分或重命名
|
||
- 每批重构执行前用提问工具获得用户确认；删除或重写前先备份原文件为 `{file}.bak.{timestamp}`
|
||
- 命名、Purpose、Requirement 标题都必须保留用户下一次最可能搜索的业务关键词
|
||
|
||
## 1. 收集
|
||
|
||
并行读取：
|
||
- `openspec/config.yaml`
|
||
- `README.md`，以及与模块结构、API、架构相关的 README 或文档
|
||
- `openspec/specs/*/spec.md`
|
||
|
||
默认不读取 `openspec/changes/**`、历史 proposal/design/tasks 作为稳定规范整理依据；仅在用户明确要求“连同历史变更一起校对”时再纳入。
|
||
|
||
先建立索引，不直接开始改写：
|
||
|
||
| 索引 | 内容 |
|
||
| ---- | ---- |
|
||
| `spec_index[]` | 每个 spec 的目录名、Purpose、Requirement 摘要、关键词、外部契约、疑似重叠对象 |
|
||
| `domain_map[]` | 从 README、API、模块文档中提炼的核心业务域、横切能力和术语 |
|
||
| `term_map[]` | 同义词、旧名、缩写和推荐标准术语 |
|
||
| `suspects[]` | 需要进一步对照代码或测试确认的 spec |
|
||
|
||
仅对 `suspects[]` 做定向读取：
|
||
- 读取与该 spec 对应的源码、测试、README 或架构文档
|
||
- 不对 `backend/`、`frontend/` 做无差别逐文件扫描
|
||
|
||
判定依据优先级：
|
||
- 当前稳定 spec 与 README 共同支持的事实，可直接视为高置信度
|
||
- 仅代码可见但 README 和 spec 未体现的内容，先判断它是稳定外部行为还是临时实现细节
|
||
- 代码、README、现有 spec 互相冲突且无法自动定夺时，进入 `待确认清单`
|
||
|
||
## 2. 审查
|
||
|
||
按 spec、Requirement、Scenario 三层检查：
|
||
|
||
| 维度 | 检查点 |
|
||
| ---- | ------ |
|
||
| 过时 | 描述的能力、术语、外部契约是否仍成立；是否存在 `TBD`、`TODO`、占位说明 |
|
||
| 冲突 | 不同规范是否对同一行为给出不同约束、命名或边界 |
|
||
| 重复/重叠 | 是否在文件级、Requirement 级、Scenario 级重复描述同一能力 |
|
||
| 错位 | 内容是否放错能力域；横切规则是否混入实体规范；平台实现是否混入通用能力规范 |
|
||
| 粒度 | 是否过大导致难检索，或过碎导致回答一个问题必须同时打开多个 spec |
|
||
| 术语 | 同一概念是否混用多个名字；旧名、别名、缩写是否需要归一并保留检索入口 |
|
||
| 命名/检索 | 目录名、Purpose、Requirement 标题是否准确；是否能被 README、API、业务术语直接命中 |
|
||
| 规范性 | 是否使用 SHALL/WHEN/THEN；是否混入变更记录、迁移说明、内部实现或 UI/代码细节 |
|
||
| 完整性 | Purpose 是否明确；是否存在空目录、非 spec 噪音文件、无清晰归属的孤立规范 |
|
||
|
||
重构判定规则：
|
||
- 若两个 spec 回答的是同一个核心问题，或其中一个只是另一个的子集，优先合并
|
||
- 若一个 spec 混合多个独立检索意图，或同时包含横切规则与业务流程，优先拆分
|
||
- 若内容正确但目录名、Purpose 或 Requirement 标题不利于检索，优先重命名或改写标题
|
||
- 若多个术语指向同一概念，统一到一个标准术语，并在 Purpose 或 Requirement 中保留必要别名以支持搜索
|
||
- 若某段内容只是内部实现细节，且不影响外部行为理解，删除该段而不是为其单独保留 spec
|
||
- 若某个具体值同时属于外部契约与内部实现，按“是否对调用方可见、是否影响兼容性”判断是否保留
|
||
|
||
### 命名约定
|
||
|
||
命名优先复用仓库已存在的稳定术语，如 `provider`、`model`、`stats`、`protocol`、`proxy`、`logging`、`validation`、`migration`、`frontend`、`desktop`、`mysql`。
|
||
|
||
| 类型 | 模式 | 示例 |
|
||
| ---- | ---- | ---- |
|
||
| 实体生命周期 | `{entity}-management` | `provider-management`、`model-management` |
|
||
| 横切能力 | `{concern}` 或 `{concern}-{qualifier}` | `error-handling`、`structured-logging` |
|
||
| 协议/适配 | `{protocol}-{capability}` 或 `protocol-adapter-{protocol}` | `openai-protocol-proxy`、`protocol-adapter-openai` |
|
||
| 运行面/入口 | `{surface}` 或 `{surface}-{capability}` | `frontend`、`desktop-app` |
|
||
| 基础设施 | `{resource}-{operation}` | `database-migration`、`mysql-driver` |
|
||
|
||
命名原则：
|
||
- 1-4 个词，保持单一主题
|
||
- 优先使用业务名词，不使用 `basic`、`general`、`misc`、`info`、`data` 等泛化词
|
||
- 不使用 `crud`、`list`、`table`、`display` 等实现模式词，除非它本身就是外部契约的一部分
|
||
- 同一主题的命名模式保持一致，不同时混用多套前后缀
|
||
|
||
## 3. 报告
|
||
|
||
输出分析结果：
|
||
|
||
1. **问题总览表**：问题类型 × 涉及规范数
|
||
2. **规范关系表**：每个 spec 的主主题、重叠对象、冲突对象、建议动作
|
||
3. **术语归一表**：旧术语 / 别名 / 缩写 → 推荐标准术语
|
||
4. **逐项分析**：每个有问题的规范说明位置、问题、影响、建议和目标规范
|
||
5. **待确认清单**：代码、README、现有 spec 冲突且无法自动定夺的事项
|
||
6. **重构方案**：按优先级分批
|
||
7. **重构后目录结构**：预期的新 `openspec/specs/` 目录树
|
||
|
||
优先级建议：
|
||
- P0：删除空目录、非 spec 噪音文件、占位内容
|
||
- P1：删除完全冗余规范；将其内容映射到主规范
|
||
- P2：合并重复/子集规范；拆分错位或过大规范
|
||
- P3：重命名目录、改写 Purpose 和 Requirement 标题以提升检索性
|
||
- P4：修正过时描述，清理实现细节、迁移说明和变更记录
|
||
|
||
若所有问题清单为空，输出“审查通过，未发现问题”，跳至步骤 5。
|
||
|
||
## 4. 计划（用户确认）
|
||
|
||
先针对 `待确认清单` 用提问工具逐项向用户确认。
|
||
|
||
再按批次展示完整重构计划，每批必须包含：
|
||
- 操作类型：删除、重命名、迁移、合并、拆分、改写
|
||
- 路径变化：源路径 → 目标路径
|
||
- 内容映射：源 spec 的 Requirement / Scenario 将迁移到哪里
|
||
- 术语处理：哪些旧词保留为检索入口，哪些词统一替换
|
||
- 执行原因：为什么这样做更利于检索、去重和边界清晰
|
||
- 验证方式：如何确认没有丢失约束或引入新的冲突
|
||
|
||
用提问工具获得当前批次确认后再执行。
|
||
|
||
## 5. 执行
|
||
|
||
按 P0 → P4 逐批执行已确认的重构。
|
||
|
||
执行要求：
|
||
- 合并或拆分时先写目标 spec，再删除或重命名源 spec
|
||
- 删除前确认其 Requirement 和 Scenario 已被完整保留、迁移或判定为纯冗余
|
||
- 每批执行后重新读取受影响的 spec，并复核结构和内容
|
||
|
||
每批执行后至少验证：
|
||
- 目录结构完整，`openspec/specs/*/spec.md` 可正常读取
|
||
- 不存在未承接的 Requirement 或 Scenario
|
||
- Purpose、Requirement 标题、目录名可以直接表达主能力
|
||
- 不再包含 `TBD`、变更记录、迁移说明、内部实现细节或噪音文件
|
||
- 若本批涉及代码对照项，相关外部契约描述与当前仓库现状一致，或已列入残留待确认
|
||
|
||
收尾时输出：修改文件清单、备份文件清单、最终目录树、残留待确认事项和整理摘要。
|