plan
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseUser request: $ARGUMENTS
Build implementation plan through structured discovery. Takes spec (from or inline), iteratively researches codebase + asks high-priority technical questions that shape implementation direction → detailed plan.
$specFocus: HOW not WHAT. Spec=what; plan=architecture, files, functions, chunks, dependencies, tests.
Loop: Research → Expand todos → Ask questions → Write findings → Repeat until complete
Output files:
- Plan:
/tmp/plan-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md - Research log: (external memory)
/tmp/plan-research-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md
用户请求：$ARGUMENTS
通过结构化探索构建实现计划。基于需求规格（来自或内联内容），迭代研究代码库并提出影响实现方向的高优先级技术问题，最终生成详细计划。
$spec核心聚焦：关注HOW而非WHAT。需求规格=要做什么；实现计划=架构、文件、函数、拆分模块、依赖、测试。
循环流程：研究 → 扩展待办事项 → 提出问题 → 记录发现 → 重复直至完成
输出文件:
- 计划文件：
/tmp/plan-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md - 研究日志：（外部记忆存储）
/tmp/plan-research-{YYYYMMDD-HHMMSS}-{name-kebab-case}.md
Boundaries
边界规则
- Spec=requirements; this skill=architecture, files, chunks, tests
- Don't modify spec; flag gaps for user
- Surface infeasibility before proceeding
- No implementation until approved
- 需求规格=功能要求；本技能负责=架构、文件、拆分模块、测试
- 不得修改需求规格；若发现缺口需告知用户
- 在推进前先明确技术可行性
- 未经批准不得开展实现工作
Phase 1: Initial Setup
阶段1：初始设置
1.1 Create todos (update_plan immediately)
1.1 创建待办事项（立即更新计划）
Todos = areas to research/decide, not steps. Expand when research reveals: (a) files/modules to modify beyond those already in todos, (b) 2+ valid implementation patterns with different trade-offs, (c) dependencies on code/systems not yet analyzed, or (d) questions that must be answered before completing an existing todo.
Starter seeds:
- [ ] Read/infer spec requirements
- [ ] Codebase research (patterns, files to modify)
- [ ] Approach identification (if >1 valid approach → trade-off analysis → user decision)
- [ ] Architecture decisions (within chosen approach)
- [ ] (expand as research reveals)
- [ ] Read full research log and spec (context refresh before output)
- [ ] Finalize chunksEvolution example - "Add real-time notifications":
- [x] Read spec → 3 types, mobile+web
- [x] Codebase research → found ws.ts, notification-service.ts, polling in legacy/
- [x] Approach selection → WebSocket vs polling? User chose WebSocket
- [ ] Architecture decisions (within WebSocket approach)
- [ ] Offline storage (IndexedDB vs localStorage)
- [ ] Sync conflict resolution
- [ ] Service worker integration
- [ ] Read full research log and spec (context refresh)
- [ ] Finalize chunksNote: Approach selection shows user decision—not auto-decided. Found two valid approaches, presented trade-offs, user chose.
Key: Never prune todos prematurely. Circular dependencies → merge into single todo: "Research {A} + {B} (merged: circular)".
Adapt to scope: Simple (1-2 files) → omit approach identification if single valid approach. Complex (5+ files) → add domain-specific todos.
待办事项=需要研究/决策的领域，而非执行步骤。当研究发现以下情况时，需扩展待办：(a) 待办中未涵盖的需修改文件/模块，(b) 2种及以上存在不同取舍的有效实现模式，(c) 依赖尚未分析的代码/系统，(d) 完成现有待办前必须解答的问题。
初始待办模板:
- [ ] 读取/推导需求规格要求
- [ ] 代码库研究（模式、需修改文件）
- [ ] 实现方案确定（若存在多种有效方案→取舍分析→用户决策）
- [ ] 架构决策（基于选定方案）
- [ ] （根据研究发现扩展）
- [ ] 通读研究日志和需求规格（输出前刷新上下文）
- [ ] 最终确定拆分模块待办演进示例 - "添加实时通知功能":
- [x] 读取需求规格→3种通知类型，支持移动端+网页端
- [x] 代码库研究→找到ws.ts、notification-service.ts，legacy/目录下存在轮询逻辑
- [x] 方案选择→WebSocket vs 轮询？用户选择WebSocket
- [ ] 架构决策（基于WebSocket方案）
- [ ] 离线存储（IndexedDB vs localStorage）
- [ ] 同步冲突解决
- [ ] Service Worker集成
- [ ] 通读研究日志和需求规格（上下文刷新）
- [ ] 最终确定拆分模块注意：方案选择需体现用户决策——不得自行决定。若发现多种有效方案，需呈现取舍分析，由用户选择。
关键规则：切勿过早删减待办事项。若存在循环依赖→合并为单个待办："研究{A}+{B}（合并：循环依赖）"。
根据范围调整：简单需求（1-2个文件）→若仅有一种有效方案，可省略方案确定步骤。复杂需求（5个及以上文件）→添加领域特定待办。
1.2 Create research log
1.2 创建研究日志
Path:
/tmp/plan-research-{YYYYMMDD-HHMMSS}-{name-kebab-case}.mdmarkdown
undefined路径：
/tmp/plan-research-{YYYYMMDD-HHMMSS}-{name-kebab-case}.mdmarkdown
undefinedResearch Log: {feature}
研究日志：{功能名称}
Started: {timestamp} | Spec: {path or "inline"}
开始时间：{时间戳} | 需求规格：{路径或"内联"}
Codebase Research
代码库研究
Approach Trade-offs
方案取舍分析
Spec Gaps
需求规格缺口
Conflicts
冲突记录
Risks & Mitigations
风险与缓解措施
Architecture Decisions
架构决策
Questions & Answers
问题与解答
Unresolved Items
未解决事项
undefinedundefinedPhase 2: Context Gathering
阶段2：上下文收集
2.1 Read/infer spec
2.1 读取/推导需求规格
Extract: requirements, user stories, acceptance criteria, constraints, out-of-scope.
No formal spec? Infer from conversation, tool outputs, user request. If spec and conversation together provide fewer than 2 concrete requirements, ask user: "I need at least 2 concrete requirements to plan. Please provide: [list what's missing]" before proceeding.
提取内容：功能要求、用户故事、验收标准、约束条件、非范围内容。
无正式需求规格？ 从对话、工具输出、用户请求中推导。若需求规格和对话合计提供的具体要求少于2项，需先询问用户："我至少需要2项具体要求才能制定计划。请补充：[列出缺失内容]"
2.2 Research codebase
2.2 研究代码库
Explore existing implementations, files to modify, patterns, integration points, test patterns. Use file search and code reading to understand:
- How similar features are implemented
- What files need modification
- Existing patterns and conventions
- Test structure and patterns
探索现有实现、需修改的文件、代码模式、集成点、测试模式。通过文件搜索和代码阅读明确：
- 类似功能的实现方式
- 需要修改的文件
- 现有代码模式与规范
- 测试结构与模式
2.3 Read ALL recommended files
2.3 阅读所有推荐文件
No skipping. Gives firsthand knowledge of patterns, architecture, integration, tests.
不得跳过。直接掌握代码模式、架构、集成方式、测试逻辑。
2.4 Update research log
2.4 更新研究日志
After EACH step:
markdown
undefined每完成一个步骤后更新：
markdown
undefined{timestamp} - {what researched}
{时间戳} - {研究内容}
- Explored: {areas}
- Key findings: {files, patterns, integration points}
- New areas: {list}
- Architectural questions: {list}
undefined- 探索范围：{领域}
- 关键发现：{文件、模式、集成点}
- 新研究领域：{列表}
- 架构问题：{列表}
undefined2.5 Approach Identification & Trade-off Analysis
2.5 方案识别与取舍分析
CRITICAL: Before implementation details, identify whether multiple valid approaches exist. This is THE question that cuts option space—answering it eliminates entire planning branches.
Valid approach = (1) fulfills all spec requirements, (2) technically feasible, (3) has at least one "When it wins" condition. Don't present invalid approaches.
When: After initial research (2.2-2.4), before any implementation details.
What counts as multiple approaches: different architectural layers, implementation patterns (eager/lazy, push/pull), integration points (modify existing vs create new), scopes (filter at source vs consumer). Multiple valid locations = multiple approaches; multiple valid patterns = multiple approaches.
Process:
- From research: Where could this live? How implemented? Who consumes what we're modifying?
- One valid approach → document why in log, proceed
- Multiple valid → STOP until user decides
Trade-off format (research log ):
## Approach Trade-offsmarkdown
undefined核心要求：在确定实现细节前，先判断是否存在多种有效方案。这是缩小选择范围的关键问题——回答后可排除大量无效规划分支。
有效方案=（1）满足所有需求规格要求，（2）技术可行，（3）至少存在一种"适用场景"。不得呈现无效方案。
执行时机：完成初始研究（2.2-2.4）后，确定任何实现细节前。
多种有效方案的判定：不同架构层、实现模式（即时/延迟、推送/拉取）、集成点（修改现有代码vs新建）、范围（源头过滤vs消费端过滤）。多个有效部署位置=多种方案；多种有效模式=多种方案。
执行流程:
- 基于研究：功能可部署在何处？如何实现？谁会依赖我们修改的内容？
- 仅一种有效方案→在日志中记录原因，继续推进
- 多种有效方案→暂停，等待用户决策
取舍分析格式（研究日志）:
## 方案取舍分析markdown
undefinedApproaches: {what deciding}
方案选择：{决策主题}
Approach A: {name}
- How: {description}
- Pros: {list}
- Cons: {list}
- When it wins: {conditions}
- Affected consumers: {list}
Approach B: {name}
- How: {description}
- Pros: {list}
- Cons: {list}
- When it wins: {conditions}
- Affected consumers: {list}
Existing codebase pattern: {how similar solved}
Recommendation: {approach} — {why}
Choose alternative if: {honest conditions where other approach wins}
**Recommendation = cleanest**: (1) separation of concerns (if unsure: use layer where similar features live), (2) matches codebase patterns, (3) minimizes blast radius, (4) most reversible. Prioritize 1>2>3>4.
**Be honest**: State clearly when alternative wins. User has context you don't (future plans, team preferences, business constraints).
**Skip asking only when**: genuinely ONE valid approach (document why others don't work) OR ALL five measurable skip criteria true:
1. Same files changed by both
2. No consumer behavior change
3. Reversible in <1 chunk (<200 lines)
4. No schema/API/public interface changes
5. No different error/failure modes
If ANY fails → ask user.方案A：{名称}
- 实现方式：{描述}
- 优势：{列表}
- 劣势：{列表}
- 适用场景：{条件}
- 影响的消费者：{列表}
方案B：{名称}
- 实现方式：{描述}
- 优势：{列表}
- 劣势：{列表}
- 适用场景：{条件}
- 影响的消费者：{列表}
现有代码库模式：{类似问题的解决方式}
推荐方案：{方案} — {理由}
可选择替代方案的场景：{客观条件}
**推荐原则=最简洁可行**：(1) 关注点分离（若不确定→选择与类似功能相同的层级），(2) 匹配现有代码库模式，(3) 最小化影响范围，(4) 最易回滚。优先级1>2>3>4。
**保持客观**：明确说明替代方案的适用场景。用户拥有你不具备的上下文（未来规划、团队偏好、业务约束）。
**仅在以下情况可跳过询问**：确实仅有一种有效方案（记录为何其他方案无效）OR 全部5项可跳过标准均满足：
1. 两种方案修改的文件完全相同
2. 消费者行为无变化
3. 回滚所需代码量<200行（少于1个拆分模块）
4. 无 schema/API/公共接口变更
5. 无不同的错误/故障模式
若任意一项不满足→询问用户。2.6 Write initial draft
2.6 编写初始草案
Precondition: Approach decided (single documented OR user chose/delegated after trade-offs). Don't write until approach resolved.
First draft with markers. Same file path for all updates.
[TBD]前置条件：方案已确定（已记录唯一有效方案OR用户已在取舍分析后选择/委托决策）。方案未确定前不得编写。
初始草案使用标记待确定内容。所有更新均使用同一文件路径。
[TBD]Phase 3: Iterative Discovery Interview
阶段3：迭代式探索与沟通
Memento Loop
记忆循环
- Mark todo
in_progress - Research (codebase) OR ask question
- Write findings immediately to research log
- Expand todos for new questions/integration points/dependencies
- Update plan (replace )
[TBD] - Mark todo
completed - Repeat until no pending todos
NEVER proceed without writing findings — research log = external memory.
If user answer contradicts prior decisions: (1) Inform user: "This contradicts earlier decision X. Proceeding with new answer." (2) Log in research log under with both decisions. (3) Re-evaluate affected todos. (4) Update plan accordingly. If contradiction cannot be resolved, ask user to clarify priority.
## Conflicts- 将待办标记为
in_progress - 研究（代码库）OR 提出问题
- 立即记录发现到研究日志
- 针对新问题/集成点/依赖扩展待办
- 更新计划（替换）
[TBD] - 将待办标记为
completed - 重复直至无待处理待办
禁止未记录发现就推进 — 研究日志=外部记忆。
若用户回答与之前决策矛盾：(1) 告知用户："此回答与之前的决策X矛盾，将基于新回答推进。" (2) 在研究日志的中记录两种决策。(3) 重新评估受影响的待办。(4) 相应更新计划。若矛盾无法解决，询问用户明确优先级。
## 冲突记录Research Log Update Format
研究日志更新格式
markdown
undefinedmarkdown
undefined{timestamp} - {what}
{时间戳} - {内容}
Todo: {which}
Finding/Answer: {result}
Impact: {what revealed/decided}
New areas: {list or "none"}
Architecture decisions:
```markdown
- {Area}: {choice} — {rationale}待办事项：{对应待办}
发现/回答：{结果}
影响：{明确的决策/发现}
新研究领域：{列表或"无"}
架构决策记录格式：
```markdown
- {领域}：{选择} — {理由}Todo Expansion Triggers
待办扩展触发条件
| Research Reveals | Add Todos For |
|---|---|
| Existing similar code | Integration approach |
| Multiple valid patterns | Pattern selection |
| External dependency | Dependency strategy |
| Complex state | State architecture |
| Cross-cutting concern | Concern isolation |
| Performance-sensitive | Performance strategy |
| Migration needed | Migration path |
| 研究发现 | 需添加的待办 |
|---|---|
| 存在类似现有代码 | 集成方案 |
| 多种有效模式 | 模式选择 |
| 外部依赖 | 依赖处理策略 |
| 复杂状态 | 状态架构 |
| 横切关注点 | 关注点隔离方案 |
| 性能敏感场景 | 性能优化策略 |
| 需要迁移 | 迁移路径 |
Interview Rules
沟通规则
Unbounded loop: Iterate until ALL completion criteria met. No fixed round limit. If user says "just decide", "you pick", "I don't care", "skip this", or otherwise explicitly delegates the decision, document remaining decisions with markers and finalize.
[INFERRED: {choice} - {rationale}]Spec-first: Business scope and requirements belong in spec. Questions here are TECHNICAL only—architecture, patterns, implementation approach. If spec has gaps affecting implementation: (1) flag in research log under , (2) ask user whether to pause for spec update OR proceed with stated assumption, (3) document choice and continue.
## Spec Gaps-
Prioritize questions that eliminate other questions - Ask questions where the answer changes what other questions you need to ask, or eliminates entire branches of implementation. If knowing X makes Y irrelevant, ask X first.
-
Interleave discovery and questions:
- User answer reveals new area → research codebase
- Need external context → use web search
- Update plan after each iteration, replacing markers
[TBD]
-
Question priority order:
Priority Type Purpose Examples 0 Approach Selection Fundamental architecture WebSocket vs polling? Modify existing vs create new? Filter at source vs consumer? Where should this live? 1 Implementation Phasing How much to build now vs later Full impl vs stub? Include migration? Optimize or simple first? 2 Branching Open/close implementation paths Sync vs async? Polling vs push? In-memory vs persistent? 3 Technical Constraints Non-negotiable technical limits Must integrate with X? Performance requirements? Backward compatibility? 4 Architectural Choose between patterns Error strategy? State management? Concurrency model? 5 Detail Refinement Fine-grained technical details Test coverage scope? Retry policy? Logging verbosity? P0 rules: If P0 question exists, ask P0 first before ANY implementation details. Wrong approach = entire plan wasted. P0 is mandatory when >1 valid approach (section 2.5). -
Always mark one option "(Recommended)" - put first with reasoning in description. When options are equivalent AND easily reversible (changes affect only 1-2 files, where each changed file is imported by 5 or fewer other files, and there are no data migrations, schema changes, or public API changes), decide yourself (lean toward existing codebase patterns).
-
Be thorough via technique:
- Cover technical decisions from each applicable priority category (1-5 in the priority table)—don't skip categories to save time
- Reduce cognitive load through HOW you ask: concrete options, good defaults
- Batching: Group related questions together (batch questions that share a common decision—e.g., multiple state management questions, or multiple error handling questions—where answers to one inform the others)
- Make decisions yourself when codebase research suffices
- Complete plan with easy questions > incomplete plan with fewer questions
-
Ask non-obvious questions - Error handling strategies, edge cases affecting correctness, performance implications, testing approach for complex logic, rollback/migration needs, failure modes
-
Ask vs Decide - Codebase patterns and technical standards are authority; user decides significant trade-offs.Ask user when:
Category Examples Trade-offs affecting measurable outcomes Estimated >20% change to latency/throughput vs current implementation, adds abstraction layers, locks approach for >6 months, changes user-facing behavior No clear codebase precedent New pattern not yet established Multiple valid approaches Architecture choice with different implications Phasing decisions Full impl vs stub, migration included or deferred Breaking changes API changes, schema migrations Resource allocation Cache size, connection pools, batch sizes with cost implications Decide yourself when:Category Examples Existing codebase pattern Error format, naming conventions, file structure Industry standard HTTP status codes, retry with exponential backoff Sensible defaults Timeout 30s, pagination 50 items, debounce 300ms Easily changed later Internal function names, log messages, test structure Implementation detail Which hook to use, internal state shape, helper organization Clear best practice Dependency injection, separation of concerns Test: "If I picked wrong, would user say 'that's not what I meant' (ASK) or 'that works, I would have done similar' (DECIDE)?"
无固定循环次数：迭代直至所有完成条件满足。若用户表示"你来决定"、"你选"、"我无所谓"、"跳过这个"或明确委托决策，需用标记剩余决策并最终确定计划。
[INFERRED: {选择} - {理由}]需求规格优先：业务范围和要求属于需求规格阶段。此处仅询问技术问题——架构、模式、实现方案。若需求规格存在影响实现的缺口：(1) 在研究日志的中标记，(2) 询问用户是暂停更新需求规格还是基于假设推进，(3) 记录选择并继续。
## 需求规格缺口-
优先询问可减少后续问题的关键问题 - 选择答案会改变后续问题方向或排除整个实现分支的问题。若知道X后Y变得无关，先询问X。
-
交替进行探索与提问:
- 用户回答揭示新领域→研究代码库
- 需要外部上下文→使用网络搜索
- 每次迭代后更新计划，替换标记
[TBD]
-
问题优先级排序:
优先级 类型 目的 示例 0 方案选择 核心架构决策 WebSocket vs 轮询？修改现有代码vs新建？源头过滤vs消费端过滤？功能部署位置？ 1 实现阶段划分 现阶段实现范围 vs 后续迭代 完整实现vs占位实现？是否包含迁移？优先实现核心功能还是优化？ 2 分支决策 开启/关闭实现路径 同步vs异步？轮询vs推送？内存存储vs持久化存储？ 3 技术约束 不可协商的技术限制 必须与X集成？性能要求？向后兼容？ 4 架构决策 模式选择 错误处理策略？状态管理？并发模型？ 5 细节优化 细粒度技术细节 测试覆盖范围？重试策略？日志级别？ P0规则：若存在P0问题，需优先询问，再处理任何实现细节。错误的方案会导致整个计划失效。当存在多种有效方案时，P0问题为必问项（见2.5节）。 -
始终标记一个"(推荐)"选项 - 将推荐选项放在首位并说明理由。当选项等价且易于回滚（仅影响1-2个文件，每个文件被不超过5个其他文件引用，无数据迁移、schema变更或公共API变更），可自行决策（倾向于匹配现有代码库模式）。
-
全面覆盖:
- 覆盖所有适用优先级类别的技术决策（优先级表1-5）——不得为节省时间跳过类别
- 通过具体选项、合理默认值降低认知负担
- 批量提问：将相关问题分组（例如，多个状态管理问题或多个错误处理问题，其中一个问题的答案会影响其他问题）
- 若代码库研究可得出结论，自行决策
- 优先完成包含简单问题的完整计划，而非仅包含少量问题的不完整计划
-
询问非显而易见的问题 - 错误处理策略、影响正确性的边缘情况、复杂逻辑的测试方案、回滚/迁移需求、故障模式
-
询问vs自行决策 - 代码库模式和技术标准为权威依据；用户决定重大取舍。需询问用户的场景:
类别 示例 影响可衡量结果的取舍 与当前实现相比，延迟/吞吐量预计变化>20%，添加抽象层，锁定方案超过6个月，改变用户可见行为 无明确代码库先例 采用尚未确立的新模式 多种有效方案 具有不同影响的架构选择 阶段划分决策 完整实现vs占位实现，迁移是否包含在当前阶段 破坏性变更 API变更、schema迁移 资源分配 缓存大小、连接池、有成本影响的批量大小 可自行决策的场景:类别 示例 现有代码库模式 错误格式、命名规范、文件结构 行业标准 HTTP状态码、指数退避重试 合理默认值 超时30s、分页50条、防抖300ms 后续易修改内容 内部函数名、日志消息、测试结构 实现细节 使用哪个Hook、内部状态结构、辅助函数组织 明确最佳实践 依赖注入、关注点分离 测试方法："如果我决策错误，用户会说'这不是我想要的'（需询问）还是'可以，我也会这么做'（可自行决策）？"
Phase 4: Finalize & Present
阶段4：最终确定与提交
4.1 Final research log update
4.1 最终更新研究日志
markdown
undefinedmarkdown
undefinedPlanning Complete
规划完成
Finished: {timestamp} | Research log entries: {count} | Architecture decisions: {count}
结束时间：{时间戳} | 研究日志条目数：{数量} | 架构决策数：{数量}
Summary
总结
{Key decisions}
undefined{关键决策}
undefined4.2 Refresh context
4.2 刷新上下文
Read the full research log file to restore all findings, decisions, and rationale into context before writing the final plan.
通读研究日志文件，在编写最终计划前恢复所有发现、决策和理由。
4.3 Finalize plan
4.3 最终确定计划
Remove , ensure chunk consistency, verify dependency ordering, add line ranges for files >500 lines.
[TBD]移除标记，确保拆分模块一致性，验证依赖顺序，为超过500行的文件添加行范围。
[TBD]4.4 Mark all todos complete
4.4 标记所有待办为完成
4.5 Present approval summary
4.5 提交审批摘要
undefinedundefinedPlan Approval Summary: {Feature}
计划审批摘要：{功能名称}
Plan file: /tmp/plan-{...}.md
计划文件：/tmp/plan-{...}.md
At a Glance
概览
| Aspect | Summary |
|---|---|
| Approach | {Chosen approach from P0 decision} |
| Chunks | {count} |
| Parallel | {which chunks can run in parallel} |
| Risk | {primary risk or "Low - standard patterns"} |
| 维度 | 摘要 |
|---|---|
| 方案 | {P0决策选定的方案} |
| 拆分模块数 | {数量} |
| 可并行模块 | {可并行的模块} |
| 风险 | {主要风险或"低 - 采用标准模式"} |
Execution Flow
执行流程
{ASCII dependency diagram}
Example format:
┌─────────────┐
│ 1. Types │
└──────┬──────┘
│
┌────┴────┐
▼ ▼
┌─────┐ ┌─────┐
│ 2.A │ │ 2.B │ ← Parallel
└──┬──┘ └──┬──┘
└────┬────┘
▼
┌─────────┐
│ 3. Integ│
└─────────┘
{ASCII依赖关系图}
示例格式：
┌─────────────┐
│ 1. 类型定义 │
└──────┬──────┘
│
┌────┴────┐
▼ ▼
┌─────┐ ┌─────┐
│ 2.A │ │ 2.B │ ← 可并行
└──┬──┘ └──┬──┘
└────┬────┘
▼
┌─────────┐
│ 3. 集成逻辑│
└─────────┘
Chunks
拆分模块
- {Name}: {one-line description}
- {Name}: {one-line description} ...
- {名称}: {一行描述}
- {名称}: {一行描述} ...
Key Decisions
关键决策
| Decision | Choice | Rationale |
|---|---|---|
| {Area} | {Choice} | {Brief why} |
| 决策领域 | 选择 | 理由 |
|---|---|---|
| {领域} | {选择} | {简要理由} |
Risks & Mitigations
风险与缓解措施
| Risk | Mitigation |
|---|---|
| {Risk} | {How addressed} |
Review full plan. Approve to start implementation.
**Diagram guidelines**:
- Show chunk dependencies and parallel opportunities
- Number chunks to match plan
- Use box characters: `┌ ┐ └ ┘ │ ─ ┬ ┴ ├ ┤ ▼` or simple ASCII
- Label parallel opportunities
- Keep to actual chunk count| 风险 | 缓解措施 |
|---|---|
| {风险} | {解决方法} |
请审阅完整计划。批准后即可开始实现。
**依赖关系图规范**:
- 展示模块依赖关系和并行机会
- 模块编号与计划一致
- 使用盒状字符：`┌ ┐ └ ┘ │ ─ ┬ ┴ ├ ┤ ▼` 或简单ASCII字符
- 标记可并行模块
- 与实际模块数一致4.6 Wait for approval
4.6 等待审批
Do NOT implement until user explicitly approves. After approval: create todos from chunks, execute.
未经用户明确批准不得开始实现。批准后：根据拆分模块创建待办并执行。
Planning Methodology
规划方法论
1. Principles
1. 核心原则
| Principle | Description |
|---|---|
| Safety | Never skip gates (type checks, tests, lint); every chunk tests+demos independently |
| Clarity | Full paths, numbered chunks, rationale for context files, line ranges |
| Minimalism | Ship today's requirements; parallelize where possible |
| Forward focus | Don't prioritize backward compatibility unless requested or public API/schema contracts would be broken |
| Cognitive load | Deep modules with simple interfaces > many shallow; reduce choices |
| Conflicts | Safety > Clarity > Minimalism > Forward focus |
Definitions:
- Gates: Quality checks every chunk must pass—type checks (0 errors), tests (pass), lint (clean)
- Mini-PR: A chunk sized to be its own small pull request—complete, mergeable, reviewable independently
- Deep modules: Modules that hide complexity behind simple interfaces (few public methods, rich internal logic)
| 原则 | 描述 |
|---|---|
| 安全优先 | 绝不跳过质量校验关卡（类型检查、测试、代码检查）；每个拆分模块需独立通过测试并可演示 |
| 清晰明确 | 完整路径、编号模块、上下文文件理由、行范围 |
| 最小化交付 | 仅交付当前需求；尽可能并行执行 |
| 面向未来 | 除非明确要求或会破坏公共API/schema契约，否则不优先考虑向后兼容 |
| 降低认知负担 | 内部复杂但接口简洁的深模块优于大量浅模块；减少选择项 |
| 冲突处理优先级 | 安全 > 清晰 > 最小化 > 面向未来 |
定义:
- 质量校验关卡：每个拆分模块必须通过的质量检查——类型检查（0错误）、测试（通过）、代码检查（无问题）
- Mini-PR：拆分后的模块可作为独立的小型Pull Request——完整、可合并、可独立评审
- 深模块：通过简单接口隐藏内部复杂度的模块（少量公共方法，丰富内部逻辑）
Code Quality (P1-P10)
代码质量原则（P1-P10）
User's explicit intent takes precedence for implementation choices (P2-P10). P1 (Correctness) and Safety gates (type checks 0 errors, tests pass, lint clean) are non-negotiable—if user requests skipping these, flag as risk but do not skip.
| # | Principle | Planning Implication |
|---|---|---|
| P1 | Correctness | Every chunk must demonstrably work |
| P2 | Observability | Plan logging, error visibility |
| P3 | Illegal States Unrepresentable | Design types preventing compile-time bugs |
| P4 | Single Responsibility | Each chunk ONE thing |
| P5 | Explicit Over Implicit | Clear APIs, no hidden behaviors |
| P6 | Minimal Surface Area | YAGNI—don't add features beyond spec |
| P7 | Tests | Specific cases, not "add tests" |
| P8 | Safe Evolution | Public API/schema changes need migration |
| P9 | Fault Containment | Plan failure isolation, retry/fallback |
| P10 | Comments Why | Document complex logic why, not what |
P1-P10 apply to code quality within chunks. Principle conflicts (Safety > Clarity > Minimalism > Forward focus) govern planning-level decisions. When both apply, Safety (gates) takes precedence over all P2-P10.
Values: Mini-PR > monolithic; parallel > sequential; function-level > code details; dependency clarity > implicit coupling; ship-ready > half-built
用户明确的实现意图优先于P2-P10原则。P1（正确性）和安全校验关卡（类型检查0错误、测试通过、代码检查无问题）为不可协商项——若用户要求跳过，需标记为风险但不得跳过。
| 编号 | 原则 | 规划影响 |
|---|---|---|
| P1 | 正确性 | 每个拆分模块必须可验证地正常工作 |
| P2 | 可观测性 | 规划日志、错误可见性 |
| P3 | 非法状态不可表示 | 设计类型以避免编译时错误 |
| P4 | 单一职责 | 每个拆分模块仅负责一件事 |
| P5 | 显式优于隐式 | 清晰的API，无隐藏行为 |
| P6 | 最小化接口 | YAGNI——不添加需求规格外的功能 |
| P7 | 测试 | 指定具体测试场景，而非笼统的"添加测试" |
| P8 | 安全演进 | 公共API/schema变更需包含迁移方案 |
| P9 | 故障隔离 | 规划故障隔离、重试/降级策略 |
| P10 | 注释说明原因 | 仅为复杂逻辑添加注释说明原因，而非功能描述 |
P1-P10适用于拆分模块内的代码质量。原则冲突处理优先级（安全 > 清晰 > 最小化 > 面向未来）管理规划层面的决策。当两者同时适用时，安全校验关卡优先于所有P2-P10原则。
价值观：Mini-PR > 单体式；并行 > 串行；函数级规划 > 代码细节；依赖清晰 > 隐式耦合；可交付 > 半成品
2. Mini-PR Chunks
2. Mini-PR拆分模块要求
Each chunk must:
- Ship complete value (demo independently)
- Pass all gates (type checks, tests, lint)
- Be mergeable alone (1-3 functions, <200 lines of code)
- Include its tests (name specific inputs/scenarios, e.g., "valid email accepts user@domain.com", "invalid rejects missing @")
每个拆分模块必须：
- 可独立交付价值（可单独演示）
- 通过所有质量校验关卡（类型检查、测试、代码检查）
- 可单独合并（1-3个函数，代码量<200行）
- 包含自身测试（指定具体输入/场景，例如："有效邮箱接受user@domain.com"、"无效邮箱拒绝缺少@的地址"）
3. Chunk Sizing
3. 模块拆分规模
| Complexity | Chunks | Guidance |
|---|---|---|
| Simple | 1-2 | 1-3 functions each |
| Medium | 3-5 | <200 lines of code per chunk |
| Complex | 5-8 | Each demo-able |
| Integration | +1 final | Connect prior work |
Decision guide: New model/schema → types chunk first | >3 files or >5 functions → split by concern | Complex integration → foundation then integration | One module <200 lines of code → single chunk OK
| 复杂度 | 模块数 | 指导原则 |
|---|---|---|
| 简单 | 1-2 | 每个模块1-3个函数 |
| 中等 | 3-5 | 每个模块代码量<200行 |
| 复杂 | 5-8 | 每个模块可独立演示 |
| 集成类 | +1个最终集成模块 | 连接之前的所有模块 |
决策指南：新模型/schema→先拆分类型定义模块 | 涉及>3个文件或>5个函数→按关注点拆分 | 复杂集成→先拆分基础模块再拆分集成模块 | 单个模块代码量<200行→可作为单个模块
4. Dependency Ordering
4. 依赖排序
- True dependencies: uses types, calls functions, extends
- False dependencies: same feature, no interaction (parallelize these)
- Minimize chains: A→B and A→C, then B,C→D (not A→B→C→D)
- Circular dependencies: If chunks form a cycle (A needs B, B needs C, C needs A), extract shared interfaces/types into a new foundation chunk that breaks the cycle
- Number chunks; mark parallel opportunities
- 真实依赖：使用类型、调用函数、继承
- 伪依赖：同属一个功能但无交互（可并行执行）
- 最小化依赖链：A→B和A→C，然后B,C→D（而非A→B→C→D）
- 循环依赖：若模块形成循环（A依赖B，B依赖C，C依赖A），提取共享接口/类型到新的基础模块以打破循环
- 为模块编号；标记可并行模块
5. What Belongs
5. 计划内容边界
| Belongs | Does Not Belong |
|---|---|
| Numbered chunks, gates, todo descriptions | Code snippets |
| File manifests with reasons | Extra features, future-proofing |
| Function names only | Performance tuning, assumed knowledge |
| 属于计划内容 | 不属于计划内容 |
|---|---|
| 编号模块、质量校验关卡、待办描述 | 代码片段 |
| 带理由的文件清单 | 额外功能、过度设计 |
| 仅函数名称 | 性能调优、假设性知识 |
6. Cognitive Load
6. 认知负担优化
- Deep modules first: fewer with simple interfaces, hide complexity
- Minimize indirection: layers only for concrete extension
- Composition root: one wiring point
- Decide late: abstraction only when PR needs extension
- Framework at edges: core logic agnostic, thin adapters
- Reduce choices: one idiomatic approach per concern
- Measure: if understanding the chunk's purpose requires reading more than 3 files or tracing more than 5 function calls, simplify it
- 优先深模块：数量少但接口简单，隐藏复杂度
- 最小化间接依赖：仅为具体扩展需求添加层级
- 组合根：单一入口点
- 延迟抽象：仅当PR需要扩展时才添加抽象
- 框架仅用于边缘层：核心逻辑与框架无关，使用薄适配器
- 减少选择：每个关注点仅保留一种惯用实现方式
- 衡量标准：若理解模块用途需要阅读超过3个文件或追踪超过5个函数调用，需简化模块
7. Common Patterns
7. 常见规划模式
| Pattern | Flow |
|---|---|
| Sequential | Model → Logic → API → Error handling |
| Parallel after foundation | Model → CRUD ops (parallel) → Integration |
| Pipeline | Types → Parse/Transform (parallel) → Format → Errors |
| Authentication | User model → Login → Auth middleware → Logout |
| Search | Data structure → Algorithm → API → Ranking |
| 模式 | 流程 |
|---|---|
| 串行 | 模型 → 逻辑 → API → 错误处理 |
| 基础模块后并行 | 模型 → CRUD操作（并行） → 集成 |
| 流水线 | 类型 → 解析/转换（并行） → 格式化 → 错误处理 |
| 认证 | 用户模型 → 登录 → 认证中间件 → 登出 |
| 搜索 | 数据结构 → 算法 → API → 排序 |
8. Plan Template
8. 计划模板
markdown
undefinedmarkdown
undefinedIMPLEMENTATION PLAN: [Feature]
实现计划: [功能名称]
[1-2 sentences]
Gates: Type checks (0 errors), Tests (pass), Lint (clean)
[1-2句话描述]
质量校验关卡：类型检查（0错误）、测试（通过）、代码检查（无问题）
Requirement Coverage
需求覆盖
- [Spec requirement] → Chunk N
- [Spec requirement] → Chunk M, Chunk N
- [需求规格要求] → 模块N
- [需求规格要求] → 模块M, 模块N
1. [Name]
1. [模块名称]
Depends on: - | Parallel: -
[What this delivers]
Files to modify:
- path.ts - [changes]
Files to create:
- new.ts - [purpose]
Context files:
- reference.ts - [why relevant]
Notes: [Assumptions, alternatives considered]
Risks:
- [Specific risk] → [mitigation]
Tasks:
- Implement fn() - [purpose]
- Tests - [cases]
- Run gates
Acceptance criteria:
- Gates pass
- [Specific verifiable criterion]
Key functions: fn(), helper()
Types: TypeName
undefined依赖模块：- | 可并行模块：-
[模块交付内容]
需修改文件:
- path.ts - [变更内容]
需创建文件:
- new.ts - [用途]
上下文文件:
- reference.ts - [相关性说明]
备注: [假设条件、已考虑的替代方案]
风险:
- [具体风险] → [缓解措施]
任务:
- 实现fn() - [用途]
- 测试 - [场景]
- 通过质量校验关卡
验收标准:
- 通过所有质量校验关卡
- [具体可验证标准]
关键函数: fn(), helper()
类型定义: TypeName
undefinedGood Example
优秀示例
markdown
undefinedmarkdown
undefined2. Add User Validation Service
2. 添加用户验证服务
Depends on: 1 (User types) | Parallel: 3
Implements email/password validation with rate limiting.
Files to modify:
- src/services/user.ts - Add validateUserInput()
Files to create:
- src/services/validation.ts - Validation + rate limiter
Context:
- src/services/auth.ts:45-80 - Existing validation patterns
- src/types/user.ts - User types from chunk 1
Tasks:
- validateEmail() - RFC 5322
- validatePassword() - Min 8, 1 number, 1 special
- rateLimit() - 5 attempts/min/IP
- Tests: valid email, invalid formats, password edges, rate limit
- Run gates
Acceptance criteria:
- Gates pass
- validateEmail() rejects invalid formats, accepts valid RFC 5322
- validatePassword() enforces min 8, 1 number, 1 special
- Rate limiter blocks after 5 attempts/min/IP
Functions: validateUserInput(), validateEmail(), rateLimit()
Types: ValidationResult, RateLimitConfig
undefined依赖模块：1（用户类型定义） | 可并行模块：3
实现邮箱/密码验证及频率限制功能。
需修改文件:
- src/services/user.ts - 添加validateUserInput()
需创建文件:
- src/services/validation.ts - 验证逻辑+频率限制器
上下文文件:
- src/services/auth.ts:45-80 - 现有验证模式
- src/types/user.ts - 模块1定义的用户类型
任务:
- validateEmail() - 符合RFC 5322标准
- validatePassword() - 最小8位，包含1个数字和1个特殊字符
- rateLimit() - 每分钟每个IP最多5次尝试
- 测试：有效邮箱、无效格式、密码边界情况、频率限制
- 通过质量校验关卡
验收标准:
- 通过所有质量校验关卡
- validateEmail()拒绝无效格式，接受符合RFC 5322的有效邮箱
- validatePassword()强制执行最小8位、1个数字、1个特殊字符的规则
- 频率限制器在每分钟每个IP尝试5次后阻止请求
关键函数: validateUserInput(), validateEmail(), rateLimit()
类型定义: ValidationResult, RateLimitConfig
undefinedBad Example
反面示例
markdown
undefinedmarkdown
undefined2. User Stuff
2. 用户相关功能
Add validation for users.
Files: user.ts
Tasks: Add validation, Add tests
**Why bad**: No dependencies, vague description, missing full paths, no context files, generic tasks, no functions listed, no acceptance criteria.添加用户验证。
文件: user.ts
任务: 添加验证、添加测试
**问题**：无依赖说明、描述模糊、缺少完整路径、无上下文文件、任务笼统、未列出函数、无验收标准。9. File Manifest & Context
9. 文件清单与上下文
- Every file to modify/create; specify changes and purpose
- Full paths; zero prior knowledge assumed
- Context files: explain WHY; line ranges for files >500 lines
- 列出所有需修改/创建的文件；说明变更内容和用途
- 使用完整路径；假设读者无前置知识
- 上下文文件：说明相关性；超过500行的文件需添加行范围
10. Quality Criteria
10. 质量标准
| Level | Criteria |
|---|---|
| Good | Each chunk ships value; dependencies ordered; parallel identified; files explicit; context has reasons; tests in todos; gates listed |
| Excellent | + optimal parallelization, line numbers, clear integration, risks, alternatives, reduces cognitive load |
| 级别 | 标准 |
|---|---|
| 良好 | 每个模块交付独立价值；依赖关系有序；识别并行机会；文件明确；上下文包含理由；测试在待办中；列出质量校验关卡 |
| 优秀 | + 最优并行化、行号、清晰集成逻辑、风险与缓解措施、降低认知负担 |
Quality Checklist
质量检查清单
MUST verify:
- Correctness: boundaries, null/empty, error paths
- Type Safety: types prevent invalid states; validation at boundaries
- Tests: critical + error + boundary paths
SHOULD verify:
- Observability: errors logged with context
- Resilience: timeouts, retries with backoff, cleanup
- Clarity: descriptive names, no magic values
- Modularity: single responsibility, <200 lines of code, minimal coupling
- Evolution: public API/schema changes have migration
必须验证:
- 正确性：边界情况、空值/空输入、错误路径
- 类型安全：类型定义防止无效状态；边界处验证
- 测试：覆盖关键路径+错误路径+边界路径
建议验证:
- 可观测性：错误日志包含上下文
- 韧性：超时、指数退避重试、资源清理
- 清晰性：命名描述性强，无魔法值
- 模块化：单一职责，代码量<200行，耦合度低
- 可演进性：公共API/schema变更包含迁移方案
Test Priority
测试优先级
| Priority | What | Requirement |
|---|---|---|
| 9-10 | Data mutations, money, auth, state machines | MUST |
| 7-8 | Business logic, API contracts, errors | SHOULD |
| 5-6 | Edge cases, boundaries, integration | GOOD |
| 1-4 | Trivial getters, pass-through | OPTIONAL |
| 优先级 | 测试内容 | 要求 |
|---|---|---|
| 9-10 | 数据变更、资金、认证、状态机 | 必须覆盖 |
| 7-8 | 业务逻辑、API契约、错误处理 | 建议覆盖 |
| 5-6 | 边缘情况、边界、集成 | 良好覆盖 |
| 1-4 | 简单Getter、透传逻辑 | 可选覆盖 |
Error Handling
错误处理
For external systems/user input, specify:
- What can fail
- How failures surface
- Recovery strategy
Avoid: empty catch, catch-return-null, silent fallbacks, broad catching.
针对外部系统/用户输入，需明确：
- 可能的故障点
- 故障暴露方式
- 恢复策略
避免：空catch块、catch后返回null、静默降级、宽泛的catch范围。
11. Problem Scenarios
11. 常见问题场景处理
| Scenario | Action |
|---|---|
| No detailed requirements | Research → core requirements/constraints unclear: ask user OR stop → non-critical: assume+document |
| Extensive requirements | MUSTs first → research scope → ask priority trade-offs → defer SHOULD/MAY |
| Multiple approaches | Research first → ask only when significantly different implications |
| Everything dependent | Start from types → question each dependency → find false dependencies → foundation → parallel → integration |
| 场景 | 行动 |
|---|---|
| 无详细需求 | 研究后核心要求/约束仍不明确：询问用户 OR 停止 → 非关键需求：基于假设推进并记录 |
| 需求繁多 | 先处理必须项 → 研究范围 → 询问优先级取舍 → 推迟可选项 |
| 多种有效方案 | 先研究 → 仅当方案存在显著不同影响时询问用户 |
| 所有模块相互依赖 | 从类型定义开始 → 逐一验证依赖 → 识别伪依赖 → 基础模块 → 并行模块 → 集成模块 |
Planning Mantras
规划口诀
Memento (always):
- Write findings BEFORE next step (research log = external memory)
- Every discovery needing follow-up → todo
- Update research log after EACH step
Primary:
4. Smallest shippable increment?
5. Passes all gates?
6. Explicitly required?
7. Passes review first submission?
Secondary:
8. Ship with less?
9. Dependencies determine order?
10. Researched first, asked strategically?
11. Reduces cognitive load?
12. Satisfies P1-P10?
13. Error paths planned?
时刻牢记:
- 先记录发现再推进下一步（研究日志=外部记忆）
- 所有需跟进的发现→添加待办
- 每步后更新研究日志
核心问题:
4. 最小可交付增量是什么？
5. 是否通过所有质量校验关卡？
6. 是否为明确要求的内容？
7. 首次提交能否通过评审？
次要问题:
8. 能否交付更少内容？
9. 依赖关系是否决定了执行顺序？
10. 是否先研究再策略性提问？
11. 是否降低了认知负担？
12. 是否满足P1-P10原则？
13. 是否规划了错误路径？
Never Do
绝对禁止
- Proceed without writing findings
- Keep discoveries as mental notes
- Skip todos
- Write to project directories (always )
/tmp/ - Ask scope/requirements questions (that's spec phase)
- Finalize with
[TBD] - Implement without approval
- Forget expanding todos on new areas
- 未记录发现就推进
- 仅将发现记在脑中
- 跳过待办事项
- 写入项目目录（始终使用）
/tmp/ - 询问范围/需求问题（属于需求规格阶段）
- 计划中保留标记
[TBD] - 未批准就开始实现
- 发现新领域时未扩展待办
Recognize & Adjust
识别并调整问题
| Symptom | Action |
|---|---|
| Chunk >200 lines of code | Split by concern |
| No clear value | Merge or refocus |
| Dependencies unclear | Make explicit, number |
| Context missing | Add files + line numbers |
| Alternative approach after draft | STOP. Back to 2.5. Document, ask, may restart |
| "Obvious" location without checking consumers | STOP. Search usages. Multiple consumers → ask user |
| User rejects approach during/after impl | Should have been asked earlier. Document lesson, present alternatives |
| 症状 | 行动 |
|---|---|
| 模块代码量>200行 | 按关注点拆分 |
| 模块无明确交付价值 | 合并或重新聚焦 |
| 依赖关系不明确 | 明确依赖并编号 |
| 缺少上下文 | 添加文件+行号 |
| 草案完成后发现替代方案 | 停止。回到2.5节。记录情况，询问用户，可能需要重新开始 |
| 未检查消费者就确定"明显"部署位置 | 停止。搜索用法。若存在多个消费者→询问用户 |
| 用户在实现中/后拒绝方案 | 本应提前询问。记录经验教训，呈现替代方案 |