create-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Implementation Plan

创建实施计划

Instructions

操作说明

Create a detailed, high-quality implementation plan as a ticket (tagged

plan

) that adheres to strict quality standards and provides complete guidance for implementation.

创建一份详细、高质量的实施计划工单（标记为

plan

），需严格遵循质量标准，为实施工作提供完整指导。

Phase 1: Understanding & Validation

第一阶段：需求理解与验证

Step 0: Extract Original Issue/Task Requirements (MANDATORY)

步骤0：提取原始需求/任务要求（必填）

CRITICAL: Before creating any plan, extract ALL requirements from the original issue/task.

bash

undefined

关键要求：在创建任何计划之前，提取原始需求/任务中的所有要求。

bash

undefined

If triggered by a GitHub issue

如果由GitHub issue触发

gh issue view <number>


Create exhaustive requirements list:
- Every functional requirement stated
- Every acceptance criterion listed
- Every edge case mentioned
- Every error handling requirement
- Any implicit requirements (derive from context)

**Store this list - the plan MUST cover 100% of these requirements.**

gh issue view <number>


创建详尽的需求列表：
- 所有明确列出的功能需求
- 所有验收标准
- 所有提及的边缘情况
- 所有错误处理要求
- 任何隐含需求（从上下文推导）

**保存此列表** - 计划必须覆盖这些需求的100%。

Step 1: Understand the Request

步骤1：理解需求请求

Review the report or analysis that triggered this plan
Map each requirement from Step 0 to plan items
Identify the type of plan needed:
- Feature: New functionality
- Refactor: Code restructuring
- Fix: Bug fix or issue resolution
- Enhancement: Improvement to existing feature

审阅触发此计划的报告或分析内容
将步骤0中的每个需求映射到计划项
确定所需计划的类型：
- Feature（功能开发）：新增功能
- Refactor（代码重构）：代码结构调整
- Fix（问题修复）：缺陷修复或问题解决
- Enhancement（功能优化）：现有功能改进

Step 2: Audit the Codebase

步骤2：代码库审计

CRITICAL: Never create a plan without thorough codebase understanding

For each item in the report, perform comprehensive analysis:

Use the audit skill if needed for deep investigation
Identify affected files - Which files will change?
Find existing patterns - How is similar code structured?
Check AGENTS.md files - What are the rules for this area?
Analyze types - What existing types can be reused?
Identify dependencies - What depends on what we're changing?
Find naming patterns - How should new files be named?

DO NOT SKIP THIS STEP - Rushed plans lead to bad implementations

关键要求：绝不跳过此步骤，未充分理解代码库就创建的计划会导致糟糕的实施结果

针对报告中的每个项，执行全面分析：

如需深入调查，使用审计技能
识别受影响文件 - 哪些文件会被修改？
查找现有模式 - 类似代码的结构是怎样的？
检查AGENTS.md文件 - 该区域的规则是什么？
分析类型定义 - 可以复用哪些现有类型？
识别依赖关系 - 我们要修改的代码被哪些部分依赖？
查找命名模式 - 新文件应如何命名？

请勿跳过此步骤 - 仓促制定的计划会导致不良的实施结果

Step 3: AGENTS.md Compliance Check

步骤3：AGENTS.md合规性检查

Read ALL relevant

AGENTS.md

files in:

Project root
Affected directories
Related modules

Extract requirements:

Naming conventions
Architecture patterns
Type requirements
File organization rules
Code style standards

阅读以下位置的所有相关

AGENTS.md

文件：

项目根目录
受影响的目录
相关模块

提取其中的要求：

命名规范
架构模式
类型定义要求
文件组织规则
代码风格标准

Phase 2: Plan Structure & Naming

第二阶段：计划结构与命名

Step 1: Choose Plan Title

步骤1：选择计划标题

Format:

Plan: [descriptive title]

Rules:

Be specific and descriptive
Reflect actual work (not vague like "improvements")

Examples:

```
Plan: Implement user authentication
```
✅
```
Plan: Refactor database layer
```
✅
```
Plan: New features
```
❌ (too vague)

格式：

Plan: [描述性标题]

规则：

