my-plan

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementation Plan Creation

实施计划创建

Create an implementation plan in

docs/plans/yyyymmdd-<task-name>.md

with interactive context gathering.

通过交互式上下文收集，在

docs/plans/yyyymmdd-<task-name>.md

中创建实施计划。

Step 0: Parse Intent and Gather Context

步骤0：解析意图并收集上下文

Before asking questions, understand what the user is working on:

Parse user's command arguments to identify intent:
- "add feature Z" / "implement W" → feature development
- "fix bug" / "debug issue" → bug fix plan
- "refactor X" / "improve Y" → refactoring plan
- "migrate to Z" / "upgrade W" → migration plan
- generic request → explore current work
Launch Explore agent (via Task tool with
```
subagent_type: Explore
```
) to gather relevant context based on intent:
For feature development:
- locate related existing code and patterns
- check project structure (README, config files, existing similar implementations)
- identify affected components and dependencies
For bug fixing:
- look for error logs, test failures, or stack traces
- find related code that might be involved
- check recent git changes in problem areas
For refactoring/migration:
- identify all files/components affected
- check test coverage of affected areas
- find dependencies and integration points
For generic/unclear requests:
- check
```
git status
```
  and recent file activity
- examine current working directory structure
- identify primary language/framework from file extensions and config files
Synthesize findings into context summary:
- what work is in progress
- which files/areas are involved
- what the apparent goal is
- relevant patterns or structure discovered

在提问之前，先了解用户正在处理的工作：

解析用户的命令参数以识别意图：
- "add feature Z" / "implement W" → 功能开发
- "fix bug" / "debug issue" → bug修复计划
- "refactor X" / "improve Y" → 重构计划
- "migrate to Z" / "upgrade W" → 迁移计划
- 通用请求 → 探索当前工作
启动Explore Agent（通过带有
```
subagent_type: Explore
```
的Task工具），根据意图收集相关上下文：
针对功能开发：
- 定位相关现有代码和模式
- 检查项目结构（README、配置文件、现有类似实现）
- 识别受影响的组件和依赖项
针对bug修复：
- 查找错误日志、测试失败记录或堆栈跟踪
- 找到可能相关的代码
- 检查问题区域的近期git变更
针对重构/迁移：
- 识别所有受影响的文件/组件
- 检查受影响区域的测试覆盖率
- 查找依赖项和集成点
针对通用/不明确的请求：
- 检查
```
git status
```
  和近期文件活动
- 查看当前工作目录结构
- 从文件扩展名和配置文件识别主要语言/框架
将发现结果合成为上下文摘要：
- 正在进行的工作内容
- 涉及哪些文件/区域
- 明显的目标是什么
- 发现的相关模式或结构

Step 1: Present Context and Ask Focused Questions

步骤1：展示上下文并提出针对性问题

Show the discovered context, then ask questions one at a time using the AskUserQuestion tool:

"Based on your request, I found: [context summary]"

Ask questions one at a time (do not overwhelm with multiple questions):

Plan purpose: use AskUserQuestion - "What is the main goal?"
- provide multiple choice with suggested answer based on discovered intent
- wait for response before next question
Scope: use AskUserQuestion - "Which components/files are involved?"
- provide multiple choice with suggested discovered files/areas
- wait for response before next question
Constraints: use AskUserQuestion - "Any specific requirements or limitations?"
- can be open-ended if constraints vary widely
- wait for response before next question
Testing approach: use AskUserQuestion - "Do you prefer TDD or regular approach?"
- options: "TDD (tests first)" and "Regular (code first, then tests)"
- store preference for reference during implementation
- wait for response before next question
Plan title: use AskUserQuestion - "Short descriptive title?"
- provide suggested name based on intent

After all questions answered, synthesize responses into plan context.

展示发现的上下文，然后使用AskUserQuestion工具一次提出一个问题：

"基于你的请求，我发现：[上下文摘要]"

一次只提一个问题（不要用多个问题让用户应接不暇）：

计划目的：使用AskUserQuestion - "主要目标是什么？"
- 根据发现的意图提供带有建议答案的选择题
- 等待回复后再提出下一个问题
范围：使用AskUserQuestion - "涉及哪些组件/文件？"
- 提供带有发现的文件/区域建议的选择题
- 等待回复后再提出下一个问题
约束条件：使用AskUserQuestion - "有任何特定要求或限制吗？"
- 如果约束条件差异较大，可以采用开放式问题
- 等待回复后再提出下一个问题
测试方法：使用AskUserQuestion - "你更喜欢TDD还是常规方法？"
- 选项："TDD（先写测试）"和"常规（先写代码，再写测试）"
- 存储用户偏好，以便在实施过程中参考
- 等待回复后再提出下一个问题
计划标题：使用AskUserQuestion - "简短的描述性标题？"
- 根据意图提供建议名称

