spec-kit分析

是魔丸啊
590 阅读7分钟

commands

specify

description: 从自然语言功能描述中创建或更新功能规范。 scripts: sh: scripts/bash/create-new-feature.sh --json "{ARGS}" ps: scripts/powershell/create-new-feature.ps1 -Json "{ARGS}"

给定作为参数提供的功能描述，执行以下步骤：

  1. 从仓库根目录运行 {SCRIPT} 脚本，并解析其 JSON 输出中的 BRANCH_NAME 和 SPEC_FILE。所有文件路径必须是绝对路径。
  2. 加载 templates/spec-template.md 以理解所需的章节。
  3. 使用模板结构将规范写入 SPEC_FILE，在保持章节顺序和标题的同时，用从功能描述（参数）中提取的具体细节替换占位符。
  4. 报告完成情况，包括分支名称、规范文件路径，以及进入下一阶段的就绪状态。

注意：该脚本会创建并切换到新分支，并在写入前初始化规范文件。

plan

description: 使用 plan 模板执行实现规划工作流，以生成设计产物。

在给定实现细节作为参数的情况下，执行以下操作：

  1. 从仓库根目录运行 .specify/scripts/bash/setup-plan.sh --json，并解析 JSON，获取 FEATURE_SPEC、IMPL_PLAN、SPECS_DIR、BRANCH。所有后续的文件路径都必须使用绝对路径。

  2. 阅读并分析功能规格文档，以理解：

    • 功能需求和用户故事
    • 功能性和非功能性需求
    • 成功标准和验收标准
    • 任何提及的技术约束或依赖

  3. 阅读 .specify/memory/constitution.md 中的“宪法”，理解宪法性要求。

  4. 执行实现计划模板：

    • 加载 .specify/templates/plan-template.md（已复制到 IMPL_PLAN 路径）

    • 将输入路径设置为 FEATURE_SPEC

    • 运行执行流程（main）中的步骤 1–10

    • 模板是自包含且可执行的

    • 按照指定的错误处理和关卡检查执行

    • 让模板指导在 $SPECS_DIR 中生成工件：

      • Phase 0 生成 research.md
      • Phase 1 生成 data-model.md、contracts/、quickstart.md
      • Phase 2 生成 tasks.md

    • 将用户提供的参数细节纳入技术上下文：$ARGUMENTS

    • 在完成每个阶段时更新进度追踪（Progress Tracking）

  5. 验证执行是否完成：

    • 检查进度追踪是否显示所有阶段已完成
    • 确认所有必需的工件已生成
    • 确认执行过程中无 ERROR 状态

  6. 报告结果，包括分支名、文件路径和生成的工件。

使用仓库根目录的绝对路径进行所有文件操作，以避免路径问题。

tasks

description: 基于可用的设计文档，为该功能生成可执行的、按依赖顺序排列的 tasks.md。 scripts: sh: scripts/bash/check-task-prerequisites.sh --json ps: scripts/powershell/check-task-prerequisites.ps1 -Json

给定作为参数提供的上下文，执行以下步骤：

  1. 从仓库根目录运行 {SCRIPT} 脚本，并解析输出中的 FEATURE_DIR 和 AVAILABLE_DOCS 列表。所有路径必须是绝对路径。

  2. 加载并分析可用的设计文档：

    • 始终读取 plan.md 以了解技术栈和依赖库
    • 如果存在：读取 data-model.md 以获取实体信息
    • 如果存在：读取 contracts/ 以获取 API 接口定义
    • 如果存在：读取 research.md 以了解技术决策
    • 如果存在：读取 quickstart.md 以获取测试场景

    注意：并非所有项目都有全部文档。例如：

    • CLI 工具可能没有 contracts/
    • 简单的库可能不需要 data-model.md
    • 根据实际可用文档生成任务

  3. 按以下模板生成任务：

    • 使用 /templates/tasks-template.md 作为基础
    • 用实际任务替换示例任务，任务依据包括：
      • 初始化任务：项目初始化、依赖、代码规范检查
      • 测试任务 [P]：每个 contract 一个测试任务，每个集成场景一个测试任务
      • 核心任务：每个实体、服务、CLI 命令、接口一个任务
      • 集成任务：数据库连接、中间件、日志等
      • 完善任务 [P]：单元测试、性能优化、文档

  4. 任务生成规则：

    • 每个 contract 文件 → 一个 contract 测试任务（标记 [P]）
    • data-model 中的每个实体 → 一个模型创建任务（标记 [P]）
    • 每个接口 → 一个实现任务（若文件共享则不可并行）
    • 每个用户故事 → 一个集成测试任务（标记 [P]）
    • 不同文件 = 可并行 [P]
    • 相同文件 = 顺序执行（不标记 [P]）

  5. 按依赖顺序排列任务：

    • 初始化任务在最前
    • 测试优先于实现（TDD 原则）
    • 模型优先于服务
    • 服务优先于接口
    • 核心优先于集成
    • 所有任务优先于完善

  6. 包含并行执行示例：

    • 将可并行的 [P] 任务分组
    • 展示实际的 Task agent 命令

  7. 在 FEATURE_DIR/tasks.md 中生成内容：

    • 使用实现计划中的正确功能名称
    • 编号任务（T001, T002, 等）
    • 为每个任务标明清晰的文件路径
    • 添加依赖说明
    • 提供并行执行指导

