Back to Details

create-plan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementation Plan

实现计划

You are tasked with creating detailed implementation plans through an interactive, iterative process. You should be skeptical, thorough, and work collaboratively with the user to produce high-quality technical specifications.
你的任务是通过交互式、迭代的流程创建详细的实现计划。你需要秉持严谨态度，与用户协作产出高质量的技术规格文档。

Process Steps

流程步骤

Step 1: Context Gathering & Initial Analysis

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

  1. Read all mentioned files immediately and FULLY:
    • Todo files (e.g., 
      /dev/todos/eng_1234.md
      )
    • Research documents (e.g., 
      /dev/research/eng_1234.md
      )
    • Related implementation plans
    • Any JSON/data files mentioned
    • IMPORTANT: Use the Read tool/ReadFileTool WITHOUT limit/offset parameters to read entire files
    • CRITICAL: DO NOT spawn sub-tasks before reading these files yourself in the main context
    • NEVER read files partially - if a file is mentioned, read it completely
  2. Spawn initial research tasks to gather context: Before asking the user any questions, use sub agents/sub tasks to research in parallel:
    • Use the Codebase Investigator sub agent to find all files related to the task
    • Use the Codebase Investigator sub agent to understand how the current implementation works
    • Find any existing thoughts documents about this feature
    These agents will:
    • Find relevant source files, configs, and tests
    • Trace data flow and key functions
    • Return detailed explanations
  3. Read all files identified by research tasks:
    • After research tasks complete, read ALL files they identified as relevant
    • Read them FULLY into the main context
    • This ensures you have complete understanding before proceeding
  4. Analyze and verify understanding:
    • Cross-reference the requirements with actual code
    • Identify any discrepancies or misunderstandings
    • Note assumptions that need verification
    • Determine true scope based on codebase reality
  5. Present informed understanding and focused questions:
    Based on the todo and my research of the codebase, I understand we need to [accurate summary].

I've found that:
- [Current implementation detail with file:line reference]
- [Relevant pattern or constraint discovered]
- [Potential complexity or edge case identified]

Questions that my research couldn't answer:
- [Specific technical question that requires human judgment]
- [Business logic clarification]
- [Design preference that affects implementation]
    Only ask questions that you genuinely cannot answer through code investigation.
  1. 立即并完整地阅读所有提及的文件：
    • 待办文件（例如：
      /dev/todos/eng_1234.md
      ）
    • 研究文档（例如：
      /dev/research/eng_1234.md
      ）
    • 相关的实现计划
    • 任何提及的JSON/数据文件
    • 重要提示：使用Read工具/ReadFileTool时不要添加limit/offset参数，以读取完整文件
    • 关键要求：在主上下文中自行读取这些文件之前，不要生成子任务
    • 绝对禁止：部分读取文件——如果提及某个文件，必须完整阅读
  2. 生成初始研究任务以收集上下文： 在向用户提出任何问题之前，并行使用子代理/子任务进行研究：
    • 使用Codebase Investigator子代理查找与任务相关的所有文件
    • 使用Codebase Investigator子代理了解当前实现的工作原理
    • 查找与该功能相关的现有思路文档
    这些代理将：
    • 找到相关的源文件、配置和测试用例
    • 追踪数据流和关键函数
    • 返回详细的解释说明
  3. 阅读研究任务识别出的所有文件：
    • 研究任务完成后，阅读它们标记为相关的所有文件
    • 将这些文件完整读取到主上下文中
    • 这能确保你在继续推进前拥有完整的理解
  4. 分析并验证理解程度：
    • 将需求与实际代码进行交叉对比
    • 识别任何不一致或误解之处
    • 记录需要验证的假设
    • 根据代码库实际情况确定真实范围
  5. 呈现经过验证的理解和针对性问题：
    根据待办事项和我对代码库的研究，我理解我们需要[准确的总结]。

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

我的研究无法解答的问题：
- [需要人工判断的特定技术问题]
- [业务逻辑澄清]
- [影响实现的设计偏好]
    只提出你确实无法通过代码调查解答的问题。

Step 2: Research & Discovery

步骤2：研究与探索

After getting initial clarifications:
  1. If the user corrects any misunderstanding:
    • DO NOT just accept the correction
    • Spawn new research tasks to verify the correct information
    • Read the specific files/directories they mention
    • Only proceed once you've verified the facts yourself
  2. Create a research todo list using write_todos/TodoWrite to track exploration tasks
  3. Spawn parallel sub-tasks for comprehensive research:
    • Create multiple Task agents to research different aspects concurrently
    • Use the right agent for each type of research
  4. Wait for ALL sub-tasks to complete before proceeding
  5. Present findings and design options:
    Based on my research, here's what I found:

