规格驱动工作流：模板如何指导 AI 智能体

Spec Kit 真正的创新之处不在于 Python CLI，而在于 CLI 生成的那些 Markdown 文件。这 9 个命令模板是专门写给 AI 智能体的结构化指令。它们通过 YAML frontmatter 将完整的开发工作流编码为有向无环图（DAG），嵌入 shell 脚本调用来处理 AI 无法独立完成的文件系统操作，并设置钩子检查点供扩展注入额外行为。AI 智能体既是这些文档的读者，也是执行者。本文将带你深入了解这些文件的内部构造。

9 个斜杠命令与工作流 DAG

templates/commands/ 目录下共有 9 个 Markdown 文件，每个文件对应一个斜杠命令：

命令	用途	移交至
specify	根据描述创建功能规格	plan, clarify
plan	生成技术实现计划	tasks, checklist
tasks	将计划拆解为有序任务列表	analyze, implement
implement	执行任务列表中的任务	—
clarify	对模糊需求进行结构化澄清	—
analyze	跨制品一致性分析	—
constitution	创建或更新项目治理原则	—
checklist	生成质量验证检查清单	—
taskstoissues	将 tasks.md 转换为 GitHub Issues	—

YAML frontmatter 中的 handoffs 字段构建了一张 DAG：

flowchart TD
    specify["speckit.specify"] -->|"Build Technical Plan"| plan["speckit.plan"]
    specify -->|"Clarify Requirements"| clarify["speckit.clarify"]
    plan -->|"Create Tasks"| tasks["speckit.tasks"]
    plan -->|"Create Checklist"| checklist["speckit.checklist"]
    tasks -->|"Analyze Consistency"| analyze["speckit.analyze"]
    tasks -->|"Implement"| implement["speckit.implement"]

    constitution["speckit.constitution"]
    taskstoissues["speckit.taskstoissues"]

handoffs 不只是文档说明，它们是元数据。部分 AI 助手会将其渲染为可操作的按钮或建议。以 templates/commands/specify.md 中的 frontmatter 为例：

handoffs:
  - label: Build Technical Plan
    agent: speckit.plan
    prompt: Create a plan for the spec. I am building with...
  - label: Clarify Spec Requirements
    agent: speckit.clarify
    prompt: Clarify specification requirements
    send: true

send: true 字段表示该移交应自动触发，无需等待用户确认。这样一来，完成规格编写后可以直接进入规划阶段，流程自然流畅。

命令模板的结构解析

所有命令模板遵循相同的结构。下面以 templates/commands/plan.md 为例逐一说明：

flowchart TD
    subgraph "YAML Frontmatter"
        A["description: one-line summary"]
        B["handoffs: next-step commands"]
        C["scripts:<br/>  sh: scripts/bash/setup-plan.sh --json<br/>  ps: scripts/powershell/setup-plan.ps1 -Json"]
        D["agent_scripts:<br/>  sh: scripts/bash/update-agent-context.sh __AGENT__"]
    end
    subgraph "Body"
        E["## User Input<br/>{ARGS} placeholder"]
        F["## Pre-Execution Checks<br/>Hook system checkpoint"]
        G["## Outline<br/>Step-by-step instructions for the AI"]
        H["## Guidelines<br/>Quality constraints"]
    end
    A --> E
    C --> E

三种占位符各有其用途：

• {SCRIPT} — 替换为 scripts.<type> 中的 shell 命令，供 AI 执行文件系统初始化操作
• {ARGS} — 替换为各智能体对应的参数占位符（大多数用 $ARGUMENTS，Gemini 用 {{args}}）
• __AGENT__ — 替换为当前智能体名称，用于需要感知活跃智能体的脚本

正如第 3 篇所述，process_template() 流水线在初始化阶段会解析上述三种占位符，并从 frontmatter 中移除 scripts: 和 agent_scripts: 块，确保最终输出整洁干净。

Shell 脚本：操作层的核心

AI 智能体能够读取文件、编写代码，但无法可靠地执行"扫描现有规格目录并确定下一个序号"这类结构化文件系统操作。这正是 shell 脚本存在的意义。

scripts/bash/create-new-feature.sh 是其中最关键的一个——它由 before_specify 钩子（通过 git 扩展）调用，用于创建带有序号的功能分支。它支持 --json 参数，输出机器可解析的结果：

JSON_MODE=false
# ... argument parsing ...
if [ "$JSON_MODE" = true ]; then
    echo "{\"BRANCH_NAME\":\"$BRANCH_NAME\",\"FEATURE_NUM\":\"$FEATURE_NUM\"}"
fi

--json 参数是所有脚本中反复出现的模式。命令模板会指示 AI 执行脚本、解析 JSON 输出，并将结果用于后续步骤。例如，check-prerequisites.sh 的输出如下：

{"FEATURE_DIR": "specs/003-user-auth", "AVAILABLE_DOCS": ["spec.md", "plan.md"]}

