architecting-solutions

架构解决方案

分析需求，并为软件实现编写技术解决方案文档。

描述

在以下情况下使用此技能：

• 创建非 PRD 的解决方案简报或技术设计文档
• 设计软件解决方案
• 分析需求
• 规范功能
• 编写技术计划文档
• 规划重构或迁移

安装

如有可能，请通过 apb skills add ./skills/architecting-solutions --scope global --target all --link 安装。

工作原理

此技能将引导 Claude 完成结构化工作流：

1. 明确需求 - 提出有针对性的问题，了解问题
2. 分析上下文 - 检查现有代码库中的模式和约束
3. 设计解决方案 - 提出并权衡各种取舍的架构方案
4. 生成解决方案文档 - 在 {PROJECT_ROOT}/docs/ 中输出 Markdown 格式的解决方案简报或技术设计文档

重要：当用户要求编写 PRD 时，请使用 prd-planner。此技能会将非 PRD 的架构和解决方案文档写入项目的 docs/ 文件夹。

工作流

复制此检查清单并跟踪进度：

Requirements Analysis:
- [ ] Step 1: Clarify user intent and success criteria
- [ ] Step 2: Identify constraints (tech stack, timeline, resources)
- [ ] Step 3: Analyze existing codebase patterns
- [ ] Step 4: Research best practices (if needed)
- [ ] Step 5: Design solution architecture
- [ ] Step 6: Generate solution document (must be in {PROJECT_ROOT}/docs/)
- [ ] Step 7: Validate with user

步骤 1：明确需求

提出以下问题以了解问题：

核心理解

• 问题陈述：我们要解决什么问题？当前的痛点是什么？
• 成功标准：我们如何判断是否成功？请具体说明。
• 目标用户：谁会使用此功能？他们的目标是什么？

针对重构/迁移：

• 为什么重构？：当前实现有什么问题？请具体说明。
• 破坏性变更：哪些内容会受到影响？需要迁移什么？
• 回滚计划：如果出现问题，我们如何还原？

步骤 2：识别约束

• 技术约束：现有技术栈、架构模式、依赖项
• 时间约束：是否有截止日期或阶段安排？
• 资源约束：团队规模、可用专业能力
• 业务约束：预算、外部依赖、第三方 API

步骤 3：分析现有代码库

# Find similar patterns in the codebase
grep -r "related_keyword" src/ --include="*.ts" --include="*.tsx"

# Find relevant directory structures
find . -type d -name "*keyword*"

# Check existing patterns
find src -maxdepth 4 -type d -name '*similar*'

重构的关键事项：

• 找出所有使用待更改代码的地方
• 识别所有状态/数据流
• 追踪所有入口点和出口点
• 查找现有机制，确认是否已经能够解决问题

# Find all imports/usages of a module
grep -r "existing-interface" src/ --include="*.ts" --include="*.tsx"
grep -r "related-event" src/ --include="*.ts" --include="*.tsx"

重要：提出重构方案前，请先确认：

1. 是否存在可扩展的现有机制？
2. 最简单的可行方案是什么？
3. 能否通过最小改动解决问题？
4. 我的解决方案是否真正打通了各个环节？（例如，空回调无法正常工作）

请查找：

• 架构模式：类似功能是如何实现的？
• 状态管理：此代码库已经采用了哪种方案和所有权边界？
• 组件模式：组件是如何组织的？
• API 模式：API 调用是如何组织的？
• 类型定义：类型定义位于何处？

步骤 4：研究最佳实践

对于不熟悉的领域，请搜索最佳实践。

步骤 5：设计解决方案架构

重要：考虑多种解决方案

确定解决方案前，务必先提供多个选项：

1. 最小改动方案 - 能够奏效的绝对最小改动是什么？
2. 中等工作量方案 - 兼顾平衡并进行一定程度的重构
3. 全面方案 - 全面改造架构

示例：

Problem: Data doesn't refresh after operation

Option 1 (Minimal): Hook into existing pending request count decrease
  - Changes: 1-2 files
  - Risk: Low
  - Selected: ✓

Option 2 (Medium): Add refresh callback through existing shared context
  - Changes: 3-5 files
  - Risk: Medium

Option 3 (Comprehensive): Migrate to a centralized state-store pattern
  - Changes: 10+ files, new atoms/actions
  - Risk: High
  - Time: 2-3 days

编写解决方案文档前，请先询问用户：

• 您更倾向于哪个选项？
• 您是否接受更大规模的重构？
• 您对变更的接受程度如何？

架构设计原则

1. 简单优先：选择满足需求的最简单方案
2. 渐进增强：从 MVP 开始，逐步迭代扩展
3. 关注点分离：UI、逻辑和数据应彼此分离
4. 可复用性：设计可复用的组件
5. 可测试性：设计易于测试的方案

记录权衡

针对每项重要决策，记录：

选项	优点	缺点	已选
方案 A	优点 1、优点 2	缺点 1	✓
方案 B	优点 1	缺点 1、缺点 2

