le-spec v1.0.0：Le SPEC 智能需求分析与 SPEC 生成总控 skill——真实集成 grilling/grill-with-docs(domain-modeling) + think + openspec(CLI 1.16.1 + 7 个 openspec-* skills，均经 skills.sh 装入 ~/.agents/skills 并软链四 runtime)；七阶段工作流（识别/十类分拣/Grill 访谈/Think 挑战/反向验收/OpenSpec 生成/四视角审查）复杂度三档自适应；状态 state.md + 调用账本 ledger.jsonl 双持久化支撑中断恢复与真实调用核验；依赖检查 deps_check.py 分级报缺+精确安装命令，ledger.py append/check/tail；四类回合终止停点（批准前不编码为硬约束）；测试 A-I 九项全过：两场景 fresh-context 子代理多轮实测（4 轮访谈+变更+中断恢复+strict validate 双项目通过），账本 28 条真实调用（grilling×9/think×2/openspec CLI×14），独立子代理审查实测抓出自审遗漏的 2 blocking；已知限制 7 项如实入库（reports/test-report.md）
This commit is contained in:
leroy
@@ -0,0 +1,106 @@
|
||||
# 七阶段工作流规程
|
||||
|
||||
阶段是逻辑流。每阶段入口先读 state.md 阶段标记，已完成的跳过。
|
||||
|
||||
## Phase 0：项目识别与上下文理解
|
||||
|
||||
1. 判任务类型：全新产品 / 已有产品加功能 / 已有功能修改 / 复杂业务模块 / 架构重构 / 探索性想法。
|
||||
2. 有代码库时只读检查（按复杂度控制深度，simple 档可缩到 3-5 分钟扫读）：
|
||||
- 项目结构、技术栈、入口文件；已有文档与 `openspec/specs/`（`openspec context --json` 探测）；GLOSSARY/ADR（domain-modeling 的管理物）；近期 git log 的设计决策线索。
|
||||
- **能从代码和文档确认的事实，绝不进访谈问题**（grilling 原义：事实自己查，决策问用户）。
|
||||
3. 复杂度定档（可随讨论动态升降级，升降级写入 state.md 并注明理由）：
|
||||
|
||||
| 档 | 特征 | 流程 |
|
||||
|---|---|---|
|
||||
| simple | 字段/筛选/文案级修改，影响单一界面或接口 | 0 → 1 → grilling 单轮（≤1 轮）→ （跳过 3）→ 清单式 4 → 5（propose，design 多为 skip）→ 快速 6 → 7 |
|
||||
| medium | 新功能模块（日历、用户管理级） | 全流程，3 按需 |
|
||||
| complex | 全新产品、多角色/多流程系统、架构重构 | 全流程；3 必用于重大决策；访谈允许多轮充分展开 |
|
||||
|
||||
## Phase 1：原始需求理解
|
||||
|
||||
对用户原始输入做**十类分拣**，产出写入 state.md：
|
||||
|
||||
1. 明确需求 2. 目标与期望结果 3. 用户角色与场景 4. 未定想法 5. 用户假设 6. 约束（产品+技术） 7. 矛盾描述（列出冲突双方与出处） 8. 重要缺失信息 9. 已否定方案 10. 明确不做
|
||||
|
||||
规则：保留原始措辞的关键短语与来源（哪条消息）；不擅自增需求；临时想法标注 [未定]；AI 推荐方案标注 [建议]，不得记为已批准。矛盾不在此阶段裁决——入开放问题，Phase 2 问。
|
||||
|
||||
state.md 初始化模板：
|
||||
|
||||
```markdown
|
||||
# Le SPEC 状态 — <项目/功能名>
|
||||
更新: <日期> | 阶段: Phase 1 | 复杂度: <档>（理由）
|
||||
|
||||
## 项目
|
||||
类型: <全新/加功能/修改/…> ｜ 目标: <一句话>
|
||||
|
||||
## 原始输入摘要
|
||||
- (来源: 首条消息) <要点，保留关键原话>
|
||||
|
||||
## 已确认决策
|
||||
| # | 决策 | 内容 | 来源 | 状态 |
|
||||
|---|------|------|------|------|
|
||||
|
||||
## 已否定方案
|
||||
- <方案> — 否定原因 <来源>
|
||||
|
||||
## 开放问题
|
||||
- [ ] Q1 <问题>（影响: 核心/边缘；依赖: -）
|
||||
|
||||
## 假设（待验证）
|
||||
- <假设>（依据）
|
||||
|
||||
## 访谈计数
|
||||
轮次: 0 ｜ 检查点: -
|
||||
|
||||
## 下一步
|
||||
- <具体动作>
|
||||
```
|
||||
|
||||
## Phase 2：Grill 深度访谈
|
||||
|
||||
入口动作（顺序固定）：
|
||||
1. 读 [dependencies.md](dependencies.md) 第 1 节，按调用方式总则**真实加载 grilling**（已有项目叠加 domain-modeling），记账本。
|
||||
2. 以 state.md 开放问题 + 十类分拣中的矛盾/缺失为 design tree 初始节点。
|
||||
|
||||
访谈中 Le SPEC 叠加于 grilling 原义之上的规则：
|
||||
- **每轮结束**（用户答完）：新决策入表、开放问题更新、轮次 +1、增量写 state.md。
|
||||
- **检查点**：每逢第 4、8、12…轮答完，附一段 ≤6 行小结（已确认 N 项 / 开放 M 项 / 收敛判断：继续｜接近｜已达标）。有 blocking 问题默认继续，不要求用户批准继续；已达标主动提议收口。
|
||||
- **收敛标准**（全部满足才收口）：目标明确 ｜ 范围明确（含不做） ｜ 角色明确 ｜ 核心流程闭环 ｜ 业务规则明确 ｜ 数据关系与权限边界明确（适用时） ｜ 异常边界已有处理原则 ｜ 无阻塞实现的重大未决。非关键细节可用「明确标注的默认方案」填充（标注 [默认] 进 state.md），不无限追问。
|
||||
- **用户控制权**：随时可换模块、改需求（记录影响范围，受影响的已确认项重开并注明）、看草稿、暂停（state.md 存「下一步」）、先谈技术（跳 Phase 3 再回）。
|
||||
- 关键需求仍有歧义时不得自行拍板；重大未决可出「标注风险的草稿」但明示未经审查。
|
||||
|
||||
## Phase 3：Think 方案分析与挑战
|
||||
|
||||
1. 无实质方案争议（simple 或方案唯一且用户已定）→ state.md 记"Phase 3 跳过（无分歧）"，进 Phase 4。
|
||||
2. 否则按 [dependencies.md](dependencies.md) 第 2 节**真实加载 think**（含其 Preflight：读项目 AGENTS/CLAUDE 索引与相关规则），记账本。
|
||||
3. think 产出推荐方案 → 向用户呈现（推荐+理由+一个替代+风险+最脆弱假设）→ **终止回合等决断** → 批准则入 state.md [已批准]，新不确定性回流 Phase 2。
|
||||
|
||||
## Phase 4：需求反向验收
|
||||
|
||||
详见 [acceptance.md](acceptance.md)。核心：fresh-context 子代理扮演"没参与讨论的资深工程师"，只读 state.md + 已确认材料，回答"由我实现的话，哪些产品行为还得靠猜？"。产出 blocking / major / minor 问题清单：
|
||||
- blocking → 以 grilling 单轮格式向用户澄清（记账本 dep=grilling, summary=acceptance-driven）→ 更新后**只复核受影响项**；
|
||||
- major → 能由已确认决策推导的当场补进 state.md 并标注推导依据，推导不了的升级 blocking；
|
||||
- minor → 记入开放问题，随 SPEC 的"非阻塞事项"呈现。
|
||||
清零 blocking 才进 Phase 5。
|
||||
|
||||
## Phase 5：OpenSpec 生成正式 SPEC
|
||||
|
||||
按 [dependencies.md](dependencies.md) 第 3 节标准路径执行（每条 CLI 命令记账本）。要点：
|
||||
- change 名 kebab-case，从需求导出；同名已存在 → 问用户续用还是新建（遵循原生 guardrail）。
|
||||
- 逐 artifact：先 `instructions`，按其 template + instruction 撰写；内容全部来自 state.md（已批准决策/已确认需求/[默认] 项如实标注），**不编造规则**；验收场景用 Requirement/Scenario 结构，可测、可观察。
|
||||
- `design.md` 遵循其 conditional 规则（跨切面/新依赖/数据模型等才写）；Phase 3 有 think 结论的，方案与已否替代直接沉淀为 Decisions。
|
||||
- `openspec validate` 必须通过；失败按输出修正后重跑。
|
||||
- SPEC 语言聚焦"系统做什么、表现什么行为、如何判断正确"——实现机制进 design/tasks（OpenSpec config 的 product-language 约定同理）。
|
||||
|
||||
## Phase 6：SPEC 独立质量审查
|
||||
|
||||
详见 [review.md](review.md)。四视角（产品/架构/开发/测试）独立审查 artifacts + `openspec validate` 复跑 + 账本核对。问题分级（blocker/major/minor）→ 修正 → 只复验受影响项 → 出审查结论（无事实依据的分数不打）。
|
||||
|
||||
## Phase 7：用户确认与交接
|
||||
|
||||
确认包含：正式 SPEC 位置与摘要、核心功能与范围、关键决策（含被否方案）、明确不做、尚存风险与非阻塞问题、审查结果摘要、账本统计（grilling/think/openspec 各 N 次真实调用）。
|
||||
**呈交后终止回合。** 用户批准 → 更新 state.md 阶段为"已交接"，提示后续：实现用 openspec-apply-change 工作流、需求变化用 openspec-update-change、完成后 openspec-archive-change。用户要改 → 只更新受影响 artifact 并复验（不重跑全流程）。
|
||||
|
||||
## 中断恢复
|
||||
|
||||
任何会话重入：`openspec context --json` → 读 `<root>/openspec/le-spec/state.md` → 校验其「下一步」与 OpenSpec 实际状态（`openspec status --change` 或 `openspec list --json`）一致 → 从断点继续。state.md 阶段标记与实际不符时以实际产物为准并修正状态。
|
||||
Reference in New Issue
Block a user