implementation-planner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementation Planner

实施计划制定工具

Overview

概述

Create detailed implementation plans through an interactive, iterative process. Be skeptical, thorough, and work collaboratively with the user to produce high-quality technical specifications with proper separation of working notes from deliverables.

Language-Agnostic Approach: This skill is language-agnostic and delegates to language-specific guidelines skills (e.g.,

go-dev-guidelines

for Go projects) for all coding standards, testing patterns, naming conventions, and architectural decisions. Always detect the project language and activate the appropriate guidelines skill at the start of planning.

Agent-First Strategy: This skill uses the Task tool extensively to spawn parallel research agents for maximum efficiency:

GitHub Issue Analysis - Invoke
```
github-issue-reader
```
skill immediately when issue number provided
Parallel Research - Launch 4-6 Task agents concurrently (using
```
Explore
```
or
```
general-purpose
```
subagent types)
Verification - Spawn Task agents to verify user corrections and validate findings
Optional Draft Generation - For complex plans, spawn agent to generate initial structure
Optional Validation - Spawn agent to cross-check plan accuracy before presenting

Task agents handle all information gathering, while the main context handles user interaction and decision-making.

Note: Use the built-in agent types (

Explore

for codebase searches,

general-purpose

for complex tasks) via the Task tool. No custom agent definitions needed.

通过交互式、迭代的流程创建详细的实施计划。保持严谨、全面的态度，与用户协作生成高质量的技术规范，确保工作笔记与交付物清晰分离。

语言无关性方法：此技能与语言无关，所有编码标准、测试模式、命名约定和架构决策均委托给特定语言的指南技能（例如Go项目使用

go-dev-guidelines

）。规划开始时，务必检测项目语言并激活相应的指南技能。

Agent优先策略：此技能大量使用Task工具来生成并行研究Agent，以实现最高效率：

GitHub Issue分析 - 提供Issue编号后，立即调用
```
github-issue-reader
```
技能
并行研究 - 同时启动4-6个Task Agent（使用
```
Explore
```
或
```
general-purpose
```
子Agent类型）
验证 - 生成Task Agent以验证用户的修正内容并确认研究结果
可选草稿生成 - 针对复杂计划，生成Agent来创建初始结构
可选验证 - 在呈现计划前，生成Agent以交叉检查计划的准确性

Task Agent负责所有信息收集工作，主上下文则处理用户交互和决策制定。

注意：通过Task工具使用内置Agent类型（代码库搜索用

Explore

，复杂任务用

general-purpose

），无需自定义Agent定义。

Quick Start

快速开始

Use the

init_plan.py

script to quickly set up the plan structure:

For GitHub issue-based plans (recommended):

bash

scripts/init_plan.py <issue-number> --type issue

Example:

scripts/init_plan.py 123 --type issue

For ad-hoc plans:

bash

scripts/init_plan.py <plan-name> --type adhoc

Example:

scripts/init_plan.py refactor-auth --type adhoc

This creates a complete plan directory with all template files ready for customization.

使用

init_plan.py

脚本快速搭建计划结构：

基于GitHub Issue的计划（推荐）：

bash

scripts/init_plan.py <issue-number> --type issue

示例：

scripts/init_plan.py 123 --type issue

临时计划：

bash

scripts/init_plan.py <plan-name> --type adhoc

示例：

scripts/init_plan.py refactor-auth --type adhoc

此命令会创建一个完整的计划目录，包含所有可自定义的模板文件。

Workflow Decision Tree

工作流决策树

Start by determining what information is available and launching agents immediately:

Check for GitHub Issue:
- If issue number provided → Launch
```
github-issue-reader
```
  agent immediately (don't wait!)
- If no issue exists → Prompt user to create one for history tracking
- If user wants ad-hoc plan → Proceed with ad-hoc workflow
Detect language and activate guidelines:
- Identify project language (Go, Python, TypeScript, etc.)
- Activate appropriate guidelines skill (e.g., go-dev-guidelines)
- Use throughout planning for coding patterns and architecture
Launch parallel research tasks:
- While waiting for user input, launch 4-6 Task tool invocations concurrently:
  - Codebase exploration (Explore subagent)
  - Pattern discovery (Explore subagent)
  - Testing strategy (Explore subagent)
  - Architecture analysis (general-purpose subagent)
  - Guidelines verification (Explore subagent)
- Task agents gather information in parallel for maximum efficiency
Parameters provided (file path, ticket reference)?
- YES → Read files immediately after agents return results
- NO → Request task description and context from user
After gathering context:
- Create TodoWrite task list to track planning process
- Review Task agent findings and read identified files
- Present comprehensive findings with focused questions
After alignment on approach:
- Optionally use Task tool to generate draft for complex plans
- Create plan structure outline
- Get feedback on structure
- Generate the four structured files following language guidelines
- Optionally use Task tool to validate accuracy before presenting

首先确定可用信息并立即启动Agent：

检查GitHub Issue：
- 若提供Issue编号 → 立即启动
```
github-issue-reader
```
  Agent（不要等待！）
- 若不存在Issue → 提示用户创建一个用于历史跟踪
- 若用户需要临时计划 → 按照临时工作流推进
检测语言并激活指南：
- 确定项目语言（Go、Python、TypeScript等）
- 激活相应的指南技能（例如go-dev-guidelines）
- 在整个规划过程中，使用该技能获取编码模式和架构相关内容
启动并行研究任务：
- 在等待用户输入的同时，并发启动4-6个Task工具调用：
  - 代码库探索（Explore子Agent）
  - 模式发现（Explore子Agent）
  - 测试策略（Explore子Agent）
  - 架构分析（general-purpose子Agent）
  - 指南验证（Explore子Agent）
- Task Agent并行收集信息，以实现最高效率
是否提供参数（文件路径、工单引用）？
- 是 → Agent返回结果后立即读取所有提供的文件
- 否 → 向用户请求任务描述和上下文信息
收集上下文后：
- 创建TodoWrite任务列表以跟踪规划流程
- 查看Task Agent的研究结果并读取指定文件
- 呈现全面的研究结果并提出针对性问题
达成方法共识后：
- 针对复杂计划，可选择使用Task工具生成草稿
- 创建计划结构大纲
- 获取用户对结构的反馈
- 遵循语言指南生成四个结构化文件
- 可选：在呈现前使用Task工具验证内容准确性

Step 1: Context Gathering & Initial Analysis

步骤1：上下文收集与初始分析

Activate Language-Specific Guidelines

激活特定语言指南

BEFORE STARTING: Determine the project's primary language and activate the appropriate guidelines skill:

Detect Project Language:
- Look at the codebase structure and file extensions
- Check for language-specific files (go.mod, package.json, requirements.txt, etc.)
- If unclear, ask the user
Activate Guidelines Skill:
- Go projects → Use
```
go-dev-guidelines
```
  skill for all coding standards, testing patterns, and architecture decisions
- Other languages → Use appropriate language-specific guidelines if available
- These skills provide the coding standards, testing patterns, and architectural patterns to follow
Apply Throughout Planning:
- Reference the guidelines skill when making architectural decisions
- Follow testing patterns from the guidelines (e.g., TDD with testify/require for Go)
- Use naming conventions and project structure from guidelines
- Include guidelines-compliant code examples in the plan

开始前：确定项目的主要语言并激活相应的指南技能：

检测项目语言：
- 查看代码库结构和文件扩展名
- 检查特定语言的文件（如go.mod、package.json、requirements.txt等）
- 若不确定，询问用户
激活指南技能：
- Go项目 → 使用
```
go-dev-guidelines
```
  技能获取所有编码标准、测试模式和架构决策
- 其他语言 → 若有可用的特定语言指南则使用
- 这些技能会提供需遵循的编码标准、测试模式和架构模式
在规划全程应用：
- 制定架构决策时参考指南技能
- 遵循指南中的测试模式（例如Go语言使用testify/require的TDD模式）
- 使用指南中的命名约定和项目结构
- 在计划中包含符合指南的代码示例

Determine Plan Type and GitHub Issue

确定计划类型与GitHub Issue

NEXT: Determine if this is an issue-based or ad-hoc plan:

Check for GitHub Issue Number:
- Look for issue number in parameters (e.g., "123", "#123", "issue 123")
- If found, launch github-issue-reader agent immediately to gather comprehensive issue information
- Plans for issues are stored in
```
.docs/issues/<issue-number>/
```
If No Issue Number Provided:
- Ask user: "Is this related to a GitHub issue? If so, please provide the issue number, or I can help you create one for tracking purposes."
- If user provides issue number: Launch github-issue-reader agent
- If user wants to create an issue: Help create it first with
```
gh issue create
```
- If user wants ad-hoc plan: Proceed without issue, store in
```
.docs/adhoc/<plan-name>/
```
GitHub Issue Analysis:
- Invoke the
```
github-issue-reader
```
  skill using Skill tool to gather:
  - Issue title, description, and labels
  - All comments and discussion threads
  - Linked PRs and cross-references
  - Assignees and milestones
  - Related issues and context
- Skill returns comprehensive analysis to main context
- Don't wait for user confirmation - start codebase research immediately after skill completes
Benefits of Issue-Based Plans:
- Provides history and tracking
- Links plan to code changes and PRs
- Enables team visibility and discussion
- Recommended for all non-trivial features

下一步：确定是基于Issue的计划还是临时计划：

检查GitHub Issue编号：
- 在参数中查找Issue编号（例如"123"、"#123"、"issue 123"）
- 若找到，立即启动github-issue-reader agent以收集完整的Issue信息
- 基于Issue的计划存储在
```
.docs/issues/<issue-number>/
```
  目录下
若未提供Issue编号：
- 询问用户：“此任务是否关联GitHub Issue？如果是，请提供Issue编号，我也可以帮你创建一个用于跟踪。”
- 若用户提供Issue编号：启动github-issue-reader agent
- 若用户需要创建Issue：使用
```
gh issue create
```
  协助创建
- 若用户需要临时计划：无需Issue即可推进，计划存储在
```
.docs/adhoc/<plan-name>/
```
  目录下
GitHub Issue分析：
- 使用Skill工具调用
```
github-issue-reader
```
  技能以收集：
  - Issue标题、描述和标签
  - 所有评论和讨论线程
  - 关联的PR和交叉引用
  - 经办人及里程碑
  - 相关Issue和上下文
- 技能会向主上下文返回完整的分析结果
- 无需等待用户确认，技能完成后立即开始代码库研究
基于Issue的计划的优势：
- 提供历史记录和跟踪能力
- 将计划与代码变更和PR关联
- 支持团队可见性和讨论
- 推荐用于所有非小型功能

Check for Provided Parameters

检查提供的参数

When the skill is invoked:

If a file path or ticket reference was provided, skip requesting information
Immediately read any provided files FULLY using the Read tool
Begin the research process without delay

调用技能时：

若提供了文件路径或工单引用，跳过信息请求步骤
使用Read工具完整读取所有提供的文件
立即开始研究流程，无需延迟

Read All Mentioned Files

读取所有提及的文件

CRITICAL: Read files completely in the main context:

Use the Read tool WITHOUT limit/offset parameters
DO NOT spawn sub-tasks before reading files in main context
NEVER read files partially - if mentioned, read completely

关键要求：在主上下文中完整读取文件：

使用Read工具时不要添加limit/offset参数
在主上下文读取文件前，不要生成子任务
绝不部分读取文件——只要被提及，就完整读取

Create Task Tracking

创建任务跟踪

Create a TodoWrite task list to track the planning process and ensure nothing is missed.

创建TodoWrite任务列表以跟踪规划流程，确保没有遗漏任何内容。

Spawn Initial Research Tasks

生成初始研究任务

Before asking the user questions, launch multiple Task tool invocations in parallel. Launch ALL these concurrently in a single message for maximum efficiency:

1. GitHub Issue Analysis (if issue-based plan)

Invoke
```
github-issue-reader
```
skill using Skill tool
Gathers: title, description, comments, linked PRs, labels, related issues
Returns: Full context and discussion history

2. Codebase Exploration (Task tool -

Explore

subagent, medium thoroughness)

Prompt: "Find all files related to [feature/task]. Identify relevant directories, modules, and entry points. Return file paths with brief descriptions of their purpose."
Returns: Relevant file paths and structure

3. Pattern Discovery (Task tool -

Explore

subagent, medium thoroughness)

Prompt: "Search for similar implementations to [feature/task] in the codebase. Identify patterns that should be followed, reusable utilities, and existing approaches. Return code examples with file:line references."
Returns: Code patterns and examples

4. Testing Strategy Research (Task tool -

Explore

subagent, medium thoroughness)

Prompt: "Research existing test patterns in this project. Find test utilities, fixtures, mocks, and integration test setup patterns. Map the testing infrastructure and conventions. Return examples with file:line references."
Returns: Test patterns and infrastructure

5. Architecture Analysis (Task tool -

general-purpose

subagent)

Prompt: "Analyze the architecture for [feature/task]. Trace data flow, map integration points and dependencies, identify shared interfaces and contracts. Find configuration and deployment patterns. Return detailed explanations with file:line references."
Returns: Architecture overview and integration points

6. Guidelines Verification (Task tool -

Explore

subagent, quick thoroughness)

Prompt: "Find examples of [language]-specific patterns currently used in the codebase. Identify coding standards, naming conventions, and architectural patterns being followed. Return code examples with file:line references."
Returns: Existing code patterns

IMPORTANT: Launch all Task tool calls in a single message (parallel execution) for maximum efficiency.

在向用户提问前，并行启动多个Task工具调用。为实现最高效率，在一条消息中同时启动所有以下任务：

1. GitHub Issue分析（若为基于Issue的计划）

使用Skill工具调用
```
github-issue-reader
```
技能
收集内容：标题、描述、评论、关联PR、标签、相关Issue
返回结果：完整上下文和讨论历史

2. 代码库探索（Task工具 -

Explore

子Agent，中等细致度）

提示：“查找与[功能/任务]相关的所有文件，识别相关目录、模块和入口点。返回文件路径及其用途的简要说明。”
返回结果：相关文件路径和结构

3. 模式发现（Task工具 -

Explore

子Agent，中等细致度）

提示：“在代码库中搜索与[功能/任务]类似的实现，识别需遵循的模式、可复用的工具和现有方案。返回包含文件:行号引用的代码示例。”
返回结果：代码模式和示例

4. 测试策略研究（Task工具 -

Explore

子Agent，中等细致度）

提示：“研究此项目中现有的测试模式，查找测试工具、fixtures、mocks和集成测试设置模式。梳理测试基础设施和约定。返回包含文件:行号引用的示例。”
返回结果：测试模式和基础设施

5. 架构分析（Task工具 -

general-purpose

子Agent）

提示：“分析[功能/任务]的架构，追踪数据流，梳理集成点和依赖关系，识别共享接口和契约。查找配置和部署模式。返回包含文件:行号引用的详细说明。”
返回结果：架构概述和集成点

6. 指南验证（Task工具 -

Explore

子Agent，快速细致度）

提示：“查找代码库中当前使用的[语言]特定模式，识别正在遵循的编码标准、命名约定和架构模式。返回包含文件:行号引用的代码示例。”
返回结果：现有代码模式

重要提示：在一条消息中同时启动所有Task工具调用（并行执行）以实现最高效率。

Read Research Results

查看研究结果

After research tasks complete:

Read ALL files identified as relevant
Read them FULLY into the main context
Ensure complete understanding before proceeding

研究任务完成后：

读取所有被标记为相关的文件
将所有文件完整读取到主上下文
确保完全理解后再推进

Present Informed Understanding

呈现已明确的理解

After research, present findings with specific questions:

Based on the ticket and research of the codebase, the task requires [accurate summary].

Found:
- [Current implementation detail with file:line reference]
- [Relevant pattern or constraint discovered]
- [Potential complexity or edge case identified]

Questions that research couldn't answer:
- [Specific technical question requiring human judgment]
- [Business logic clarification]
- [Design preference affecting implementation]

Only ask questions that cannot be answered through code investigation.

研究完成后，呈现结果并提出具体问题：

基于工单和代码库研究，此任务需要[准确摘要]。

研究发现：
- [当前实现细节，包含文件:行号引用]
- [发现的相关模式或约束]
- [识别出的潜在复杂性或边缘情况]

研究无法解答的问题：
- [需要人工判断的特定技术问题]
- [业务逻辑澄清需求]
- [影响实现的设计偏好]

仅提出无法通过代码调查解答的问题。

Step 2: Research & Discovery

步骤2：研究与发现

Verify User Corrections

验证用户修正内容

If the user corrects any misunderstanding:

DO NOT just accept the correction
Spawn verification Task agents immediately to confirm the correct information
Launch multiple Task tool invocations in parallel to research specific areas mentioned
Read the specific files/directories identified by Task agents
Only proceed once facts are verified through code

若用户纠正了任何误解：

不要直接接受修正内容
立即生成验证用Task Agent以确认正确信息
并行启动多个Task工具调用，研究用户提及的特定领域
读取Task Agent指定的文件/目录
仅在通过代码验证事实后再推进

Update Task Tracking

更新任务跟踪

Update TodoWrite list to track exploration tasks and Task agent launches.

更新TodoWrite列表以跟踪探索任务和Task Agent的启动情况。

Spawn Follow-Up Research Tasks

生成后续研究任务

Based on initial findings and user input, launch additional Task tool invocations in parallel:

Deep Dive Research (Task tool - as needed):

Dependency Impact - "Map all affected systems and dependencies for [feature]. Find all integration points and impacted code. Return file:line references."
Migration Strategy - "Research data migration patterns in the codebase. Find examples of previous migrations. Return patterns with file:line references."
Performance Analysis - "Find performance-critical code paths related to [feature]. Identify bottlenecks and optimization patterns. Return file:line references."
Security Pattern - "Identify security patterns currently used for [related feature]. Find authentication, authorization, and validation patterns. Return examples with file:line references."
Error Handling - "Research existing error handling patterns in the codebase. Find how errors are created, wrapped, and handled. Return examples with file:line references."

For each Task agent:

Use
```
Explore
```
subagent for codebase searches (specify thoroughness level)
Use
```
general-purpose
```
subagent for complex analysis
Each should return specific file:line references and code examples
Launch all in a single message for parallel execution
Wait for ALL to complete before proceeding

基于初始研究结果和用户输入，并行启动额外的Task工具调用：

深度研究（Task工具 - 根据需要使用）：

依赖影响 - “梳理[功能]影响的所有系统和依赖，查找所有集成点和受影响的代码。返回文件:行号引用。”
迁移策略 - “研究代码库中的数据迁移模式，查找之前的迁移示例。返回包含文件:行号引用的模式。”
性能分析 - “查找与[功能]相关的性能关键代码路径，识别瓶颈和优化模式。返回文件:行号引用。”
安全模式 - “识别当前用于[相关功能]的安全模式，查找认证、授权和验证模式。返回包含文件:行号引用的示例。”
错误处理 - “研究代码库中现有的错误处理模式，查找错误的创建、包装和处理方式。返回包含文件:行号引用的示例。”

对于每个Task Agent：

代码库搜索使用
```
Explore
```
子Agent（指定细致度级别）
复杂分析使用
```
general-purpose
```
子Agent
每个Agent都应返回具体的文件:行号引用和代码示例
在一条消息中同时启动所有调用以实现并行执行
等待所有调用完成后再推进

Present Findings with Code Examples

呈现包含代码示例的研究结果

Based on research, here's what was found:

**Current State:**
- In `<file-path>:<line-range>`, the [component] uses:
  ```<language>
  // existing code pattern
  // show actual code from codebase

Pattern to follow: [describe existing pattern with code example]
Related patterns found in [other files with line numbers]

Design Options:

[Option A with code sketch following language guidelines] - [pros/cons]
[Option B with code sketch following language guidelines] - [pros/cons]

Open Questions:

[Technical uncertainty]
[Design decision needed]

Which approach aligns best with your vision?


**Important:** All code examples must follow the patterns from the language-specific guidelines skill (e.g., go-dev-guidelines for Go projects).

基于研究，以下是发现的内容：

**当前状态**：
- 在`<file-path>:<line-range>`中，[组件]使用了：
  ```<language>
  // 现有代码模式
  // 展示代码库中的实际代码

需遵循的模式：[使用代码示例描述现有模式]
在[其他带行号的文件]中发现了相关模式

设计选项：

[选项A，包含遵循语言指南的代码框架] - [优缺点]
[选项B，包含遵循语言指南的代码框架] - [优缺点]

待解决问题：

[技术不确定性]
[需要做出的设计决策]

哪种方案最符合你的预期？


**重要提示**：所有代码示例必须遵循特定语言指南技能中的模式（例如Go项目使用go-dev-guidelines）。

Step 3: Plan Structure Development

步骤3：计划结构开发

Once aligned on approach:

Create initial plan outline with phases
Get feedback on structure before writing details
Determine task name for the directory structure

达成方法共识后：

创建包含阶段划分的初始计划大纲
在编写细节前获取用户对结构的反馈
确定目录结构使用的任务名称

Optional: Draft Generation Task

可选：草稿生成任务

For complex plans, consider using Task tool to generate initial draft:

Plan Draft Task (Task tool -
```
general-purpose
```
subagent)
- Prompt: "Based on all research findings about [feature], generate an initial implementation plan structure. Include phases, file references with line numbers, code examples following [language] guidelines, testing strategy, and success criteria. Return a structured plan draft."
- Uses findings from all previous Task agents
- Follows language-specific guidelines
- Creates skeleton with phases, file references, and code examples
- Returns draft for review and refinement in main context
- Human reviews and refines the draft before finalizing

When to use: Complex multi-phase implementations with extensive research findings.

针对复杂计划，可考虑使用Task工具生成初始草稿：

计划草稿任务（Task工具 -
```
general-purpose
```
子Agent）
- 提示：“基于关于[功能]的所有研究结果，生成初始的实施计划结构。包含阶段划分、带行号的文件引用、遵循[语言]指南的代码示例、测试策略和成功标准。返回结构化的计划草稿。”
- 利用所有之前Task Agent的研究结果
- 遵循特定语言指南
- 创建包含阶段、文件引用和代码示例的框架
- 返回草稿供主上下文审核和完善
- 人工审核并完善草稿后再最终确定

适用场景：包含大量研究结果的复杂多阶段实现。

Step 4: Detailed Plan Writing

步骤4：详细计划编写

Initialize Plan Structure

初始化计划结构

Use the

scripts/init_plan.py

script to create the directory structure:

For issue-based plans:

bash

scripts/init_plan.py <issue-number> --type issue

This creates

.docs/issues/<issue-number>/

with four template files.

For ad-hoc plans:

bash

scripts/init_plan.py <plan-name> --type adhoc

This creates

.docs/adhoc/<plan-name>/

with four template files.

使用

scripts/init_plan.py

脚本创建目录结构：

基于Issue的计划：

bash

scripts/init_plan.py <issue-number> --type issue

此命令会创建

.docs/issues/<issue-number>/

目录，并生成四个模板文件。

临时计划：

bash

scripts/init_plan.py <plan-name> --type adhoc

此命令会创建

.docs/adhoc/<plan-name>/

目录，并生成四个模板文件。

Customize the Four Files

自定义四个文件

File 1:

[task-name]-plan.md

(The Implementation Plan)

文件1：

[task-name]-plan.md

（实施计划）

The main deliverable with ALL technical details. Use

assets/plan-template.md

as the base.

Key sections to complete:

Overview: Brief description of what is being implemented and why
Current State Analysis: What exists now, what's missing, key constraints
Desired End State: Specification of end state and verification method
What We're NOT Doing: Explicitly list out-of-scope items
Implementation Approach: High-level strategy and reasoning

For each phase:

Phase name and overview
Development approach following language guidelines (e.g., TDD approach for Go: Write failing tests FIRST)
Changes required with:
- File paths with line numbers
- Current code examples
- Proposed changes with detailed comments (following language-specific patterns)
- Reasoning for changes
Testing strategy following language guidelines (e.g., testify/require for Go, separate positive/negative tests)
Success criteria split into:
- Automated Verification (commands to run)
- Manual Verification (human testing steps)

Include:

Testing Strategy: Unit tests, integration tests, manual steps
Performance Considerations: Implications and metrics
Migration Notes: How to handle existing data/systems
References: Original ticket, key files examined, similar patterns

包含所有技术细节的主要交付物，以

assets/plan-template.md

为基础。

需完成的关键章节：

概述：简要说明要实现的内容及原因
当前状态分析：现有内容、缺失部分、关键约束
预期最终状态：最终状态的规范和验证方法
不包含的内容：明确列出范围外的事项
实施方法：高层策略和理由

每个阶段需包含：

阶段名称和概述
遵循语言指南的开发方法（例如Go语言的TDD方法：先编写失败的测试）
所需的变更，包含：
- 带行号的文件路径
- 当前代码示例
- 带详细注释的提议变更（遵循特定语言模式）
- 变更理由
遵循语言指南的测试策略（例如Go语言使用testify/require，分离正向/负向测试）
拆分后的成功标准：
- 自动化验证（可运行的命令）
- 人工验证（人工测试步骤）

需包含的其他内容：

测试策略：单元测试、集成测试、人工步骤
性能考虑：影响和指标
迁移说明：如何处理现有数据/系统
参考资料：原始工单、检查的关键文件、类似模式

File 2:

[task-name]-research.md

(Research & Working Notes)

文件2：

[task-name]-research.md

（研究与工作笔记）

Captures all research process, questions asked, decisions made. Use

assets/research-template.md

as the base.

Document:

Initial Understanding: What the task seemed to be initially
Research Process: Files examined, findings, sub-tasks spawned
Questions Asked & Answers: Q&A with user, follow-up research
Key Discoveries: Technical discoveries, patterns, constraints
Design Decisions: Options considered, chosen approach, rationale
Open Questions: All must be resolved before finalizing plan
Code Snippets Reference: Relevant existing code and patterns

记录所有研究流程、提出的问题和做出的决策，以

assets/research-template.md

为基础。

需记录的内容：

初始理解：任务最初的预期内容
研究流程：检查的文件、发现的内容、生成的子任务
提出的问题与答案：与用户的问答、后续研究
关键发现：技术发现、模式、约束
设计决策：考虑的选项、选定的方案、理由
待解决问题：在最终确定计划前必须解决所有问题
代码片段参考：相关的现有代码和模式

File 3:

[task-name]-context.md

(Quick Reference Context)

文件3：

[task-name]-context.md

（快速参考上下文）

Quick reference for key information. Use

assets/context-template.md

as the base.

Include:

Quick Summary: 1-2 sentence summary
Key Files & Locations: Files to modify, reference, and test
Dependencies: Code dependencies and external dependencies
Key Technical Decisions: Brief decisions and rationale
Integration Points: How systems integrate
Environment Requirements: Versions, variables, migrations
Related Documentation: Links to other plan files

关键信息的快速参考，以

assets/context-template.md

为基础。

需包含的内容：

快速摘要：1-2句话的摘要
关键文件与位置：需修改、参考和测试的文件
依赖：代码依赖和外部依赖
关键技术决策：简要说明决策和理由
集成点：系统的集成方式
环境要求：版本、变量、迁移需求
相关文档：指向其他计划文件的链接

File 4:

[task-name]-tasks.md

(Task Checklist)

文件4：

[task-name]-tasks.md

（任务清单）

Actionable checklist. Use

assets/tasks-template.md

as the base.

For each task:

Task description in imperative form
File path where work happens
Effort estimate (S/M/L)
Dependencies on other tasks
Acceptance criteria

Include:

Phase verification steps (automated and manual)
Final verification checklist
Notes section for implementation notes

可执行的任务清单，以

assets/tasks-template.md

为基础。

每个任务需包含：

祈使句形式的任务描述
工作所在的文件路径
工作量估算（S/M/L）
对其他任务的依赖
验收标准

需包含的其他内容：

阶段验证步骤（自动化和人工）
最终验证清单
实施说明的备注部分

Important Guidelines

重要指南

Follow Language-Specific Guidelines:

Use the appropriate language guidelines skill (e.g., go-dev-guidelines for Go)
Follow testing patterns from the guidelines (e.g., TDD with testify/require for Go)
Use naming conventions from the guidelines
Follow project structure conventions from the guidelines
Apply architectural patterns from the guidelines
All code examples must be compliant with the language guidelines

Be Detailed with Code:

Include code snippets showing current state
Include code snippets showing proposed changes
Add file:line references throughout
Show concrete examples, not abstract descriptions

Separate Concerns:

Plan file = clean, professional implementation guide
Research file = working notes, questions, discoveries
Context file = quick reference
Tasks file = actionable checklist

Be Skeptical & Thorough:

Question vague requirements
Identify potential issues early
Ask "why" and "what about"
Don't assume - verify with code

No Open Questions in Final Plan:

If open questions arise during planning, STOP
Research or ask for clarification immediately
DO NOT write the plan with unresolved questions
Implementation plan must be complete and actionable
Every decision must be made before finalizing

Success Criteria: Always separate into two categories:

Automated Verification: Commands that can be run by execution agents
Manual Verification: UI/UX, performance, edge cases requiring human testing

遵循特定语言指南：

使用相应的语言指南技能（例如Go项目使用go-dev-guidelines）
遵循指南中的测试模式（例如Go语言使用testify/require的TDD模式）
使用指南中的命名约定
遵循指南中的项目结构约定
应用指南中的架构模式
所有代码示例必须符合语言指南

代码细节要求：

包含展示当前状态的代码片段
包含展示提议变更的代码片段
全程添加文件:行号引用
展示具体示例，而非抽象描述

关注点分离：

计划文件 = 清晰、专业的实施指南
研究文件 = 工作笔记、问题、发现
上下文文件 = 快速参考
任务文件 = 可执行的清单

保持严谨与全面：

质疑模糊的需求
尽早识别潜在问题
多问“为什么”和“如果...会怎样”
绝不假设——通过代码验证

最终计划中不能有待解决问题：

若规划过程中出现待解决问题，暂停推进
立即研究或请求澄清
不要在计划中保留未解决的问题
实施计划必须完整且可执行
最终确定前必须做出所有决策

成功标准：始终分为两类：

自动化验证：可由执行Agent运行的命令
人工验证：需要人工测试的UI/UX、性能、边缘情况

Step 5: Validation & Review

步骤5：验证与审核

Optional: Plan Validation Task

可选：计划验证任务

Before presenting to user, consider using Task tool for validation:

Plan Validation Task (Task tool -
```
general-purpose
```
subagent)
- Prompt: "Review the implementation plan for [feature]. Verify all file paths and line numbers exist and are accurate. Check for conflicts with existing code. Validate that code patterns match the codebase style. Confirm test strategy matches project patterns. Return any issues found."
- Verifies all file paths and line numbers are accurate
- Ensures no conflicts with existing code
- Checks that patterns match existing codebase style
- Validates test strategy matches project patterns
- Returns issues found for correction

When to use: Complex plans with many file references and integration points.

向用户呈现前，可考虑使用Task工具进行验证：

计划验证任务（Task工具 -
```
general-purpose
```
子Agent）
- 提示：“审核[功能]的实施计划，验证所有文件路径和行号是否存在且准确。检查是否与现有代码冲突。验证代码模式是否符合代码库风格。确认测试策略是否匹配项目模式。返回发现的所有问题。”
- 验证所有文件路径和行号的准确性
- 确保与现有代码无冲突
- 检查模式是否符合现有代码库风格
- 验证测试策略是否匹配项目模式
- 返回发现的问题以供修正

适用场景：包含大量文件引用和集成点的复杂计划。

Present Plan to User

向用户呈现计划

After creating the plan structure (and optional validation):

For issue-based plans:

Implementation plan structure created at:
`.docs/issues/<issue-number>/`

Files created:
- `<issue-number>-plan.md` - Detailed implementation plan with code snippets
- `<issue-number>-research.md` - All research notes and working process
- `<issue-number>-context.md` - Quick reference for key information
- `<issue-number>-tasks.md` - Actionable task checklist

GitHub Issue: #<issue-number> - [Issue Title]

For ad-hoc plans:

Implementation plan structure created at:
`.docs/adhoc/<plan-name>/`

Files created:
- `<plan-name>-plan.md` - Detailed implementation plan with code snippets
- `<plan-name>-research.md` - All research notes and working process
- `<plan-name>-context.md` - Quick reference for key information
- `<plan-name>-tasks.md` - Actionable task checklist

The plan includes detailed code examples and file:line references throughout. Research notes are kept separate from implementation details.

Please review:

Are technical details accurate?
Are code examples clear and helpful?
Are phases properly scoped?
Any missing considerations?

Iterate based on feedback and continue refining until the user is satisfied.

创建计划结构（并完成可选验证）后：

基于Issue的计划：

实施计划结构已创建于：
`.docs/issues/<issue-number>/`

创建的文件：
- `<issue-number>-plan.md` - 包含代码片段的详细实施计划
- `<issue-number>-research.md` - 所有研究笔记和工作流程
- `<issue-number>-context.md` - 关键信息的快速参考
- `<issue-number>-tasks.md` - 可执行的任务清单

GitHub Issue: #<issue-number> - [Issue标题]

临时计划：

实施计划结构已创建于：
`.docs/adhoc/<plan-name>/`

创建的文件：
- `<plan-name>-plan.md` - 包含代码片段的详细实施计划
- `<plan-name>-research.md` - 所有研究笔记和工作流程
- `<plan-name>-context.md` - 关键信息的快速参考
- `<plan-name>-tasks.md` - 可执行的任务清单

计划全程包含详细的代码示例和文件:行号引用。研究笔记与实施细节分离存储。

请审核：

技术细节是否准确？
代码示例是否清晰有用？
阶段划分是否合理？
是否有遗漏的考虑事项？

根据反馈迭代完善，直到用户满意为止。

Resources

资源

scripts/

```
init_plan.py
```
- Initialize a new implementation plan structure with all template files

```
init_plan.py
```
- 初始化包含所有模板文件的新实施计划结构

assets/

```
plan-template.md
```
- Template for the main implementation plan
```
research-template.md
```
- Template for research and working notes
```
context-template.md
```
- Template for quick reference context
```
tasks-template.md
```
- Template for actionable task checklist

```
plan-template.md
```
- 主实施计划的模板
```
research-template.md
```
- 研究与工作笔记的模板
```
context-template.md
```
- 快速参考上下文的模板
```
tasks-template.md
```
- 可执行任务清单的模板

File Organization

文件组织

Issue-Based Plans:

.docs/
└── issues/
    └── <issue-number>/
        ├── <issue-number>-plan.md      # Main deliverable (detailed, with code)
        ├── <issue-number>-research.md  # Working notes (kept separate)
        ├── <issue-number>-context.md   # Quick reference
        └── <issue-number>-tasks.md     # Actionable checklist

Ad-Hoc Plans:

.docs/
└── adhoc/
    └── <plan-name>/
        ├── <plan-name>-plan.md      # Main deliverable (detailed, with code)
        ├── <plan-name>-research.md  # Working notes (kept separate)
        ├── <plan-name>-context.md   # Quick reference
        └── <plan-name>-tasks.md     # Actionable checklist

The plan file should be professional and detailed enough to hand to an implementation agent, while the research file captures all the working process that led to the decisions.

基于Issue的计划：

.docs/
└── issues/
    └── <issue-number>/
        ├── <issue-number>-plan.md      # 主要交付物（详细，包含代码）
        ├── <issue-number>-research.md  # 工作笔记（单独存储）
        ├── <issue-number>-context.md   # 快速参考
        └── <issue-number>-tasks.md     # 可执行清单

临时计划：

.docs/
└── adhoc/
    └── <plan-name>/
        ├── <plan-name>-plan.md      # 主要交付物（详细，包含代码）
        ├── <plan-name>-research.md  # 工作笔记（单独存储）
        ├── <plan-name>-context.md   # 快速参考
        └── <plan-name>-tasks.md     # 可执行清单

计划文件需足够专业和详细，可直接交付给执行Agent，而研究文件则记录决策背后的整个工作流程。

implementation-planner

Original

Translation

Implementation Planner

实施计划制定工具

Overview

概述

Quick Start

快速开始

Workflow Decision Tree

工作流决策树

Step 1: Context Gathering & Initial Analysis

步骤1：上下文收集与初始分析

Activate Language-Specific Guidelines

激活特定语言指南

Determine Plan Type and GitHub Issue

确定计划类型与GitHub Issue

Check for Provided Parameters

检查提供的参数

Read All Mentioned Files

读取所有提及的文件

Create Task Tracking

创建任务跟踪

Spawn Initial Research Tasks

生成初始研究任务

Read Research Results

查看研究结果

Present Informed Understanding

呈现已明确的理解

Step 2: Research & Discovery

步骤2：研究与发现

Verify User Corrections

验证用户修正内容

Update Task Tracking

更新任务跟踪

Spawn Follow-Up Research Tasks

生成后续研究任务

Present Findings with Code Examples

呈现包含代码示例的研究结果

Step 3: Plan Structure Development

步骤3：计划结构开发

Optional: Draft Generation Task

可选：草稿生成任务

Step 4: Detailed Plan Writing

步骤4：详细计划编写

Initialize Plan Structure

初始化计划结构

Customize the Four Files

自定义四个文件

File 1: [task-name]-plan.md (The Implementation Plan)

文件1：[task-name]-plan.md（实施计划）

File 2: [task-name]-research.md (Research & Working Notes)

文件2：[task-name]-research.md（研究与工作笔记）

File 3: [task-name]-context.md (Quick Reference Context)

文件3：[task-name]-context.md（快速参考上下文）

File 4: [task-name]-tasks.md (Task Checklist)

文件4：[task-name]-tasks.md（任务清单）

Important Guidelines

重要指南

Step 5: Validation & Review

步骤5：验证与审核

Optional: Plan Validation Task

可选：计划验证任务

Present Plan to User

向用户呈现计划

Resources

资源

scripts/

scripts/

assets/

assets/

File Organization

文件组织

File 1:
`[task-name]-plan.md`
(The Implementation Plan)

文件1：
`[task-name]-plan.md`
（实施计划）

File 2:
`[task-name]-research.md`
(Research & Working Notes)

文件2：
`[task-name]-research.md`
（研究与工作笔记）

File 3:
`[task-name]-context.md`
(Quick Reference Context)

文件3：
`[task-name]-context.md`
（快速参考上下文）

File 4:
`[task-name]-tasks.md`
(Task Checklist)

文件4：
`[task-name]-tasks.md`
（任务清单）