在所有问题得到回答后，将回复合成为计划上下文。

Step 1.5: Explore Approaches

步骤1.5：探索实现方案

Once the problem is understood, propose implementation approaches:

Propose 2-3 different approaches with trade-offs for each
Lead with recommended option and explain reasoning
Present conversationally - not a formal document yet

Example format:

I see three approaches:

**Option A: [name]** (recommended)
- How it works: ...
- Pros: ...
- Cons: ...

**Option B: [name]**
- How it works: ...
- Pros: ...
- Cons: ...

Which direction appeals to you?

Use AskUserQuestion tool to let user select preferred approach before creating the plan.

Skip this step if:

the implementation approach is obvious (single clear path)
user explicitly specified how they want it done
it's a bug fix with clear solution

在理解问题后，提出实施方案：

提出2-3种不同的方案，并说明每种方案的权衡
优先推荐最优选项并解释理由
以对话形式呈现 - 暂时不要用正式文档格式

示例格式：

我想到三种方案：

**方案A：[名称]**（推荐）
- 工作原理：...
- 优点：...
- 缺点：...

**方案B：[名称]**
- 工作原理：...
- 优点：...
- 缺点：...

你倾向于哪个方向？

使用AskUserQuestion工具让用户选择偏好的方案后再创建计划。

跳过此步骤的情况：

实现方案显而易见（只有一条清晰路径）
用户明确指定了他们想要的实现方式
这是一个有明确解决方案的bug修复

Step 2: Create Plan File

步骤2：创建计划文件

Check

docs/plans/

for existing files, then create

docs/plans/<task-name>.md

检查

docs/plans/

中的现有文件，然后创建

docs/plans/<task-name>.md

：

Plan Structure

计划结构

markdown

undefined

markdown

undefined

[Plan Title]

[计划标题]

Overview

概述

Clear description of the feature/change being implemented
Problem it solves and key benefits
How it integrates with existing system

对要实现的功能/变更的清晰描述
解决的问题和主要收益
与现有系统的集成方式

Context (from discovery)

上下文（来自发现阶段）

Files/components involved: [list from step 0]
Related patterns found: [patterns discovered]
Dependencies identified: [dependencies]

涉及的文件/组件：[步骤0中的列表]
发现的相关模式：[发现的模式]
识别的依赖项：[依赖项]

Development Approach

开发方法

Testing approach: [TDD / Regular - from user preference in planning]
Complete each task fully before moving to the next
Make small, focused changes
CRITICAL: every task MUST include new/updated tests for code changes in that task
- tests are not optional - they are a required part of the checklist
- write unit tests for new functions/methods
- write unit tests for modified functions/methods
- add new test cases for new code paths
- update existing test cases if behavior changes
- tests cover both success and error scenarios
CRITICAL: all tests must pass before starting next task - no exceptions
CRITICAL: update this plan file when scope changes during implementation
Run tests after each change
Maintain backward compatibility

测试方法：[TDD / 常规 - 来自规划阶段的用户偏好]
完成每个任务后再进行下一个任务
进行小而聚焦的变更
关键要求：每个任务必须包含针对该任务代码变更的新增/更新测试
- 测试不是可选的 - 它们是检查清单的必填部分
- 为新函数/方法编写单元测试
- 为修改的函数/方法编写单元测试
- 为新代码路径添加新测试用例
- 如果行为发生变化，更新现有测试用例
- 测试需覆盖成功和错误场景
关键要求：开始下一个任务前所有测试必须通过 - 无例外
关键要求：实施过程中范围变化时更新此计划文件
每次变更后运行测试
保持向后兼容性

Testing Strategy

测试策略

Unit tests: required for every task (see Development Approach above)
E2E tests: if project has UI-based e2e tests (Playwright, Cypress, etc.):
- UI changes → add/update e2e tests in same task as UI code
- Backend changes supporting UI → add/update e2e tests in same task
- Treat e2e tests with same rigor as unit tests (must pass before next task)
- Store e2e tests alongside unit tests (or in designated e2e directory)

单元测试：每个任务都需要（见上方开发方法）
E2E测试：如果项目有基于UI的e2e测试（Playwright、Cypress等）：
- UI变更 → 在与UI代码相同的任务中添加/更新e2e测试
- 支持UI的后端变更 → 在相同任务中添加/更新e2e测试
- 对待e2e测试的严格程度要与单元测试相同（开始下一个任务前必须通过）
- 将e2e测试与单元测试放在一起（或放在指定的e2e目录中）

