11 - 功能评审与重设计食谱

对已上线功能进行系统性评审，发现结构性问题，制定经得起质检的重设计方案并一步到位执行。

适用场景

场景	信号	食谱
功能腐化	高频使用但布局不合理、操作路径长、代码臃肿	食谱 1 + 2 + 3
代码膨胀	单文件超 500 行、状态 15+、多职责混杂	食谱 2 + 3
用户反馈	使用者（含自己）反复吐槽某个交互	食谱 1
重大重构前	已知要改，但不确定改多深、改什么	食谱 1 → 2 → 3

与现有食谱的关系

食谱	定位	输入	输出
04-代码审查	已有代码的质量检查	git diff	问题报告
06-重构优化	已知问题的代码修复	问题清单	重构后代码
11-功能评审（本篇）	功能要不要重做、怎么重做	运行中的功能	重设计方案 + 执行

---

食谱 1：多视角并行评审

场景描述

一个功能用久了，隐隐觉得"不太对"但说不清哪里不对。单一视角（只看代码、或只看交互）容易遗漏结构性问题。需要从多个专业维度同时审视，找出共识问题和各自盲区。

核心模板

对 {{功能名称}} 进行多视角并行评审。

背景信息：
- 功能描述：{{一句话描述}}
- 使用频率：{{高频/中频/低频}}
- 已知痛点：{{用户或自己的直觉感受}}
- 核心代码：{{主要文件路径}}

请启动 3 个 Agent 并行评估，各自独立分析后输出报告：

Agent 1 — UX/交互设计专家：
  评估维度：信息架构、操作路径效率、视觉层级、移动端体验、空状态处理
  输出：每个问题标注严重程度（🔴🟡🟢），给出改进方案

Agent 2 — 产品经理：
  评估维度：核心流程步数、功能使用频率分布（80/20）、功能重叠、竞品参考
  输出：每个分析标注 ROI（高/中/低），给出"只能改 3 件事"清单

Agent 3 — 前端架构师：
  评估维度：文件大小、状态管理、组件拆分、数据流、性能、可维护性
  输出：每个问题标注影响等级（🔴🟡🟢），给出重构优先级清单

三方报告完成后，综合输出共识矩阵。

变量说明

变量	含义	示例
{{功能名称}}	要评审的功能	prompt-combiner 提示词组合器
{{一句话描述}}	功能的核心用途	快速组合 AI 提示词并复制
{{使用频率}}	使用频率	每天多次
{{已知痛点}}	直觉感受	场景标签太多、布局不合理
{{主要文件路径}}	核心代码位置	src/app/prompt-combiner/page.tsx

好坏对比

❌ 这个功能不太好用，帮我改进一下

✅ 启动 3 个 Agent（UX 专家、产品经理、前端架构师）并行评审 prompt-combiner。它是高频工具，痛点是场景标签太多、操作路径长。各自独立分析后输出报告，最后综合共识矩阵。

实战案例

对 prompt-combiner 进行多视角并行评审。
背景：高频使用的 AI 提示词组合工具，9 个场景标签平铺，
定制 tab 混杂使用/配置功能，page.tsx 1315 行。
启动 UX/PM/Arch 三方 Agent 并行评估。

实际产出（prompt-combiner 重设计案例）：

• UX 发现：定制 tab 职责混杂（P0）、场景标签过多（P0）
• PM 发现：默认场景不记忆（P0）、缺少直接固定到常用的操作（P1）
• Arch 发现：1315 行大文件（P0）、26 个 useState（P0）、engine.ts/templates.ts 死代码
• 三方共识：定制 tab 必须拆分、场景标签需分组、代码需模块化
• 独特洞察：PM 发现"开发"是最高频场景却内容最薄；Arch 发现 DeepBuilder 的 useMemo 有 eslint-disable 隐患

Claude 增强 💡

• 3 个 Agent 使用 run_in_background: true 并行启动，互不干扰
• 每个 Agent 用 model: sonnet 即可（评审不需要最强模型，节省成本）
• Agent 完成后在主会话综合，避免任何一方的分析污染另一方的判断