sequenceDiagram
    participant AI as AI Agent
    participant CMD as Command Template
    participant SH as Shell Script

    AI->>CMD: Read /speckit.tasks
    CMD->>AI: "Run: .specify/scripts/bash/check-prerequisites.sh --json"
    AI->>SH: Execute script
    SH->>AI: {"FEATURE_DIR": "...", "AVAILABLE_DOCS": [...]}
    AI->>AI: Parse JSON, locate spec artifacts
    AI->>AI: Generate tasks.md

所有脚本都同时提供 bash/ 和 powershell/ 两个版本。specify init 时通过 --script 参数决定将哪个版本安装到 .specify/scripts/。跨平台支持做到了彻底——每个 .sh 脚本都有行为完全一致的 .ps1 对应版本。

提示： --json 输出模式是将 AI 智能体与 shell 脚本结合使用的关键洞察。人类可读的输出便于调试，但 JSON 输出能让 AI 可靠地提取结构化数据，无需依赖正则解析。如果你正在构建类似的 AI 智能体工具，务必提供机器可解析的输出模式。

钩子系统：每个命令中的扩展点

每个命令模板都包含两个钩子检查点——一个在执行前，一个在执行后。以下是 specify.md 中的执行前检查：

## Pre-Execution Checks

**Check for extension hooks (before specification)**:
- Check if `.specify/extensions.yml` exists in the project root.
- If it exists, read it and look for entries under the `hooks.before_specify` key
- Filter out hooks where `enabled` is explicitly `false`
- For each executable hook, output based on its `optional` flag:
  - **Optional hook**: Present to user with prompt
  - **Mandatory hook**: Execute immediately via `EXECUTE_COMMAND: {command}`

这是一套以 AI 智能体为运行时的声明式插件系统。模板告诉 AI："读取这个 YAML 文件，检查钩子，执行强制钩子，建议可选钩子。"实际的钩子逻辑定义在扩展清单中（如 git 扩展），并在安装扩展时合并到 .specify/extensions.yml。

flowchart TD
    A["AI reads command template"] --> B{"extensions.yml exists?"}
    B -->|No| C["Skip hooks silently"]
    B -->|Yes| D["Parse hooks.before_{stage}"]
    D --> E{"Hook optional?"}
    E -->|Yes| F["Present to user:<br/>'Run /speckit.git.commit?'"]
    E -->|No| G["Execute immediately:<br/>EXECUTE_COMMAND: speckit.git.feature"]
    F --> H["User decides"]
    G --> I["Wait for result"]
    H --> J["Continue to main logic"]
    I --> J

钩子系统将在第 5 篇中详细介绍。这里需要关注的是：每个命令模板都包含 before_ 和 after_ 两个检查点，9 个命令共计 18 个潜在钩子点。git 扩展一项就使用了全部 18 个。

文档模板：约束 AI 输出的结构框架

除命令模板外，Spec Kit 还提供了文档模板，用于约束 AI 智能体的输出结构。templates/spec-template.md 是其中最重要的一个，它定义了功能规格的结构：

# Feature Specification: [FEATURE NAME]

## User Scenarios & Testing *(mandatory)*

<!--
  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
  Each user story/journey must be INDEPENDENTLY TESTABLE
-->

### User Story 1 - [Brief Title] (Priority: P1)

该模板对 AI 施加了多项约束：

1. 用户故事优先级排序 — 每个故事标注 P1/P2/P3 优先级，避免生成"一切都同等重要"的扁平列表
2. [NEEDS CLARIFICATION] 标记 — 命令模板将其数量上限设为 3，迫使 AI 主动给出合理的默认值，而不是提出数十个问题
3. 与技术无关的成功标准 — 例如"用户能在 3 分钟内完成结账"，而非"API 响应时间低于 200ms"
4. 必填与选填章节 — 部分章节必须填写，其余章节若不适用应直接删除，而非填写"N/A"

templates/plan-template.md 包含引用治理原则的"Phase -1 门控"：

## Constitution Check

Language/Version: [e.g., Python 3.11]
Primary Dependencies: [e.g., FastAPI]

而 templates/constitution-template.md 则定义了治理框架的骨架——包括 Library-First、CLI Interface Mandate、Test-First Imperative 等核心原则，这些原则对所有生成的实现计划起到约束作用。

这些模板本质上是规模化的 prompt 工程。与其为每次交互精心设计提示词，不如将结构性约束直接嵌入模板，从而引导 AI 产出更高质量的结果，且这一效果与底层模型无关。正如 spec-driven.md 理念文档所言：这些模板"将 LLM 从一个自由创作者，转变为一名严谨的规格工程师。"

下一步

命令与模板定义了 AI 做什么。但如何新增命令？生命周期钩子又是如何接入工作流的？第 5 篇将深入介绍 Spec Kit 的两种可扩展机制：扩展（自定义命令 + 钩子）与预设（模板覆盖），并详细拆解内置 git 扩展与多目录发现系统的实现原理。