plan-feature

功能规划

为功能和复杂改动制定具体且可直接实施的计划。

规划期间不要编写代码。只进行探索、分析并记录结果。

规划门槛

深入规划前，先快速确认范围：

• 如果改动影响 3 个或更多文件，或涉及多个系统，则详细规划
• 如果需求不明确，或存在架构权衡，则详细规划
• 对于需求明确的单文件改动，跳过繁重的规划
• 对于小型或显而易见的改动，提供简短的执行概要，而非完整规格说明

规划工作流

1. 探索

提出有针对性的问题，以了解意图。每个问题都要：

• 提供 2–3 个具体选项，并说明各自的权衡
• 给出你推荐的选项，并清晰说明理由
• 一次只问一个问题；等待用户回复
• 跳过用户已经回答的问题

关键问题：

• 你要解决什么问题？（用户痛点、业务目标）
• 应该发生什么？（预期行为、成功标准）
• 哪些事情不应该发生？（需要避免的限制条件、边缘情况）
• 目标用户是谁？（用户类型、环境、规模）
• 如何验证功能正常？（测试方法、验证方式）

加速学习参考

• 使用 ship-fast-loop.md 了解轻量级交付循环和反馈节奏。

2. 分析

系统地探索代码库：

• 找出相关文件（记录路径和行号）
• 梳理现有模式（架构、命名、数据流）
• 确定依赖关系（会受改动影响的部分）
• 查找类似实现（以保持一致性）
• 记录相关标准（来自 implement-frontend、define-architecture 等）

记录发现：

• 文件：path/to/file.ts:123 - 说明其作用及相关性
• 模式：类似功能的现有实现方式
• 限制：技术限制或要求

3. 规划

制定具体且有序的计划，包含：

对于每项改动，说明：

• 文件路径和大致行号
• 要修改的确切函数、组件或类
• 要添加、删除或更改的内容（具体说明）
• 修改原因（与目标的契合方式）
• 依赖关系（必须先完成哪些事项）

计划结构：

## Goal
[One sentence: what we're building and why]

## Changes

### 1. [Description]
- File: `path/to/file.ts:45`
- Action: Add `functionName()` that does X
- Reasoning: Needed because Y
- Dependencies: None

### 2. [Description]
- File: `path/to/other.ts:89`
- Action: Modify `existingFunction()` to handle Z
- Reasoning: Integrates with change #1
- Dependencies: #1 must complete first

## Validation
- [ ] Tests pass
- [ ] Feature works for case A
- [ ] Edge case B is handled
- [ ] Follows `implement-frontend` (if frontend)
- [ ] No console logs or debug code

4. 标准参考

明确说明适用的标准：

• 前端改动：参考 implement-frontend、audit-ui
• UI 改动：参考 design-ui
• 动效：参考 ui-animation
• 后端：参考 define-architecture
• 排版：参考 audit-ui

格式：“此计划中的表单和类型安全必须遵循 implement-frontend。”

反模式

避免含糊的计划：

• 不好：“更新身份验证系统”
• 好： “修改 auth/middleware.ts:34，添加用于检查令牌是否过期的 validateSession()”

避免遗漏上下文：

• 不好：“添加错误处理”
• 好：“在 auth/api.ts:67 中用 try/catch 包裹 API 调用，并按照 audit-ui 的要求在出错时显示 toast 提示”

避免假设他人了解相关知识：

• 不好：“使用标准模式”
• 好：“遵循 user/dao.ts:12 中现有的 DAO 模式（基于类并显式声明类型）”

避免验收标准不完整：

• 不好：“确保功能正常”
• 好：“验证：（1）按 Enter 键可提交表单；（2）显示内联错误；（3）请求期间禁用提交按钮”

避免忽略标准：

• 不好：计划使用 any 类型并手动管理表单状态
• 好：计划遵循 implement-frontend：不使用 any，使用 React Hook Form

验证清单

移交计划前，确认：

• 他人无需提问即可实施
• 文件路径有效，并提供大致行号
• 步骤顺序合理，依赖关系明确
• 验收标准可测试
• 明确引用相关技能标准
• 每项决策都有理由（“为什么”）
• 不含模糊措辞（未具体说明的“更新”“改进”“增强”）