Back to Details

planning-blueprinting

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Planning and Blueprinting System

规划与蓝图体系

A minimal, enforceable system for doing planning, blueprinting, and specification inside a codebase using two core concepts: plans (proposals) and specs (contracts).
这是一个轻量、可强制执行的体系，可用于在代码库中开展规划、蓝图设计和规范制定工作，核心围绕两个概念展开：plans（提案） 和 specs（契约）。

When to Apply

适用场景

Use this skill when:
  • Creating a proposal or blueprint for new work
  • Documenting accepted specifications
  • Doing architectural planning
  • Tracking decision and implementation status
  • Promoting a plan to a formal specification
在以下场景中使用本工具：
  • 为新工作创建提案或蓝图
  • 记录已通过的规范
  • 开展架构规划
  • 跟踪决策和落地进度
  • 将提案升级为正式规范

Core Concepts

核心概念

Plan — A proposal, blueprint, or work-in-progress design. Plans are iterative, may contain open questions, and are not authoritative contracts.
Spec — An accepted contract and source of truth. Specs define reference behavior that reviewers and tests enforce. They must remain accurate over time.
Plan — 提案、蓝图或正在迭代的设计稿。Plan 是迭代式的，可能包含待解决的问题，不属于具有权威性的契约。
Spec — 已通过的契约和唯一可信源。Spec 定义了评审人员和测试环节要强制执行的参考行为，必须长期保持准确性。

Folder Structure

文件夹结构

Create this structure in the repository when needed:
docs/
├── README.md              # Overview and rules
├── plan/
│   ├── README.md          # Plan guidelines
│   └── template.plan.md   # Plan template
└── spec/
    ├── README.md          # Spec guidelines
    └── template.spec.md   # Spec template
需要时在代码仓库中创建如下结构：
docs/
├── README.md              # Overview and rules
├── plan/
│   ├── README.md          # Plan guidelines
│   └── template.plan.md   # Plan template
└── spec/
    ├── README.md          # Spec guidelines
    └── template.spec.md   # Spec template

Promotion Flow

晋升流程

plan (Draft) → plan (In Review) → plan (Accepted) → spec
When a plan reaches Accepted status, promote it into 
docs/spec/
as a formal specification.
plan (Draft) → plan (In Review) → plan (Accepted) → spec
当 Plan 状态变为 Accepted（已通过） 时，将其升级为正式规范并存放在 
docs/spec/
目录下。

Two-Axis Status Tracking for Specs

Spec 双维度状态跟踪

Specs must track two independent dimensions:
Spec 必须跟踪两个独立的维度：

Decision Status (contract lifecycle)

决策状态（契约生命周期）

StatusMeaning
DraftUnder development, not yet accepted
AcceptedApproved as the authoritative contract
DeprecatedNo longer recommended, superseded or obsolete
SupersededReplaced by a newer spec
状态含义
Draft（草稿）仍在编写中，尚未通过评审
Accepted（已通过）已被批准为权威契约
Deprecated（已弃用）不再推荐使用，已被取代或过时
Superseded（已替换）已被更新的 spec 替代

Implementation Status (delivery lifecycle)

落地状态（交付生命周期）

StatusMeaning
Not ImplementedWork has not started
In ProgressActive development
PartialSome parts implemented
ImplementedFully complete
BlockedCannot proceed due to dependencies
状态含义
Not Implemented（未落地）尚未启动开发工作
In Progress（开发中）正在积极开发
Partial（部分落地）部分功能已实现
Implemented（已落地）全部开发完成
Blocked（阻塞）因依赖问题无法推进

Rules