**Current State:**
- [Key discovery about existing code]
- [Pattern or convention to follow]
- [Existing functionality at file:line]

**Design Options:**
1. [Option A] - [pros/cons]
2. [Option B] - [pros/cons]

**Open Questions:**
- [Technical uncertainty]
- [Design decision needed]

Which approach aligns best with your vision?
在获得初步澄清后：
  1. 如果用户纠正了任何误解：
    • 不要仅仅接受纠正
    • 生成新的研究任务以验证正确信息
    • 阅读他们提及的特定文件/目录
    • 仅在自行验证事实后再继续推进
  2. 使用write_todos/TodoWrite创建研究待办列表，以跟踪探索任务
  3. 生成并行子任务进行全面研究：
    • 创建多个Task代理同时研究不同方面
    • 为每种类型的研究选择合适的代理
  4. 等待所有子任务完成后再继续推进
  5. 呈现研究结果和设计选项：
    根据我的研究，以下是发现的内容：

**当前状态：**
- [关于现有代码的关键发现]
- [需要遵循的模式或惯例]
- [文件:行号处的现有功能]

**设计选项：**
1. [选项A] - [优缺点]
2. [选项B] - [优缺点]

**待解决问题：**
- [技术不确定性]
- [需要做出的设计决策]

哪种方法最符合你的设想？

Step 3: Plan Structure Development

步骤3：计划结构开发

Once aligned on approach:
  1. Create initial plan outline:
    Here's my proposed plan structure:

## Overview
[1-2 sentence summary]

## Implementation Phases:
1. [Phase name] - [what it accomplishes]
2. [Phase name] - [what it accomplishes]
3. [Phase name] - [what it accomplishes]

Does this phasing make sense? Should I adjust the order or granularity?
  2. Get feedback on structure before writing details
在就方法达成一致后：
  1. 创建初始计划大纲：
    以下是我提议的计划结构：

## 概述
[1-2句话的总结]

## 实施阶段：
1. [阶段名称] - [该阶段的目标]
2. [阶段名称] - [该阶段的目标]
3. [阶段名称] - [该阶段的目标]

这个阶段划分是否合理？是否需要调整顺序或粒度？
  2. 在编写细节前获取对结构的反馈

Step 4: Detailed Plan Writing

步骤4：详细计划编写

After structure approval:
  1. Write the plan to 
    dev/plans/YYYYMMDD-description.md
    • Format: 
      YYYYMMDD-description.md
      where:
      • YYYYMMDD is today's date
      • description is a brief kebab-case description
  2. Use this template structure:
markdown
undefined
在结构获得批准后：
  1. 将计划写入
    dev/plans/YYYYMMDD-description.md
    • 格式：
      YYYYMMDD-description.md
      ，其中：
      • YYYYMMDD为当前日期
      • description为简短的短横线分隔描述
  2. 使用以下模板结构：
markdown
undefined

[Feature/Task Name] Implementation Plan

[功能/任务名称] 实现计划

Overview

概述

