Menu
从 refine 产出到结构化 spec。当 refine 完成后需要编写正式 spec，或提到"规格""spec""需求文档"
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
| name | define-workflow-spec |
| description | 从 refine 产出到结构化 spec。当 refine 完成后需要编写正式 spec，或提到"规格""spec""需求文档" |
define-workflow-refine 完成，用户已批准方向docs/features/YYYYMMDD-<name>/01-spec.md + 用户批准design-workflow-design；纯后端/脚本/迁移可跳过到 build-workflow-planbuild-cognitive-decision-record/SKILL.md — 有架构决策时再加载）写任何 spec 内容前，先列假设：
ASSUMPTIONS I'M MAKING:
1. 这是 Web 应用（不是原生移动端）
2. 认证使用 session cookie（不是 JWT）
3. 数据库是 PostgreSQL（基于现有 Prisma schema）
4. 目标现代浏览器（不支持 IE11）
→ 现在纠正我，否则我按这些继续。
不要静默填补模糊需求。spec 的全部价值在于在写代码前暴露误解。
覆盖以下内容：
software；可选 software / document / article / deck / visual/goal 生命周期管理的替代品。Build: npm run build
Test: npm test -- --coverage
Lint: npm run lint --fix
Dev: npm run dev
doc_intent: feature_only | feature_plus_project | project_onlyproject_truth_changed: yes | noaffected_project_docs: 明确列出 README.md、AGENTS.md、CHANGELOG.md、DESIGN.md 或 docs/architecture/*.mdrationale: 为什么只写 feature docs，或为什么必须同步 project docsspec 模板：
# Spec: [功能名称]
## Objective
[构建什么、为什么。用户故事或验收条件。]
## Artifact Type
artifact_type: software
Allowed: software / document / article / deck / visual
## Goal Alignment
- Source Goal: conversation / `GOAL.md`
- Goal Status: accepted / needs-refinement / blocked
- Goal Review Score: <score>/12
### One-line Goal
[一句话目标]
### Done When
- [ ] Functional:
- [ ] Technical:
- [ ] Regression:
- [ ] Output:
### Stop Conditions
- [ ] Acceptance 无法验证
- [ ] 需要修改明确排除范围
- [ ] 需要改变 API / 权限 / 数据结构 / 生产配置
- [ ] 实际范围明显大于当前 Goal
## Documentation Impact
- doc_intent: feature_only
- project_truth_changed: no
- affected_project_docs:
- none
- rationale:
## Tech Stack
[software 时填写框架、语言、关键依赖；非 software 时填写工具链、格式、模板或品牌约束]
## Commands / Tools
[Build, test, lint, dev，或 DOCX/PPTX/PDF/PNG/SVG 导出工具与命令]
## Project Structure / Artifact Paths
[目录布局、源文件路径、最终交付物路径]
## Style / Quality Bar
[代码约定，或文风、叙事、版式、视觉标准]
## Verification Strategy
[自动测试、事实核查、人工审查、版式检查、导出验证]
## Documentation Impact
[默认 `feature_only`。当公共 API / CLI / 启动方式 / 部署配置 / 跨 feature 设计约束 / 系统边界 / 监控安全规则变化时，升级为 `feature_plus_project` 或 `project_only`，并明确列出受影响的项目级文档路径。]
## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]
## Success Criteria
[如何判定"做完"——具体、可测试的条件]
`Done When` 是 goal 级完成定义；`Success Criteria` 是 spec 级验收标准。两者必须一致，不能出现 Done When 说完成但 Success Criteria 无法验证的情况。
## Risks and Mitigations
| 风险 | 概率 | 影响 | 应对方案 |
|------|------|------|---------|
| [风险] | [高/中/低] | [高/中/低] | [策略] |
## Open Questions
[需要用户输入的未解决问题]
当接收到模糊需求时，翻译成具体可测试的条件：
REQUIREMENT: "让仪表盘更快"
REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s（4G 网络）
- 初始数据加载 < 500ms
- 加载时无布局偏移（CLS < 0.1）
→ 这些目标对吗？
spec 写完 → 请用户审查 spec 文件 → 确认或修改 → 用户批准后才进入 plan。
| 失败场景 | 处理方式 |
|---|---|
| 用户拒绝 spec | 回到 define-workflow-refine Phase 1，获取澄清后重新写 spec。不修改已拒绝的 spec 直接推进。 |
| 用户要求大幅修改 | 直接在 spec 文件上修改，重走用户审查步骤。修改后仍需用户批准。 |
| 需求变更 | 更新 spec，不需要重新 refine。但变更涉及 Goal Alignment 时需重新做 Goal Review。 |
| spec 缺少 Success Criteria | 强制补充具体可测试的验收条件。抽象描述（如"更好""更快")不能替代量化标准。 |
project_truth_changed: yes 但缺少 affected_project_docs | 阻塞。必须显式写出要同步的项目级文档路径，不能写“之后补文档”。 |
| Goal Alignment 与 Success Criteria 冲突 | 标记为 Blocking，优先修正 Done When 或 Success Criteria 使其一致。 |
| 隐藏假设未被 Surface Assumptions 列出 | 回到 Step 1 补列假设。不带着未列出的假设进入 spec 编写。 |
输出或记录必须包含：
| 说辞 | 现实 | 后果 |
|---|---|---|
| "这个简单不需要 spec" | 简单任务不需要长 spec，但验收条件仍然需要。两行 spec 就够了。 | 无 spec 的简单任务平均遗漏 1-2 个验收条件，上线后以 bug 形式暴露。 |
| "写代码后再写 spec" | 那是文档，不是规范。spec 的价值在于在写代码前理清需求。 | 事后补写的 spec 会顺应已实现的行为而非需求，遗漏的边界情况被永久锁定。 |
| "spec 会拖慢我们" | 15 分钟 spec 防止数小时返工。15 分钟瀑布比 15 小时调试快。 | 跳过 spec 直接编码的典型返工 1-2 轮，每轮 4-8 小时，总耗时 > spec 流程的 10-20x。 |
project_truth_changed: yes 但没有 affected_project_docssoftware 处理docs/features/YYYYMMDD-<name>/01-spec.md用户: "让仪表盘更快"
Step 1 Surface Assumptions:
ASSUMPTIONS I'M MAKING:
1. 当前 LCP > 5s（需验证）
2. 用户主要在 4G 网络使用
3. 首屏数据来自 3 个 API
→ 现在纠正我
Step 3 转化:
REQUIREMENT: "让仪表盘更快"
REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s（4G 网络）
- 初始数据加载 < 500ms
- 加载时无布局偏移（CLS < 0.1）
→ 量化验收条件替代模糊描述，spec 可验证
用户: "让仪表盘更快"
（跳过 Surface Assumptions，跳过 Step 3 转化）
spec: "优化仪表盘性能，让页面更快"
→ 问题: 没有量化标准 → 无法验收 → "更快"无法判定是否完成
→ 问题: 没有列出假设 → 优化方向基于猜测而非数据 → 可能优化了不重要的瓶颈
→ 问题: Success Criteria 和 Done When 无法一致 → Goal Review 失败
### Spec 交付记录 — <feature-name>
**artifact_type**: [software / document / article / deck / visual]
**Goal Alignment**: [来源 / 状态 / 评分]
**Done When**: [具体可验证条件]
**Stop Conditions**: [具体阻断条件]
**Documentation Impact**: [doc_intent / project_truth_changed / affected_project_docs]
**核心区域覆盖**:
- Objective: ✓ / ✗
- Artifact Type: ✓ / ✗
- Goal Alignment: ✓ / ✗
- Documentation Impact: ✓ / ✗
- Commands / Tools: ✓ / ✗
- Project Structure: ✓ / ✗
- Style / Quality Bar: ✓ / ✗
- Verification Strategy: ✓ / ✗
- Boundaries: ✓ / ✗
**Surface Assumptions**: [已列出 / 未列出]
**用户批准**: [已批准 / 待批准]
结构化脑暴——发散探索 + 收敛评估。当想法模糊、面临开放性问题或需要方案对比，或提到"脑暴""想法""方案对比""怎么办"
恢复保存的工作上下文。当新 session 需要继续之前的工作，或提到"恢复""restore""继续上次"
保存工作上下文。当需要保存当前工作状态供后续 session 恢复，或提到"保存""save""checkpoint""挂起"
架构决策记录（ADR）。当面临技术选型、架构决策、方案取舍需要记录，或提到"ADR""决策记录""为什么这样做"
发布或导出检查 → Go/No-Go → 归档。当审查通过后需要上线或交付最终产物，或提到"发布""上线""ship""Go/No-Go"
合并 PR → 等待 CI → 验证生产。当 PR 已创建需要合并到主分支并验证部署，或提到"合并""merge""PR""land"