speckit-baseline

Spec Kit 基线技能

适用场景

• 你需要为现有代码或旧代码编写规格说明。
• 你想在重构前记录某项功能。
• 你接手了一个没有书面需求的代码库。

输入

• 一个目标路径、文件列表或 glob 模式，用于描述要分析的代码。
• 包含 .specify/ 脚本和模板的仓库上下文。

如果目标缺失或不明确，请先提出一个有针对性的问题，再继续。

目标

为现有代码生成一份与技术无关的规格说明，然后使用标准 Spec Kit 模板创建功能分支和规格文件。

工作流

1. 解析目标输入：确定要分析的文件、目录或模式。

   • 接受文件路径、glob 模式或目录路径。
   • 如果为空：停止并要求提供具体目标。

2. 发现并读取源文件：

   • 将 glob 模式展开为文件列表。
   • 读取文件内容进行分析。
   • 确定主要语言和框架。
   • 梳理关键文件之间的关系和依赖项。

3. 分析代码结构：

   • 确定入口点和公共接口。
   • 提取函数/方法签名及其行为。
   • 查找数据模型和实体。
   • 检测 API 端点和路由。
   • 确定面向用户的功能。

4. 生成简短名称（2-4 个词），根据分析出的代码确定：

   • 使用“动作-名词”格式（例如，“user-auth”、“payment-processing”）。
   • 以发现的主要功能为依据。
   • 有意义时保留技术术语。

5. 创建功能分支和规格文件：

   • 查找该简短名称对应的最大现有功能编号（分支/规格）。
   • 使用计算出的编号和简短名称运行 .specify/scripts/bash/create-new-feature.sh --json。
   • 从脚本的 JSON 输出中读取 BRANCH_NAME、FEATURE_DIR 和 SPEC_FILE 路径。
   • 对于像 "I'm Groot" 这样的参数中的单引号，请使用转义语法，例如 'I'''m Groot'（或在可行时使用双引号："I'm Groot"）。

6. 加载规格模板 .specify/templates/spec-template.md。

7. 使用模板结构起草规格说明：

   • 用户故事：从面向用户的代码路径和交互中推断。
   • 验收场景：根据验证逻辑、错误处理和测试推导。
   • 功能需求：从业务规则和约束中提取。
   • 关键实体：从数据模型和架构中识别。
   • 成功标准：从指标、日志或与性能相关的代码中推断。
   • 假设：记录分析过程中作出的推断。

8. 抽象实现细节：

   • 将技术模式转化为面向用户的需求。
   • 移除特定于框架的术语。
   • 关注代码做了什么，而不是如何实现。

9. 在 FEATURE_DIR/checklists/requirements.md 创建规格质量检查清单。

10. 报告完成情况，包括：

    • 分支名称和规格文件路径。
    • 已分析文件的摘要。
    • 发现的关键功能。
    • 需要澄清或审查的领域。

输出

• specs/<feature>/spec.md
• specs/<feature>/checklists/requirements.md

关键规则

• 专注于从“如何实现”中提取“做什么”和“为什么”。
• 在生成的规格说明中抽象掉实现细节。
• 记录代码分析过程中作出的假设。
• 标记代码行为不明确的领域。
• 保留发现的业务规则和约束。
• 对含糊不清的代码部分使用 [NEEDS CLARIFICATION]（最多 3 处）。
• 生成的规格说明应由了解该功能的人进行验证。

示例

代码模式 → 规范要求：

• if (user.role === 'admin') →“系统 MUST 将操作限制为管理员用户”
• password.length >= 8 →“密码 MUST 至少为 8 个字符”
• cache.set(key, value, 3600) →“系统 MUST 缓存结果以提升性能”
• try { ... } catch (e) { notify(e) } →“发生错误时，系统 MUST 通知用户”

代码模式 → 用户故事：

• 使用 OAuth 的登录端点 →“作为用户，我可以使用社交账号登录”
• 购物车逻辑 →“作为客户，我可以将商品加入购物车以便稍后购买”
• 报告生成 →“作为分析师，我可以生成系统活动报告”

后续步骤

生成 spec.md 后：

• 使用 speckit-clarify 与领域专家澄清需求。
• 使用 speckit-plan 规划现代化改造／重构。
• 将生成的规范与实际需求进行对比，找出差距。