Back to Details

rpi-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.
你的任务是通过交互式、迭代的流程创建详细的实施计划。你需要秉持严谨审慎的态度，与用户协作产出高质量的技术规格文档。

Initial Setup

初始设置

If the user already provided a task description, file path, or topic alongside this command, proceed directly to step 1 below. Only if no context was given, respond with:
I'll help you create a detailed implementation plan. Let me start by understanding what we're building.

Please provide:
1. A description of what you want to build or change
2. Any relevant context, constraints, or specific requirements
3. Pointers to related files or previous research

I'll analyze this information and work with you to create a comprehensive plan.
Then wait for the user's input.
如果用户在触发本指令时已提供任务描述、文件路径或主题，请直接进入下方的步骤1。仅当未提供任何上下文时，才回复以下内容：
我将帮你创建一份详细的实施计划。首先让我了解我们要构建的内容。

请提供：
1. 你想要构建或修改的内容描述
2. 任何相关的上下文、约束条件或特定要求
3. 相关文件或前期研究的参考信息

我会分析这些信息，并与你协作制定一份全面的计划。
然后等待用户输入。

Process Steps

流程步骤

Step 1: Context Gathering & Initial Analysis

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

  1. Read all mentioned files immediately and FULLY:
    • Any files the user referenced (docs, research, code)
    • IMPORTANT: Use the Read tool 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. Determine if research already exists:
    • If the user provided a research document (e.g. from 
      docs/agents/research/
      ), trust it as the source of truth. Do NOT re-research topics that the document already covers. Use its findings, file references, and architecture analysis directly as the basis for planning.
    • NEVER repeat or re-do research that has already been provided. The plan phase is about turning existing research into actionable implementation steps, not about gathering information that's already available.
    • If NO research document was provided, proceed with targeted research as described below.
  3. Read the most relevant files directly into your main context:
    • Based on the research document and/or user input, identify the most relevant source files
    • Read these files yourself using the Read tool — do NOT delegate this to sub-agents. You need these files in your own context to write an accurate plan.
    • Focus on files that will be modified or that define interfaces/patterns you need to follow
  4. Only spawn sub-agents for genuinely missing information:
    • Do NOT spawn sub-agents to re-discover what the research document already covers
    • Only use sub-agents if there are specific gaps: e.g. the research doesn't cover test conventions, a specific API surface, or a file that was added after the research was written
    • Each sub-agent should have a narrow, specific question to answer — not broad exploration
  5. Analyze and verify understanding:
    • Cross-reference the requirements with actual code (and research document if provided)
    • Identify any discrepancies or misunderstandings
    • Note assumptions that need verification
    • Determine true scope based on codebase reality
  6. Present informed understanding and focused questions:
    Based on the task 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. 立即完整阅读所有提及的文件：
    • 用户引用的任何文件（文档、研究资料、代码）
    • 重要提示：使用Read工具时不要添加limit/offset参数，以读取完整文件
    • 关键要求：在主上下文中自行读取这些文件之前，不要生成子任务
    • 绝对不要部分读取文件——只要文件被提及，就必须完整阅读
  2. 判断是否已有研究资料：
    • 如果用户提供了研究文档（例如来自
      docs/agents/research/
      ），将其视为事实依据。对于文档已涵盖的主题，请勿重复调研。直接使用其研究结果、文件引用和架构分析作为计划的基础。
    • 绝对不要重复或重做已提供的研究工作。计划阶段的核心是将现有研究转化为可执行的实施步骤，而非收集已有的信息。
    • 如果未提供研究文档，请按照以下描述开展针对性调研。
  3. 将最相关的文件直接读取到主上下文中：
    • 根据研究文档和/或用户输入，确定最相关的源文件
    • 使用Read工具自行读取这些文件——不要将此工作委托给子Agent。你需要在自己的上下文中掌握这些文件的内容，才能编写准确的计划。
    • 重点关注需要修改的文件，或定义了你需要遵循的接口/模式的文件
  4. 仅在确实存在信息缺口时生成子Agent：
    • 不要为重新发现研究文档已涵盖的内容而生成子Agent
    • 仅在存在特定信息缺口时使用子Agent：例如研究未涵盖测试规范、特定API接口，或研究完成后新增的文件
    • 每个子Agent都应负责解决一个具体、明确的问题——而非进行宽泛的探索
  5. 分析并验证理解程度：
    • 将需求与实际代码（以及提供的研究文档，如果有的话）进行交叉核对
    • 识别任何不一致或误解之处
    • 记录需要验证的假设
    • 根据代码库的实际情况确定真实的项目范围
  6. 呈现经过验证的理解和针对性问题：
    根据任务和我对代码库的调研，我理解我们需要[准确的内容摘要]。

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

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

