470 lines
12 KiB
Markdown
470 lines
12 KiB
Markdown
# 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` 中，为每个阶段明确标注"能力来源"：
|
||
|
||
```markdown
|
||
## 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` 中增加清晰的状态定义：
|
||
|
||
```markdown
|
||
## 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 阶段增加硬性检查：
|
||
|
||
```markdown
|
||
## 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` 中明确标注"可选"：
|
||
|
||
```markdown
|
||
## 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 开头增加"执行检查清单"
|
||
|
||
```markdown
|
||
# 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 每个阶段增加"能力来源"
|
||
|
||
```markdown
|
||
## Specify 阶段
|
||
|
||
**能力来源**：openspec-propose skill（必须调用）
|
||
|
||
## Grill 阶段
|
||
|
||
**能力来源**：grill-with-docs skill（可选，推荐）
|
||
```
|
||
|
||
### 优化 3：增加阶段门控检查
|
||
|
||
在 sm-flow 主逻辑中，Apply 阶段入口增加：
|
||
```python
|
||
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% 的执行偏差问题。
|