Spec-Plan Workflow (Spec-driven)
输出物（强制）
- 仅一个文件：
docs/specs/spec{n}_<slug>.md - 仅一次提交：只提交该 spec（不生成 design、不额外 commit）
0) 建立仓库上下文（必须做）
在提问前先快速扫一遍（减少无效问题）：
- 目录：
README*,docs/,src/,packages/,configs/ - 是否已有
docs/specs/与命名规则/模版 git log -n 20 --oneline了解近期方向与约束- 基本约定：API 风格/配置方式/CI 门槛（知道“怎么跑”即可）
若无法访问仓库：明确说明“缺少仓库上下文”，请用户粘贴目录树/相关模块/现有接口示例；同时继续推进，使用
TBD标注不确定项。
提问规则（强制）
- 只问 关键 / 核心 / 有歧义 的问题（会影响实现路径、范围或接口）
- 分组提问方式：每轮最多问 3 个「最关键、最阻塞」的问题；用户回答后，模型必须先用 2–4 句复述：
- ✅ 已确认的信息
- ⚠️ 仍待明确（TBD）的关键点
- 在完成复述后，模型必须进行一次 关键歧义自检：
- 判断当前信息是否仍存在 会影响实现路径、范围或接口的关键不确定性
- 若 存在，进入下一轮继续追问（仍遵循每轮最多 3 个的问题限制）
- 若 不存在，立即停止提问并进入下一阶段
- 全程严格去重与合并相近问题，累计问题总数 不超过 10 个，确保聚焦而不发散
- 问题优先采用 多选形式，并提供
Other / 不确定
你必须优先搞清的点（从上往下问）
- 用户/场景：谁用？何时触发？现在怎么做？最大痛点？
- 成功标准：怎样算成功？验收口径是什么？
- 范围边界：必须做/不做/可选（YAGNI：可选放 Future Work）
- 输入输出：UI/API/CLI/配置/任务？对外契约是什么？
- 约束：兼容性/性能/权限/合规/依赖系统/上线窗口
- 风险：失败点、回滚要求、数据一致性要求
2) 方案收敛（必须给 2-3 个）
当信息够用时，给出 2-3 个方案，并明确推荐方案。 每个方案包含：
- 适用前提
- 优点
- 缺点/风险
- 复杂度（低/中/高）
- 影响模块/大概改动点
- Future Work（明确这次不做的）
推荐方案必须解释“为何在当前约束下最合适”，避免过度设计。
3) Spec 写作（可评审、可实施）
Spec 必须具备
- 可实现：模块改动点、接口契约、数据结构、边界条件
- 可验收：Acceptance Criteria（对齐 FR/NFR）
- 可发布：上线/迁移/回滚/兼容策略
- 不确定项：正文标
TBD，末尾Open Questions汇总
Spec 结构（精简版）
- Background（痛点与现状）
- Goals / Non-goals（防止范围膨胀）
- Use Cases（关键用户路径）
- Requirements（FR / NFR：最小必要）
- Proposed Solution（推荐方案 + 关键决策 + 备选方案简述）
- Architecture & Data Flow（流程/时序/边界）
- Interfaces / Data Model（如适用：API、事件、存储变更）
- Error Handling & Edge Cases（幂等/重试/降级/一致性）
- Rollout / Migration / Rollback（发布与回退）
- Work Breakdown（按顺序的任务拆解 + Done Definition）
- Testing Notes（关键用例与覆盖范围说明）
- Acceptance Criteria（Checklist）
- Open Questions（汇总 TBD）
- Future Work（可选）
4) 落盘规则（强制）
目录与编号
- 目录：
docs/specs/（不存在则创建） - 编号自增：
- 扫描
docs/specs/下匹配spec(\d+)_的文件 n = max_n + 1；若无则n = 1
- 扫描
文件名 slug（snake_case）
- 文件名：
spec{n}_<slug>.md - 规则：小写；空格/连字符→
_；去特殊字符；合并连续_ - 中文主题：优先简短英文/拼音；否则用语义清晰英文兜底
5) 唯一一次提交（强制）
完成并确认 spec 后：
git status --porcelain确认变更git add docs/specs/spec{n}_<slug>.mdgit commit -m "docs: add spec{n} <slug>"（若仓库有规范则遵循）
对话中必须返回：
- spec 文件路径
- Spec 标题 + 3-5 行摘要
- Top 3 Open Questions（如有）
结束语（必须）： “Spec 已生成并一次性提交。Ready to set up for implementation?”