---
name: fe-feature-plan
description: 前端功能循环第 2 步。将 FE 规格转任务级实现计划（每任务 2-5 分钟，含组件路径、props 契约、测试意图），产出到 docs/superpowers/plans/，链入 fe-feature-tdd。
user-invocable: false
allowed-tools: Read Write Grep Skill AskUserQuestion
---

**所有输出必须使用中文。**

# fe-feature-plan

## 阶段范围（前端）

把当前 FE 的规格转成任务级实现计划。任务粒度限定为：**组件文件 / 路由配置 / store hook / API client 包装函数**。**不允许**生成涉及后端文件（controller / service / repository / SQL）的任务。

## 计划写作原则

- Plan 告诉 TDD 执行者**做什么**，不是**怎么写代码**——执行者是 `fe-feature-tdd`（同一模型，全上下文）
- Plan 锁定**文件边界 + 测试意图 + props 契约 + 完成判据**；代码由 TDD 红绿循环产出
- **禁止 dump 整个文件内容**（vue/react 组件源码、config 文件）到 plan
- 每个任务标注"测试先行类型" = **jsdom 组件测试** OR **Playwright E2E**
- DRY、YAGNI、TDD、frequent commits

## 占位符规则

每个 step 必须写实际内容。以下绝不出现：

- `TBD` / `TODO` / `implement later` / `fill in details`
- **`【人工填写：】`** — A 阶段标记。需要具体值时：
  1. 先查 `.env.local` / `docs/07` / `docs/04` / `docs/06` / `docs/09` / 关联 prototype / 现有代码并引用源
  2. 查不到 → 按 `docs/06 Token` / prototype 复刻 / UI 库官方默认 / 最简实现 的优先级自主选定，在 plan 中以 `自动选用 X（来源: ...）` 注明
  3. 仅在四级都给不出合理推荐 + 决策影响重大时（组件库选型 / 跨页面状态同步 / 不可逆 UX）才 `AskUserQuestion`
- 涉及后端文件（`backend/` / `sql/` / `scripts/`）的任务——**硬护栏**
- 未在任何 task 定义的组件 / hook / API client 函数

## 执行步骤

1. **收集输入**：
   - 当前 FE 的规格 `docs/superpowers/specs/<YYYY-MM-DD>-<fe_id>.md`（不存在则报错）
   - `docs/04-技术规范.md § 一前端架构`（路由 / 状态库 / 组件目录约定 / 测试栈）
   - `docs/09-项目目录结构.md § 前端目录结构`（文件落盘位置规范）
   - 相关代码指针（通过 `Grep` 在 `frontend/` 下定位现有前端文件）

2. **范围检查**：spec 跨多页/多业务 → 提示拆分

3. **文件结构推导**：
   - 组件 / 路由 / hook / API client 各放哪里（依 docs/09 § 前端目录结构）
   - 每个文件单一职责
   - 同 feature 的相关文件放一起

4. **任务粒度推导**（参考下方"任务原则"）：
   - 每个任务 = 一个 red-green-commit 单元
   - 4 个 step：写失败测试 → 实现最小代码 → 子会话验证 PASS → commit
   - 任务粒度 2-5 分钟
   - 每个任务必须含：`test_file::test_name` + `impl_file` + 完成判据 + "测试先行类型"标注

5. **写 plan 到 `docs/superpowers/plans/<YYYY-MM-DD>-<fe_id>.md`**：
   - 按 `${CLAUDE_SKILL_DIR}/templates/fe-feature-plan-template.md` 渲染
   - 文件已存在 → 直接覆盖（plan 是 CC 内部产物，无需确认）

6. **Plan 自审**（inline 修，无须用户等待）：
   - 每个任务必须含 `test_file::test_name`、`impl_file`、完成标准
   - **每个任务的 `impl_file` 路径必须以 `frontend/` 开头**（或 `docs/09` 声明的前端根目录）；命中 `backend/` / `sql/` / `scripts/` → 修正后重渲染
   - **占位符扫描**：`TBD` / `【人工填写：】` → 修
   - **Spec coverage**：spec 每节能指向至少一个 task 吗
   - **类型一致性**：组件 props 类型 / hook 签名跨 task 一致

7. **输出 + 链 fe-feature-tdd**（**直接做这两件事，不要输出"回交父 skill / 交给 caller / 等下一步 / 准备好了请检查"之类的桥接叙述**——那些会被解读为 turn 结束信号）：
   - 输出一行 `fe-feature-plan: <fe_id> → <path>`
   - **同一 turn 内立即** `Skill(fe-feature-tdd)`

## 任务原则

### Plan 文件头

每个 plan 必须以以下头部开始：

```markdown
# [FE Feature Name] Implementation Plan

> **Execution:** Parent skill `fe-feature-tdd` executes this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [一句话描述]

**Architecture:** [2-3 句方法论]

**Tech Stack:** [关键技术 / 库]

---
```

### Task 结构

每个 task 是 red-green-commit 单元：

````markdown
### Task N: [组件名]

**Files:**
- Create: `frontend/src/components/LoginForm.tsx`
- Test: `frontend/src/components/LoginForm.test.tsx`
- 测试先行类型: jsdom 组件测试

**Props/API shape**（只写需要约束实现的签名）:
- `<LoginForm onSubmit={(username: string, password: string) => Promise<void>} loading={boolean} />`

- [ ] **Step 1: 写失败测试**
  - 测试名: `LoginForm renders username and password fields`
  - 意图: 验证组件渲染 username / password input，submit button disabled when empty
  - 子会话确认 FAIL（组件不存在）

- [ ] **Step 2: 实现最小代码**
  - 目标: 让 Step 1 测试通过；不多做
  - 涉及文件: `frontend/src/components/LoginForm.tsx`

- [ ] **Step 3: 子会话验证 PASS**

- [ ] **Step 4: Commit**
  - `git add <文件>`
  - `git commit -m "feat(fe): LoginForm 组件 FE-01"`
````

### 允许的代码块场景

少数例外，需要写死而非让 TDD 自由发挥：

- **路由配置**：`routes.ts` 中 path 注册（路径是契约级）
- **API client 契约**：fetch 包装函数签名 + headers + 错误码 mapping
- **Design Tokens 名称**：`var(--color-primary)` 列表（跨组件复用）
- **测试断言形状**（可选）

除此之外一律散文 + 签名描述，**不贴完整组件源码**。

### 记住

- Exact file paths always（必须以 `frontend/` 开头）
- 测试先行类型必须明确（jsdom / Playwright）
- 组件 props / hook 签名 / API client 函数签名 — **必须写死**
- Internal implementation code — **不写**；留给 TDD 阶段

## 参考

- `${CLAUDE_SKILL_DIR}/templates/fe-feature-plan-template.md`
- 上游：`fe-feature-brainstorm`
- 下游：`fe-feature-tdd`