与三会话隔离的区别

维度	三会话隔离（prompt-04 食谱 6）	多视角评审（本食谱）
目的	防确认偏差	补视角盲区
角色	同角色（都是审查者）	不同角色（UX/PM/Arch）
输入	同一份 diff	同一个功能
关系	串行（实现→审查→仲裁）	并行（三方同时评估）
适用	代码提交前的质量把关	功能重设计前的问题发现

---

食谱 2：跨模型方案质检

场景描述

重构方案写完后，"自己审自己"容易护短。用不同的 AI 模型（如 OpenAI Codex）做独立审查，能发现同模型内的认知盲区：基线数据错误、未验证的假设、执行顺序陷阱。

核心模板

方案已完成，用 /codex review 做跨模型质检。

方案文件：{{方案路径}}
源代码：{{代码路径}}

质检重点：
1. 基线数据是否准确（行数、状态数、引用关系——让 Codex 实际读代码验证）
2. "未使用"代码是否真的无引用（grep 全仓库，包括被间接引用的文件）
3. 清理列表是否安全（删除的类型/函数/文件是否仍被其他文件 import）
4. Phase 之间是否有耦合导致返工（同一组件在不同 Phase 被改两遍）
5. 持久化/恢复逻辑是否有边界情况（无效值、SSR 水合不匹配）
6. 验收标准是否可验证（不是虚指标）

变量说明

变量	含义	示例
{{方案路径}}	方案文件	docs/plans/prompt-combiner-redesign.md
{{代码路径}}	涉及的源代码	src/app/prompt-combiner/page.tsx

好坏对比

❌ 帮我看看这个方案有没有问题（同模型自审，确认偏差）

✅ /codex review docs/plans/xxx.md（跨模型独立审查，读源码验证声明）

实战案例

prompt-combiner 方案 v1 经 Codex 审查发现 14 个问题，核心包括：

#	问题	类型	后果
1	声称 1316 行实际 1315 行，声称 18 个 useState 实际 26 个	基线错误	方案目标建立在错误数据上
3	声称旧类型"未使用"，但 engine.ts/templates.ts 仍引用	清理未验证	删除后编译报错
4	Phase 1 提取 DeepBuilder，Phase 3 又要移动它	Phase 耦合	同组件改两遍
7	loadLastScene() 作为 useState 初始值	SSR 陷阱	水合不匹配或恢复无效值
11	首次重排指令会冻结整个列表到 overrides	存储陷阱	阻断未来内置更新
12	验收标准 page.tsx < 350 行	虚指标	搬代码即可达成，不验证功能

修订后的 v2 方案合并了 Phase 1+3 避免返工，补充了死代码验证、ID 校验、功能回归验收。

Claude 增强 💡

• /codex review 会让 Codex 实际读取源代码验证方案中的声明，而不只是审查方案文本
• Codex 的 model_reasoning_effort="xhigh" 会做深度推理，适合方案级审查
• 审查结果逐条判断"有效/值得考虑/过度"，不要全盘接受——Codex 也会有误判

---

食谱 3：评审驱动的重设计

场景描述

多视角评审（食谱 1）发现了问题，跨模型质检（食谱 2）验证了方案，现在要把方案转化为可执行的重设计计划并一步到位完成。

核心模板

基于评审结果，制定 {{功能名称}} 的重设计方案。

## 评审共识
{{从食谱 1 提取的共识矩阵}}

## 设计约束
- 保留有效的现有设计：{{明确列出要保留的部分}}
- 改造目标：{{核心改造点}}

## 方案要求
1. 数据层和 UI 层改造合并执行，不分 Phase（避免耦合返工）
2. 清理代码前 grep 全仓库验证无引用
3. 持久化恢复逻辑必须校验有效性
4. 验收标准必须包含功能回归（场景切换→指令复制→组合→收藏→管理→刷新恢复）
5. 先清理死代码 → 再抽离数据 → 最后组件拆分 + UX 改造一步到位