步骤 6：生成解决方案文档

重要：始终将解决方案文档写入项目的 docs/ 目录，切勿写入计划文件或隐藏位置。如果请求的产物是 PRD，则改用 prd-planner。

输出位置：{PROJECT_ROOT}/docs/{feature-name}-solution.md

示例：

• 如果项目根目录是 /Users/user/my-project/，则写入 /Users/user/my-project/docs/feature-name-solution.md
• 文件名使用 kebab-case：data-refresh-logic-refactoring-solution.md

步骤 7：与用户确认

定稿前：

1. 审查成功标准——这些标准是否符合用户目标？
2. 检查约束——是否已处理所有约束？
3. 验证完整性——其他 Agent 能否根据此解决方案文档完成实施？
4. 与用户确认——定稿前获得明确批准

---

解决方案质量检查清单

内容质量

• 问题陈述清晰且具体
• 成功标准可衡量
• 功能需求明确无歧义
• 已说明非功能需求
• 已记录约束
• 已解释权衡

实施就绪度

• 架构定义清晰
• 已指定文件结构
• 已定义 API 契约（如适用）
• 已指定数据模型
• 已考虑边界情况
• 已概述测试方案

对 Agent 友好

• 其他 Agent 无需澄清即可完成实施
• 在适当之处提供代码示例
• 文件路径使用正斜杠
• 对现有代码的引用准确

---

根因分析检查清单（重要）

对于 Bug、状态、刷新或生命周期问题，请核实：

• 现有机制——其他位置是否已存在可用的解决方案？
• 因果缺口——现有解决方案为何不适用于此处：时机、范围、所有权还是缺少接线？
• 状态所有权——哪个实例或服务拥有每项状态转换？
• 完整事件链——追踪触发器 → 处理程序 → 状态变化 → 可观察效果。
• 已实现的边界——确认每个回调、适配器、队列或注册点都确实执行了实际工作。
• 时序语义——识别时间间隔、重试、焦点/生命周期事件以及取消行为。

常见错误包括：假设不同实例共享状态、留下无效回调、只检查链路中的第一环，以及将事件已注册误认为事件已触发的证明。

---

迁移范围完整性

• 已涵盖所有现有状态：列出正在迁移的每一项状态

  • 正在迁移哪些状态？（例如：items、summary、isLoading、filters、pendingRequests）
  • 每项状态的迁移策略是什么？（直接迁移／转换／弃用）

• 已识别所有使用方：找出所有使用待更改代码的文件

  rg -n "ModuleName|PublicInterfaceName" .
  

• 已涵盖依赖项的使用位置：已识别所有使用更改后接口的使用方

  • 主要运行时组合
  • 存在时，还包括叠加层、工作进程、作业或测试等次要上下文

状态／数据流验证

• 没有孤立状态：每项状态都有明确的来源和使用方
• 没有无效状态：每个新增状态／状态变量都有明确用途和使用方
• 没有未定义引用：所有导入／引用都能解析到现有代码
• 已记录完整调用链：从触发器 → 回调 → 效果，展示每个步骤
• 已涵盖所有相关操作：如果模块包含 Create/Edit/Delete/Import/Export，则逐一测试

框架不变量（适用时）

• 生命周期规则成立：检查实际框架的顺序、注册和拆除要求。
• 引用语义成立：根据仓库使用的框架，验证可变句柄、值快照和依赖项生命周期。
• 条件行为合法：如果框架要求顺序稳定，就不要有条件地注册原语。

依赖组合完整性

• 已明确组合所有者：已确定仓库中的实际依赖所有者
• 已涵盖次要上下文：在相关情况下，检查模态框、覆盖层、工作器、测试或并行运行时
• 所有使用点均已接入：每个使用方都能获得所需依赖
• 已证明运行时注册：相关提供方、容器、注册表或适配器在每个必需上下文中均已就位。

框架／系统集成

• 注册点：已更新所需的注册表、路由、依赖容器或插件清单
• 初始化：启动和拆除遵循仓库现有的生命周期
• 无重复注册：确认没有与现有条目冲突
• 适用性：如果仓库未使用该机制，则跳过特定于框架的检查

向后兼容性

• 现有使用方可正常工作：迁移期间，使用旧模式的代码仍可正常工作
• 迁移路径清晰：使用方如何迁移到新模式？
• 弃用时间表：旧模式何时移除？

代码示例

• 变更前／变更后对比：清楚展示代码变更
• 类型定义准确：TypeScript 类型与实现相符
• 导入路径正确：所有导入均使用正确的工作区路径

---

应避免的常见反模式

反模式	更好的做法
“优化代码”	“通过缓存开销大的计算，将渲染时间从 100ms 降至 16ms”
“让它更快”	“实现缓存，将每次会话的 API 调用从 5 次减少到 1 次”
“清理代码”	“将重复逻辑提取到共享实用函数中”
“修复 bug”	“当用户不存在时，在 getUserById 中处理 null 情况”
“重构状态层”	“从 Context+Ref 迁移到集中式存储：<详细的状态列表和迁移策略>”
过度设计	从最简单的解决方案开始，仅在必要时扩展

