spec-kit-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Spec Kit Plan

Spec Kit 规划

Generate implementation design artifacts from the approved feature specification.

从已获批的功能规格说明书生成实现设计工件。

When to Use

使用场景

```
spec.md
```
exists and you need
```
plan.md
```
plus Phase 0/1 design outputs for task generation.
```
plan.md
```
is missing, stale, or invalid after changes to
```
spec.md
```
or
```
memory/constitution.md
```
.
The next step is
```
spec-kit-tasks
```
, but technical context and design decisions are not yet documented.

已存在
```
spec.md
```
，且需要
```
plan.md
```
以及用于任务生成的第0/1阶段设计输出。
在
```
spec.md
```
或
```
memory/constitution.md
```
变更后，
```
plan.md
```
缺失、过时或无效。
下一步是执行
```
spec-kit-tasks
```
，但技术背景和设计决策尚未形成文档。

When Not to Use

不适用场景

No usable
```
spec.md
```
exists yet (
```
spec-kit-specify
```
first).
High-impact ambiguity in
```
spec.md
```
still blocks architecture or validation decisions (
```
spec-kit-clarify
```
first).
You are decomposing design into executable work items (
```
spec-kit-tasks
```
).
You only need a read-only consistency audit (
```
spec-kit-analyze
```
).
You are reconciling cross-artifact drift discovered mid-work (
```
spec-kit-reconcile
```
).

尚无可用的
```
spec.md
```
（需先执行
```
spec-kit-specify
```
）。
```
spec.md
```
中存在高影响的歧义，仍会阻碍架构或验证决策（需先执行
```
spec-kit-clarify
```
）。
正在将设计分解为可执行的工作项（应使用
```
spec-kit-tasks
```
）。
仅需进行只读一致性审计（应使用
```
spec-kit-analyze
```
）。
正在协调工作过程中发现的跨工件偏差（应使用
```
spec-kit-reconcile
```
）。

Router Fit

工作流适配

Primary route from

spec-kit

after

spec-kit-specify

spec-kit-clarify

Must complete before
```
spec-kit-tasks
```
.
Depends on constitution output from
```
spec-kit-constitution
```
.

是

spec-kit

在

spec-kit-specify

spec-kit-clarify

之后的主要流程环节。

必须在
```
spec-kit-tasks
```
之前完成。
依赖
```
spec-kit-constitution
```
输出的constitution文件。

Preconditions

前置条件

Work from the target repository root.
Active feature branch resolves to a spec directory (
```
NNN-feature-name
```
format when git is available).
```
memory/constitution.md
```
exists and is current for planning gates.

在目标仓库根目录下开展工作。
活跃功能分支对应到一个规格目录（当Git可用时，格式为
```
NNN-feature-name
```
）。
```
memory/constitution.md
```
已存在，且针对规划检查项是最新的。

Workflow

工作流程

Resolve active feature paths and initialize
```
plan.md
```
:
- Run
```
scripts/setup-plan.sh --json
```
  exactly once.
- Parse and retain:
```
FEATURE_SPEC
```
  ,
```
IMPL_PLAN
```
  ,
```
SPECS_DIR
```
  ,
```
BRANCH
```
  .
- If the script exits non-zero (for example branch gate failure), stop and report the blocking error.
Enforce artifact gates before writing design outputs:
- If
```
FEATURE_SPEC
```
  (
```
spec.md
```
  ) is missing, stop and route to
```
spec-kit-specify
```
  .
- If
```
memory/constitution.md
```
  is missing, stop and route to
```
spec-kit-constitution
```
  .
- If
```
spec.md
```
  has unresolved high-impact ambiguity that can change architecture, data model, testing, UX, operations, or compliance, stop and route to
```
spec-kit-clarify
```
  .
Load planning inputs with template fallback:
- Required:
```
spec.md
```
  ,
```
memory/constitution.md
```
  .
- Preferred plan template:
```
{REPO_ROOT}/.specify/templates/plan-template.md
```
  .
- Fallback template:
```
assets/plan-template.md
```
  .
