impl-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementation Plan Skill

实施规划技能

Create implementation plans for software development tasks with sufficient detail for execution.

为软件开发任务制定具备足够执行细节的实施规划。

Workflow

工作流程

1. Gather Requirements

1. 收集需求

Collect necessary information before planning:

Clarify the goal and scope of the task
For existing codebases only: Investigate existing code to identify affected files and understand existing patterns (skip for new projects with no existing code)
Identify dependencies and constraints
Record external sources: If the user references external sources (Notion pages, Figma designs, GitHub issues, Jira tickets, Slack threads, etc.), collect their URLs/identifiers and include them in the plan's Sources section

Clarification Process:

Identify all unclear points upfront and ask the user in a batch
Proceed with plan creation
If new blockers arise, batch remaining questions and ask again

Topics that may require clarification:

Ambiguous requirements or specifications
Technology choices not explicitly stated
Scope boundaries that are unclear
Priority or ordering preferences

在规划前收集必要信息：

明确任务的目标与范围
仅针对现有代码库：调研现有代码以确定受影响文件并理解现有模式（无现有代码的新项目可跳过此步骤）
识别依赖关系与约束条件
记录外部来源：如果用户引用了外部资源（Notion页面、Figma设计稿、GitHub议题、Jira工单、Slack线程等），收集其URL/标识符并纳入计划的「来源」部分

澄清流程：

提前识别所有不明确的点，批量向用户询问
开始制定计划
如果出现新的阻碍，将剩余问题批量汇总后再次询问

可能需要澄清的事项：

模糊的需求或规格说明
未明确说明的技术选型
不清晰的范围边界
优先级或排序偏好

2. Analyze and Decompose

2. 分析与拆解

Break down the task into implementable units:

Each task should be a coherent unit of functionality (see Task Granularity for details)
Tasks should have clear inputs and outputs
Note which tasks depend on others (detailed dependency analysis in step 4)

将任务拆解为可执行的单元：

每个任务应是一个连贯的功能单元（详见「任务粒度」章节）
任务需具备清晰的输入与输出
标注任务间的依赖关系（步骤4会进行详细的依赖分析）

3. Create the Plan

3. 制定计划

Task Categories

任务分类

Assign a category to each task. Categories determine the task ID prefix:

Category	Prefix	Target Tasks
`backend`	B	APIs, database, business logic, server-side code
`frontend`	F	UI components, client-side logic, styling
`documentation`	D	README, user guides, tutorials, changelog
`other`	X	Tasks that do not fit into the above categories

Task prefixes are numbered per category: B1, B2, B3... / F1, F2, F3... / D1, D2, D3... / X1, X2, X3...

为每个任务分配分类，分类决定任务ID的前缀：

分类	前缀	适用任务
`backend`	B	API、数据库、业务逻辑、服务器端代码
`frontend`	F	UI组件、客户端逻辑、样式
`documentation`	D	README、用户指南、教程、变更日志
`other`	X	不适合上述分类的任务

任务前缀按分类编号：B1、B2、B3... / F1、F2、F3... / D1、D2、D3... / X1、X2、X3...

Task ID (UUID)

任务ID（UUIDv4）

Each task requires a unique identifier in UUIDv4 format.

Generation: Use any UUID generator (e.g.,

uuidgen

command, online generator, or programming language library).

Format:

xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx

(e.g.,

550e8400-e29b-41d4-a716-446655440000

)

每个任务需要一个UUIDv4格式的唯一标识符。

生成方式：使用任意UUID生成器（如

uuidgen

命令、在线生成器或编程语言库）。

格式：

xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx

（示例：

550e8400-e29b-41d4-a716-446655440000

）

Plan Template

计划模板

Generate a plan with the following structure. See references/plan.md for a complete example.

markdown

undefined

按照以下结构生成计划。完整示例请参考references/plan.md。

markdown

undefined

Implementation Plan: {Title}

Overview

Brief description of what this plan accomplishes.

Goal

Clear statement of the end state after implementation.

Scope

What is included
What is explicitly excluded

What is included
What is explicitly excluded

Prerequisites

Required knowledge or context
Dependencies that must be in place

Required knowledge or context
Dependencies that must be in place

Sources

External references provided as input for this plan. Include URLs, document titles, and a brief note on what each source covers.

Source	URL / Identifier	Description
{Source name}	{URL or identifier}	{What this source covers}

Omit this section if no external sources were provided.

