Back to Details

planning

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Planning Skill

规划Skill

When to use

使用场景

Use this skill when the user asks for planning, a roadmap, a spec-to-implementation breakdown, or wants decisions documented.
当用户要求制定规划、路线图、从规格到实现的拆解方案，或希望将决策记录在案时，使用此Skill。

Modes

模式

Choose the lightest mode that meets the request.
选择能满足需求的最轻量模式。

quick-plan

quick-plan

Use when:
  • task is small/medium and non-breaking
  • no migrations and no multi-phase rollout
Output:
  • 3–8 Work Items (WI-###), each with tests + acceptance
适用场景：
  • 任务为中小型且无破坏性变更
  • 无需迁移和多阶段发布
输出：
  • 3–8个工作项（WI-###），每个工作项包含测试与验收标准

full-plan
(default)

full-plan
（默认模式）

Use when:
  • migrations/persistence changes
  • API/contract changes (public tools, schemas, SDKs)
  • multi-phase roadmaps
  • performance-sensitive work
Output:
  • structured plan sections (see “Plan file template”)
适用场景：
  • 涉及迁移/持久化变更
  • API/契约变更（公共工具、schema、SDK）
  • 多阶段路线图
  • 对性能敏感的工作
输出：
  • 结构化的计划章节（参见“计划文件模板”）

Process

流程

  1. Clarify outcomes
    • Restate desired behaviors and constraints.
    • Identify ambiguities and propose defaults if the user doesn’t decide.
    • Capture constraints & dependencies (runtime versions, OS, external services, feature flags, required tools).
    • Capture gaps: list requirement/behavior gaps or missing decisions revealed here.
  2. Inventory current behavior
    • Trace entry points → state/store → side effects → persistence.
    • List key files/modules and the invariants they rely on.
    • Note ownership/priority rules (windows, workspaces, files).
    • Capture gaps: list where current behavior diverges from the stated outcomes.
  3. Define target rules
    • Convert outcomes into explicit rules and precedence.
    • For each rule, include: trigger/context, expected behavior, scope, constraints, and exclusions.
    • Edge-case pass: cover empty/none, invalid/malformed, boundary sizes, conflicting state, multi-surface coordination, persistence/restore, and I/O failures.
    • Capture gaps: list rules that lack implementation support or current behavior conflicts.
    • Create a Decision Log:
      • decision, options considered, rationale, and why alternatives were rejected.
    • Create an Open Questions list:
      • questions that block correctness, who decides, and what the default is if not decided.
  4. Structure the plan
    • Break into Work Items (WI-###), each with:
      • Goal
      • Acceptance (measurable) (correctness + performance + UX where relevant)
      • Tests (first) (file names + test intent; unit/integration/e2e as applicable)
      • Touched areas (file paths + key functions/classes/symbols)
      • Dependencies (other WIs, external tools/services)
      • Risks + mitigations
      • Rollback / revert strategy
    • Add priority + estimates (S/M/L) and explicit ordering/dependencies between WIs.
    • Capture gaps: map each gap to at least one WI (or record as “out of scope”).
    • Plan lint (required):
      • Sections present (Outcomes, Constraints, Current Behavior, Target Rules, Work Items, Testing).
      • WI numbering is sequential and referenced consistently.
      • Every WI includes tests + acceptance.
  5. Write the plan file
    • Use the template at 
      templates/TEMPLATE.md
      (bundled with this skill) if available, otherwise follow the structure above.
    • Write plans to a local directory (e.g. 
      dev-docs/plans/YYYYMMDD-HHMM-<topic>.md
      — local, not in repo).
    • Always report the saved plan path.
  1. 明确预期成果
    • 重述期望的行为与约束条件。
    • 识别模糊点，若用户未明确则提出默认方案。
    • 记录约束与依赖（运行时版本、操作系统、外部服务、功能开关、所需工具）。
    • 记录缺口：列出此阶段发现的需求/行为缺口或未明确的决策。
  2. 梳理当前行为
    • 追踪入口点 → 状态/存储 → 副作用 → 持久化流程。
    • 列出关键文件/模块及其依赖的不变量。
    • 记录所有权/优先级规则（窗口、工作区、文件）。
    • 记录缺口：列出当前行为与预期成果的偏差之处。
  3. 定义目标规则
    • 将预期成果转化为明确的规则与优先级。
    • 每条规则需包含：触发条件/上下文、预期行为、适用范围、约束条件与排除项。
    • 边缘场景覆盖：涵盖空值/无数据、无效/格式错误、边界大小、冲突状态、多界面协调、持久化/恢复以及I/O故障场景。
    • 记录缺口：列出缺乏实现支持或与当前行为冲突的规则。
    • 创建决策日志：
      • 记录决策内容、考虑的选项、决策理由以及否决其他方案的原因。
    • 创建待解决问题清单：
      • 记录阻碍正确性的问题、决策负责人以及未决策时的默认方案。
  4. 构建计划结构
    • 拆解为工作项（WI-###），每个工作项包含：
      • 目标
      • 验收标准（可量化）（正确性 + 性能 + 相关UX指标）
      • 测试（优先编写）（文件名 + 测试意图；按需包含单元/集成/端到端测试）
      • 涉及范围（文件路径 + 关键函数/类/符号）
      • 依赖项（其他工作项、外部工具/服务）
      • 风险与缓解措施
      • 回滚/撤销策略
    • 添加优先级与估算（S/M/L），并明确工作项之间的顺序与依赖关系。
    • 记录缺口：将每个缺口映射到至少一个工作项（或标记为“超出范围”）。
    • 计划检查（必填）：
      • 确保包含所有章节（预期成果、约束条件、当前行为、目标规则、工作项、测试）。
      • 工作项编号连续且引用一致。
      • 每个工作项均包含测试与验收标准。
  5. 编写计划文件
    • 若可用，使用此Skill附带的
      templates/TEMPLATE.md
      模板；否则遵循上述结构。
    • 将计划写入本地目录（例如 
      dev-docs/plans/YYYYMMDD-HHMM-<topic>.md
      — 本地存储，无需提交到代码库）。
    • 务必在响应中报告保存的计划路径。

Testing Requirements

测试要求

  • Every WI must include explicit tests to write before implementation (file names and test intent).
  • If tests cannot be written, call it out explicitly and propose the smallest test seam to enable them.
  • Include a Testing Procedures section in the plan with required commands and when to run them.
  • End the plan with a short Manual Test Checklist.
  • 每个工作项必须包含明确的测试用例，且需在实现前编写（包含文件名与测试意图）。
  • 若无法编写测试用例，需明确指出，并提出最小化的测试切入点方案。
  • 在计划中添加测试流程章节，包含所需命令与执行时机。
  • 在计划末尾添加简短的手动测试清单。

Acceptance Criteria Guidance

验收标准指南

Acceptance must be measurable and verifiable:
  • Good: “Search returns v1 schema with 
    locator_v1
    for every result (unit test).”
  • Bad: “Search feels better.”
验收标准必须可量化、可验证：
  • 示例（合格）：“搜索结果均返回带有
    locator_v1
    的v1 schema（单元测试验证）。”
  • 示例（不合格）：“搜索体验有所提升。”

Plan → Verify Handoff (required)

计划→验证交接（必填）

At the end of the plan, include:
  • Evidence to collect per WI (tests, logs, manual steps).
  • Any required fixtures or sample data.
在计划末尾添加：
  • 每个工作项需收集的验证证据（测试结果、日志、手动步骤）。
  • 所需的任何测试数据或样本数据。

Migration / persistence requirements (when applicable)

迁移/持久化要求（适用时）

If the plan changes anything persisted (DB, on-disk cache, config files, APIs that clients store):
  • Add a Data Model section (tables/columns/keys, versions).
  • Add a Migration Plan:
    • forward migration steps
    • rollback steps
    • compatibility guarantees (old clients vs new server)
  • Add Invariants + validation queries (what to check post-migration).
  • Add a Backfill / reindex strategy if needed.
若计划涉及持久化内容变更（数据库、磁盘缓存、配置文件、客户端存储的API）：
  • 添加数据模型章节（表/列/键、版本）。
  • 添加迁移计划：
    • 正向迁移步骤
    • 回滚步骤
    • 兼容性保证（旧客户端与新服务器的适配）
  • 添加不变量与验证查询（迁移后需检查的内容）。
  • 若需要，添加回填/重新索引策略。

Observability requirements (when applicable)

可观测性要求（适用时）

If the plan touches indexing/search/performance-sensitive paths:
  • Define metrics (latency, throughput, memory, DB size growth).
  • Define where logs go and how to enable verbose tracing.
  • Add acceptance thresholds (e.g. “index 1000 docs < X minutes on machine Y”).
若计划涉及索引/搜索/性能敏感路径：
  • 定义指标（延迟、吞吐量、内存占用、数据库大小增长）。
  • 定义日志存储位置与启用详细追踪的方式。
  • 添加验收阈值（例如“在机器Y上索引1000个文档耗时< X分钟”）。

Rollout requirements (when applicable)

发布要求（适用时）

If behavior changes are user-visible or risky:
  • Add a Rollout Plan (feature flags, staged enablement, default-off vs default-on).
  • Define “kill switch” conditions and how to revert quickly.
若行为变更对用户可见或存在风险：
  • 添加发布计划（功能开关、分阶段启用、默认关闭 vs 默认开启）。
  • 定义“紧急关停”条件与快速回滚方式。

Output Requirements

输出要求

  • Always produce a plan file and include its path in the response.
  • Ask at most 1–2 clarifying questions only when they change the rules.
  • 务必生成计划文件，并在响应中包含其路径。
  • 仅当问题会改变规则时，最多提出1-2个澄清问题。