- Preserve template heading order; replace placeholders rather than adding parallel structures.
Draft
```
plan.md
```
core sections:
- Complete Summary and Technical Context.
- Mark unknown technical decisions as
```
NEEDS CLARIFICATION
```
  .
- Fill Constitution Check from
```
memory/constitution.md
```
  with explicit pass/fail status.
- Select one concrete project structure and remove unused template options.
- Use Complexity Tracking only when a constitutional violation remains and is explicitly justified.
Run Phase 0 research (
```
research.md
```
):
- Turn each
```
NEEDS CLARIFICATION
```
  in Technical Context into a focused research question.
- Record outcomes as:
  - ```
  Decision
```
- ```
Rationale
```
  - ```
  Alternatives considered
```
- Resolve all blockers needed for design decisions before continuing.
Run Phase 1 design outputs:
- Create/update
```
data-model.md
```
  with entities, fields, relationships, validation rules, and state transitions where relevant.
- Create/update
```
contracts/
```
  for externally visible interfaces that the feature introduces or modifies.
- Create/update
```
quickstart.md
```
  with concrete validation flow for the designed feature.
- Reflect final decisions back into
```
plan.md
```
  so downstream task generation has a single source of truth.
Update agent context (explicit user approval required):
- Before running the script, ask for explicit approval to update agent context files (for example
```
AGENTS.md
```
  ,
```
CLAUDE.md
```
  ,
```
GEMINI.md
```
  ,
```
.github/agents/copilot-instructions.md
```
  ).
- Run
```
scripts/update-agent-context.sh
```
  from repository root only after user approval.
- If an agent type is provided by the user, pass it as the first argument.
- If approval is declined or unavailable, skip this step and report it as skipped.
- Report script failures explicitly; do not silently skip context updates.
Re-check gates and report completion:
- Re-evaluate Constitution Check after Phase 1 outputs.
- Stop with
```
ERROR
```
  if unresolved constitutional violations or unresolved blocking clarifications remain.
- Report
```
BRANCH
```
  , absolute artifact paths, and readiness for
```
spec-kit-tasks
```
  .

解析活跃功能路径并初始化
```
plan.md
```
：
- 准确执行一次
```
scripts/setup-plan.sh --json
```
  。
- 解析并保留以下变量：
```
FEATURE_SPEC
```
  、
```
IMPL_PLAN
```
  、
```
SPECS_DIR
```
  、
```
BRANCH
```
  。
- 如果脚本非零退出（例如分支检查项失败），停止操作并报告阻塞错误。
在编写设计输出前强制执行工件检查项：
- 如果
```
FEATURE_SPEC
```
  （即
```
spec.md
```
  ）缺失，停止操作并引导至
```
spec-kit-specify
```
  。
- 如果
```
memory/constitution.md
```
  缺失，停止操作并引导至
```
spec-kit-constitution
```
  。
- 如果
```
spec.md
```
  中存在未解决的高影响歧义，可能会改变架构、数据模型、测试、UX、运维或合规性，停止操作并引导至
```
spec-kit-clarify
```
  。
加载规划输入并使用模板回退：
- 必需文件：
```
spec.md
```
  、
```
memory/constitution.md
```
  。
- 首选规划模板：
```
{REPO_ROOT}/.specify/templates/plan-template.md
```
  。
- 回退模板：
```
assets/plan-template.md
```
  。
- 保留模板的标题顺序；替换占位符而非添加并行结构。
编写
```
plan.md
```
核心章节：
- 完成“摘要”和“技术背景”部分。
- 将未知的技术决策标记为
```
NEEDS CLARIFICATION
```
  。
- 从
```
memory/constitution.md
```
  中填充“合规性检查”部分，并明确标记通过/失败状态。
- 选择一种具体的项目结构，并移除未使用的模板选项。
- 仅当存在合规性违规且已明确说明理由时，才使用复杂度跟踪。
执行第0阶段研究（生成
```
research.md
```
）：
- 将“技术背景”中的每个
```
NEEDS CLARIFICATION
```
  转换为聚焦的研究问题。