具体且具有描述性
反映实际工作内容（避免“改进”这类模糊表述）

示例：

```
Plan: Implement user authentication
```
✅（正确）
```
Plan: Refactor database layer
```
✅（正确）
```
Plan: New features
```
❌（错误，过于模糊）

Step 2: Determine File Names for Implementation

步骤2：确定实施所需的文件名

CRITICAL RULES:

❌ NEVER create migration files like
```
foo_v2.ts
```
,
```
foo-new.ts
```
,
```
foo-enhanced.ts
```
❌ NEVER use temporary naming like
```
simple-*.ts
```
,
```
temp-*.ts
```
✅ ALWAYS use proper, final names from the start
✅ ALWAYS follow existing naming patterns in the directory
✅ ALWAYS check AGENTS.md for naming requirements

Process:

Identify existing file naming patterns
Check AGENTS.md for conventions
Choose names that fit the pattern
If unsure, analyze similar existing files
Plan to replace existing files directly (not create duplicates)

关键规则：

❌ 绝不要创建类似
```
foo_v2.ts
```
、
```
foo-new.ts
```
、
```
foo-enhanced.ts
```
的迁移文件
❌ 绝不要使用
```
simple-*.ts
```
、
```
temp-*.ts
```
这类临时命名
✅ 从一开始就使用恰当的最终名称
✅ 始终遵循目录中的现有命名模式
✅ 始终检查AGENTS.md中的命名要求

流程：

识别现有文件命名模式
检查AGENTS.md中的规范
选择符合模式的名称
如有疑问，分析类似的现有文件
计划直接替换现有文件（而非创建重复文件）

Phase 3: Plan Content - Required Sections

第三阶段：计划内容 - 必备章节

Create plan document with ALL of the following sections:

创建包含以下所有章节的计划文档：

1. Overview & Issue Coverage

1. 概述与需求覆盖

markdown

undefined

markdown

undefined

[Plan Title]

[计划标题]

Summary

摘要

[2-3 sentences explaining what and why]

[2-3句话说明计划内容及目的]

Type

类型

[Feature | Refactor | Fix | Enhancement]

Source Issue/Task

来源需求/任务

[Link to GitHub issue or task description]

[GitHub issue链接或任务描述]

Original Requirements (100% Coverage Required)

原始需求（必须100%覆盖）

ALL requirements from source issue/task that this plan MUST address:

#	Requirement	Plan Step(s)
1	[Requirement from issue]	Step X
2	[Requirement from issue]	Step Y, Z
3	[Requirement from issue]	Step W

Coverage Check: X of X requirements mapped to plan steps (must be 100%)

本计划必须解决的来源需求/任务中的所有要求：

序号	需求内容	计划步骤
1	[需求内容]	步骤X
2	[需求内容]	步骤Y、Z
3	[需求内容]	步骤W

覆盖检查：X项需求已映射到计划步骤（必须达到100%）

Status

状态

Open (ticket will be closed when plan is complete)

undefined

待处理（计划完成后关闭工单）

undefined

2. Context & Motivation

2. 背景与动机

markdown

undefined

markdown

undefined

Context

背景

[Why is this needed? What problem does it solve?]

[为什么需要此计划？解决了什么问题？]

Current State

当前状态

[What exists now? What are the limitations?]

[现有情况如何？存在哪些局限性？]

Desired State

预期状态

[What will exist after? What improvements will we gain?]

undefined

[实施后会是什么样？能获得哪些改进？]

undefined

3. AGENTS.md Compliance

3. AGENTS.md合规性

markdown

undefined

markdown

undefined

AGENTS.md Requirements

AGENTS.md要求

Naming Conventions

命名规范

[List relevant naming rules from AGENTS.md]

[列出AGENTS.md中的相关命名规则]

Architecture Requirements

架构要求

[List relevant architectural rules]

[列出相关架构规则]

Type Requirements

类型定义要求

[List type-related rules]

[列出类型相关规则]

Other Guidelines

其他指南

[Any other relevant rules]

undefined

[任何其他相关规则]

undefined

4. Existing Types Analysis

4. 现有类型分析

markdown

undefined

markdown

undefined

Existing Types

现有类型