Progress Tracking

进度跟踪

Mark completed items with
```
[x]
```
immediately when done
Add newly discovered tasks with ➕ prefix
Document issues/blockers with ⚠️ prefix
Update plan if implementation deviates from original scope
Keep plan in sync with actual work done

完成后立即用
```
[x]
```
标记已完成项
为新发现的任务添加➕前缀
为问题/障碍添加⚠️前缀
如果实施偏离原始范围，更新计划
保持计划与实际完成的工作同步

What Goes Where

内容分类

Implementation Steps (
```
[ ]
```
checkboxes): tasks achievable within this codebase - code changes, tests, documentation updates
Post-Completion (no checkboxes): items requiring external action - manual testing, changes in consuming projects, deployment configs, third-party verifications

实施步骤（
```
[ ]
```
复选框）：可在本代码库中完成的任务 - 代码变更、测试、文档更新
完成后事项（无复选框）：需要外部操作的项 - 手动测试、依赖项目的变更、部署配置、第三方验证

Implementation Steps

实施步骤

<!-- Task structure guidelines: - Each task = ONE logical unit (one function, one endpoint, one component) - Use specific descriptive names, not generic "[Core Logic]" or "[Implementation]" - Aim for ~5 checkboxes per task (more is OK if logically atomic) - **CRITICAL: Each task MUST end with writing/updating tests before moving to next** - tests are not optional - they are a required deliverable of every task - write tests for all NEW code added in this task - write tests for all MODIFIED code in this task - include both success and error scenarios in tests - list tests as SEPARATE checklist items, not bundled with implementation Example (NOTICE: tests are separate checklist items):

<!-- 任务结构指南： - 每个任务 = 一个逻辑单元（一个函数、一个接口、一个组件） - 使用具体的描述性名称，不要用通用的"[核心逻辑]"或"[实现]" - 每个任务目标为约5个复选框（如果逻辑上是原子性的，更多也可以） - **关键要求：进入下一个任务前，每个任务必须以编写/更新测试结束** - 测试不是可选的 - 它们是每个任务的必填交付项 - 为本任务中添加的所有新代码编写测试 - 为本任务中修改的所有代码编写测试 - 测试需包含成功和错误场景 - 将测试列为单独的复选框项，不要与实施内容捆绑示例（注意：测试是单独的复选框项）：

Task 1: Add password hashing utility

任务1：添加密码哈希工具

create
```
auth/hash
```
module with HashPassword and VerifyPassword functions
implement secure hashing with configurable cost
write tests for HashPassword (success + error cases)
write tests for VerifyPassword (success + error cases)
run project tests - must pass before task 2

创建
```
auth/hash
```
模块，包含HashPassword和VerifyPassword函数
实现可配置成本的安全哈希算法
为HashPassword编写测试（成功+错误场景）
为VerifyPassword编写测试（成功+错误场景）
运行项目测试 - 必须通过才能进入任务2

Task 2: Add user registration endpoint

任务2：添加用户注册接口

create
```
POST /api/users
```
handler
add input validation (email format, password strength)
integrate with password hashing utility
write tests for handler success case with table-driven cases
write tests for handler error cases (invalid input, missing fields)
run project tests - must pass before task 3 -->

创建
```
POST /api/users
```
处理器
添加输入验证（邮箱格式、密码强度）
集成密码哈希工具
为处理器成功场景编写表格驱动测试用例
为处理器错误场景编写测试（无效输入、缺失字段）
运行项目测试 - 必须通过才能进入任务3 -->

Task 1: [specific name - what this task accomplishes]

任务1：[具体名称 - 本任务要完成的内容]

Task N-1: Verify acceptance criteria

任务N-1：验证验收标准

Task N: [Final] Update documentation

任务N：[最终] 更新文档

update README.md if needed
update project knowledge docs if new patterns discovered

如有需要，更新README.md
如果发现新模式，更新项目知识文档

Technical Details

技术细节

Data structures and changes
Parameters and formats
Processing flow

数据结构和变更
参数和格式
处理流程

Post-Completion

完成后事项

Items requiring manual intervention or external systems - no checkboxes, informational only

Manual verification (if applicable):

Manual UI/UX testing scenarios
Performance testing under load
Security review considerations

External system updates (if applicable):

Consuming projects that need updates after this library change
Configuration changes in deployment systems
Third-party service integrations to verify

undefined