- 按以下格式记录结果：
  - ```
  Decision
```
  （决策）
- ```
Rationale
```
    （理由）
  - ```
  Alternatives considered
```
  （考虑过的替代方案）
- 在继续之前解决所有设计决策所需的阻塞问题。
执行第1阶段设计输出：
- 创建/更新
```
data-model.md
```
  ，包含实体、字段、关系、验证规则和相关的状态转换（如适用）。
- 创建/更新
```
contracts/
```
  目录，用于该功能引入或修改的外部可见接口。
- 创建/更新
```
quickstart.md
```
  ，包含所设计功能的具体验证流程。
- 将最终决策反馈到
```
plan.md
```
  中，以便下游任务生成有单一的事实来源。
更新Agent上下文（需要明确的用户批准）：
- 在运行脚本前，请求明确批准以更新Agent上下文文件（例如
```
AGENTS.md
```
  、
```
CLAUDE.md
```
  、
```
GEMINI.md
```
  、
```
.github/agents/copilot-instructions.md
```
  ）。
- 仅在获得用户批准后，从仓库根目录执行
```
scripts/update-agent-context.sh
```
  。
- 如果用户提供了Agent类型，将其作为第一个参数传递。
- 如果被拒绝或无法获得批准，跳过此步骤并报告已跳过。
- 明确报告脚本执行失败；不要静默跳过上下文更新。
重新检查检查项并报告完成：
- 在第1阶段输出后重新评估合规性检查。
- 如果存在未解决的合规性违规或未解决的阻塞性澄清需求，以
```
ERROR
```
  状态停止操作。
- 报告
```
BRANCH
```
  、工件的绝对路径，以及是否已准备好执行
```
spec-kit-tasks
```
  。

Output

输出结果

```
plan.md
```
:
- Fully populated from the selected plan template.
- Technical Context reflects final decisions from Phase 0.
- Constitution Check is explicit (
```
pass
```
  ,
```
fail
```
  , or justified exception).
- Project Structure shows one concrete layout (no placeholder option blocks).
```
research.md
```
:
- One entry per planning unknown using:
  - ```
  Decision
```
- ```
Rationale
```
  - ```
  Alternatives considered
```
- Resolves all blocking
```
NEEDS CLARIFICATION
```
  items required for design.
```
data-model.md
```
:
- Captures entities, fields, relationships, validation constraints, and relevant state transitions.
- Maps model decisions back to spec requirements where practical.
```
contracts/*
```
(when applicable):
- Defines each new/changed external interface (endpoint/event/schema).
- Includes input/output shape, validation/error behavior, and compatibility notes.
```
quickstart.md
```
:
- Describes a concrete validation flow for the designed feature.
- Covers primary success path plus key error/edge behavior from the spec.
Updated agent context file(s) from
```
scripts/update-agent-context.sh
```
(only when user-approved):
- Contains newly introduced technologies from the final plan.
- Preserves user-maintained manual sections.
If the user does not approve context updates:
- Report that agent context sync was intentionally skipped.

```
plan.md
```
：
- 从所选规划模板完全填充。
- 技术背景反映了第0阶段的最终决策。
- 合规性检查明确标记（
```
pass
```
  、
```
fail
```
  或有正当理由的例外）。
- 项目结构显示一种具体的布局（无占位符选项阻塞）。
```
research.md
```
：
- 每个规划未知项对应一个条目，格式为：
  - ```
  Decision
```
- ```
Rationale
```
  - ```
  Alternatives considered
```
- 解决了设计所需的所有阻塞性
```
NEEDS CLARIFICATION
```
  项。
