SuperBizAgent-java/.claude/skills/sm-flow/references/operating-rules.md

运行规则

本文件承载稳定但不必放在顶层 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 + 归档确认。
   • 自然语言指定阶段继续：识别意图后，自动补做最小前置检查，然后从指定阶段继续。
2. 判断启动模式：
   • 完整模式：用户提供粗略想法或初始 PRD。
   • Research 模式：用户已有 research，需要转成或修正 OpenSpec。
   • PRD 文件模式：用户提供已有 PRD 路径。
   • 恢复模式：用户希望从某个阶段继续（补做最小前置检查）。
   • 快速模式：小改动，合并 gate（见下文）。
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 不可用，不要直接绕过；使用内置执行协议（见 references/fallbacks.md），并在 apply 前向用户说明。

项目标识规则

• 整个流程使用同一个 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 结论和汇报状态。
• 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：小且低风险，gate 合并（见快速模式），最终档案同 standard。
• standard：默认模式。
• complex：高风险、跨模块、需求不清或多人协作时，在 standard 基础上按需增加扩展产物。

快速模式

快速模式适用于小而低风险的变更。它合并 gate 而不仅仅是压缩产物：

standard 流程：clarify → context → propose checkpoint → grill → specify → audit checkpoint → commit
micro 流程：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题） → commit（简化检查）

micro 的定位：gate 变少但保留最关键的（grill 最小澄清 + commit gate）。

无论什么模式，以下内容必须保留：

• context 最小上下文收集：至少检查 glossary 和相关 ADR。
• grill 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论仍需汇报。
• commit gate：确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。
• apply 仍由 OpenSpec tasks/specs 驱动执行。
• archive 轻量回填：记录验收结果、OpenSpec 链接和归档状态。

完成标准

只有同时满足以下条件，流程才算完成：

• OpenSpec proposal/design/specs/tasks 已生成或更新到可执行状态。
• 实现或规划工作已完成，且执行依据来自 OpenSpec。
• 已运行验证，或已记录未运行验证的原因。
• devflow/projects/YYYY-MM-DD-{slug}/ 包含 brief.md、evidence.md、decisions.md、acceptance.md。
• 用户知道剩余风险与下一步，并已被询问是否归档 OpenSpec change。