需要人工干预或涉及外部系统的项 - 无复选框，仅作信息说明

人工验证（如适用）：

手动UI/UX测试场景
负载下的性能测试
安全审查注意事项

外部系统更新（如适用）：

本库变更后需要更新的依赖项目
部署系统中的配置变更
需要验证的第三方服务集成

undefined

Step 3: Offer to Start

步骤3：提议开始执行

After creating the file, tell user:

"Created plan:

docs/plans/<task-name>.md

Ready to start implementation?"

If yes, begin with task 1.

创建文件后，告知用户：

"已创建计划：

docs/plans/<task-name>.md

准备好开始实施了吗？"

如果用户同意，从任务1开始。

Execution Enforcement

执行规则强制执行

CRITICAL testing rules during implementation:

After completing code changes in a task:
- STOP before moving to next task
- Add tests for all new functionality
- Update tests for modified functionality
- Run project test command
- Mark completed items with
```
[x]
```
  in plan file
- Use TodoWrite tool to track progress and mark todos completed immediately (do not batch)
If tests fail:
- Fix the failures before proceeding
- Do NOT move to next task with failing tests
- Do NOT skip test writing
Only proceed to next task when:
- All task items completed and marked
```
[x]
```
- Tests written/updated
- All tests passing
Plan tracking during implementation:
- Update checkboxes immediately when tasks complete
- Add ➕ prefix for newly discovered tasks
- Add ⚠️ prefix for blockers
- Modify plan if scope changes significantly
On completion:
- Verify all checkboxes marked
- Run final test suite
Partial implementation exception:
- If a task provides partial implementation where tests cannot pass until a later task:
  - Still write the tests as part of this task (required)
  - Add TODO comment in test code noting the dependency
  - Mark the test checkbox as completed with note:
```
[x] write tests ... (fails until Task X)
```
  - Do NOT skip test writing or defer until later
- When the dependent task completes, remove the TODO comment and verify tests pass

This ensures each task is solid before building on top of it.

实施过程中的关键测试规则：

完成一个任务中的代码变更后：
- 在进入下一个任务前暂停
- 为所有新功能添加测试
- 为修改的功能更新测试
- 运行项目测试命令
- 在计划文件中用
```
[x]
```
  标记已完成的项
- 使用TodoWrite工具跟踪进度并立即标记待办事项完成（不要批量处理）
如果测试失败：
- 在继续之前修复失败的测试
- 不要带着失败的测试进入下一个任务
- 不要跳过编写测试
只有满足以下条件才能进入下一个任务：
- 所有任务项已完成并标记为
```
[x]
```
- 已编写/更新测试
- 所有测试通过
实施过程中的计划跟踪：
- 任务完成后立即更新复选框
- 为新发现的任务添加➕前缀
- 为障碍添加⚠️前缀
- 如果范围发生重大变化，修改计划
完成时：
- 验证所有复选框都已标记
- 运行最终测试套件
部分实现例外情况：
- 如果一个任务提供的部分实现需要等到后续任务才能让测试通过：
  - 仍需在本任务中编写测试（必填）
  - 在测试代码中添加TODO注释说明依赖关系
  - 标记测试复选框为已完成，并注明：
```
[x] 编写测试...（需等到任务X才能通过）
```
  - 不要跳过编写测试或推迟到以后
- 当依赖任务完成后，移除TODO注释并验证测试通过

这确保在继续构建之前，每个任务都足够稳固。

Key Principles

核心原则

One question at a time - do not overwhelm user with multiple questions in a single message
Multiple choice preferred - easier to answer than open-ended when possible
YAGNI ruthlessly - remove unnecessary features from all designs, keep scope minimal
Lead with recommendation - have an opinion, explain why, but let user decide
Explore alternatives - always propose 2-3 approaches before settling (unless obvious)
Duplication vs abstraction - when code repeats, ask user: prefer duplication (simpler, no coupling) or abstraction (DRY but adds complexity)? explain trade-offs before deciding

一次只提一个问题 - 不要在一条消息中用多个问题让用户应接不暇
优先使用选择题 - 可能的话，选择题比开放式问题更容易回答
严格遵循YAGNI原则 - 从所有设计中移除不必要的功能，保持最小范围
优先给出推荐方案 - 要有明确的观点，解释原因，但让用户做决定
探索替代方案 - 在确定方案前，始终提出2-3种方案（除非方案显而易见）
重复代码 vs 抽象 - 当代码重复时，询问用户：更喜欢重复代码（更简单，无耦合）还是抽象（遵循DRY原则但增加复杂度）？在做决定前解释权衡利弊