95 lines
5.2 KiB
Markdown
95 lines
5.2 KiB
Markdown
# 运行规则
|
||
|
||
本文件承载稳定但不必放在顶层 `SKILL.md` 的运行规则。
|
||
|
||
## 接口影响分级
|
||
|
||
接口影响分级决定“记录在哪里”以及“是否需要独立接口文档”。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义，或内部决策逻辑改变可观察行为的变更，都必须先做分级。
|
||
|
||
| 级别 | 判断条件 | 产物要求 |
|
||
| --- | --- | --- |
|
||
| L1 内部实现 | 不改变调用方可观察行为 | 在 OpenSpec tasks 或 acceptance 记录验证 |
|
||
| L2 内部接口 | 内部 DTO/service/event/RPC/decision-logic 变化，且所有消费者仍在同一实现边界内 | 在 OpenSpec design/specs/tasks 或 devflow evidence/decisions 中内联记录影响 |
|
||
| L3 协作接口 | 影响其他模块/服务、前端、外部系统、跨团队消费者、数据库契约、事件、回调或 SDK | 产出独立接口文档或等价独立章节 |
|
||
| L4 破坏性接口 | 破坏兼容、改变语义/错误码/状态机、可能让旧调用方失败，或需要迁移/灰度/回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR |
|
||
|
||
判断启发：
|
||
|
||
- 如果变更只是把接口恢复到原 OpenSpec 或既有文档承诺，通常是 L1 或 L2。
|
||
- 如果决策逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。
|
||
- 如果旧调用方不改代码就可能失败，或会观察到缺失/额外数据、不同状态或不同错误码，按 L4 处理。
|
||
- 如果消费者边界或兼容性不明确，默认提高一级，并转成 `user-interview` 问题。
|
||
|
||
## 启动检查
|
||
|
||
1. 判断启动模式：
|
||
- 完整模式：用户提供粗略想法或初始 PRD。
|
||
- Research 模式：用户已有 research，需要生成或修正 OpenSpec。
|
||
- PRD 文件模式：用户提供已有 PRD 路径。
|
||
- 指定阶段模式：用户希望从某个 Phase 恢复。
|
||
- 快速模式：小改动；Phase 2 和 Phase 4 可以轻量化，但不能跳过。
|
||
2. 如果缺少 `devflow/`，初始化：
|
||
- `devflow/projects/`
|
||
- `devflow/glossary/CONTEXT.md`
|
||
- `devflow/compound/`
|
||
- `devflow/reference/`
|
||
3. 如果根目录旧 `CONTEXT.md` 存在，而 `devflow/glossary/CONTEXT.md` 缺失或为空，询问是迁移还是合并。
|
||
4. 检查 OpenSpec 和辅助能力是否可用：
|
||
- OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`
|
||
- 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`
|
||
5. 如果 OpenSpec 能力不可用，不要静默绕过；要走 fallback 协议，并在 Phase 3 前披露降级风险。
|
||
|
||
## 项目标识规则
|
||
|
||
- 整个流程使用同一个 slug。
|
||
- 优先使用 OpenSpec change name。
|
||
- 如果还没有，则从功能标题生成 kebab-case slug。
|
||
- 项目档案目录格式：`devflow/projects/YYYY-MM-DD-{slug}/`
|
||
- 如果目录已存在，默认恢复该项目；除非用户明确要求新开一轮。
|
||
|
||
## Devflow 产物分层
|
||
|
||
Devflow 是辅助 OpenSpec 的人类可读档案层，不应复制 OpenSpec 的执行产物。
|
||
|
||
必需产物：
|
||
|
||
- `brief.md`：背景、目标、范围、非目标、分档、关联 OpenSpec change
|
||
- `evidence.md`：代码/文档证据、历史决策、evidence-driven 结论、汇报状态
|
||
- `decisions.md`：user-interview 条目、确认结果、取舍、风险接受、OpenSpec 回写记录
|
||
- `acceptance.md`：结果、验证、未验证项、归档状态、后续事项
|
||
|
||
按需产物：
|
||
|
||
- `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`：使用 `brief.md`、`decisions.md`、`acceptance.md`；证据很少时并入 `brief.md`
|
||
- `standard`：使用 `brief.md`、`evidence.md`、`decisions.md`、`acceptance.md`
|
||
- `complex`：`standard` 基础上按需增加 PRD/research/design/tasks/alignment
|
||
|
||
## 快速模式
|
||
|
||
快速模式只适用于小而低风险的变更。它可以压缩 Phase 1.5 和 Phase 2.5，但必须保留：
|
||
|
||
- 最小 Phase 0.5 上下文收集：至少检查 glossary 和相关 ADR
|
||
- 最小 Phase 2 澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论仍需汇报
|
||
- Phase 2.9 commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行
|
||
- Phase 3 仍由 OpenSpec tasks/specs 驱动执行
|
||
- 轻量 Phase 4 回填：记录验收结果、OpenSpec 链接和归档状态
|
||
|
||
## 完成标准
|
||
|
||
只有同时满足以下条件，流程才算完成：
|
||
|
||
- OpenSpec proposal/design/specs/tasks 已生成或更新到可执行状态
|
||
- 实现或规划工作已完成，且执行依据来自 OpenSpec
|
||
- 已运行验证，或已记录未运行验证的原因
|
||
- `devflow/projects/YYYY-MM-DD-{slug}/` 包含所选分档要求的必要产物
|
||
- 用户知道剩余风险与下一步，并已被询问是否归档 OpenSpec change
|