Step 2: Targeted Research & Discovery

步骤2：针对性调研与探索

After getting initial clarifications:
  1. If the user corrects any misunderstanding:
    • DO NOT just accept the correction
    • Read the specific files/directories they mention directly into your context
    • Only proceed once you've verified the facts yourself
  2. If you have a todo list, use it to track exploration progress
  3. Fill in gaps — do NOT redo existing research:
    • If a research document was provided, identify only the specific gaps that need filling
    • Read additional files directly when possible — only spawn sub-agents for searches where you don't know the file paths
    • Ask yourself before any research action: "Is this already covered by the provided research?" If yes, skip it and use what's there.
  4. 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]

**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. 如果你有任务清单，使用它来跟踪探索进度
  3. 填补信息缺口——不要重复已有研究：
    • 如果提供了研究文档，仅识别需要填补的特定信息缺口
    • 尽可能直接读取额外文件——仅在不知道文件路径时才生成子Agent进行搜索
    • **在执行任何调研操作前问自己：“这部分内容是否已被提供的研究涵盖？”**如果是，跳过并直接使用已有内容。
  4. 呈现调研结果和设计选项：
    根据我的调研，以下是发现的内容：

**当前状态：**
- [关于现有代码的关键发现]
- [需要遵循的模式或规范]

**设计选项：**
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. Gather metadata:
    • Run 
      python3 <skill_directory>/scripts/metadata.py
      to get date, commit, branch, and repository info
    • Determine the output filename: 
      docs/agents/plans/YYYY-MM-DD-description.md
      • YYYY-MM-DD is today's date
      • description is a brief kebab-case description
      • Example: 
        2025-01-08-improve-error-handling.md
      • The output folder (
        docs/agents/plans/
        ) can be overridden by instructions in the project's 
        AGENTS.md
        or 
        CLAUDE.md
  2. Write the plan to 
    docs/agents/plans/YYYY-MM-DD-description.md
    • Ensure the 
      docs/agents/plans/
      directory exists (create if needed)
    • Every actionable item must have a checkbox (
      - [ ]
      ) so progress can be tracked during implementation. This includes each change in "Changes Required" and each verification step in "Success Criteria".
    • Use the template structure below:
markdown
---
date: [ISO date/time from metadata]
git_commit: [Current commit hash from metadata]
branch: [Current branch name from metadata]
topic: "[Feature/Task Name]"
tags: [plan, relevant-component-names]
status: draft
---
在结构获批后：
  1. 收集元数据：
    • 运行
      python3 <skill_directory>/scripts/metadata.py
      以获取日期、提交记录、分支和仓库信息
    • 确定输出文件名：
      docs/agents/plans/YYYY-MM-DD-description.md
      • YYYY-MM-DD为当前日期
      • description为简短的kebab-case格式描述
      • 示例：
        2025-01-08-improve-error-handling.md
      • 输出目录(
        docs/agents/plans/
        )可根据项目
        AGENTS.md
        或
        CLAUDE.md
        中的说明进行覆盖
  2. 将计划写入
    docs/agents/plans/YYYY-MM-DD-description.md
    • 确保
      docs/agents/plans/
      目录存在（如果不存在则创建）
    • 每个可执行项都必须包含复选框(
      - [ ]
      )，以便在实施过程中跟踪进度。这包括“所需变更”中的每一项修改，以及“成功标准”中的每一项验证步骤。
    • 使用以下模板结构：
markdown
---
date: [来自元数据的ISO日期/时间]
git_commit: [来自元数据的当前提交哈希]
branch: [来自元数据的当前分支名称]
topic: "[功能/任务名称]"
tags: [plan, relevant-component-names]
status: draft
---

