implementation-planning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementation Planning

实施规划

This is a strict guideline. Follow these rules exactly.

Instructions for creating and managing implementation plans that persist across sessions.

这是严格的指南，请严格遵守以下规则。

用于创建和管理跨会话生效的实施计划的说明。

Structure

结构

Implementation plans follow this directory structure:

docs/planning/implementation/
  {feature-name}/
    index.md              # Navigation hub with progress tracking
    phase-0-*.md          # Prerequisite/setup phase
    phase-1-*.md          # First implementation phase
    phase-2-*.md          # Second implementation phase
    ...
    post-implementation.md # Validation, handoff, troubleshooting

实施计划遵循如下目录结构：

docs/planning/implementation/
  {feature-name}/
    index.md              # Navigation hub with progress tracking
    phase-0-*.md          # Prerequisite/setup phase
    phase-1-*.md          # First implementation phase
    phase-2-*.md          # Second implementation phase
    ...
    post-implementation.md # Validation, handoff, troubleshooting

Phases vs Steps

阶段与步骤

Phase = One document containing related work

Each phase has its own file:
```
phase-N-descriptive-name.md
```
Keep phases under 500 lines (LLMs struggle with longer documents)
Phases are executed in numerical order (0, 1, 2, ...)
Renaming a phase file requires updating all references in index.md

Step = One unit of work within a phase

Each step is numbered: Step N.1, Step N.2, etc. (where N is the phase number)
Steps within a phase are executed in order
Each step should be:
- Completable in 15-60 minutes
- Independently testable
- Committable (leaves codebase in working state)

Example:

phase-1-api-endpoints.md contains:
  - Step 1.1: Define TypeScript interfaces
  - Step 1.2: Create Lambda handler
  - Step 1.3: Add API Gateway route
  - Step 1.4: Test endpoint

phase-2-database-setup.md contains:
  - Step 2.1: Define DynamoDB table
  - Step 2.2: Create table in CDK
  - Step 2.3: Add IAM permissions

阶段 = 包含相关工作的单个文档

每个阶段对应独立文件：
```
phase-N-descriptive-name.md
```
请将阶段文档的长度控制在500行以内（LLM难以处理过长的文档）
阶段按数字顺序执行（0, 1, 2, ...）
重命名阶段文件需要更新index.md里的所有引用

步骤 = 阶段内的单个工作单元

每个步骤编号：步骤N.1、步骤N.2等（N为阶段编号）
阶段内的步骤按顺序执行
每个步骤应该满足：
- 15-60分钟内可完成
- 可独立测试
- 可提交（提交后代码库仍处于可工作状态）

示例：

phase-1-api-endpoints.md contains:
  - Step 1.1: Define TypeScript interfaces
  - Step 1.2: Create Lambda handler
  - Step 1.3: Add API Gateway route
  - Step 1.4: Test endpoint

phase-2-database-setup.md contains:
  - Step 2.1: Define DynamoDB table
  - Step 2.2: Create table in CDK
  - Step 2.3: Add IAM permissions

Numbering Rules

编号规则

Phase numbering:

Sequential: 0, 1, 2, 3, ...
Phase 0 is always prerequisites/setup
Phases must be executed in order

Step numbering:

Format:
```
{phase}.{step}
```
— Phase 1 steps: 1.1, 1.2, 1.3
Steps must be executed in order within a phase
Step numbers indicate execution order within their phase

General rules:

Phase numbers indicate execution order (must be sequential: 0, 1, 2, ...)
Phase 0 is for prerequisites/setup
Use
```
post-implementation.md
```
for validation and handoff
Keep phase documents under 500 lines (LLMs struggle with longer files)

阶段编号：

顺序为0, 1, 2, 3, ...
阶段0始终是前置准备/设置环节
阶段必须按顺序执行

步骤编号：

格式：
```
{阶段}.{步骤}
```
— 阶段1的步骤为1.1, 1.2, 1.3
阶段内步骤必须按顺序执行
步骤编号代表其在所属阶段内的执行顺序

通用规则：

阶段编号代表执行顺序（必须连续：0, 1, 2, ...）
阶段0用于前置准备/设置
使用
```
post-implementation.md
```
存放验证、交接和故障排查相关内容
阶段文档长度控制在500行以内（LLM难以处理过长文件）

Index File Structure

索引文件结构

The

index.md

serves as the single navigation and progress tracking hub:

markdown

undefined

index.md

作为统一的导航和进度追踪中心：

markdown

undefined

{Feature Name} - Implementation Guide

Last Updated: YYYY-MM-DD

🎯 Quick Navigation

Phase	Document
Phase 0	Phase Name
Phase 1	Phase Name
Phase 2	Phase Name

Phase	Document
Phase 0	Phase Name
Phase 1	Phase Name
Phase 2	Phase Name

Overview

Brief description of what this implementation achieves.

Prerequisites

Before starting:

Requirement 1
Requirement 2
Requirement 3

