121 lines
7.3 KiB
Markdown
121 lines
7.3 KiB
Markdown
# 运行规则
|
||
|
||
本文件承载稳定但不必放在顶层 `SKILL.md` 的运行规则。
|
||
|
||
## 接口影响分级
|
||
|
||
接口影响分级判断的是"记录在哪里、是否需要独立文档"，不是判断"是否需要关注"。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义或内部决策逻辑变化，都必须先做分级。
|
||
|
||
| 级别 | 判断条件 | 产物要求 |
|
||
| --- | --- | --- |
|
||
| L1 内部实现 | 不改变任何调用方可观察的接口、字段、状态、错误码、数据范围、排序、过滤、权限结果、状态流转、副作用或文档承诺 | 不需要接口影响文档，只在 OpenSpec tasks 或 acceptance 记录验证 |
|
||
| L2 内部接口 | 改 DTO、service 方法、内部事件、内部 RPC 或内部判断逻辑，且所有消费者都在同一实现范围内 | 必须记录接口影响范围，可内联到 OpenSpec design/specs/tasks 或 devflow evidence/decisions |
|
||
| L3 协作接口 | 影响其他模块、其他服务、前端、外部系统、跨团队消费者、数据库契约、消息事件、回调或 SDK | 必须产出独立接口文档或等价独立章节 |
|
||
| L4 破坏性接口 | 删除字段、改字段语义、改状态机、改错误码、破坏兼容、旧调用方可能失败，或需要迁移、灰度、回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR |
|
||
|
||
判断策略：
|
||
|
||
- 如果只是修复 bug，让接口回到原 OpenSpec 或原文档承诺，通常是 L1/L2。
|
||
- 如果判断逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。
|
||
- 如果旧调用方不改代码会失败、少数据、多数据、状态不同或错误码不同，按 L4 处理。
|
||
- 如果无法确定调用方边界或兼容性，默认提高一级并作为 `user-interview` 问题等待确认。
|
||
|
||
## 启动检查
|
||
|
||
1. 识别用户命令意图：
|
||
- `/sm-flow`（无参数）：完整流程，从 clarify 开始。
|
||
- `/sm-flow apply [change]`：只执行，检查 commit gate → apply。
|
||
- `/sm-flow explore`：带上下文的探索模式，不走标准阶段链。
|
||
- `/sm-flow archive [change]`：收尾，回填 devflow + 归档确认。
|
||
- 明确要求"使用 sm-flow"或"走 sm-flow 流程"：按显式调用处理。
|
||
- 自然语言指定阶段继续：识别意图后，自动补做最小前置检查，然后从指定阶段继续。
|
||
2. 判断启动模式：
|
||
- 完整模式：用户提供粗略想法或初始 PRD。
|
||
- Research 模式：用户已有 research，需要转成或修正 OpenSpec。
|
||
- PRD 文件模式：用户提供已有 PRD 路径。
|
||
- 恢复模式：用户希望从某个阶段继续（补做最小前置检查）。
|
||
- 快速模式：小改动，合并 gate；具体分档规则见 `references/scales.md`。
|
||
3. 如果缺少 `devflow/`，初始化：
|
||
- `devflow/projects/`
|
||
- `devflow/glossary/CONTEXT.md`
|
||
- `devflow/compound/`
|
||
4. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
|
||
5. 检查 OpenSpec 和子 skill 是否可用：
|
||
- OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。
|
||
- 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。
|
||
6. 如果 OpenSpec 或子 skill 不可用，不要静默跳过；使用内置执行协议（见 `references/fallbacks.md`），并在当前 checkpoint 说明 fallback 来源、影响和剩余风险。
|
||
|
||
## 进度汇报
|
||
|
||
用户可见进度默认折叠为 4 个 checkpoint：
|
||
|
||
| Checkpoint | 内部阶段 |
|
||
| --- | --- |
|
||
| Discover | clarify + context + propose + grill |
|
||
| Commit | specify + audit + commit |
|
||
| Apply | apply |
|
||
| Archive | archive |
|
||
|
||
汇报规则：
|
||
|
||
- 面向用户时优先使用 checkpoint 名称，不逐个汇报 9 个内部阶段。
|
||
- 内部阶段只在 checkpoint 摘要中作为证据列出，例如"Discover 已完成：读取了 devflow、生成 proposal、解决 2 个问题"。
|
||
- 只有发生阻塞、冲突、fallback、用户要求继续某个内部阶段，或需要解释恢复位置时，才暴露内部阶段名。
|
||
- 当前分档的汇报压缩规则见 `references/scales.md`；无论分档如何，都不要把内部阶段名当作用户操作入口。
|
||
|
||
## 项目标识规则
|
||
|
||
- 整个流程使用同一个 slug。
|
||
- 优先使用 OpenSpec change name。
|
||
- 如果还没有，则从功能标题生成 kebab-case slug。
|
||
- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`。
|
||
- 如果目录已存在，默认恢复该项目；除非用户明确要求新开一轮。
|
||
|
||
## Devflow 产物分层
|
||
|
||
Devflow 是 sm-flow 自动维护的项目长期记忆层，不复制 OpenSpec 的执行产物。
|
||
|
||
**过程日志**（clarify → apply 期间维护）：
|
||
|
||
- `decisions.md`：question pool、evidence-driven 汇报状态、user-interview 确认状态、关键取舍、风险接受、OpenSpec 回写记录、冲突分类记录。
|
||
|
||
**最终档案**（archive 阶段从 decisions.md + OpenSpec 产物提取）：
|
||
|
||
- `brief.md`：背景、目标、范围、非目标、分档、关联 OpenSpec change。
|
||
- `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论和汇报状态；分档要求见 `references/scales.md` 和 `references/archive-rules.md`。
|
||
- `acceptance.md`：实现结果、验证命令、未验证项、归档状态、后续事项。
|
||
|
||
**按需产物**（archive 阶段按需创建）：
|
||
|
||
- `prd.md`：需求复杂、用户明确要求、或需要对外协作。
|
||
- `research.md`：存在真实调研、代码考古、竞品/API 对比或复杂方案比较。
|
||
- `design.md`：不适合放进 OpenSpec design 的长期背景或架构审计摘要。
|
||
- `tasks.md`：跨会话的人类追踪；执行任务仍属于 OpenSpec。
|
||
- `alignment.md` / `clarifications.md`：仅在 gap 或澄清很多时使用。
|
||
- `adr/*.md` 和 `compound/*.md`：仅在满足 ADR / compound knowledge 规则时使用。
|
||
|
||
**规模分档**：`micro / standard / complex` 的唯一规则源是 `references/scales.md`。
|
||
|
||
## 快速模式
|
||
|
||
快速模式适用于 `references/scales.md` 定义的 micro 变更。它合并 gate 而不仅仅是压缩产物；具体覆盖规则见 `references/scales.md`。
|
||
|
||
无论什么模式，以下内容必须保留：
|
||
|
||
- context 最小上下文收集：至少检查 glossary 和相关 ADR。
|
||
- grill 最小澄清：按 `references/scales.md` 当前分档要求执行；evidence-driven 结论仍需汇报。
|
||
- commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行；完整性检查按 `references/scales.md` 当前分档要求执行。
|
||
- apply 仍由 OpenSpec tasks/specs 驱动执行。
|
||
- archive 轻量回填：记录验收结果、OpenSpec 链接和归档状态。
|
||
|
||
## 完成标准
|
||
|
||
只有同时满足以下条件，流程才算完成：
|
||
|
||
- 用户可见的 Discover、Commit、Apply、Archive checkpoint 已完成，或未完成项已明确标记为暂停/不适用。
|
||
- OpenSpec proposal、设计产物、specs、tasks 已按当前分档生成或更新到可执行状态。
|
||
- 实现或规划工作已完成，且执行依据来自 OpenSpec。
|
||
- 已运行验证，或已记录未运行验证的原因。
|
||
- `devflow/projects/YYYY-MM-DD-{slug}/` 包含 `references/scales.md` 和 `references/archive-rules.md` 要求的当前分档档案。
|
||
- 用户知道剩余风险与下一步，并已被询问是否归档 OpenSpec change。
|