spec-kit 到底干了啥

最近有一些计划使用 spec 模式来澄清需求内容，进一步提升下游 AI Coding 任务的准确率。

github.com/github/spec...

背景

让 AI 基于规范驱动开发（Spec-Driven Development），先定义好软件研发规约、业务逻辑，减少一上来就开始写代码导致的各种问题。

spec-kit 的设计架构是需要与 AI Coding 工具（GitHub Copilot, Claude Code, Gemini CLI,Cursor,Qwen Code..）集成才能工作

安装套件

Plain 复制代码

# 安装工具
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 初始项目
specify init .

注意：安装好后，会根据你选择的 AI Coding 工具初始化项目环境，我这里用了 Claude Code，所以会在 .claude 目录添加好 commands，以及 .specify 常用的工具包

流程概览

按照 spec-kit 推荐 steps 和增强命令我们可以梳理下工作流（8 个节点，5 个必须，3 个可选增强）

过程	命令	功能	过程 & 产物
制定原则	/speckit.constitution	建立项目原则根据互动输入或提供的原则，创建或更新项目章程	读取当前项目信息 + memory/constitution.md 内容，进行修改 Input：项目仓库文件内容 Output：constitution.md
指定研发规格	/speckit.specify	制定基础规格说明根据自然语言的功能描述来创建或更新功能规范。	调用 shell 脚本 create-new-feature.sh 结合.specify/templates/spec-template.md和用户需求生成001-ai-interface-wrapper/spec.md Input：.specify/templates/spec-template.md, User Query Output：specs/xxx/spec.md
指定研发规格	/speckit.clarify【可选】	【可选】消除模糊风险通过最多 5 个有针对性的澄清问题，找出当前功能说明里不够明确的地方，并把得到的答案写回到说明里。	结合用户的 Query 和现有的 spec.md 进行需求澄清 Input：specs/xxx/spec.md, User Query Output: Updatespecs/xxx/spec.md
制定计划表	/speckit.plan	制定实施计划按照计划模板来做实施规划，并产出设计文件	结合项目 constitution.md 和 specs/xxx/spec.md 生成多个子文档内容 Input：constitution.md, specs/xxx/spec.md Output： plan.md, data-model.md, quickstart.md, research.md
制定计划表	/speckit.checkList【可选】	【可选】检查完整性、一致性根据用户需求（项目）为当前功能生成一个自定义检查清单。	根据 spec.md 进行 checklist 内容生成 Output：checklists/requirements.md
制定任务表	/speckit.tasks	生成任务列表根据现有的设计资料，为这个功能生成一个可执行的、按依赖顺序排列的 tasks.md 文件。	读取前面任务生成的多个文件，进行 Tasks 任务生成 Input：plan.md, data-model.md, quickstart.md, research.md, spec.md Output：tasks.md
制定任务表	/speckit.analyze【可选】	【可选】分析跨文档一致性在生成任务后，对 spec.md、plan.md 和 tasks.md 之间进行一次不破坏内容的跨文件一致性和质量分析。	做完前置校验后，进行全局规约 + 局部功能方案进行分析 Output：文本校验报告
实施计划	/speckit.implement	按照 tasks.md（项目）里定义的任务，处理并执行实现计划。	实现，按照前面的文档内容进行理解，完成 Coding 工作 Input： tasks.md，plan.md，data-model.md，quickstart.md，research.md ，spec.md

细节记录

/speckit.constitution

读项目去生成项目 constitution.md 输入：/speckit.constitution 过程：读取项目信息 + memory/constitution.md 内容，进行修改

Plain 复制代码

⏺ Read(.specify/memory/constitution.md)
  ⎿  Read 51 lines

⏺ Update(.specify/memory/constitution.md)

输出：constitution.md

/speckit.specify

进行需求描述，生成对应功能规范输入：/speckit.specify is running... 使用 ai.generateText 封装一个接口文件出来 过程：可以看到调用了 shell 脚本 create-new-feature.sh 生成 001-ai-interface-wrapper/spec.md 文件

create-new-feature.sh：根据功能描述自动生成一个标准化的 Git 分支名，并创建对应的规格说明文件（spec）目录

Plain 复制代码