---

过度设计警告（重要经验）

直接采用复杂方案的问题

经验示例： 请求在某个操作完成后刷新，可能只需要使用现有的完成信号，而不需要新增共享状态子系统。提出更广泛的抽象方案前，先梳理当前生命周期。

可能存在过度设计的迹象

• ❌ 现有模式可行，却仍提出新模式
• ❌ 尚未穷尽当前方案，就创建新的状态管理机制
• ❌ 原本只需修改一个文件，却新增多个文件
• ❌ 以“最佳实践”为由，却不考虑实际可行性

编写解决方案前应先问的问题

1. 是否已有能满足我们 80% 需求的机制？
2. 能否扩展／修改现有代码，而不是创建新模式？
3. 解决这个问题所需的最小改动究竟是什么？
4. 用户真的需要大规模重构吗？
5. 我的解决方案中的回调实际会执行操作吗？（空回调是 bug！）
6. 我是否追踪了完整的调用链？（触发 → …… → 效果）

适合采用全面解决方案的情况

• 当前架构存在根本性问题
• 技术债务阻碍了所有新功能
• 团队已明确决定进行现代化改造
• 如果不妥善解决，问题会再次出现

关键：全面解决方案应当是一种选择，而不是默认做法。

---

常见场景的模式

新功能实现

1. Read similar feature implementations
2. Identify reusable patterns
3. Design component hierarchy
4. Define state management approach
5. Specify API integration points
6. List all new files to create
7. List all existing files to modify

重构现有代码

1. Analyze current implementation
2. Find ALL consumers (grep -r imports)
3. Identify pain points and technical debt
4. PROPOSE MULTIPLE SOLUTIONS (minimal → comprehensive)
5. GET USER APPROVAL on approach
6. Plan migration strategy (phased vs big-bang)
7. Define rollback approach
8. List migration checklist

# CRITICAL: Start with the simplest solution!
# Only propose comprehensive refactoring if user explicitly wants it.

Bug 修复调查

1. Understand expected vs actual behavior
2. Locate root cause in code
3. Identify affected areas
4. Design fix approach
5. Specify testing for regression prevention

---

参考资料

• 解决方案模板：查看项目 docs/ 文件夹中的现有架构或解决方案文档
• 类似实现：参考代码库中类似的功能／模块

---

编写有效解决方案文档的提示

1. 具体说明：“提升性能” → “将 API 响应时间从 2s 降至 500ms”
2. 说明背景：解释做出某项决定的原因，而不只是说明决定的内容
3. 提供示例：为复杂模式展示代码片段
4. 考虑边缘情况：API 失败时会发生什么？用户没有数据时呢？
5. 考虑迁移：重构时，如何安全地从 A 迁移到 B？
6. 列出所有更改：重构时，列出每个有更改的文件
7. 验证导入：确认所有导入路径都存在且正确
8. 检查 Hook 规则：确保没有条件 Hook，且 Hook 依赖项正确

---

准确性与完整性（从实际解决方案审查中吸取的重要教训）

技术术语——务必准确

错误	正确	原因
“共享状态”	“每个实例独立轮询”	除非显式连接，否则 Hook 不会共享状态
“待处理更改”	“待处理计数减少”	代码检查 !isPending && prevIsPending（true→false）
“触发刷新”	“调用 navigation.goBack()，进而触发……”	展示完整调用链

调用链文档——不要跳过步骤

错误：“onRefresh 会触发数据刷新” 正确：

onRefresh() → navigation.goBack() → Dashboard focused
  → usePromiseResult (revalidateOnFocus: true) fires
  → refreshItems() → handleRefresh()
  → fetchItems() + refreshSummary() + refreshMetrics()

为每个步骤注明文件路径和行号！

测试覆盖——涵盖所有操作

如果模块有 5 种操作（创建／编辑／删除／导入／导出），就测试全部 5 种。 不要只测试关注的 2 种。

刷新／时序问题的时间线分析

绘制时间线：

0s  ---- Modal opens, user starts Edit
10s ---- Action submitted, pending: 0→1
15s ---- Modal closes
        └─ Dashboard hook last polled at 5s
        └─ Next poll at 35s (25s away!) ❌

这能说明它为什么不起作用。

常见解决方案错误

错误	示例	修正方法
空回调	onRefresh: () => {}	实现实际逻辑或移除
根本原因说明不完整	“它不会刷新”	解释原因：时序／作用域／未连接
缺少调用链	“不知何故触发了刷新”	使用 文件:行号 记录每个步骤
测试不完整	只测试创建／编辑	也测试删除／导入／导出
将假设当作事实	“revalidateOnFocus 会在模态框关闭时触发”	核实：只有焦点实际变化时才会触发
触发条件错误	“待处理更改”	代码显示：!isPending && prevIsPending（计数减少）

---