需要做技术方案设计（非 PRD）时…

当用户要求做方案设计、架构设计、技术设计（且不涉及 PRD）时，通过澄清需求、分析代码库、对比多方案、输出方案文档到 docs/ 的流程完成设计。

适用场景

解决思路

1. 先判断产物类型：若用户要的是 PRD，改用 prd-planner 技能；本技能只产出非 PRD 的架构/方案文档。
2. 按清单跟踪进度：澄清意图与成功标准 → 识别约束 → 分析现有代码库模式 → 调研最佳实践（如需）→ 设计架构 → 生成方案文档（必须写入 {PROJECT_ROOT}/docs/）→ 与用户确认。
3. 澄清需求时问清：问题陈述与当前痛点、可衡量的成功标准、目标用户及其目标；若为重构/迁移，还要问清重构原因、破坏性变更、回滚方案。
4. 识别约束：技术约束（现有技术栈、架构模式、依赖）、时间约束（截止日期/阶段）、资源约束（团队规模与专长）、业务约束（预算、外部依赖、第三方 API）。
5. 分析现有代码库：用 grep -r "related_keyword" src/ --include="*.ts" --include="*.tsx" 找相似模式，用 find . -type d -name "*keyword*" 找相关目录，用 find src -maxdepth 4 -type d -name '*similar*' 查现有模式。
6. 重构场景必须：找出被改代码的所有消费方、所有状态/数据流、所有入口与出口，并查找是否已有可复用的现成机制（grep -r "existing-interface" 与 grep -r "related-event"）。
7. 提出重构前先自问：是否有现成机制可扩展？最简单的解法是什么？能否用最小改动解决？我的方案是否真正把链路接通（空回调是 bug）？
8. 梳理代码库既有约定：架构模式、状态管理方案与归属边界、组件组织方式、API 调用结构、类型定义位置。
9. 对不熟悉的领域，先搜索最佳实践。
10. 设计架构前必须给出多个方案：最小改动方案、中等投入方案、全面重构方案，并列出各自改动文件数、风险、耗时。
11. 写方案文档前先问用户：偏好哪个方案？是否接受更大范围重构？对变更的容忍度如何？
12. 遵循设计原则：简单优先、渐进增强（先 MVP 再迭代）、关注点分离（UI/逻辑/数据分离）、可复用、可测试。
13. 对每个重大决策记录权衡表：选项 / 优点 / 缺点 / 是否选中。
14. 方案文档输出到 {PROJECT_ROOT}/docs/{feature-name}-solution.md，文件名用 kebab-case（如 data-refresh-logic-refactoring-solution.md），不要写到 plan 文件或隐藏位置。
15. 定稿前与用户确认：成功标准是否对齐目标、约束是否全部覆盖、方案是否完整到另一个 agent 可直接实现、并获得明确批准。
16. 内容质量自检：问题陈述清晰具体、成功标准可衡量、功能需求无歧义、非功能需求已说明、约束已记录、权衡已解释。
17. 实现就绪自检：架构定义清晰、文件结构明确、API 契约已定义、数据模型已指定、边界情况已考虑、测试方案已列出。
18. Agent 友好性自检：另一个 agent 无需追问即可实现、必要时给出代码示例、文件路径用正斜杠、引用的现有代码准确。
19. 根因分析（针对 bug/状态/刷新/生命周期问题）逐项验证：是否已有可用机制、现有方案为何不适用（时序/作用域/归属/未接线）、每个状态转换由哪个实例或服务拥有、完整事件链（触发 → 处理 → 状态变更 → 可观察效果）、每个回调/适配器/队列/注册点是否真的做了事、时序语义（间隔、重试、focus/生命周期事件、取消行为）。
20. 避免常见根因误判：假设不同实例共享状态、留下空回调、只检查链路第一环、把事件注册当作已触发。
21. 迁移范围完整性检查：列出所有被迁移状态（如 items、summary、isLoading、filters、pendingRequests）及各自迁移策略（直接搬/转换/废弃）；用 rg -n "ModuleName|PublicInterfaceName" . 找出所有消费方；覆盖所有依赖使用点（主运行时组合、以及 overlay/worker/job/test 等次要上下文）。
22. 状态/数据流校验：无孤儿状态、无死状态（每个新状态都有明确用途与消费方）、无未定义引用、完整调用链已记录（触发 → 回调 → 效果）、模块若有 Create/Edit/Delete/Import/Export 则全部覆盖。
23. 框架不变量校验（如适用）：生命周期规则（顺序、注册、销毁）、引用语义（可变句柄、值快照、依赖生命周期）、条件行为合法性（框架要求稳定顺序时不得条件式注册）。
24. 依赖组合完整性：明确组合归属方、覆盖次要上下文（弹窗、overlay、worker、测试、并行运行时）、所有使用点都已接线、运行时注册在每个必需上下文中都已被证明存在。
25. 框架/系统集成检查：注册点（注册表、路由、依赖容器、插件清单）已更新、初始化与销毁遵循仓库既有生命周期、无重复注册、仓库不使用该机制时跳过对应检查。
26. 向后兼容检查：迁移期间旧模式仍可用、迁移路径清晰、废弃时间表明确。
27. 代码示例检查：给出 Before/After 对比、TypeScript 类型与实现一致、import 路径正确。
28. 避免模糊表述：把「优化代码」写成「通过 memo 化昂贵计算把渲染时间从 100ms 降到 16ms」；把「让它更快」写成「加缓存把每会话 API 调用从 5 次降到 1 次」；把「清理代码」写成「把重复逻辑抽成共享工具函数」；把「修 bug」写成「在 getUserById 中处理用户不存在的 null 情况」；把「重构状态层」写成「从 Context+Ref 迁移到集中式 store：<详细状态清单与迁移策略>」。
29. 警惕过度设计：不要在有现成模式时引入新模式、不要在穷尽现有状态方案前新建状态管理、不要一个文件能改却新建多个文件、不要只凭「最佳实践」而不考虑实用性。
30. 写方案前自问：是否有现成机制完成 80% 需求？能否扩展现有代码而非新建模式？解决当前问题的绝对最小改动是什么？用户是否真的想要大重构？回调是否真的做了事？是否追踪了完整调用链？
31. 仅在以下情况才提全面方案：现有架构根本性损坏、技术债阻塞所有新功能、团队明确决定现代化、不彻底解决会反复出现；全面方案应是主动选择而非默认。
32. 新功能实现按此顺序：读相似功能实现 → 找可复用模式 → 设计组件层级 → 定义状态管理方式 → 指定 API 集成点 → 列出所有新建文件 → 列出所有需修改的现有文件。
33. 重构现有代码按此顺序：分析当前实现 → 找出所有消费方（grep -r imports）→ 识别痛点与技术债 → 提出多个方案（最小 → 全面）→ 获得用户批准 → 规划迁移策略（分阶段 vs 一次性）→ 定义回滚方案 → 列出迁移清单；务必从最简单方案开始。
34. Bug 修复调查按此顺序：理解预期与实际行为 → 在代码中定位根因 → 识别受影响范围 → 设计方案 → 指定回归防护测试。
35. 技术术语要精确：区分「共享状态」与「各实例独立轮询」、区分「待处理变更」与「待处理计数下降」（代码检查 !isPending && prevIsPending，即 true→false）、区分「触发刷新」与「调用 navigation.goBack() 进而触发……」，展示完整链路。
36. 调用链文档不要跳步：不要写「onRefresh 触发数据刷新」，要写完整链路并标注每步的文件路径与行号，例如 onRefresh() → navigation.goBack() → Dashboard focused → usePromiseResult（revalidateOnFocus: true）触发 → refreshItems() → handleRefresh() → fetchItems() + refreshSummary() + refreshMetrics()。
37. 测试覆盖所有操作：模块有 5 个操作（Create/Edit/Delete/Import/Export）就测 5 个，不要只测关注的那 2 个。
38. 刷新/时序问题画时间线，例如：0s 弹窗打开开始编辑；10s 提交，pending 0→1；15s 弹窗关闭，而 Dashboard hook 上次轮询在 5s、下次在 35s（还有 25s）——以此说明为何不生效。
39. 避免常见方案错误：空回调（onRefresh: () => {}）要么实现要么删除；根因不完整（「它不刷新」要解释为何：时序/作用域/断链）；调用链缺失（「不知怎么就触发了刷新」要逐步记录 file:line）；测试不全（只测 Create/Edit 要补 Delete/Import/Export）；把假设当事实（「revalidateOnFocus 在弹窗关闭时触发」需验证，实际只在真正 focus 变化时触发）；触发条件写错（「待处理变更」实际代码是 !isPending && prevIsPending，即计数下降）。
40. 方案文档写作要点：具体化、说明决策背景而非只写结论、复杂模式给代码片段、考虑边界情况（API 失败、用户无数据）、重构时说明如何安全从 A 到 B、列出所有变更文件、校验 import 路径存在且正确、检查 hook 规则（无条件 hook、正确的依赖）。
41. 参考项目 docs/ 目录中已有的架构或方案文档作为模板，并参考代码库中相似功能/模块的实现。

适用边界 · 注意事项

• 用户要的是 PRD 时，应改用 prd-planner 技能，而非本技能。
• 问题简单、现有机制已能覆盖 80% 需求时，不要启动全面架构设计或大重构。
• 仓库不使用某框架机制（如依赖容器、插件清单）时，跳过对应的框架特定检查。