```
data-model.md
```
：
- 记录实体、字段、关系、验证约束和相关的状态转换。
- 尽可能将模型决策映射回规格需求。
```
contracts/*
```
（如适用）：
- 定义每个新增/修改的外部接口（端点/事件/ schema）。
- 包含输入/输出格式、验证/错误行为和兼容性说明。
```
quickstart.md
```
：
- 描述所设计功能的具体验证流程。
- 覆盖主要成功路径以及规格中关键的错误/边缘行为。
经用户批准后，由
```
scripts/update-agent-context.sh
```
生成的更新后的Agent上下文文件：
- 包含最终规划中引入的新技术。
- 保留用户维护的手动章节。
如果用户未批准上下文更新：
- 报告Agent上下文同步已被有意跳过。

Key rules

关键规则

Use absolute paths in completion reporting.
Treat missing prerequisites as hard stops with reroutes to the owning sibling skill.
Do not generate
```
tasks.md
```
or implementation code in this skill.
Keep plan artifacts at design granularity: architecture, data model, interfaces/contracts, constraints, and validation approach.
Do not include execution-level content such as code snippets, patch-style file edits, command runbooks, or checklist task breakdowns.
Do not leave blocking
```
NEEDS CLARIFICATION
```
unresolved by completion.
Emit
```
ERROR
```
for unresolved constitution gates without justification.
Never run
```
scripts/update-agent-context.sh
```
without explicit user approval in the current session.

在完成报告中使用绝对路径。
将缺失的前置条件视为硬停止，并引导至对应的关联工具。
不要在本工具中生成
```
tasks.md
```
或实现代码。
保持规划工件处于设计粒度：架构、数据模型、接口/契约、约束和验证方法。
不要包含执行级内容，如代码片段、补丁式文件编辑、命令手册或清单任务分解。
完成时不要留下未解决的阻塞性
```
NEEDS CLARIFICATION
```
项。
对于未说明理由的未解决合规性检查项，输出
```
ERROR
```
。
切勿在当前会话未获得用户明确批准的情况下运行
```
scripts/update-agent-context.sh
```
。

Common Mistakes

常见错误

Planning without an approved spec — the plan will lack stable requirements and churn.
Using the wrong template source path (
```
spec-template
```
instead of
```
plan-template
```
).
Keeping placeholder project-structure options in
```
plan.md
```
instead of selecting one concrete layout.
Including execution details in plan artifacts (code snippets, exact commands, patch-level file changes, or task checklists) — design belongs in
```
spec-kit-plan
```
; execution belongs to
```
spec-kit-tasks
```
and
```
spec-kit-implement
```
.
Skipping the post-design constitution re-check before handing off to
```
spec-kit-tasks
```
.
Running context-file updates automatically without asking the user to approve changes to
```
AGENTS.md
```
/
```
CLAUDE.md
```
/related files.

在没有获批规格的情况下进行规划——规划将缺乏稳定的需求并会不断变动。
使用错误的模板源路径（
```
spec-template
```
而非
```
plan-template
```
）。
在
```
plan.md
```
中保留占位符项目结构选项，而非选择一种具体的布局。
在规划工件中包含执行细节（代码片段、确切命令、补丁级文件更改或任务清单）——设计属于
```
spec-kit-plan
```
；执行属于
```
spec-kit-tasks
```
和
```
spec-kit-implement
```
。
在交接给
```
spec-kit-tasks
```
之前跳过设计后的合规性重新检查。
自动运行上下文文件更新，而未请求用户批准对
```
AGENTS.md
```
/
```
CLAUDE.md
```
/相关文件的更改。

References

参考资料

```
references/spec-kit-workflow.dot
```
for overall context of where planning fits in the Spec Kit sequence.
```
scripts/setup-plan.sh
```
```
scripts/update-agent-context.sh
```
```
assets/plan-template.md
```

https://github.com/github/spec-kit/blob/9111699cd27879e3e6301651a03e502ecb6dd65d/templates/commands/plan.md

```
references/spec-kit-workflow.dot
```
：了解规划在Spec Kit序列中的整体上下文。
```
scripts/setup-plan.sh
```
```
scripts/update-agent-context.sh
```
```
assets/plan-template.md
```

https://github.com/github/spec-kit/blob/9111699cd27879e3e6301651a03e502ecb6dd65d/templates/commands/plan.md