输出结构化方案，然后用 /codex review 质检。

Phase 合并原则

重设计方案拆 Phase 时，检查以下条件：

Phase A 和 Phase B 是否修改同一组件的同一段逻辑？
  ├─ 是 → 合并为一个 Phase
  └─ 否 → 可以分开

实战案例：prompt-combiner 的原方案将"提取 DeepBuilder 组件"（Phase 1）和"将 DeepBuilder 从定制 tab 移入场景视图"（Phase 3）分开，导致同一组件改两遍。合并后一步到位完成。

验收标准的正确写法

❌ 虚指标：page.tsx < 350 行、useState < 4 个

✅ 功能回归：

必须手动验证通过的流程：
1. 场景切换 — 点击不同场景标签，内容正确切换
2. 指令复制 — 点击指令卡片，剪贴板内容正确
3. 深度组合 — 选角色+指令+修饰词，预览和复制正确
4. 存为常用 — 组合结果保存到常用区，刷新后仍在
5. 管理编辑 — 设置面板中编辑/删除/排序指令正常
6. 刷新恢复 — 刷新页面后恢复上次场景，无效场景 fallback
7. 构建通过 — npm run build 零错误零警告

实战案例

prompt-combiner 重设计执行顺序：

Step 1: 清理死代码
  - 验证 engine.ts/templates.ts 无外部引用 → 删除
  - 清理 types.ts/constants.ts/storage.ts 中仅被死文件引用的符号

Step 2: 数据层抽离
  - 新建 scenes.ts（类型 + 数据 + assembler）
  - 新建 clipboard.ts（UI 工具函数）
  - storage.ts 新增 lastScene 持久化（带 ID 验证）

Step 3: 组件拆分 + UX 改造（一步到位）
  - 去掉"定制"tab
  - 深度组合移入场景视图（快速/组合 切换）
  - 管理功能移入 ⚙ 设置面板
  - 场景标签分组（前 5 + "更多"下拉）
  - 拆出 7 个组件 + 2 个 hooks

结果：page.tsx 从 1315 行降到 141 行，net -493 行，build 通过。

Claude 增强 💡

• 重设计涉及多文件时，用 TaskCreate 追踪进度，每完成一步标记 completed
• 每个 Step 完成后跑 npm run build，不要积累到最后
• 清理死代码时用 Grep 工具搜索全仓库，不要用 Bash 的 grep（Grep 工具有更好的权限处理）

---

组合技巧

完整闭环：评审 → 质检 → 执行

阶段 1 — 多视角评审（食谱 1）：
  启动 3 个 Agent 并行评估，输出共识矩阵和优先级排序

阶段 2 — 方案制定：
  基于评审结果制定重设计方案（食谱 3）

阶段 3 — 跨模型质检（食谱 2）：
  用 /codex review 审查方案，逐条判断反馈有效性，修订为 v2

阶段 4 — 执行：
  按修订后的方案一步到位执行，每步验证

评审深度与功能规模的匹配

功能规模	评审方式	理由
小（< 200 行，单一职责）	直接 /review	不值得启动多 Agent
中（200-500 行，2-3 职责）	/codex review 单模型质检	跨模型视角足够
大（500+ 行，多职责混杂）	多视角评审 + Codex 质检	需要 UX/PM/Arch 多维度

与现有工具的衔接

/plan          → 制定方案（适合新功能）
本食谱          → 评审 + 重设计（适合已有功能的改造）
/codex review  → 方案质检（跨模型第二意见）
/review        → 代码审查（实现完成后）
/checkpoint    → 大改造完成后存档

---

相关资源

• doc-03 子代理体系 — Agent 并行派发机制
• doc-12 效率最佳实践 — 按规模选择开发模式
• 04-代码审查食谱 — 三会话隔离审查（互补关系）
• 06-重构优化食谱 — 模块拆分、代码异味消除
• 09-进阶技巧食谱 — Prompt 链、多模型协作