Types to Reuse

可复用类型

```
TypeName
```
from
```
path/to/file.ts
```
- [what it represents]
[List ALL types that can be reused]

```
TypeName
```
来自
```
path/to/file.ts
```
- [该类型的作用]
[列出所有可复用的类型]

Types to Create

需创建的类型

```
NewTypeName
```
- [what it will represent, why needed]
[Only create if NO existing type works]

```
NewTypeName
```
- [该类型的作用及创建原因]
[仅在没有合适的现有类型时才创建]

Type Guidelines

类型指南

❌ NEVER use
```
any
```
❌ NEVER use
```
unknown
```
(unless absolutely necessary with justification)
✅ ALWAYS prefer existing types
✅ ALWAYS use strict typing

undefined

❌ 绝不要使用
```
any
```
类型
❌ 绝不要使用
```
unknown
```
类型（除非绝对必要并提供理由）
✅ 优先使用现有类型
✅ 始终使用严格类型定义

undefined

5. Impact Analysis

5. 影响分析

markdown

undefined

markdown

undefined

Impact Analysis

影响分析

Files to Modify

需修改的文件

```
path/to/file1.ts
```
- [what changes, why]
```
path/to/file2.ts
```
- [what changes, why]

```
path/to/file1.ts
```
- [修改内容及原因]
```
path/to/file2.ts
```
- [修改内容及原因]

Files to Create

需创建的文件

```
path/to/newfile.ts
```
- [purpose, why not existing file]

```
path/to/newfile.ts
```
- [文件用途，为何不使用现有文件]

Files to Delete

需删除的文件

```
path/to/oldfile.ts
```
- [why removing, what replaces it]

```
path/to/oldfile.ts
```
- [删除原因，替代方案]

Dependencies Affected

受影响的依赖

[List what depends on changed code]
[How will dependencies be updated?]

[列出依赖修改后代码的部分]
[如何更新这些依赖？]

Breaking Changes

破坏性变更

[List any breaking changes]
[How will they be handled?]

undefined

[列出所有破坏性变更]
[如何处理这些变更？]

undefined

6. Implementation Steps

6. 实施步骤

markdown

undefined

markdown

undefined

Implementation Steps

实施步骤

Each step should be:

Specific and actionable
Single responsibility
Ordered correctly (dependencies first)

每个步骤应满足：

具体且可执行
单一职责
顺序正确（先处理依赖项）

Step 1: [Descriptive Title]

步骤1：[描述性标题]

File:

path/to/file.ts

Action: [What to do] Why: [Why this step] Details:

[Specific implementation detail]
[Another detail]

文件：

path/to/file.ts

操作：[具体操作内容] 原因：[此步骤的目的] 细节：

[具体实施细节]
[其他细节]

Step 2: [Next Step]

步骤2：[下一步骤]

[Same structure]

[Continue for all steps]

undefined

[相同结构]

[继续列出所有步骤]

undefined

7. REMOVAL SPECIFICATION ⚠️

7. 移除规范 ⚠️

markdown

undefined

markdown

undefined

REMOVAL SPECIFICATION

移除规范

CRITICAL: This section tracks OLD code that must be REMOVED.

关键要求：本部分跟踪必须移除的旧代码。

Code to Remove

需移除的代码

From

path/to/file1.ts

来自

path/to/file1.ts

Lines X-Y:
```
function oldFunction() {...}
```
- Why removing: Replaced by newFunction
- Replacement: Step 3 in implementation
- Dependencies: Used by A, B, C (all updated in steps 5, 6, 7)

行X-Y：
```
function oldFunction() {...}
```
- 移除原因：被newFunction替代
- 替代方案：实施步骤3
- 依赖情况：被A、B、C使用（均在步骤5、6、7中更新）

File to Delete:

path/to/old-file.ts

需删除的文件：

path/to/old-file.ts

Why removing: Functionality moved to new-file.ts
Replacement: Step 2 creates replacement
Dependencies: Imported by X, Y, Z (all updated in steps 8, 9, 10)

移除原因：功能已迁移至new-file.ts
替代方案：步骤2创建替代文件
依赖情况：被X、Y、Z导入（均在步骤8、9、10中更新）