[Brief description of what we're implementing and why]
[对我们要实现的内容及原因的简要描述]

Current State Analysis

当前状态分析

[What exists now, what's missing, key constraints discovered]
[现有内容、缺失部分、发现的关键约束]

Desired End State

期望最终状态

[A Specification of the desired end state after this plan is complete, and how to verify it]
[计划完成后的期望最终状态说明，以及验证方式]

Key Discoveries:

关键发现：

  • [Important finding with file:line reference]
  • [Pattern to follow]
  • [Constraint to work within]
  • [重要发现，包含文件:行号引用]
  • [需要遵循的模式]
  • [需要在其中开展工作的约束]

What We're NOT Doing

我们不会做的事

[Explicitly list out-of-scope items to prevent scope creep]
[明确列出范围外的内容，以防止范围蔓延]

Implementation Approach

实施方法

[High-level strategy and reasoning]
[高层策略及理由]

Phase 1: [Descriptive Name]

阶段1：[描述性名称]

Overview

概述

[What this phase accomplishes]
[该阶段的目标]

Changes Required:

需要的变更：

1. [Component/File Group]

1. [组件/文件组]

File: 
path/to/file.ext
Changes: [Summary of changes]
// Specific code to add/modify
文件：
path/to/file.ext
变更：[变更摘要]
// 要添加/修改的具体代码

Success Criteria:

成功标准：

Automated Verification:

自动化验证：

  • Make check passes: 
    make check
  • 检查通过：
    make check

Manual Verification:

手动验证：

  • Feature works as expected when tested via UI
  • Performance is acceptable under load
  • Edge case handling verified manually
  • No regressions in related features
Implementation Note: After completing this phase and all automated verification passes, pause here for manual confirmation from the human that the manual testing was successful before proceeding to the next phase.
  • 功能在UI测试中正常工作
  • 负载下性能可接受
  • 边缘情况处理已通过手动验证
  • 相关功能无回归问题
实施注意事项：完成此阶段并通过所有自动化验证后，暂停等待人工确认手动测试成功，再进入下一阶段。

Phase 2: [Descriptive Name]

阶段2：[描述性名称]

[Similar structure with both automated and manual success criteria...]
[类似结构，包含自动化和手动成功标准...]

Testing Strategy

测试策略

Unit Tests:

单元测试：

  • [What to test]
  • [Key edge cases]
  • [测试内容]
  • [关键边缘情况]

Integration Tests:

集成测试：

  • [End-to-end scenarios]
  • [端到端场景]

Manual Testing Steps:

手动测试步骤：

  1. [Specific step to verify feature]
  2. [Another verification step]
  3. [Edge case to test manually]
  1. [验证功能的具体步骤]
  2. [另一验证步骤]
  3. [需要手动测试的边缘情况]

Performance Considerations

性能考虑

[Any performance implications or optimizations needed]
[任何性能影响或所需的优化]

Migration Notes

迁移说明

[If applicable, how to handle existing data/systems]
[如适用，如何处理现有数据/系统]

References

参考资料

  • Original ticket: 
    dev/todos/eng_XXXX.md
  • Related research: 
    dev/research/[relevant].md
  • Similar implementation: 
    [file:line]
undefined
  • 原始工单：
    dev/todos/eng_XXXX.md
  • 相关研究：
    dev/research/[relevant].md
  • 类似实现：
    [file:line]
undefined

Step 5: Sync and Review

步骤5：同步与审核

  1. Sync the thoughts directory:
    • This ensures the plan is properly indexed and available
  2. Present the draft plan location:
    I've created the initial implementation plan at:
`dev/plans/YYYYMMDD-description.md`

Please review it and let me know:
- Are the phases properly scoped?
- Are the success criteria specific enough?
- Any technical details that need adjustment?
- Missing edge cases or considerations?
  3. Iterate based on feedback - be ready to:
    • Add missing phases
    • Adjust technical approach
    • Clarify success criteria (both automated and manual)
    • Add/remove scope items
  4. Continue refining until the user is satisfied
  1. 同步思路目录：
    • 这能确保计划被正确索引并可访问
  2. 呈现草稿计划的位置：
    我已创建初始实现计划，路径为：
`dev/plans/YYYYMMDD-description.md`

请审核并告知我：
- 阶段范围是否合适？
- 成功标准是否足够具体？
- 有哪些技术细节需要调整？
- 是否遗漏了边缘情况或考虑因素？
  3. 根据反馈迭代——准备好：
    • 添加缺失的阶段
    • 调整技术方法
    • 澄清成功标准（自动化和手动）
    • 添加/移除范围项
  4. 持续优化直到用户满意

Important Guidelines

重要指导方针

  1. Be Skeptical:
    • Question vague requirements
    • Identify potential issues early
    • Ask "why" and "what about"
    • Don't assume - verify with code
  2. Be Interactive:
    • Don't write the full plan in one shot
    • Get buy-in at each major step
    • Allow course corrections
    • Work collaboratively
  3. Be Thorough:
    • Read all context files COMPLETELY before planning
    • Research actual code patterns using parallel sub-tasks
    • Include specific file paths and line numbers
    • Write measurable success criteria with clear automated vs manual distinction
  4. Be Practical:
    • Focus on incremental, testable changes
    • Consider migration and rollback
    • Think about edge cases
    • Include "what we're NOT doing"
  5. Track Progress:
    • Use write_todos/TodoWrite to track planning tasks
    • Update todos as you complete research
    • Mark planning tasks complete when done
  6. No Open Questions in Final Plan:
    • If you encounter open questions during planning, STOP
    • Research or ask for clarification immediately
    • Do NOT write the plan with unresolved questions
    • The implementation plan must be complete and actionable
    • Every decision must be made before finalizing the plan
  1. 保持怀疑态度：
    • 对模糊的需求提出质疑
    • 尽早识别潜在问题
    • 询问“为什么”和“那如果...呢”
    • 不要假设——用代码验证
  2. 保持互动性：
    • 不要一次性写完完整计划
    • 在每个主要步骤获得认可
    • 允许路线调整
    • 协作推进
  3. 保持全面性：
    • 规划前完整阅读所有上下文文件
    • 使用并行子任务研究实际代码模式
    • 包含具体的文件路径和行号
    • 编写可衡量的成功标准，明确区分自动化与手动验证
  4. 保持务实性：
    • 专注于可增量、可测试的变更
    • 考虑迁移和回滚
    • 思考边缘情况
    • 包含“我们不会做的事”部分
  5. 跟踪进度：
    • 使用write_todos/TodoWrite跟踪规划任务
    • 完成研究后更新待办事项
    • 完成规划任务后标记为已完成
  6. 最终计划中不能有未解决问题：
    • 如果在规划过程中遇到未解决问题，立即停止
    • 研究或请求澄清
    • 不要编写包含未解决问题的计划
    • 实现计划必须完整且可执行
    • 所有决策必须在最终确定计划前做出

Success Criteria Guidelines

成功标准指导方针

Always separate success criteria into two categories:
  1. Automated Verification (can be run by execution agents):
    • Commands that can be run: 
      make test
      , 
      make check
      , 
      make lint
      , 
      make fix
      etc.
    • Specific files that should exist
    • Code compilation/type checking
    • Automated test suites
  2. Manual Verification (requires human testing):
    • UI/UX functionality
    • Performance under real conditions
    • Edge cases that are hard to automate
    • User acceptance criteria
Format example:
markdown
undefined
始终将成功标准分为两类：
  1. 自动化验证（可由执行代理运行）：
    • 可运行的命令：
      make test
      、
      make check
      、
      make lint
      、
      make fix
      等
    • 应存在的特定文件
    • 代码编译/类型检查
    • 自动化测试套件
  2. 手动验证（需要人工测试）：
    • UI/UX功能
    • 实际条件下的性能
    • 难以自动化的边缘情况
    • 用户验收标准
格式示例：
markdown
undefined

Success Criteria:

成功标准：

Automated Verification:

自动化验证：

  • Database migration runs successfully: 
    make migrate
  • All unit tests pass: 
    go test ./...
  • No linting errors: 
    golangci-lint run
  • API endpoint returns 200: 
    curl localhost:8080/api/new-endpoint
  • 数据库迁移成功运行：
    make migrate
  • 所有单元测试通过：
    go test ./...
  • 无代码检查错误：
    golangci-lint run
  • API端点返回200：
    curl localhost:8080/api/new-endpoint

Manual Verification:

手动验证：

  • New feature appears correctly in the UI
  • Performance is acceptable with 1000+ items
  • Error messages are user-friendly
  • Feature works correctly on mobile devices
undefined
  • 新功能在UI中正确显示
  • 1000+条数据时性能可接受
  • 错误消息对用户友好
  • 功能在移动设备上正常工作
undefined

Common Patterns

常见模式

For Database Changes:

数据库变更：

  • Start with schema/migration
  • Add store methods
  • Update business logic
  • Expose via API
  • Update clients
  • 从架构/迁移开始
  • 添加存储方法
  • 更新业务逻辑
  • 通过API暴露
  • 最后更新客户端

For New Features:

新功能：

  • Research existing patterns first
  • Start with data model
  • Build backend logic
  • Add API endpoints
  • Implement UI last
  • 先研究现有模式
  • 从数据模型开始
  • 构建后端逻辑
  • 添加API端点
  • 最后实现UI

For Refactoring:

重构：

  • Document current behavior
  • Plan incremental changes
  • Maintain backwards compatibility
  • Include migration strategy
  • 记录当前行为
  • 规划增量变更
  • 保持向后兼容性
  • 包含迁移策略

Sub-task Spawning Best Practices

子任务生成最佳实践

When spawning research sub-tasks:
  1. Spawn multiple tasks in parallel for efficiency
  2. Each task should be focused on a specific area
  3. Provide detailed instructions including:
    • Exactly what to search for
    • Which directories to focus on
    • What information to extract
    • Expected output format
  4. Be EXTREMELY specific about directories:
    • Include the full path context in your prompts
  5. Specify read-only tools to use
  6. Request specific file:line references in responses
  7. Wait for all tasks to complete before synthesizing
  8. Verify sub-task results:
    • If a sub-task returns unexpected results, spawn follow-up tasks
    • Cross-check findings against the actual codebase
    • Don't accept results that seem incorrect
生成研究子任务时：
  1. 并行生成多个任务以提高效率
  2. 每个任务应聚焦于特定领域
  3. 提供详细指令，包括：
    • 确切的搜索内容
    • 要关注的目录
    • 要提取的信息
    • 预期的输出格式
  4. 对目录的描述要极其具体：
    • 在提示中包含完整的路径上下文
  5. 指定要使用的只读工具
  6. 要求在响应中包含具体的文件:行号引用
  7. 等待所有任务完成后再进行综合
  8. 验证子任务结果：
    • 如果子任务返回意外结果，生成后续任务
    • 将发现与实际代码库进行交叉核对
    • 不要接受看起来不正确的结果