任务生成上下文：{ARGS}

生成的 tasks.md 必须可以立即执行——每个任务都要足够具体，使 LLM 无需额外上下文即可完成。

产物

  • plan.md 是在 /plan 阶段生成的。

  • 流程顺序是：

    1. /specify → 写功能规格 spec.md（解决 What/Why）
    2. /plan → 生成实现计划 plan.md（解决 How）
    3. /tasks → 生成任务清单 tasks.md（解决 Who/When）

在 CLI 里，你会先跑 setup-plan.sh/ps1 --json，拿到路径（FEATURE_SPEC、IMPL_PLAN、SPECS_DIR、BRANCH），然后 Claude Code 根据模板填充 plan.md。

plan.md 的内容取决于 .specify/templates/plan-template.md，通常包括这些模块：

  1. Title / Metadata

    • Feature 名称、ID
    • 作者、日期、版本

  2. Technical Context

    • 引用 spec.md 中的需求
    • 合并用户提供的参数（$ARGUMENTS，比如技术栈、运行环境）

  3. Architecture & Design

    • 系统架构图（组件、服务、接口）
    • 流程图 / 时序图（数据流、调用链）
    • 部署拓扑（本地 / 云 / VPC）

  4. Implementation Phases

    • Phase 0：调研，生成 research.md
    • Phase 1：核心设计，生成 data-model.md、contracts/、quickstart.md
    • Phase 2：任务拆解，生成 tasks.md

  5. Data Model & Contracts 概述

    • 要有哪些实体（再细化到 data-model.md）
    • API / 事件接口的框架（再细化到 contracts/）

  6. Acceptance Gates / Milestones

    • 每个阶段的“完成”定义（Gate checks）
    • 验收条件：必须哪些工件齐全、测试通过

  7. Risk & Mitigation

    • 潜在风险（技术/依赖/性能/安全）
    • 应对策略

  8. Open Questions

    • 未决问题，需要进一步确认的事项

  9. Progress Tracking

    • 每个 Phase 的完成状态（Started / Done / Error）
    • 便于自动化工具或人工勾选

  • plan.md 在 /plan 阶段生成

  • 它的定位是 承上启下：

    • 上承 spec.md（业务需求）
    • 下启 research.md / data-model.md / contracts / tasks.md（技术落地）

  • 本质上是“实施蓝图”，保证团队对 怎么实现 达成共识。

🔎 Phase 0 → research.md

作用：前置调研文档，帮助团队在定方案前统一信息和决策依据。
典型模块：

  • Problem framing：要解决的问题、背景。
  • Prior art / References：相关产品或开源项目、论文、业界实践。
  • Option A / B / C：候选方案、技术路线。
  • Pros / Cons：每个方案的优势、劣势、风险点。
  • Decision rationale：最终选型理由（性能、成本、生态、合规、团队技能）。
  • Open questions：仍需验证或后续澄清的问题。

🔎 Phase 1 → 技术设计与契约工件

这一阶段会生成 3 类文件，聚焦于**“How” 的设计层**。

1) data-model.md

作用：系统中要用到的核心实体和数据结构。
典型模块：

  • Entity definitions（用户、订单、任务等）
  • Attributes（字段、类型、约束、默认值）
  • Relationships（一对多、多对多、继承等）
  • Persistence strategy（存储表设计、索引、分片）
  • Example payloads（JSON 示例、SQL schema）

2) contracts/ 目录

作用：对外或模块间的契约（接口、事件、配置）。
典型模块：

  • api-spec.yaml/json（OpenAPI / gRPC IDL）
  • event-spec.md（消息/事件格式）
  • config-schema.json（配置项约定）
  • Versioning & Compatibility（如何保证升级兼容、Deprecation 规则）

3) quickstart.md

作用：开发者上手指南，保证“拉代码 → 能跑”。
典型模块：

  • Prerequisites（环境依赖：语言版本、依赖库、Docker）
  • Setup steps（克隆、安装依赖、环境变量配置）
  • Run locally（启动命令、URL、端口）
  • Run tests（测试命令）
  • Common issues（已知坑点与解决方法）

🔎 Phase 2 → tasks.md

作用：把计划拆分成最小可执行任务，变成开发 backlog。
典型模块：

  • Task list（逐条列出）

    • ID：任务号（T1, T2...）
    • Goal：要实现什么
    • Files impacted：预计修改或新增的文件
    • Acceptance criteria：完成的标准（可运行/通过测试/能演示）
    • Estimated effort：预估工时
    • Branch naming：推荐的分支名（如 feature/auth-login）

  • Milestones（里程碑/交付节奏）

  • Dependencies（任务间依赖关系）

  • Rollback strategy（失败时如何回退）

  • research.md → 为什么这样做（调研/选型依据）

  • data-model.md / contracts/ → 做什么 & 怎么设计（实体、接口、协议）

  • quickstart.md → 怎么跑起来（开发/测试环境指南）

  • tasks.md → 谁来做、先后顺序、完成标准

avatar
文章
阅读
粉丝