Removal Checklist

移除检查清单

All deprecated functions removed
All old files deleted
All imports updated
All references updated
No dead code remains

VERIFICATION: At completion, grep for old symbols to ensure complete removal.

undefined

所有废弃函数已移除
所有旧文件已删除
所有导入已更新
所有引用已更新
无死代码残留

验证方式：完成后，使用grep查找旧符号以确保完全移除。

undefined

8. Anti-Patterns to Avoid

8. 需避免的反模式

markdown

undefined

markdown

undefined

Anti-Patterns to Avoid

需避免的反模式

❌ NEVER include:

Migration mechanisms (gradual rollout, feature flags for this)
Fallback mechanisms (keeping old code "just in case")
Risk mitigation (running old and new in parallel)
Backward compatibility layers (unless external API)
Temporary bridges between old and new

✅ ALWAYS instead:

Replace completely and cleanly
Make all necessary changes at once
Remove old code immediately
Trust the plan and execute fully

Why: Half-migrations leave bad code in the codebase forever.

undefined

❌ 绝不要包含：

迁移机制（逐步推出、功能标志等）
回退机制（保留旧代码“以防万一”）
风险缓解措施（同时运行新旧代码）
向后兼容层（除非是外部API）
新旧代码之间的临时桥接

✅ 应始终：

完全、干净地替换
一次性完成所有必要修改
立即移除旧代码
信任计划并完整执行

原因：半迁移状态会导致代码库中永久残留不良代码。

undefined

9. Validation Criteria

9. 验证标准

markdown

undefined

markdown

undefined

Validation Criteria

验证标准

Pre-Implementation Checklist

实施前检查清单

Post-Implementation Checklist

实施后检查清单

All steps completed
All old code removed (per REMOVAL SPEC)
TypeScript compiles (
```
tsc --noEmit
```
)
Linting passes (
```
npm run lint
```
)
Tests pass (if applicable)
No
```
any
```
or
```
unknown
```
types added
AGENTS.md compliance verified
Single responsibility maintained

undefined

所有步骤已完成
所有旧代码已按移除规范移除
TypeScript编译通过（
```
tsc --noEmit
```
）
代码检查通过（
```
npm run lint
```
）
测试通过（如适用）
未添加
```
any
```
或
```
unknown
```
类型
已验证符合AGENTS.md要求
保持单一职责

undefined

Phase 4: Plan Creation & Validation

第四阶段：计划创建与验证

Step 1: Write the Plan

步骤1：编写计划

Create as a ticket using
```
todos_oneshot
```
with tags
```
plan
```
Include ALL required sections above in the ticket description
Be thorough - never skip items

使用
```
todos_oneshot
```
创建标记为
```
plan
```
的工单
在工单描述中包含上述所有必填章节
内容需详尽，绝不跳过任何项

Step 2: Validate Plan Completeness

步骤2：验证计划完整性

Checklist:

100% of original issue/task requirements mapped to plan steps
Overview section complete with requirements table
Context & motivation clear
AGENTS.md compliance documented
Existing types analyzed
Impact analysis thorough
Implementation steps detailed and ordered
Every requirement from issue appears in at least one step
REMOVAL SPECIFICATION complete
Anti-patterns section included
Validation criteria defined
No migration/fallback mechanisms
No temporary file names
No
```
any
```
or
```
unknown
```
types planned

检查清单：

原始需求/任务的100%需求已映射到计划步骤
概述章节包含需求表格
背景与动机清晰
已记录AGENTS.md合规性
已完成现有类型分析
影响分析全面
实施步骤详细且顺序正确
需求中的每一项至少对应一个计划步骤
移除规范完整
包含反模式章节
已定义验证标准
无迁移/回退机制
无临时文件名
未计划使用
```
any
```
或
```
unknown
```
类型

Step 3: Review Against Guidelines

步骤3：对照指南审核

Double-check:

✅ Follows naming conventions from AGENTS.md
✅ Uses existing types where possible
✅ Single responsibility maintained
✅ Complete removal spec included
✅ No migration code planned
✅ All steps are specific and actionable
✅ No items skipped or rushed