External references provided as input for this plan. Include URLs, document titles, and a brief note on what each source covers.

Source	URL / Identifier	Description
{Source name}	{URL or identifier}	{What this source covers}

Omit this section if no external sources were provided.

Design

Describe the technical design before listing tasks. Include:

Architecture and component structure
Data flow and key interactions
API contracts or interfaces
Key algorithms or business logic

UI/UX Design: For tasks involving user interfaces, include the following design considerations:

Design system (typography, colors, spacing, component library)
User flows and wireframes
Interaction patterns and micro-interactions
Accessibility specifications (WCAG 2.1 AA/AAA)
Design tokens for implementation

Use Mermaid diagrams to visualize complex flows or relationships (see Diagrams for examples).

Describe the technical design before listing tasks. Include:

Architecture and component structure
Data flow and key interactions
API contracts or interfaces
Key algorithms or business logic

UI/UX Design: For tasks involving user interfaces, include the following design considerations:

Design system (typography, colors, spacing, component library)
User flows and wireframes
Interaction patterns and micro-interactions
Accessibility specifications (WCAG 2.1 AA/AAA)
Design tokens for implementation

Use Mermaid diagrams to visualize complex flows or relationships (see Diagrams for examples).

Decisions

Clarifications and decisions made during planning. This section preserves context that would otherwise be lost when implementation starts in a new session.

Topic	Decision	Rationale
Token storage	Access token in memory, refresh token in httpOnly cookie	Balances security and usability
Rate limiting	5 attempts per minute for login	Prevent brute force attacks

Clarifications and decisions made during planning. This section preserves context that would otherwise be lost when implementation starts in a new session.

Topic	Decision	Rationale
Token storage	Access token in memory, refresh token in httpOnly cookie	Balances security and usability
Rate limiting	5 attempts per minute for login	Prevent brute force attacks

Tasks

{Prefix}{N}: {Task Title}

ID:
```
{uuid}
```
Category:
```
{category}
```
File(s):
```
src/models/user
```
(or specific path if modifying existing files)

ID:
```
{uuid}
```
Category:
```
{category}
```
File(s):
```
src/models/user
```
(or specific path if modifying existing files)

Description

What to implement (1-2 paragraphs explaining the purpose and context)

Details

Specific implementation steps
Code patterns to follow
Edge cases to handle

(Include code examples, data structures, API contracts, mockups as needed)

Specific implementation steps
Code patterns to follow
Edge cases to handle

(Include code examples, data structures, API contracts, mockups as needed)

Acceptance Criteria

Verification

How to verify the entire implementation is complete and correct.

Include:

Automated tests: Commands to run (e.g.,
```
pnpm test
```
,
```
pytest
```
)
Manual testing steps: Step-by-step verification procedure
Demo scenario: End-to-end user flow to demonstrate

Example:

Run
```
pnpm test
```
- all tests pass
Manual test: Register → Login → Access protected route → Logout
Verify error cases: Invalid credentials show error message

undefined

How to verify the entire implementation is complete and correct.

Include:

Automated tests: Commands to run (e.g.,
```
pnpm test
```
,
```
pytest
```
)
Manual testing steps: Step-by-step verification procedure
Demo scenario: End-to-end user flow to demonstrate

Example:

Run
```
pnpm test
```
- all tests pass
Manual test: Register → Login → Access protected route → Logout
Verify error cases: Invalid credentials show error message

undefined

4. Analyze Dependencies

4. 分析依赖关系

After creating the plan, analyze the dependency graph to populate

dependsOn

for each task in

plan.json

制定计划后，分析依赖图以在

plan.json

中填充每个任务的

dependsOn

字段。

Dependency Analysis Algorithm

依赖分析算法

Step 1: Build Dependency Graph

For each task, identify:

Direct dependencies (tasks that must complete before this task can start)
Dependents (tasks that depend on this task)

Step 2: Validate No Circular Dependencies

Ensure the dependency graph has no cycles:

Find all tasks with no dependencies → Wave 0
Mark Wave 0 tasks as "scheduled"
For remaining unscheduled tasks:
- If ALL dependencies are scheduled → add to next wave
Repeat step 3 until all tasks are scheduled
If any tasks remain unscheduled, there is a circular dependency → error

Step 3: Record Dependencies in plan.json

For each task, record its direct dependencies in the

dependsOn

array using task UUIDs.

Example:

Given dependencies:

B1 → B2 → B3
B2 → F1

Result in

plan.json

json