Before starting:

Requirement 1
Requirement 2
Requirement 3

Implementation Principles

Key principle 1
Key principle 2
Non-negotiable constraint

Key principle 1
Key principle 2
Non-negotiable constraint

Progress Tracking

Current Step: Phase X, Step X.X - {Step Name}

Phase 0: {Name}

Step 0.1: Description
Step 0.2: Description

Step 0.1: Description
Step 0.2: Description

Phase 1: {Name}

Step 1.1: Description
Step 1.2: Description

Step 1.1: Description
Step 1.2: Description

Phase Document Structure

阶段文档结构

Each phase document should follow this structure:

markdown

undefined

每个阶段文档遵循如下结构：

markdown

undefined

Phase {N}: {Phase Name}

Goal: Single sentence describing what this phase achieves.

Duration: Estimated time

Goal: Single sentence describing what this phase achieves.

Duration: Estimated time

Context

Why this phase is needed. Background information.

Step {N}.1: {Step Name}

Goal: What this step accomplishes.

Tasks:

Specific task
Specific task

Implementation:

Detailed instructions, code examples, commands.

Testing:

How to verify this step worked.

Commit:

git commit -m "Step {N}.{X}: [brief description]"

Goal: What this step accomplishes.

Tasks:

Specific task
Specific task

Implementation:

Detailed instructions, code examples, commands.

Testing:

How to verify this step worked.

Commit:

git commit -m "Step {N}.{X}: [brief description]"

Step {N}.2: {Step Name}

...


**Important:**
- Step numbers must match phase number: Phase 1 has steps 1.1, 1.2, 1.3, etc.
- Each step should be small enough to complete in 15-60 minutes
- Each step should be testable independently
- Each step should leave codebase in committable state
- Keep total phase document under 500 lines
  - If approaching 500 lines, the phase is too big and unmanageable
  - Don't arbitrarily split the document — reorganize the work
  - Split into multiple focused phases with clear goals
  - Each phase should have a single, focused goal

---

...


**注意事项：**
- 步骤编号必须与阶段编号匹配：阶段1的步骤为1.1、1.2、1.3等
- 每个步骤的体量应该足够小，可在15-60分钟内完成
- 每个步骤可独立测试
- 每个步骤执行完成后代码库处于可提交状态
- 阶段文档总长度控制在500行以内
  - 如果接近500行，说明该阶段体量过大难以管理
  - 不要随意拆分文档，而是重新规划工作内容
  - 拆分为多个目标清晰的聚焦阶段
  - 每个阶段应该有单一、明确的目标

---

Implementation Workflow

实施工作流

The Golden Rule: ALWAYS FOLLOW THE PLAN

黄金法则：始终遵循计划

Never write code without updating the plan first.

The implementation plan is the single source of truth for what gets built and how. During implementation:

Read the current step in index.md
Follow the step exactly as documented in the phase file
If you need to deviate → STOP and enter planning mode

永远不要在未更新计划的前提下编写代码。

实施计划是开发内容和开发方式的唯一可信来源。实施过程中：

阅读index.md中的当前步骤
严格按照阶段文档中记录的内容执行步骤
如果你需要调整方案 → 停止当前工作并进入规划模式

Planning Mode

规划模式

When you discover:

The current step won't work as written
A better approach exists
Something needs refactoring
A dependency is missing
An assumption was wrong

Immediately enter planning mode:

STOP writing code
Discuss the issue with the developer
Update the plan with the new approach
Check all other steps — does this change affect them?
Verify against principles — does this follow core principles and patterns?
Check dependencies — does this break earlier steps or block later steps?
Update index.md — reflect any step changes in progress tracking
Get confirmation before resuming implementation

当你发现：

当前步骤无法按文档执行
存在更优方案
内容需要重构
缺失依赖
假设错误

立即进入规划模式：

停止编写代码
与开发人员讨论该问题
用新方案更新计划
检查所有其他步骤 — 本次变更是否会影响这些步骤？
对照原则验证 — 本次变更是否符合核心原则和模式？
检查依赖 — 本次变更是否会破坏之前的步骤或阻塞后续步骤？
更新index.md — 在进度追踪中反映所有步骤变更
获得确认后再恢复实施工作

Plan Updates

计划更新

When updating the plan:

Be specific: Document exactly what changes and why
Update dependencies: Note which other steps are affected
Preserve history: Don't delete old approaches, mark them as superseded
Update index.md: Keep progress tracking current

更新计划时：

内容具体： 准确记录变更内容和变更原因
更新依赖： 注明受影响的其他步骤
保留历史： 不要删除旧方案，将其标记为已被取代
更新index.md： 保持进度追踪内容为最新状态

Phase Completion

阶段完成

Creating a New Implementation Plan

创建新的实施计划

