speckit-baseline

来源说明：本技能产出的规格结构沿用 GitHub Spec Kit 的模板约定（MIT License, Copyright GitHub, Inc.，完整文本见同目录 LICENSE.txt）。 "从现有代码反向提取需求"的执行流程为本项目原创，不属于 Spec Kit 官方命令集。

When to Use

• 代码库缺少需求文档，需要补齐一份可信的规格。
• 重构、迁移或交接之前，要先把现有实际行为固化成可审阅的基线。
• 接手无文档的遗留系统，需要区分"当前行为"与"应有行为"。

Inputs

• 目标范围：路径、文件清单、模块名或 glob 模式。
• 代码库上下文：需要能读取源码；若存在 .specify/ 目录，一并读取其中的模板与脚本。
• 可选业务背景：领域术语、用户角色、外部依赖方。

如果目标范围缺失或有歧义，先提出一个聚焦的问题再继续。

Workflow

Step 1 — 界定范围

确认要分析的最小完整单元：一个模块、一组接口，或一条端到端流程。 范围过大会产出泛泛而谈的规格；范围过小则无法形成完整需求。

Step 2 — 提取可观察行为

从代码中收集事实，逐项记录证据位置（文件与行号）：

• 入口点：HTTP 路由、CLI 参数、事件消费者、公开 API。
• 输入与校验：接受的字段、类型、约束、默认值。
• 输出与副作用：响应结构、写入的存储、发出的事件、外部调用。
• 错误路径：抛出的异常、返回的错误码、重试与降级逻辑。
• 状态与生命周期：持久化模型、状态机、并发假设。

只记录代码中可观察到的行为。不要根据命名或注释推测设计意图。

Step 3 — 归纳为需求

把散落的行为事实聚合成"用户/系统能做什么"的陈述：

• 每个需求必须可测试——给定输入，能判断是否满足。
• 保留现有行为中有意设计与历史包袱的区别：拿不准的归入假设或待澄清，不要替代码作者辩解。
• 发现的缺口（如未处理的边界情况）单独列出，不要直接写成需求。

Step 4 — 按 Spec Kit 结构产出 spec.md

写入 specs/<feature>/spec.md，章节结构沿用 Spec Kit 约定（见下节）。 若 .specify/templates/spec-template.md 存在，以它为准。

Step 5 — 标注不确定项与假设

• 最多保留 3 个 [NEEDS CLARIFICATION] 标记，只用于影响范围、安全或用户体验的关键分歧。
• 其余不确定处写入 Assumptions 章节，记录采用的合理默认值。

规格结构（沿用 Spec Kit 约定）

• Mandatory sections：每个功能都必须完成。
• Optional sections：仅在相关时纳入。
• 某章节不适用时整节删除，不要留 "N/A"。

质量要求（与 Spec Kit 一致）：

1. 优先用上下文和行业惯例填补空白，而不是提问。
2. 把采用的默认值记入 Assumptions 章节。
3. 澄清问题按优先级排序：范围 > 安全/隐私 > 用户体验 > 技术细节。
4. 用测试者视角审视：含糊的需求应当无法通过"可测试且无歧义"检查。

成功标准（Success Criteria）

成功标准必须满足：

1. 可度量 —— 含具体指标（时间、百分比、数量、比率）。
2. 与技术无关 —— 不提及框架、语言、数据库或工具。
3. 以用户为中心 —— 描述用户/业务视角的结果，而非系统内部结构。
4. 可验证 —— 无需了解实现细节即可检验。

示例（好）："用户可在 3 分钟内完成结账"、"95% 的搜索在 1 秒内返回结果"。 示例（差）："API 响应时间低于 200ms"、"Redis 缓存命中率高于 80%"。

Outputs

• specs/<feature>/spec.md —— 反向生成的基线规格。
• 若发现实现缺口：在汇报中单列"与现有实现的差异"，不写入规格正文。

Guardrails

• 不臆测意图：代码没做的事，不写成需求。
• 区分基线与目标：本技能产出的是"当前行为基线"，不是"期望状态"。
• 证据可追溯：每条需求应能回溯到具体代码位置。
• 不修改代码：这是只读分析流程，产出物只有规格文档。