Back to Details

speckit-plan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spec Kit Plan Skill

Spec Kit Plan Skill

When to Use

使用场景

  • The feature spec is ready and you need a technical implementation plan.
  • 功能规格说明书已准备就绪，需要制定技术实施计划时。

Inputs

输入项

  • specs/<feature>/spec.md
  • Repo context and 
    .specify/
    templates
  • User-provided constraints or tech preferences (if any)
If the spec is missing, ask the user to run speckit-specify first.
  • specs/<feature>/spec.md
  • 代码仓库上下文以及
    .specify/
    模板
  • 用户提供的约束条件或技术偏好（如有）
如果缺少规格说明书，请先让用户运行speckit-specify命令。

Workflow

工作流

  1. Setup: Run 
    .specify/scripts/bash/setup-plan.sh --json
    from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").
  2. Load context: Read FEATURE_SPEC and 
    .specify/memory/constitution.md
    . Load IMPL_PLAN template (already copied).
  3. Execute plan workflow: Follow the structure in IMPL_PLAN template to:
    • Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
    • Fill Constitution Check section from constitution
    • Evaluate gates (ERROR if violations unjustified)
    • Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
    • Phase 1: Generate data-model.md, contracts/, quickstart.md
    • Phase 1: Update agent context by running the agent script
    • Re-evaluate Constitution Check post-design
  4. Stop and report: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
  1. 环境准备：从代码仓库根目录运行
    .specify/scripts/bash/setup-plan.sh --json
    ，并解析JSON获取FEATURE_SPEC、IMPL_PLAN、SPECS_DIR、BRANCH参数。对于参数中的单引号（例如"I'm Groot"），请使用转义语法：比如'I'''m Groot'（或尽可能使用双引号："I'm Groot"）。
  2. 加载上下文：读取FEATURE_SPEC和
    .specify/memory/constitution.md
    文件，加载已复制的IMPL_PLAN模板。
  3. 执行规划工作流：按照IMPL_PLAN模板的结构执行以下操作：
    • 填写技术上下文（将未知内容标记为"NEEDS CLARIFICATION"）
    • 依据constitution.md填写合规性检查部分
    • 评估准入条件（若违规且无合理解释则触发ERROR）
    • 阶段0：生成research.md文件（解决所有NEEDS CLARIFICATION项）
    • 阶段1：生成data-model.md、contracts/目录下文件以及quickstart.md
    • 阶段1：运行agent脚本更新Agent上下文
    • 设计完成后重新评估合规性检查
  4. 停止并报告：命令在完成阶段2规划后结束。报告分支信息、IMPL_PLAN路径以及生成的产物。

Phases

阶段详情

Phase 0: Outline & Research

阶段0：大纲与调研

  1. Extract unknowns from Technical Context above:
    • For each NEEDS CLARIFICATION → research task
    • For each dependency → best practices task
    • For each integration → patterns task
  2. Generate and dispatch research agents:
    text
    For each unknown in Technical Context:
  Task: "Research {unknown} for {feature context}"
For each technology choice:
  Task: "Find best practices for {tech} in {domain}"
  3. Consolidate findings in 
    research.md
    using format:
    • Decision: [what was chosen]
    • Rationale: [why chosen]
    • Alternatives considered: [what else evaluated]
Output: research.md with all NEEDS CLARIFICATION resolved
  1. 从技术上下文中提取未知项：
    • 每个NEEDS CLARIFICATION项对应一个调研任务
    • 每个依赖项对应一个最佳实践调研任务
    • 每个集成项对应一个模式调研任务
  2. 生成并分派调研Agent：
    text
    For each unknown in Technical Context:
  Task: "Research {unknown} for {feature context}"
For each technology choice:
  Task: "Find best practices for {tech} in {domain}"
  3. 将调研结果整理到
    research.md
    文件中    ，格式如下：
    • 决策：[所选方案]
    • 理由：[选择该方案的原因]
    • 备选方案：[评估过的其他方案]
输出：已解决所有NEEDS CLARIFICATION项的research.md文件

Phase 1: Design & Contracts

阶段1：设计与合约

Prerequisites: 
research.md
complete
  1. Extract entities from feature spec → 
    data-model.md
    :
    • Entity name, fields, relationships
    • Validation rules from requirements
    • State transitions if applicable
  2. Generate API contracts from functional requirements:
    • For each user action → endpoint
    • Use standard REST/GraphQL patterns
    • Output OpenAPI/GraphQL schema to 
      /contracts/
  3. Agent context update:
    • Run 
      .specify/scripts/bash/update-agent-context.sh <agent_type>
    • Use the current runtime agent type (e.g., claude, codex, copilot, gemini). Leave empty to update all existing agent files.
    • Update the appropriate agent-specific context file
    • Add only new technology from current plan
    • Preserve manual additions between markers
Output: data-model.md, /contracts/*, quickstart.md, agent-specific file
前置条件：
research.md
文件已完成
  1. 从功能规格说明书中提取实体，生成
    data-model.md
    文件：
    • 实体名称、字段、关系
    • 需求中的验证规则
    • 适用的状态转换逻辑
  2. 根据功能需求生成API合约：
    • 每个用户操作对应一个接口
    • 使用标准REST/GraphQL模式
    • 将OpenAPI/GraphQL schema输出到
      /contracts/
      目录
  3. Agent上下文更新：
    • 运行
      .specify/scripts/bash/update-agent-context.sh <agent_type>
    • 使用当前运行时的Agent类型（例如claude、codex、copilot、gemini）。留空则更新所有现有Agent文件。
    • 更新对应的Agent专属上下文文件
    • 仅添加当前计划中的新技术内容
    • 保留标记之间的手动添加内容
输出：data-model.md、/contracts/下所有文件、quickstart.md、Agent专属文件

Key rules

核心规则

  • Use absolute paths
  • ERROR on gate failures or unresolved clarifications
  • 使用绝对路径
  • 若准入条件不通过或存在未解决的待澄清项，触发ERROR

Outputs

输出产物

  • specs/<feature>/plan.md
    (filled implementation plan)
  • specs/<feature>/research.md
  • specs/<feature>/data-model.md
  • specs/<feature>/contracts/
    (API schemas)
  • specs/<feature>/quickstart.md
  • Updated agent context file (runtime-specific)
  • specs/<feature>/plan.md
    （已填写完成的实施计划）
  • specs/<feature>/research.md
  • specs/<feature>/data-model.md
  • specs/<feature>/contracts/
    （API schema文件）
  • specs/<feature>/quickstart.md
  • 更新后的Agent上下文文件（与运行时相关）

Next Steps

后续步骤

After planning:
  • Generate tasks with speckit-tasks.
  • Create a checklist with speckit-checklist when a quality gate is needed.
完成规划后：
  • 使用speckit-tasks生成任务列表。
  • 当需要质量准入检查时，使用speckit-checklist创建检查清单。