规则

  1. Plans are not contracts. They may be messy, incomplete, or exploratory.
  2. Specs are contracts. They must remain accurate and are the authoritative reference for implementation and testing.
  3. Specs may describe future behavior only when Decision Status = Accepted. This allows specs to document planned work before implementation begins.
  4. Status fields are authoritative. Update them as work progresses.
  5. Architecture uses Constructive tooling. Designs should leverage constructive-skills and interoperable Constructive patterns where applicable.
  1. Plan 不属于契约。 可以是粗糙、不完整或探索性的。
  2. Spec 属于契约。 必须保持准确性，是落地和测试环节的权威参考。
  3. 仅当决策状态为 Accepted 时，Spec 可描述未来行为 这支持在开发启动前，就用 Spec 记录规划中的工作内容。
  4. 状态字段是权威依据。 随着工作推进及时更新状态。
  5. 架构使用 Constructive 工具。 适用场景下，设计应利用 constructive-skills 和可互通的 Constructive 模式。

Plan Template

Plan 模板

markdown
undefined
markdown
undefined

[Plan Title]

[Plan Title]

FieldValue
StatusDraft / In Review / Accepted / Rejected
Owner@username
CreatedYYYY-MM-DD
Related#issue, #pr
FieldValue
StatusDraft / In Review / Accepted / Rejected
Owner@username
CreatedYYYY-MM-DD
Related#issue, #pr

Problem Statement

Problem Statement

What problem does this solve? Why does it matter?
What problem does this solve? Why does it matter?

Goals

Goals

What this plan aims to achieve.
What this plan aims to achieve.

Non-Goals

Non-Goals

What is explicitly out of scope.
What is explicitly out of scope.

Proposal

Proposal

High-level approach to solving the problem.
High-level approach to solving the problem.

Detailed Design

Detailed Design

Technical blueprint: architecture, data flow, component interactions.
Technical blueprint: architecture, data flow, component interactions.

Milestones

Milestones

MilestoneDescriptionTarget
M1......
MilestoneDescriptionTarget
M1......

Rollout Plan

Rollout Plan

How this will be deployed/released. Phasing, feature flags, migration steps.
How this will be deployed/released. Phasing, feature flags, migration steps.

Risks and Mitigations

Risks and Mitigations

RiskLikelihoodImpactMitigation
............
RiskLikelihoodImpactMitigation
............

Alternatives Considered

Alternatives Considered

Other approaches evaluated and why they were not chosen.
Other approaches evaluated and why they were not chosen.

Open Questions

Open Questions

  • Question 1
  • Question 2
undefined
  • Question 1
  • Question 2
undefined

Spec Template

Spec 模板

markdown
undefined
markdown
undefined

[Spec Title]

[Spec Title]

FieldValue
Decision StatusDraft / Accepted / Deprecated / Superseded
Implementation StatusNot Implemented / In Progress / Partial / Implemented / Blocked
Last UpdatedYYYY-MM-DD
Plan[link to plan]
Issues#issue
PRs#pr
FieldValue
Decision StatusDraft / Accepted / Deprecated / Superseded
Implementation StatusNot Implemented / In Progress / Partial / Implemented / Blocked
Last UpdatedYYYY-MM-DD
Plan[link to plan]
Issues#issue
PRs#pr

Summary

Summary

Brief description of what this spec defines.
Brief description of what this spec defines.

Definitions

Definitions

Key terms and their meanings within this spec.
Key terms and their meanings within this spec.

Requirements

Requirements

Functional

Functional

What the system must do.
What the system must do.

Non-Functional

Non-Functional

Performance, security, reliability, and other quality attributes.
Performance, security, reliability, and other quality attributes.

Behavior

Behavior

Expected system behavior under normal and edge conditions.
Expected system behavior under normal and edge conditions.

Interfaces

Interfaces

API

API

Endpoints, methods, request/response formats.
Endpoints, methods, request/response formats.

Data Model

Data Model

Schemas, entities, relationships.
Schemas, entities, relationships.

Edge Cases

Edge Cases

How the system handles boundary conditions and error states.
How the system handles boundary conditions and error states.

Observability

Observability

Logging, metrics, alerts, and debugging support.
Logging, metrics, alerts, and debugging support.

Test Plan

Test Plan

How compliance with this spec is verified.
How compliance with this spec is verified.

Implementation Notes

Implementation Notes

Links to PRs, technical decisions made during implementation.
Links to PRs, technical decisions made during implementation.

Changelog