[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]
[本计划完成后期望达到的状态说明，以及验证方式]

UI Mockups (if applicable)

UI原型（如适用）

[If the changes involve user-facing interfaces (CLI output, web UI, terminal UI, etc.), include ASCII mockups that visually illustrate the intended result. This helps the reader quickly grasp the change.]
[如果变更涉及用户交互界面（CLI输出、Web UI、终端UI等），请包含ASCII原型，直观展示预期结果。这有助于读者快速理解变更内容。]

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]
[高层次策略及理由]

Architecture and Code Reuse

架构与代码复用

[Explicitly list the code & utils we can reuse or should extract. Refactorings are fine if they are related to the task and improve the code regarding DRY and reuse. Also make sure to research & mention all relevant third party libs and APIs you plan to use. Use ascii diagrams to visualize architecture decisions if appropriate.]
[High level file tree showing the affected files with comments on how they will change]
[明确列出我们可以复用或应该提取的代码和工具。如果重构与任务相关，且能提升代码的DRY（不重复）特性和复用性，那么重构是可行的。同时务必调研并提及你计划使用的所有相关第三方库和API。如有必要，使用ASCII图表可视化架构决策。]
[展示受影响文件的高层次文件树，并注释其变更方式]

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]
// High level code to add/modify
// Focus on signatures, types, and structure
文件：
path/to/file.ext
变更：[变更摘要]
// 待添加/修改的高层级代码
// 重点关注签名、类型和结构

Success Criteria:

成功标准：

Automated Verification:

自动化验证：

  • Tests pass: 
    [test command]
  • Type checking passes: 
    [typecheck command]
  • Linting passes: 
    [lint command]
  • 测试通过：
    [测试命令]
  • 类型检查通过：
    [类型检查命令]
  • 代码检查通过：
    [代码检查命令]

Manual Verification (only if the phase produces a testable, user-facing feature):

手动验证（仅当该阶段产出可测试的用户交互功能时适用）：

  • Feature works as expected when tested
  • Edge case handling verified
  • No regressions in related features
Implementation Note: Only pause for manual confirmation if this phase has manual verification steps. If the phase has only automated verification, continue to the next phase without stopping.
  • 功能测试符合预期
  • 边缘情况处理已验证
  • 相关功能无回归问题
实施说明：仅当该阶段包含手动验证步骤时，才暂停等待人工确认。如果该阶段只有自动化验证步骤，无需停止直接进入下一阶段。

Phase 2: [Descriptive Name]

阶段2：[描述性名称]

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

Testing Strategy

测试策略

Unit Tests:

单元测试：

  • [What to test. List concrete test cases that cover all the requirements.]
  • [Key edge cases]
  • [测试内容。列出覆盖所有需求的具体测试用例。]
  • [关键边缘情况]

Integration Tests:

集成测试：

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

Manual Testing Steps:

手动测试步骤：

Only include steps the user can test by interacting with the app naturally. You MUST NOT include "review the code" or similar non-interactive steps here.
  1. [Specific step to verify feature]
  2. [Another verification step]
仅包含用户可以通过自然交互应用程序完成的测试步骤。 绝对不要包含“审查代码”或类似的非交互步骤。
  1. [验证功能的具体步骤]
  2. [另一验证步骤]

Performance Considerations

性能考量

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

Migration Notes

迁移说明

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

References

参考资料

  • [Related research or documentation]
  • [Similar implementation: file:line]
undefined
  • [相关研究或文档]
  • [类似实现：文件:行号]
undefined

Step 5: Review & Iterate

步骤5：评审与迭代

  1. Present the draft plan location:
    I've created the initial implementation plan at:
`docs/agents/plans/YYYY-MM-DD-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?
  2. Iterate based on feedback - be ready to:
    • Add missing phases
    • Adjust technical approach
    • Clarify success criteria (both automated and manual)
    • Add/remove scope items
  3. Continue refining until the user is satisfied
  1. 呈现 draft 计划的位置：
    我已创建初始实施计划，路径为：
`docs/agents/plans/YYYY-MM-DD-description.md`

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

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 But Not Redundant:
    • Read all context files COMPLETELY before planning
    • Use provided research as-is — do not re-investigate what's already documented
    • Read key source files directly into your context rather than delegating to sub-agents
    • Only spawn sub-agents for narrow, specific questions that aren't answered by existing research
    • Include specific file paths and line numbers
    • Write measurable success criteria with clear automated vs manual distinction
  4. Be Visual:
    • If the change involves any user-facing interface (web UI, CLI output, terminal UI, forms, dashboards, etc.), include ASCII mockups in the plan
    • Mockups make the intended result immediately understandable and help catch misunderstandings early
    • Study the current UI before creating mockups
    • Show both the current state and the proposed state when the change modifies an existing UI
    • Keep mockups simple but accurate enough to convey layout, key elements, and interactions
  5. Be Practical:
    • Focus on incremental, testable changes
    • Consider migration and rollback
    • Think about edge cases
    • Include "what we're NOT doing"
  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. 全面但不冗余：
    • 规划前完整阅读所有上下文文件
    • 直接使用提供的研究内容——不要重新调研已记录的信息
    • 将关键源文件直接读取到你的上下文中，而非委托给子Agent
    • 仅为现有研究无法解答的具体、明确问题生成子Agent
    • 包含具体的文件路径和行号
    • 编写可衡量的成功标准，明确区分自动化与手动验证
  4. 可视化呈现：
    • 如果变更涉及任何用户交互界面（Web UI、CLI输出、终端UI、表单、仪表板等），请在计划中包含ASCII原型
    • 原型可以让预期结果一目了然，有助于尽早发现误解
    • 创建原型前先研究当前UI
    • 当变更修改现有UI时，同时展示当前状态和提议状态
    • 保持原型简洁，但要足够准确以传达布局、关键元素和交互方式
  5. 务实可行：
    • 专注于可增量、可测试的变更
    • 考虑迁移和回滚方案
    • 考虑边缘情况
    • 包含“我们不会做的事”部分
  6. 最终计划中不能有未解决的问题：
    • 如果在规划过程中遇到未解决的问题，请暂停
    • 立即开展调研或请求澄清
    • 不要带着未解决的问题编写计划
    • 实施计划必须完整且可执行
    • 在最终确定计划前，必须做出所有决策

Success Criteria Guidelines

成功标准指南

Always separate success criteria into two categories:
  1. Automated Verification (can be run by agents):
    • Commands that can be run: test suites, linters, type checkers
    • Specific files that should exist
    • Code compilation/type checking
  2. Manual Verification (requires human testing):
    • You MUST only add manual verification when the user can interact with a working feature (e.g. open a UI, run a command, trigger a workflow).
    • You MUST NOT use "review the code" or "check the implementation" as a verification step.
    • You MUST NOT add manual verification to internal phases (refactoring, utilities, types, backend without entry point). Use automated verification instead.
    • You SHOULD place manual verification at milestones where a user-facing feature is complete.
    • Examples: UI/UX functionality, performance under real conditions, edge cases that are hard to automate, user acceptance criteria.
始终将成功标准分为两类：
  1. 自动化验证（可由Agent执行）：
    • 可运行的命令：测试套件、代码检查工具、类型检查工具
    • 应存在的特定文件
    • 代码编译/类型检查
  2. 手动验证（需要人工测试）：
    • 仅当用户可以与可用功能交互（例如打开UI、运行命令、触发工作流）时，才添加手动验证步骤。
    • 绝对不要将“审查代码”或“检查实现”作为验证步骤。
    • 绝对不要为内部阶段（重构、工具、类型、无入口点的后端）添加手动验证。请改用自动化验证。
    • 应在用户交互功能完成的里程碑处设置手动验证步骤。
    • 示例：UI/UX功能、实际条件下的性能、难以自动化的边缘情况、用户验收标准。

Common Patterns

常见模式

For Database Changes:

数据库变更：

  • Start with schema/migration
  • Add store methods
  • Update business logic
  • Expose via API
  • Update clients
  • 从 schema/迁移开始
  • 添加存储方法
  • 更新业务逻辑
  • 通过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
  • 记录当前行为
  • 规划增量变更
  • 保持向后兼容性
  • 包含迁移策略