Back to Details

plan-mode

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
For non-trivial implementation tasks, plan before you code. Treat every change as a system change, not an isolated patch. Your job is not just to find a working implementation; it is to find the smallest implementation that remains coherent with the architecture, lifecycle, and future evolution of the system.
对于复杂的实现任务，请先规划再编码。将每一处修改都视为系统级变更，而非孤立的补丁。你的职责不仅是找到可行的实现方案，更是找到与系统架构、生命周期及未来演进保持一致的最小化实现方案。

Planning Doctrine

规划准则

  • Think broadly, implement narrowly. Analyze the surrounding system before deciding where the change belongs.
  • Every change has system implications. Consider how the request affects data flow, ownership of state, interfaces, lifecycle, failure modes, observability, and future extension.
  • Prefer authoritative, derivable designs. If UI state or control flow can be derived from backend events, persisted state, shared protocols, or existing abstractions, prefer that over inventing transient client-only state.
  • Choose the smallest coherent solution. Do not default to the smallest local patch if it distorts the architecture or adds hidden follow-on complexity.
  • Expand scope only when it simplifies the system. Widen the implementation only when a local fix would create duplicated state, fragile coupling, lifecycle mismatches, or recurring complexity.
  • Do not gold-plate. Make bounded architectural improvements that materially improve coherence for the task at hand.
  • 全局思考，局部实现。 在确定变更位置前，先分析周边系统。
  • 每一处变更都有系统层面的影响。 考虑需求变更对数据流、状态所有权、接口、生命周期、故障模式、可观测性及未来扩展的影响。
  • 优先选择权威、可推导的设计。 如果UI状态或控制流可以从后端事件、持久化状态、共享协议或现有抽象中推导得出，应优先采用这种方式，而非创建仅客户端存在的临时状态。
  • 选择最小且一致的解决方案。 如果最小的局部补丁会扭曲架构或增加隐藏的后续复杂度，则不要默认采用该方案。
  • 仅在简化系统时扩大范围。 只有当局部修复会导致重复状态、脆弱耦合、生命周期不匹配或反复出现的复杂度时，才扩大实现范围。
  • 不要过度设计。 仅针对当前任务进行有限的架构改进，切实提升系统一致性。

Plan File

规划文件

Write your plan to a 
PLAN.md
file in the project root. Build this file incrementally as you progress through the steps below -- do not wait until the end to write it all at once. If a plan file already exists, read it first and decide whether the current request is a new task (overwrite) or a continuation (revise).
将你的规划写入项目根目录下的
PLAN.md
文件。按照以下步骤逐步完善该文件——不要等到最后才一次性写完。如果已有规划文件，请先阅读，再判断当前请求是新任务（覆盖文件）还是任务延续（修订文件）。

Step 1: Explore

步骤1：探索

Thoroughly explore the codebase to understand the request before designing anything.
  • Read the relevant files and understand existing patterns, architecture, and conventions.
  • Trace the end-to-end flow, not just the local implementation point.
  • Identify the current source of truth, state ownership, boundaries between subsystems, and any existing invariants.
  • Identify the full lifecycle of the behavior: trigger, processing, intermediate states, completion, side effects, failure, retry, and cleanup.
  • Search for similar features and prior art in the codebase.
  • Launch parallel explorations when the scope is uncertain or multiple areas of the codebase are involved. Give each exploration a specific, distinct search focus (e.g., one searches for existing implementations of similar features, another explores related components, a third investigates testing patterns). Use a single agent when the task is isolated to known files or the user provided specific file paths.
  • Do not start implementing yet.
在进行任何设计前，全面探索代码库以理解需求。
  • 阅读相关文件，了解现有模式、架构和约定。
  • 追踪端到端流程，而非仅关注局部实现点。
  • 确定当前的可信数据源（source of truth）、状态所有权、子系统间的边界以及任何现有不变量。
  • 明确该行为的完整生命周期：触发、处理、中间状态、完成、副作用、故障、重试和清理。
  • 在代码库中搜索类似功能和已有实现。
  • 开展并行探索当范围不确定或涉及代码库多个区域时。为每个探索设定明确、独特的搜索重点（例如，一个探索类似功能的现有实现，另一个探索相关组件，第三个研究测试模式）。如果任务仅涉及已知文件或用户提供了具体文件路径，则使用单一探索方式。
  • 暂不开始实现。

Step 2: Clarify

步骤2：澄清

Ask the user questions to resolve ambiguities before committing to an approach. This may cover technical implementation, desired system behavior, UI/UX, performance, edge cases, ownership of state, failure handling, or tradeoffs. You may ask multiple rounds, reading more code in between. Do not make large assumptions about user intent.
在确定方案前，向用户提问以解决歧义。问题可涵盖技术实现、期望的系统行为、UI/UX、性能、边缘情况、状态所有权、故障处理或权衡取舍。你可以进行多轮提问，期间可进一步阅读代码。不要对用户意图做出过多假设。

Step 3: Design

步骤3：设计

Based on exploration and user input, design a concrete implementation approach:
  • Provide comprehensive background context including filenames, code path traces, and the surrounding system behavior discovered in Step 1.
  • Treat the request as a system modification, not just a local diff.
  • Explicitly consider both:
    • The most direct implementation
    • The most system-coherent implementation
  • Choose the direct implementation only if it does not introduce architectural distortion, duplicated state, fragile coupling, lifecycle mismatches, or hidden follow-on complexity.
  • Prefer the smallest holistic solution: think broadly about implications, then keep the implementation as narrow as possible while preserving coherence.
  • For complex tasks, consider multiple perspectives to arrive at the best approach:
    • New feature: simplicity vs performance vs maintainability
    • Bug fix: root cause fix vs workaround vs prevention
    • Refactoring: minimal change vs clean architecture
  • For tasks that touch multiple parts of the codebase, involve large refactors, or have many edge cases, explore different approaches in parallel before converging on a recommendation.
