SuperBizAgent-java/.docs/sm-flow-doc-management-ui-analysis.md

sm-flow 执行问题分析 - 文档管理页面开发案例

执行时间

2026-06-25

任务背景

用户要求："开发文档管理页面"，已有后端 API，需要开发前端页面。

实际执行情况

执行的阶段

1. ✅ Clarify - 尝试 AskUserQuestion → 被用户拒绝 → 使用默认假设
2. ✅ Context - 读取后端代码、表设计、devflow/glossary
3. ✅ Propose - 生成 proposal.md（放在 .docs/）
4. ⚠️ Grill - 手工查证（读代码），未调用 grill-with-docs
5. ⚠️ Specify - 生成 design.md 和 tasks.md，未调用 openspec-propose
6. ❌ Audit - 完全跳过
7. ❌ Commit - 完全跳过
8. ✅ Apply - 直接实现代码（基于 tasks.md，不是 change.json）
9. ⚠️ Archive - 生成 acceptance.md（放在 .docs/，不是 devflow/）

违反的规则

• ❌ 规则 1: OpenSpec 是唯一执行真理源（实际基于 markdown）
• ❌ 规则 2: 不得跳过 context（虽然读了，但没读历史项目）
• ❌ 规则 3: 不得跳过 grill（没有调用工具）
• ❌ 规则 4: 不得跳过 commit（完全跳过）
• ⚠️ 规则 6: 子 skill 必须显式调用（未调用 openspec-propose 和 grill-with-docs）

---

根因分析

1. 用户打断后，Agent 误判流程模式 ⭐⭐⭐

问题： Clarify 阶段调用 AskUserQuestion 时，用户拒绝并说"继续"。

Agent 的理解：

用户拒绝 AskUserQuestion
  ↓
Agent 推理：用户不想走完整流程，要快速实现
  ↓
Agent 行动：跳过后续检查点，直接写代码

正确理解应该是：

用户拒绝 AskUserQuestion
  ↓
仅表示：跳过这一步澄清，使用默认假设
  ↓
不意味着：跳过整个 sm-flow 流程

优化建议： 当用户拒绝 AskUserQuestion 时，明确询问：

⚠️ 已跳过澄清，将基于默认假设继续。

📋 默认假设：
   - 列表排序：按上传时间倒序
   - 页面入口：侧边栏添加入口
   - 状态更新：手动刷新

是否继续完整的 sm-flow 流程（含 OpenSpec 生成、Commit 检查）？
  [Y] 是，走完整流程
  [N] 否，快速实现（仍需基本检查）

---

2. OpenSpec 工具调用不明确 ⭐⭐⭐ (最关键)

问题： Agent 不知道是否必须调用 openspec-propose，结果只写了 markdown。

Agent 的困惑：

Specify 阶段：
  我应该做什么？
  - 写 design.md ✅（确定要做）
  - 写 tasks.md ✅（确定要做）
  - 调用 openspec-propose？❓
    - 技能列表里有 openspec-propose-change
    - 但不确定是否必须调用
    - phase-contracts.md 没有明确说"必须调用"
    
  结果：只做了确定的事（写 markdown），跳过了不确定的（工具调用）

优化建议：

在 references/phase-contracts.md 中，为每个阶段明确标注"能力来源"：

## Specify 阶段

**能力来源**：openspec-propose skill（必须调用）

**动作**：
1. 手工编写 design.md 和 tasks.md
2. ✅ **必须调用 openspec-propose**

Skill(skill="openspec-propose", args="基于 proposal.md 生成 OpenSpec change")

该工具会生成：openspec/changes/{slug}/change.json

**退出条件**：
- [ ] design.md 存在且完整
- [ ] tasks.md 存在且包含至少 5 个任务
- [ ] ✅ openspec/changes/{slug}/change.json 存在（必须由工具生成）

关键改进：

• 明确标注"必须调用"
• 提供具体的工具调用示例
• 在退出条件中检查工具生成的文件

---

3. Draft vs Committed OpenSpec 概念模糊 ⭐⭐

问题： Agent 不清楚什么是 Committed OpenSpec，没有明确的 commit 步骤。

Agent 的理解：

我写了 proposal.md + design.md + tasks.md
  ↓
这些是 Draft OpenSpec？
  ↓
那什么是 Committed OpenSpec？
  ↓
没有明确的 commit 步骤，那就直接实现吧

优化建议：

在 references/operating-rules.md 中增加清晰的状态定义：

## OpenSpec 状态机