⏺ Bash(.specify/scripts/bash/create-new-feature.sh --json "使用 ai.generateText 封装一个接口文件出来"
      --number 1 --short-name "ai-interface-wrapper")
  ⎿ {
      "BRANCH_NAME": "001-ai-interface-wrapper",
      "SPEC_FILE": "/Users/workspace/test/specs/001-ai-interface-wrapper/spec.md"
    ... +4 lines (ctrl+o to expand)


⏺ Read(.specify/templates/spec-template.md)
  ⎿  Read 116 lines
  
  
⏺ Read(specs/001-ai-interface-wrapper/spec.md)
  ⎿  Read 116 lines

⏺ Write(specs/001-ai-interface-wrapper/spec.md)
  ⎿  Updated specs/001-ai-interface-wrapper/spec.md with 29 additions and 88 removals

输出：001-ai-interface-wrapper/spec.md

Plain 复制代码

⏺ The specification for the "AI Interface Wrapper" feature has been successfully created and
  validated.

  Branch Name: 001-ai-interface-wrapper
  Specification File: /Users/workspace/test/specs/001-ai-interface-wrapper/spec.md
  Checklist Results: All items passed.

  The feature is now ready for the next phase, which can be further clarification using
  /speckit.clarify or planning with /speckit.plan.

/speckit.clarify

澄清下需求内容输入：/speckit.clarify 过程：调用 check-prerequisites.sh 脚本，进行预检测

check-prerequisites.sh: 前置条件检查脚本，用于在 Spec‑Driven Development（规范驱动开发）的工作流中，统一检测当前功能分支是否满足继续执行某些步骤的必要条件

TypeScript 复制代码

⏺ Bash(.specify/scripts/bash/check-prerequisites.sh --json --paths-only)
  ⎿  {
       "REPO_ROOT": "/Users/workspace/test",
       "BRANCH": "001-ai-interface-wrapper",
     ... +7 lines (ctrl+o to expand)

⏺ Read(specs/001-ai-interface-wrapper/spec.md)
  ⎿  Read 57 lines

⏺ User answered Claude's questions:
  ⎿  · What types of natural language descriptions or interface complexities are explicitly out of
     scope for the initial version of this feature? → Very complex data structures

⏺ Update(specs/001-ai-interface-wrapper/spec.md)
  ⎿  Error editing file

⏺ Read(specs/001-ai-interface-wrapper/spec.md)
  ⎿  Read 57 lines

⏺ Update(specs/001-ai-interface-wrapper/spec.md)
  ⎿  Updated specs/001-ai-interface-wrapper/spec.md with 6 additions and 1 removal

spec.md 部分文件内容 Q&A 补充

SQL 复制代码

### Session 2025-12-08
- Q: What types of natural language descriptions or interface complexities are explicitly out of scope for the initial version of this feature? → A: More than 5 nested levels, recursive types, or extensive conditional types.
- Q: What is the behavior if the AI model fails to generate a valid interface or returns an error? → A: Return a specific error message indicating AI generation failure or invalid output format.
- Q: How does the system handle descriptions that are not in English (e.g., Chinese in the user prompt)? → A: The AI model is expected to understand and process natural language descriptions in multiple specified languages (e.g., English, Chinese).

输出：澄清后的

/speckit.plan

输入：/speckit.plan 过程：调用 setup-plan.sh 脚本，进行预检测

setup-plan.sh: 根据当前 Git 分支和项目目录结构，创建一个对应功能的实现计划文件（可能还有相关的功能规范文件），并可选择输出信息为 JSON 格式或普通文本。

Plain 复制代码

⏺ Bash(.specify/scripts/bash/setup-plan.sh --json)
  ⎿ Copied plan template to /Users/workspace/test/specs/001-ai-interface-wrapper/
    plan.md
    {
    ... +8 lines (ctrl+o to expand)


⏺ Read(specs/001-ai-interface-wrapper/spec.md)
  ⎿  Read 64 lines

⏺ Read(.specify/memory/constitution.md)
  ⎿  Read 62 lines

⏺ Read(specs/001-ai-interface-wrapper/plan.md)

输出：plan.md，data-model.md，quickstart.md，research.md 暂时无法在飞书文档外展示此内容暂时无法在飞书文档外展示此内容暂时无法在飞书文档外展示此内容暂时无法在飞书文档外展示此内容

/speckit.checkList

过程：根据 spec.md 进行 checklist 内容生成产物：checklists/requirements.md 暂时无法在飞书文档外展示此内容

/speckit.tasks

过程：可以看到读取了前置所有生成的内容文件，进行 tasks.md 文件的编写

Bash 复制代码

⏺ Bash(.specify/scripts/bash/check-prerequisites.sh --json)
  ⎿  {
       "FEATURE_DIR": "/Users/workspace/test/specs/001-ai-interface-wrapper",
       "AVAILABLE_DOCS": [
     ... +5 lines (ctrl+o to expand)

⏺ Read(specs/001-ai-interface-wrapper/spec.md)
  ⎿  Read 64 lines

⏺ Read(specs/001-ai-interface-wrapper/plan.md)
  ⎿  Read 83 lines

⏺ Read(specs/001-ai-interface-wrapper/research.md)
  ⎿  Read 16 lines

⏺ Read(specs/001-ai-interface-wrapper/data-model.md)
  ⎿  Read 24 lines

⏺ Read(specs/001-ai-interface-wrapper/quickstart.md)
  ⎿  Read 59 lines

⏺ Write(specs/001-ai-interface-wrapper/tasks.md)
  ⎿  Wrote 69 lines to specs/001-ai-interface-wrapper/tasks.md

输出：tasks.md 可以看到产物都是 TODO List 暂时无法在飞书文档外展示此内容

/speckit.analyze

过程：做完前置校验后，进行全局规约 + 局部功能方案进行分析

Bash 复制代码

⏺ Bash(.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks)
  ⎿  {
       "FEATURE_DIR": "/Users/workspace/test/specs/001-ai-interface-wrapper",
       "AVAILABLE_DOCS": [
     ... +6 lines (ctrl+o to expand)

⏺ Read(specs/001-ai-interface-wrapper/spec.md)
  ⎿  Read 64 lines

⏺ Read(specs/001-ai-interface-wrapper/plan.md)
  ⎿  Read 83 lines

⏺ Read(specs/001-ai-interface-wrapper/tasks.md)
  ⎿  Read 69 lines

⏺ Read(.specify/memory/constitution.md)
  ⎿  Read 62 lines

输出：报告内容，也可以让 AI 进行内容优化

Plain 复制代码

  Metrics:
  - Total Requirements: 10
  - Total Tasks: 20
  - Coverage % (requirements with >=1 task): 60% (if counting only FRs as fully covered, SCs as
  partial/none)
  - Ambiguity Count: 1
  - Duplication Count: 0
  - Critical Issues Count: 1

/speckit.implement

过程

Bash 复制代码

⏺ Bash(.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks)
  ⎿  {
       "FEATURE_DIR": "/Users/workspace/test/specs/001-ai-interface-wrapper",
       "AVAILABLE_DOCS": [
     ... +6 lines (ctrl+o to expand)

⏺ Read(specs/001-ai-interface-wrapper/tasks.md)
  ⎿  Read 69 lines

⏺ Read(specs/001-ai-interface-wrapper/plan.md)
  ⎿  Read 83 lines

⏺ Read(specs/001-ai-interface-wrapper/spec.md)
  ⎿  Read 64 lines

⏺ Read(specs/001-ai-interface-wrapper/research.md)
  ⎿  Read 16 lines

⏺ Read(specs/001-ai-interface-wrapper/data-model.md)
  ⎿  Read 24 lines

⏺ Read(specs/001-ai-interface-wrapper/quickstart.md)
  ⎿  Read 59 lines

启发

最快的形式直接在项目中使用 spec-kit，但是横向的流程

从整体流程来看 spec-kit 完成了从整体规约生成、更新，研发规范、澄清、计划编写、任务生成、校验一致性几个步骤，把一个需求变得更明确更有指导意义。

通过 sh 工具的调用可以极大的提升确定性的事情发生，避免模型猜测
废话有点多，执行一个需求，至少要 5 步，可以参考 openspec 的三步走
过程产物有点多

Plain 复制代码

├── specs
|  └── 001-ai-interface-wrapper
|     ├── checklists
|     |  └── requirements.md
|     ├── data-model.md
|     ├── plan.md
|     ├── quickstart.md
|     ├── research.md
|     ├── spec.md
|     └── tasks.md

附

请求 api.github.com/repos/githu... 获取模板信息。文件结构如下

Plain 复制代码

./spec-kit-template-auggie-ps-v0.0.69
├── .augment
|  └── commands
|     ├── speckit.analyze.md
|     ├── speckit.checklist.md
|     ├── speckit.clarify.md
|     ├── speckit.constitution.md
|     ├── speckit.implement.md
|     ├── speckit.plan.md
|     ├── speckit.specify.md
|     └── speckit.tasks.md
└── .specify
   ├── memory
   |  └── constitution.md
   ├── scripts
   |  └── powershell
   |     ├── check-prerequisites.ps1
   |     ├── common.ps1
   |     ├── create-new-feature.ps1
   |     ├── setup-plan.ps1
   |     └── update-agent-context.ps1
   └── templates
      ├── agent-file-template.md
      ├── checklist-template.md
      ├── plan-template.md
      ├── spec-template.md
      └── tasks-template.md