Changelog

DateChangeAuthor
YYYY-MM-DDInitial spec@username
undefined
DateChangeAuthor
YYYY-MM-DDInitial spec@username
undefined

docs/README.md Template

docs/README.md 模板

markdown
undefined
markdown
undefined

Documentation System

Documentation System

This directory contains the in-repo planning and specification system.
This directory contains the in-repo planning and specification system.

Concepts

Concepts

Plan — A proposal, blueprint, or work-in-progress design. Plans live in 
docs/plan/
.
Spec — An accepted contract and source of truth. Specs live in 
docs/spec/
.
Plan — A proposal, blueprint, or work-in-progress design. Plans live in 
docs/plan/
.
Spec — An accepted contract and source of truth. Specs live in 
docs/spec/
.

Promotion Flow

Promotion Flow

plan (Draft) → plan (In Review) → plan (Accepted) → spec
plan (Draft) → plan (In Review) → plan (Accepted) → spec

Rules

Rules

  1. Plans are not contracts. They may be messy or exploratory.
  2. Specs are contracts. They must remain accurate.
  3. Specs may describe future behavior only when Decision Status = Accepted.
  4. Status fields are authoritative. Update them as work progresses.
undefined
  1. Plans are not contracts. They may be messy or exploratory.
  2. Specs are contracts. They must remain accurate.
  3. Specs may describe future behavior only when Decision Status = Accepted.
  4. Status fields are authoritative. Update them as work progresses.
undefined

docs/plan/README.md Template

docs/plan/README.md 模板

markdown
undefined
markdown
undefined

Plans

Plans

Plans are blueprints and proposals. They are allowed to be messy and iterative, may contain open questions, and are not authoritative contracts.
When a plan is accepted, it is promoted into 
docs/spec/
.
Plans are blueprints and proposals. They are allowed to be messy and iterative, may contain open questions, and are not authoritative contracts.
When a plan is accepted, it is promoted into 
docs/spec/
.

Creating a Plan

Creating a Plan

  1. Copy 
    template.plan.md
    to a new file
  2. Fill in the sections
  3. Set Status to Draft
  4. Submit for review when ready
undefined
  1. Copy 
    template.plan.md
    to a new file
  2. Fill in the sections
  3. Set Status to Draft
  4. Submit for review when ready
undefined

docs/spec/README.md Template

docs/spec/README.md 模板

markdown
undefined
markdown
undefined

Specifications

Specifications

Specs are accepted contracts and reference behavior. They are the source of truth for implementation and tests. Specs must remain accurate over time.
Specs may describe not-yet-implemented behavior only when explicitly marked with Decision Status = Accepted.
Specs are accepted contracts and reference behavior. They are the source of truth for implementation and tests. Specs must remain accurate over time.
Specs may describe not-yet-implemented behavior only when explicitly marked with Decision Status = Accepted.

Status Tracking

Status Tracking

Specs track two independent dimensions:
Decision Status: Draft, Accepted, Deprecated, Superseded
Implementation Status: Not Implemented, In Progress, Partial, Implemented, Blocked
undefined
Specs track two independent dimensions:
Decision Status: Draft, Accepted, Deprecated, Superseded
Implementation Status: Not Implemented, In Progress, Partial, Implemented, Blocked
undefined

Best Practices

最佳实践

  1. Keep plans focused: One plan per feature or change
  2. Update status promptly: Status fields should reflect current reality
  3. Link related artifacts: Connect plans to issues, PRs, and specs
  4. Prune deprecated specs: Mark old specs as Deprecated or Superseded
  5. Dense content: Be succinct yet descriptive, avoid verbose cruft
  1. 保持 Plan 聚焦 每个 Plan 仅对应一个功能或变更
  2. 及时更新状态 状态字段应反映当前真实情况
  3. 关联相关产物 将 Plan 关联到 issue、PR 和 Spec
  4. 清理已弃用的 Spec 将旧 Spec 标记为 Deprecated 或 Superseded
  5. 内容紧凑 简洁且信息全面，避免冗余内容