{
  "tasks": [
    { "id": "b1-uuid", "title": "B1: Create Model", "status": "pending", "dependsOn": [] },
    { "id": "b2-uuid", "title": "B2: Create Service", "status": "pending", "dependsOn": ["b1-uuid"] },
    { "id": "b3-uuid", "title": "B3: Create API", "status": "pending", "dependsOn": ["b2-uuid"] },
    { "id": "f1-uuid", "title": "F1: Create Form", "status": "pending", "dependsOn": ["b2-uuid"] }
  ]
}

Note: The

status

field tracks task progress:

"pending"

(not started),

"in_progress"

(currently being implemented),

"done"

(passes all acceptance criteria). See references/plan-json-schema.md for full schema.

步骤1：构建依赖图

针对每个任务，识别：

直接依赖（必须在此任务开始前完成的任务）
依赖方（依赖此任务的其他任务）

步骤2：验证无循环依赖

确保依赖图中不存在循环：

找出所有无依赖的任务 → 第0波
将第0波任务标记为「已排期」
对于剩余未排期的任务：
- 如果所有依赖均已排期 → 加入下一波
重复步骤3直至所有任务均已排期
如果仍有任务未排期，则存在循环依赖 → 错误

步骤3：在plan.json中记录依赖关系

为每个任务使用任务UUID在

dependsOn

数组中记录其直接依赖。

示例：

给定依赖关系：

B1 → B2 → B3
B2 → F1

plan.json

中的结果：

json

{
  "tasks": [
    { "id": "b1-uuid", "title": "B1: Create Model", "status": "pending", "dependsOn": [] },
    { "id": "b2-uuid", "title": "B2: Create Service", "status": "pending", "dependsOn": ["b1-uuid"] },
    { "id": "b3-uuid", "title": "B3: Create API", "status": "pending", "dependsOn": ["b2-uuid"] },
    { "id": "f1-uuid", "title": "F1: Create Form", "status": "pending", "dependsOn": ["b2-uuid"] }
  ]
}

注意：

status

字段用于跟踪任务进度：

"pending"

（未开始）、

"in_progress"

（正在实施）、

"done"

（通过所有验收标准）。完整 Schema 请参考references/plan-json-schema.md。

5. Save the Plan

5. 保存计划

Save the plan to

.tasks/

directory:

Directory:
```
.tasks/{YYYY-MM-DD}-{nn}-{slug}/
```
(create if not exists)
- Example:
```
.tasks/2026-01-15-00-user-authentication/
```
- ```
{YYYY-MM-DD}
```
  : Date prefix for chronological ordering
- ```
{nn}
```
  : Two-digit sequence number starting from
```
00
```
  (use 3+ digits if needed:
```
100
```
  ,
```
101
```
  , ...)
- ```
{slug}
```
  : Kebab-case slug derived from the plan title
- Sequence number assignment: List existing directories matching
```
.tasks/{YYYY-MM-DD}-*
```
  , find the highest sequence number, and increment by 1

将计划保存至

.tasks/

目录格式：
```
.tasks/{YYYY-MM-DD}-{nn}-{slug}/
```
（不存在则创建）
- 示例：
```
.tasks/2026-01-15-00-user-authentication/
```
- ```
{YYYY-MM-DD}
```
  ：日期前缀，用于按时间排序
- ```
{nn}
```
  ：两位数字的序列号，从
```
00
```
  开始（如需可使用3位及以上数字：
```
100
```
  、
```
101
```
  ...）
- ```
{slug}
```
  ：由计划标题衍生的短横线分隔式（Kebab-case）标识符
- 序列号分配：列出所有匹配
```
.tasks/{YYYY-MM-DD}-*
```
  的现有目录，找到最大的序列号并加1

Plan Document (

plan.md

)

计划文档（plan.md）

Filename:
```
plan.md
```
Content: The complete plan created in step 3
Language: ALWAYS English (no exceptions)
- plan.md is consumed by AI agents, not humans; English maximizes token efficiency
- This rule overrides any repository-level language settings

文件名：
```
plan.md
```
内容：步骤3中创建的完整计划
语言要求：始终使用英文（无例外）
- plan.md供AI代理使用，而非人类；英文可最大化令牌效率
- 此规则优先级高于任何仓库级别的语言设置

Progress Tracking (

plan.json

)

进度跟踪文件（plan.json）

Save a JSON file alongside the plan for tracking task progress:

Filename:
```
plan.json
```
Purpose: Machine-readable progress tracking for agents and tools
Schema: See references/plan-json-schema.md for the schema definition