再次检查：

✅ 遵循AGENTS.md中的命名规范
✅ 尽可能使用现有类型
✅ 保持单一职责
✅ 包含完整的移除规范
✅ 未计划迁移代码
✅ 所有步骤具体且可执行
✅ 无跳过或仓促处理的项

Step 4: Final Audit Recommendation

步骤4：最终审计建议

Before finalizing, consider:

Should specific areas be audited more deeply?
Are there unknowns that need investigation?
Is more context needed before implementation?

If yes, recommend using the audit skill for those areas.

在最终确定前，考虑：

是否需要对特定区域进行更深入的审计？
是否存在需要调查的未知项？
实施前是否需要更多背景信息？

如果是，建议针对这些区域使用审计技能。

Phase 5: Report to User

第五阶段：向用户汇报

Provide summary:

markdown

undefined

提供以下摘要：

markdown

undefined

Plan Created: [plan-name]

计划已创建：[计划名称]

Location

位置

Saved as ticket tagged

plan

已保存为标记

plan

的工单

Summary

摘要

[Brief description of what the plan covers]

[计划覆盖内容的简要描述]

Key Points

关键点

[Important aspect 1]
[Important aspect 2]
[Important aspect 3]

[重要方面1]
[重要方面2]
[重要方面3]

Files Affected

受影响文件

X files to modify
Y files to create
Z files to delete

X个文件需修改
Y个文件需创建
Z个文件需删除

REMOVAL SPEC

移除规范

[Summary of what will be removed]

[将被移除内容的摘要]

Ready to Implement

可实施状态

The plan is complete and ready for implementation. All required sections are included, AGENTS.md compliance is verified, and the removal specification is thorough. Use

tk show <ticket-id>

to review.

计划已完成，可开始实施。包含所有必填章节，已验证符合AGENTS.md要求，移除规范详尽。使用

tk show <ticket-id>

查看详情。

Next Steps

下一步

Review the plan ticket and begin implementation when ready.

undefined

审阅计划工单，准备就绪后开始实施。

undefined

Critical Principles

核心原则

100% ISSUE COVERAGE - Plan MUST address every requirement from original issue
NEVER RUSH - Thorough planning prevents bad implementations
NEVER SKIP AUDIT - Always understand the codebase first
NEVER CREATE MIGRATIONS - Replace completely, not gradually
NEVER USE TEMPORARY NAMES - Use final, proper names from the start
NEVER SKIP REMOVAL SPEC - Track what must be deleted
NEVER SKIP REQUIREMENT - Every issue requirement MUST have a plan step
ALWAYS USE EXISTING TYPES - Create new types only when necessary
ALWAYS FOLLOW AGENTS.MD - Read and apply all guidelines
ALWAYS BE SPECIFIC - Vague steps lead to bad implementations
ALWAYS THINK HOLISTICALLY - Consider full impact of changes
COMPLETENESS OVER SPEED - A complete plan prevents future problems

100%需求覆盖 - 计划必须解决原始需求中的每一项要求
绝不仓促 - 详尽的规划可避免糟糕的实施结果
绝不跳过审计 - 始终先理解代码库
绝不创建迁移代码 - 完全替换，而非逐步迁移
绝不使用临时名称 - 从一开始就使用最终的恰当名称
绝不跳过移除规范 - 跟踪必须删除的内容
绝不遗漏需求 - 需求中的每一项必须对应一个计划步骤
始终使用现有类型 - 仅在必要时创建新类型
始终遵循AGENTS.md - 阅读并应用所有指南
始终保持具体 - 模糊的步骤会导致糟糕的实施结果
始终全面考虑 - 考虑变更的全部影响
完整性优先于速度 - 完整的计划可避免未来问题

Templates

模板

See

templates/

directory for:

```
feature-plan-template.md
```
- Template for new features
```
refactor-plan-template.md
```
- Template for refactoring
```
fix-plan-template.md
```
- Template for bug fixes

请查看

templates/

目录下的模板：

```
feature-plan-template.md
```
- 新功能计划模板
```
refactor-plan-template.md
```
- 代码重构计划模板
```
fix-plan-template.md
```
- 问题修复计划模板