### Draft OpenSpec
- 文件：openspec/changes/{slug}/change.json
- metadata.status: "draft"
- 特征：可以修改，不能用于 apply，是讨论和审计的对象

### Committed OpenSpec
- 文件：openspec/changes/{slug}/change.json
- metadata.status: "committed"
- 特征：已通过检查，可以用于 apply，是唯一执行真理源

### Commit 检查清单
在 Commit 阶段，必须检查：
- [ ] change.json 存在
- [ ] proposal/design/tasks 完整
- [ ] 所有 MUST 级别的设计决策已明确
- [ ] 所有高风险项已识别并有缓解措施

通过检查后，将 change.json 的 metadata.status 从 "draft" 改为 "committed"。

---

4. Apply 阶段缺少强制检查 ⭐⭐⭐ (最关键)

问题： Agent 没有检查 OpenSpec 是否 committed，直接基于 markdown 实现。

Agent 的执行：

Apply 阶段：
  → 读取 tasks.md（markdown 文件）
  → 直接开始写代码
  → 没有检查 change.json 是否存在
  → 没有检查 metadata.status 是否为 "committed"

优化建议：

在 references/phase-contracts.md 的 Apply 阶段增加硬性检查：

## Apply 阶段

**进入条件（硬约束）**：

在开始 apply 之前，必须执行以下检查：

```python
def can_enter_apply(slug: str) -> bool:
    change_path = f"openspec/changes/{slug}/change.json"
    
    # 1. change.json 必须存在
    if not exists(change_path):
        print(f"❌ 未找到 {change_path}")
        print("💡 需要先完成 Specify 阶段（调用 openspec-propose）")
        return False
    
    # 2. 读取 change.json
    change = read_json(change_path)
    
    # 3. metadata.status 必须为 "committed"
    status = change.get("metadata", {}).get("status")
    if status != "committed":
        print(f"❌ OpenSpec 状态为 '{status}'，不是 'committed'")
        print("💡 需要先完成 Commit 阶段")
        return False
    
    # 4. 必须包含 tasks
    if not change.get("tasks"):
        print("❌ OpenSpec 缺少 tasks 字段")
        return False
    
    print(f"✅ Apply 检查通过")
    print(f"📋 将基于 {change_path} 执行")
    return True

执行约束：

• ✅ 只能读取 openspec/changes/{slug}/change.json
• ✅ 从 tasks 字段获取任务列表
• ❌ 不能基于对话内容实现
• ❌ 不能基于 .docs/ 下的 markdown 实现

---

### 5. 文件路径规范冲突 ⭐⭐

**问题**：
CLAUDE.md 说"文档统一放到 `.docs`"，sm-flow 要求用 `openspec/changes/`。

**Agent 的困惑**：

CLAUDE.md: 所有文档放 .docs sm-flow: OpenSpec 放 openspec/changes/

我应该听谁的？ → 选择了 CLAUDE.md（项目全局规范） → 结果违反了 sm-flow 规范

**优化建议**：

在 sm-flow SKILL.md **开头**（第一段）明确优先级：

```markdown
# SM Flow

## 路径规范（覆盖项目 CLAUDE.md）

⚠️ **重要**：sm-flow 使用专用路径，优先级高于项目 CLAUDE.md。

| 内容类型 | 路径 | 说明 |
|---------|------|------|
| OpenSpec | openspec/changes/{slug}/ | proposal.md, design.md, tasks.md, change.json |
| 长期记忆 | devflow/ | glossary, ADRs, 历史项目 |
| ❌ 不使用 | .docs/ | sm-flow 不使用此路径 |

...（后续内容）...

---

6. Grill 阶段工具调用不明确 ⭐

问题： 技能列表有 grill-with-docs，但 Agent 不确定是否必须调用。

Agent 的困惑：

Grill 阶段：
  - 要求：evidence-driven 查证 ✅（我读了代码）
  - 要求：user-interview one-at-a-time（用户拒绝了）
  - 要求：至少 3 个高价值问题
  
  但是否需要调用 grill-with-docs？
    - 技能列表里有
    - 但 phase-contracts.md 没有明确说"必须"
    - 那我就只做查证，不调用工具了

优化建议：

在 references/phase-contracts.md 中明确标注"可选"：

## Grill 阶段

**能力来源**：grill-with-docs skill（可选，推荐）

**动作**：
1. **如果 grill-with-docs 已安装**：调用 skill

Skill(skill="grill-with-docs", args="proposal: openspec/changes/{slug}/proposal.md")