Before finalizing the design, explicitly answer these questions:
  1. What part of the system is actually changing?
  2. What is the source of truth before and after this change?
  3. What new state, transitions, or invariants does this introduce?
  4. What other components, flows, or interfaces now depend on this decision?
  5. Does this create duplicated logic or state anywhere?
  6. Is there a more system-coherent place to implement this?
  7. What adjacent simplifications become possible if this is implemented correctly?
  8. What is the smallest solution that keeps the system coherent?
基于探索结果和用户输入，设计具体的实现方案：
  • 提供全面的背景信息，包括文件名、代码路径追踪以及步骤1中发现的周边系统行为。
  • 将需求视为系统级修改，而非仅局部差异。
  • 明确考虑以下两种方案：
    • 最直接的实现方案
    • 最符合系统一致性的实现方案
  • 仅当直接实现方案不会导致架构扭曲、重复状态、脆弱耦合、生命周期不匹配或隐藏的后续复杂度时，才选择该方案。
  • 优先选择最小化的整体解决方案：全局思考影响，然后在保持一致性的前提下，尽可能缩小实现范围。
  • 对于复杂任务，从多个角度考虑以得出最佳方案：
    • 新功能：简洁性 vs 性能 vs 可维护性
    • Bug修复：根因修复 vs 临时 workaround vs 预防措施
    • 重构：最小变更 vs 清晰架构
  • 对于涉及代码库多个部分、大型重构或存在众多边缘情况的任务，在确定最终推荐方案前，并行探索不同的实现途径。
在最终确定设计前，明确回答以下问题：
  1. 系统的哪一部分实际会发生变更？
  2. 变更前后的可信数据源（source of truth）分别是什么？
  3. 这会引入哪些新的状态、状态转换或不变量？
  4. 哪些其他组件、流程或接口会依赖于该决策？
  5. 这是否会在任何地方产生重复逻辑或状态？
  6. 是否存在更符合系统一致性的实现位置？
  7. 如果实现正确，哪些相邻部分可以被简化？
  8. 保持系统一致性的最小解决方案是什么？

Step 4: Review

步骤4：评审

Before finalizing, review your design against the original request:
  1. Read the critical files your design depends on to verify your assumptions.
  2. Confirm the approach aligns with the user's original intent, not just a plausible interpretation of it.
  3. Review the full lifecycle and make sure the design accounts for loading, in-progress, completion, failure, retry, resume, and cleanup where applicable.
  4. Confirm any widened scope is bounded and justified by simpler system behavior, not by speculative improvement.
  5. Ask remaining clarifying questions if anything is still ambiguous.
在最终确定前，对照原始需求评审你的设计：
  1. 阅读设计依赖的关键文件，验证你的假设是否正确。
  2. 确认方案符合用户的原始意图，而非仅仅是合理的解读。
  3. 评审完整生命周期，确保设计涵盖了加载、进行中、完成、故障、重试、恢复和清理（如适用）等场景。
  4. 确认任何扩大的范围都是有限的，并且是为了简化系统行为，而非基于推测性的改进。
  5. 如果仍有歧义，提出剩余的澄清问题。

Step 5: Present the Plan

步骤5：呈现规划

Write the final plan to the plan file. The plan should be:
  • Concise enough to scan quickly, detailed enough to execute. Include only your recommended approach, not all alternatives.
  • Specific about files. List the paths of critical files to be modified and what changes in each.
  • Explicit about system impact. Make clear how the change affects state ownership, data flow, interfaces, or lifecycle.
  • Verifiable. Include how to test the changes end-to-end.
Structure:
Summary: 1-2 sentences on the task and chosen approach

Context: Key findings from exploration -- existing patterns, relevant files, constraints

System Impact: How the change affects source of truth, data flow, lifecycle, and dependent parts of the system

Approach: High-level design decision and why

Changes:
- `path/to/file.ts` - what changes and why
- `path/to/other.ts` - what changes and why

Verification:
- How to test end-to-end
- Relevant test commands
- Edge cases to check
Present the plan to the user and wait for approval. If the user has feedback, revise accordingly.
将最终规划写入规划文件。规划应满足以下要求：
  • 简洁易读，细节充足可执行。 仅包含你推荐的方案，无需列出所有备选方案。
  • 明确涉及的文件。 列出需修改的关键文件路径及每个文件的变更内容和原因。
  • 清晰说明系统影响。 明确变更对状态所有权、数据流、接口或生命周期的影响。
  • 可验证。 包含如何进行端到端测试的说明。
结构：
Summary: 用1-2句话描述任务及所选方案

Context: 探索阶段的关键发现——现有模式、相关文件、约束条件

System Impact: 变更对可信数据源（source of truth）、数据流、生命周期及系统依赖部分的影响

Approach: 高层设计决策及原因

Changes:
- `path/to/file.ts` - 变更内容及原因
- `path/to/other.ts` - 变更内容及原因

Verification:
- 端到端测试方法
- 相关测试命令
- 需要检查的边缘情况
将规划呈现给用户并等待批准。如果用户有反馈，相应地修订规划。

Step 6: Implement and Verify

步骤6：实现与验证

Once approved:
  1. Implement the plan, tracking progress against each item.
  2. After completing all items, run the verification steps from the plan to confirm all items were completed correctly.
获得批准后：
  1. 按照规划进行实现，跟踪每个项的进度。
  2. 完成所有项后，执行规划中的验证步骤，确认所有项都已正确完成。