在计划旁保存一个JSON文件以跟踪任务进度：

文件名：
```
plan.json
```
用途：供代理与工具读取的机器可读进度跟踪文件
Schema：请参考references/plan-json-schema.md获取Schema定义

6. Plan Review

6. 计划审核

After saving the plan, perform review to ensure quality before implementation.

保存计划后，在实施前进行审核以确保质量。

Review Criteria

审核标准

Both self-review and external review evaluate the plan against these criteria:

Criterion	Description
Completeness	All requirements are covered by tasks
Clarity	Tasks are unambiguous and have sufficient detail
Dependencies	Dependency graph is correct and has no cycles
Granularity	Tasks are coherent functional units, not over-fragmented. Implementation and tests are in the same task
Acceptance Criteria	Each task has verifiable acceptance criteria
Scope	Tasks stay within defined scope boundaries
Risks	Potential risks or blockers are identified

自我审核与外部审核均需依据以下标准评估计划：

标准	描述
完整性	所有需求均被任务覆盖
清晰度	任务明确且具备足够细节
依赖关系	依赖图正确且无循环
粒度	任务为连贯的功能单元，未过度拆分。实施与测试属于同一任务
验收标准	每个任务均具备可验证的验收标准
范围	任务未超出定义的范围边界
风险	已识别潜在风险或阻碍

Review Process

审核流程

Self-review the plan first (basic quality check)
- Verify all tasks have clear acceptance criteria
- Check for missing dependencies or circular dependencies
- Ensure detail level is sufficient for implementation
- Confirm scope boundaries are clear
Launch review subagent (external quality check)
- Request review of the plan document (
```
plan.md
```
  )
- Keep the agent ID in session memory for potential re-review
Process review findings
- Identify all issues and suggestions from subagent response
If issues exist:
- Fix all identified issues in
```
plan.md
```
  and
```
plan.json
```
- Perform self-review again
- Resume the same subagent using the stored agent ID
- Repeat until external review passes
If no issues:
- External review passed
- Plan is ready for implementation

首先进行自我审核（基础质量检查）
- 验证所有任务均具备清晰的验收标准
- 检查是否存在缺失的依赖或循环依赖
- 确保细节程度足以支持实施
- 确认范围边界清晰
启动审核子代理（subagent）（外部质量检查）
- 请求审核计划文档（
```
plan.md
```
  ）
- 将代理ID保存在会话内存中，以便后续可能的重新审核
处理审核结果
- 识别子代理回复中的所有问题与建议
若存在问题：
- 在
```
plan.md
```
  与
```
plan.json
```
  中修复所有已识别的问题
- 再次进行自我审核
- 使用存储的代理ID重新启动同一子代理
- 重复此过程直至外部审核通过
若无问题：
- 外部审核通过
- 计划可进入实施阶段

Guidelines

指南

Diagrams

图表

Actively use diagrams to make plans clearer and easier to understand. All diagrams MUST be written in Mermaid format.

When to use diagrams:

System architecture or component relationships (use flowchart or C4 diagram)
Data flow or process sequences (use sequence diagram)
State transitions (use state diagram)
Entity relationships (use ER diagram)

Example - Sequence Diagram:

mermaid

sequenceDiagram
    participant Client
    participant API
    participant AuthService
    participant DB

    Client->>API: POST /auth/login
    API->>AuthService: login(email, password)
    AuthService->>DB: findUser(email)
    DB-->>AuthService: user
    AuthService-->>API: {accessToken, refreshToken}
    API-->>Client: 200 OK with tokens

积极使用图表使计划更清晰易懂。所有图表必须使用Mermaid格式编写。

使用场景：

系统架构或组件关系（使用流程图或C4图）
数据流或流程序列（使用序列图）
状态转换（使用状态图）
实体关系（使用ER图）

示例 - 序列图：

mermaid

sequenceDiagram
    participant Client
    participant API
    participant AuthService
    participant DB

    Client->>API: POST /auth/login
    API->>AuthService: login(email, password)
    AuthService->>DB: findUser(email)
    DB-->>AuthService: user
    AuthService-->>API: {accessToken, refreshToken}
    API-->>Client: 200 OK with tokens

Task Granularity

任务粒度

Each task should represent a coherent unit of functionality:

Represent a coherent unit of functionality that can be independently verified
Group closely related changes together within the same build unit (e.g., model + service layer + route handler in a single application)
Split across build unit boundaries — when changes span different build units (e.g., separate packages in a monorepo such as BFF, backend service, and frontend), create separate tasks for each unit. Different build units have independent build, test, and deploy processes, making them natural task boundaries.
Split only when a task has a genuinely different concern or can be tested in isolation
Implementation and tests are always a single task — never separate test code into its own task. Each task includes writing the production code AND its corresponding tests. Acceptance criteria should reflect both implementation correctness and test coverage.

Do NOT split tasks based on file count or estimated time alone. Over-fragmentation (e.g., separating a model from its directly associated service, or separating tests from their implementation) makes implementation harder, not easier.

每个任务应代表一个连贯的功能单元：

代表可独立验证的连贯功能单元
将紧密相关的变更分组在同一构建单元内（例如，单应用中的模型+服务层+路由处理器）
跨构建单元边界拆分 — 当变更涉及不同构建单元时（例如，单体仓库中的独立包如BFF、后端服务与前端），为每个单元创建单独的任务。不同的构建单元拥有独立的构建、测试与部署流程，是天然的任务边界。
仅当任务涉及完全不同的关注点或可独立测试时才进行拆分
实施与测试始终属于同一任务 — 切勿将测试代码拆分为单独任务。每个任务包括编写生产代码及其对应的测试。验收标准应同时反映实施正确性与测试覆盖率。

请勿仅根据文件数量或预估时间拆分任务。过度拆分（例如，将模型与其直接关联的服务分离，或将测试与实施分离）会使实施更困难，而非更简单。

Detail Level

细节程度

CRITICAL: The plan must contain ALL information needed for implementation. The implementer cannot know what is not written in the plan, even if you (the plan author) know it. Write as if the implementer has no context beyond what is in the plan document.

Include enough detail that another engineer can implement without asking questions:

Specific file paths
Function/class names to create or modify
Data structures and types
Error handling requirements
Integration points
Design decisions and their rationale
Edge cases and how to handle them
Any assumptions made during planning

关键要求：计划必须包含实施所需的所有信息。实施人员无法知晓计划中未写明的内容，即使计划作者知道这些信息。撰写计划时，需假设实施人员除计划文档外无其他上下文。

需包含足够细节，使其他工程师无需询问即可完成实施：

具体的文件路径
需创建或修改的函数/类名称
数据结构与类型
错误处理要求
集成点
设计决策及其理由
边缘情况及处理方式
规划过程中做出的任何假设

What to Avoid

注意事项

Do not include design decisions that need discussion (flag these as blockers)
Do not include tasks outside the stated scope
Do not create circular dependencies between tasks

请勿包含需要讨论的设计决策（将这些标记为阻碍）
请勿包含超出既定范围的任务
请勿在任务间创建循环依赖

References

参考资料

references/plan.md - Complete example plan
references/plan.json - Corresponding progress tracking file
references/plan-json-schema.md - JSON schema definition

references/plan.md - 完整示例计划
references/plan.json - 对应的进度跟踪文件
references/plan-json-schema.md - JSON Schema定义

impl-plan

Original

Translation

Implementation Plan Skill

实施规划技能

Workflow

工作流程

1. Gather Requirements

1. 收集需求

2. Analyze and Decompose

2. 分析与拆解

3. Create the Plan

3. 制定计划

Task Categories

任务分类

Task ID (UUID)

任务ID（UUIDv4）

Plan Template

计划模板

Implementation Plan: {Title}

Implementation Plan: {Title}

Overview

Overview

Goal

Goal

Scope

Scope

Prerequisites

Prerequisites

Sources

Sources

Design

Design

Decisions

Decisions

Tasks

Tasks

{Prefix}{N}: {Task Title}

{Prefix}{N}: {Task Title}

Description

Description

Details

Details

Acceptance Criteria

Acceptance Criteria

Verification

Verification

4. Analyze Dependencies

4. 分析依赖关系

Dependency Analysis Algorithm

依赖分析算法

5. Save the Plan

5. 保存计划

Plan Document (plan.md)

计划文档（plan.md）

Progress Tracking (plan.json)

进度跟踪文件（plan.json）

6. Plan Review

6. 计划审核

Review Criteria

审核标准

Review Process

审核流程

Guidelines

指南

Diagrams

图表

Task Granularity

任务粒度

Detail Level

细节程度

What to Avoid

注意事项

References

参考资料

Plan Document (
`plan.md`
)

Progress Tracking (
`plan.json`
)