该工具会：
- 挑战方案与现有领域模型的对齐
- 审查术语一致性（与 devflow/glossary 对比）
- 至少提出 3 个高价值澄清问题

2. **如果 grill-with-docs 未安装**：手工 grill
- 读取 devflow/glossary/CONTEXT.md
- 验证关键技术假设（读代码）
- 至少解决 3 个高价值问题

**退出条件**：
- [ ] 至少解决 3 个高价值问题
- [ ] 关键技术假设已验证
- [ ] 输出"解决的问题"列表

---

7. 阶段切换缺少明确提示 ⭐

问题： Agent 和用户都不清楚当前在哪个阶段。

优化建议：

每个阶段开始时输出：

🔄 进入 Specify 阶段
📖 目标：补全 design 和 tasks，调用 openspec-propose
🛠️ 将要做的事：
   1. 手工编写 design.md
   2. 手工编写 tasks.md
   3. 调用 openspec-propose skill

每个阶段结束时输出：

✅ Specify 完成
📋 产出：
   - design.md
   - tasks.md
   - change.json（由 openspec-propose 生成）
📍 下一阶段：Audit

---

综合优化方案

优化 1：在 SKILL.md 开头增加"执行检查清单"

# SM Flow

## 路径规范（覆盖 CLAUDE.md）
...

## 执行检查清单（Agent 自查）

每个阶段结束前，检查：

### Specify
- [ ] 创建了 design.md 和 tasks.md
- [ ] ✅ **调用了 openspec-propose skill**
- [ ] change.json 存在

### Commit
- [ ] change.json 的 metadata.status == "committed"

### Apply
- [ ] ✅ **检查了 metadata.status == "committed"**
- [ ] 基于 change.json 的 tasks 执行

优化 2：phase-contracts.md 每个阶段增加"能力来源"

## Specify 阶段

**能力来源**：openspec-propose skill（必须调用）

## Grill 阶段

**能力来源**：grill-with-docs skill（可选，推荐）

优化 3：增加阶段门控检查

在 sm-flow 主逻辑中，Apply 阶段入口增加：

if not can_enter_apply(slug):
    print("⏸️ 流程暂停：无法进入 Apply 阶段")
    print("💡 需要先完成 Specify 和 Commit 阶段")
    halt()

---

优先级建议

P0（立即修复，阻塞性）

1. 明确工具调用要求：phase-contracts.md 标注"能力来源"（必须/可选/无）
2. Apply 阶段强制检查：检查 change.json 的 metadata.status
3. 路径规范优先级：SKILL.md 开头明确 sm-flow 路径覆盖 CLAUDE.md

P1（重要优化）

4. 阶段切换提示：明确输出当前状态
5. OpenSpec 状态定义：operating-rules.md 中定义 Draft vs Committed
6. 执行检查清单：Agent 自查用，避免遗漏步骤

P2（增强体验）

7. 用户打断处理：明确询问是否继续完整流程
8. 流程可视化：进度条
9. 错误恢复：支持从中断点恢复

---

测试建议

测试用例 1：完整流程

用户输入："开发一个用户管理页面"
期望：
  Specify 阶段调用 openspec-propose
  Commit 阶段检查 metadata.status="committed"
  Apply 阶段基于 change.json 执行

测试用例 2：跳过工具调用

Specify 阶段：只写 markdown，未调用 openspec-propose
期望：
  Commit 阶段检查失败："❌ change.json 不存在"
  提示："需要调用 openspec-propose"
  流程暂停

测试用例 3：未 Commit 就 Apply

Specify 完成后，用户说"直接实现"
期望：
  Apply 阶段检查 metadata.status
  如果不是 "committed"，拒绝执行
  提示："必须先通过 Commit 检查"

---

总结

核心问题

隐式假设太多，硬性约束太少。

Agent 在不确定时会选择：

1. 做确定的事（写 markdown）
2. 跳过不确定的事（工具调用）
3. 选择"更快"的路径（直接实现）

解决方案

1. 明确化：标注"能力来源"，说明哪些工具必须调用
2. 强制化：Apply 阶段强制检查 Committed OpenSpec
3. 可视化：明确输出当前状态
4. 优先级明确：sm-flow 路径规范 > 项目 CLAUDE.md

最关键的 3 个改进

1. ⭐⭐⭐ Specify 阶段明确标注"必须调用 openspec-propose"
2. ⭐⭐⭐ Apply 阶段强制检查 change.json 的 metadata.status
3. ⭐⭐ SKILL.md 开头明确 sm-flow 使用 openspec/changes/ 路径

这三个改进可以解决 80% 的执行偏差问题。