Create index.md first — Establish navigation and progress tracking
Break into phases — Each phase = one document, completable in 1-3 days
Break phases into steps — Each step completable in 15-60 minutes
Number sequentially — Phases: 0, 1, 2, ... | Steps: 1.1, 1.2, ... | 2.1, 2.2, ...
Keep phases manageable — If a phase document approaches 500 lines, it's too big
Verify prerequisites — Document what must exist before starting

首先创建index.md — 搭建导航和进度追踪框架
拆分为多个阶段 — 每个阶段对应一个文档，可在1-3天内完成
将阶段拆分为多个步骤 — 每个步骤可在15-60分钟内完成
按顺序编号 — 阶段：0, 1, 2, ... | 步骤：1.1, 1.2, ... | 2.1, 2.2, ...
保持阶段体量可控 — 如果阶段文档接近500行，说明体量过大
验证前置条件 — 记录开始前必须具备的条件

During Implementation

实施过程中

Check index.md — Know exactly which step you're on
Read the step — Understand what needs to be done
Execute the step — Follow instructions exactly
Test the step — Verify it worked
Commit the step — Save progress with clear commit message
Update index.md — Check off the completed step
Move to next step — Repeat

Important: Steps must be executed in order. Phases must be executed in order.

查看index.md — 明确你当前所处的步骤
阅读步骤内容 — 理解需要完成的工作
执行步骤 — 严格遵循说明
测试步骤 — 验证执行成功
提交步骤变更 — 用清晰的提交信息保存进度
更新index.md — 勾选已完成的步骤
进入下一步骤 — 重复上述流程

注意： 步骤必须按顺序执行，阶段必须按顺序执行。

Reordering Work

工作重排

To reorder steps within a phase:

Update step numbers in phase document
Update step references in index.md
Verify implementation dependencies
Check no steps are blocked by reordering

To insert a new phase:

Create new phase file with appropriate number
Renumber subsequent phase files
Update step numbers inside renumbered phase files
Update all references in index.md
Verify overall implementation order still makes sense

如需在阶段内重排步骤：

更新阶段文档中的步骤编号
更新index.md中的步骤引用
验证实施依赖
确认重排不会阻塞任何步骤

如需插入新阶段：

创建对应编号的新阶段文件
对后续阶段文件重新编号
更新重新编号的阶段文件内的步骤编号
更新index.md中的所有引用
验证整体实施顺序仍然合理

When to Create Implementation Plans

何时需要创建实施计划

Create for:

Multi-day features requiring coordination
Features with multiple dependent phases
Features requiring careful sequencing
Features that need progress tracking across sessions

Don't create for:

Single-file changes
Simple bug fixes
Routine maintenance tasks
One-step operations

需要创建的场景：

需要协调的多日开发功能
包含多个依赖阶段的功能
需要仔细编排执行顺序的功能
需要跨会话追踪进度的功能

无需创建的场景：

单文件变更
简单bug修复
日常维护任务
单步操作

Key Principles

核心原则

Fail fast: Validate prerequisites before starting
Incremental: Each step should be independently testable
Reversible: Each step ends with git commit for easy reset
Explicit: No assumptions, document everything
Trackable: Clear progress indicators at all times

快速试错： 开始前先验证前置条件
增量推进： 每个步骤可独立测试
可回滚： 每个步骤结束后进行git提交，方便重置
明确无歧义： 不做假设，所有内容文档化
可追踪： 全程提供清晰的进度标识

Progressive Improvement

持续改进

If the developer corrects a behavior that this skill should have prevented, suggest a specific amendment to this skill to prevent the same correction in the future.

如果开发人员修正了本规范本应避免的行为，请提出对本规范的具体修订建议，避免后续再次出现同类修正。

implementation-planning

Original

Translation

Implementation Planning

实施规划

Structure

结构

Phases vs Steps

阶段与步骤

Numbering Rules

编号规则

Index File Structure

索引文件结构

{Feature Name} - Implementation Guide

{Feature Name} - Implementation Guide

🎯 Quick Navigation

🎯 Quick Navigation

Overview

Overview

Prerequisites

Prerequisites

Implementation Principles

Implementation Principles

Progress Tracking

Progress Tracking

Phase 0: {Name}

Phase 0: {Name}

Phase 1: {Name}

Phase 1: {Name}

Related Documents

Related Documents

Phase Document Structure

阶段文档结构

Phase {N}: {Phase Name}

Phase {N}: {Phase Name}

Context

Context

Step {N}.1: {Step Name}

Step {N}.1: {Step Name}

Step {N}.2: {Step Name}

Step {N}.2: {Step Name}

Implementation Workflow

实施工作流

The Golden Rule: ALWAYS FOLLOW THE PLAN

黄金法则：始终遵循计划

Planning Mode

规划模式

Plan Updates

计划更新

Phase Completion

阶段完成

Creating a New Implementation Plan

创建新的实施计划

During Implementation

实施过程中

Reordering Work

工作重排

When to Create Implementation Plans

何时需要创建实施计划

Key Principles

核心原则

Progressive Improvement

持续改进