Back to Details

architecting-solutions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Architecting Solutions

解决方案架构设计

Analyzes requirements and creates detailed PRD documents for software implementation.
分析需求并为软件实现创建详细的PRD文档。

Description

说明

Use this skill when you need to:
  • Create PRD documents
  • Design software solutions
  • Analyze requirements
  • Specify features
  • Document technical plans
  • Plan refactoring or migration
在以下场景中使用此技能：
  • 创建PRD文档
  • 设计软件解决方案
  • 分析需求
  • 定义功能特性
  • 记录技术方案
  • 规划重构或迁移

Installation

安装

This skill is typically installed globally at 
~/.claude/skills/architecting-solutions/
.
此技能通常全局安装在 
~/.claude/skills/architecting-solutions/
路径下。

How It Works

工作原理

The skill guides Claude through a structured workflow:
  1. Clarify requirements - Ask targeted questions to understand the problem
  2. Analyze context - Review existing codebase for patterns and constraints
  3. Design solution - Propose architecture with trade-offs considered
  4. Generate PRD - Output markdown PRD to 
    {PROJECT_ROOT}/docs/
    directory
IMPORTANT: Always write PRD to the project's 
docs/
folder, never to plan files or hidden locations.
该技能引导Claude遵循结构化工作流程：
  1. 明确需求 - 提出针对性问题以理解问题本质
  2. 分析上下文 - 审查现有代码库的模式与约束
  3. 设计解决方案 - 提出考虑了权衡的架构方案
  4. 生成PRD - 将Markdown格式的PRD输出到 
    {PROJECT_ROOT}/docs/
    目录
重要提示：务必将PRD写入项目的
docs/
文件夹，切勿写入计划文件或隐藏位置。

Workflow

工作流程

Copy this checklist and track progress:
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 PRD document (must be in {PROJECT_ROOT}/docs/)
- [ ] Step 7: Validate with user
复制以下清单并跟踪进度：
需求分析:
- [ ] 步骤1：明确用户意图与成功标准
- [ ] 步骤2：识别约束条件（技术栈、时间线、资源）
- [ ] 步骤3：分析现有代码库模式
- [ ] 步骤4：研究最佳实践（如有需要）
- [ ] 步骤5：设计解决方案架构
- [ ] 步骤6：生成PRD文档（必须存储在 {PROJECT_ROOT}/docs/）
- [ ] 步骤7：与用户确认验证

Step 1: Clarify Requirements

步骤1：明确需求

Ask these questions to understand the problem:
提出以下问题以理解问题：

Core Understanding

核心认知

  • Problem Statement: What problem are we solving? What is the current pain point?
  • Success Criteria: How do we know this is successful? Be specific.
  • Target Users: Who will use this feature? What are their goals?
  • 问题陈述：我们要解决什么问题？当前的痛点是什么？
  • 成功标准：如何判断解决方案成功？请具体化。
  • 目标用户：谁会使用此功能？他们的目标是什么？

For Refactoring/Migration:

针对重构/迁移场景：

  • Why Refactor?: What's wrong with current implementation? Be specific.
  • Breaking Changes: What will break? What needs migration?
  • Rollback Plan: How do we revert if something goes wrong?
  • 重构原因：当前实现存在哪些问题？请具体化。
  • 破坏性变更：哪些功能会受影响？需要迁移哪些内容？
  • 回滚计划：如果出现问题，如何回滚？

Step 2: Identify Constraints

步骤2：识别约束条件

  • Technical Constraints: Existing tech stack, architecture patterns, dependencies
  • Time Constraints: Any deadlines or phases?
  • Resource Constraints: Team size, expertise availability
  • Business Constraints: Budget, external dependencies, third-party APIs
  • 技术约束：现有技术栈、架构模式、依赖关系
  • 时间约束：是否有截止日期或阶段要求？
  • 资源约束：团队规模、专业技能可用性
  • 业务约束：预算、外部依赖、第三方API

Step 3: Analyze Existing Codebase

步骤3：分析现有代码库

bash
undefined
bash
undefined

Find similar patterns in the codebase

在代码库中查找相似模式

grep -r "related_keyword" packages/ --include=".ts" --include=".tsx"
grep -r "related_keyword" packages/ --include=".ts" --include=".tsx"

Find relevant directory structures

查找相关目录结构

find packages/ -type d -name "keyword"
find packages/ -type d -name "keyword"

Check existing patterns

查看现有模式

ls -la packages/kit/src/views/similar-feature/

**Critical for Refactoring:**
- Find ALL consumers of the code being changed
- Identify ALL state/data flows
- Trace ALL entry points and exit points
- **Look for existing mechanisms that might solve the problem already**

```bash
ls -la packages/kit/src/views/similar-feature/

**重构关键要点:**
- 找出所有使用待修改代码的消费者
- 识别所有状态/数据流
- 追踪所有入口点与出口点
- **寻找已有的可解决问题的机制**

```bash

Find all imports/usages of a module

查找模块的所有导入/使用情况

grep -r "useBorrowContext" packages/ --include=".ts" --include=".tsx" grep -r "borrowRefreshReservesRef" packages/ --include=".ts" --include=".tsx"

**CRITICAL: Before proposing a refactoring, ask:**
1. Is there an **existing mechanism** that can be extended?
2. What's the **simplest possible solution**?
3. Can we solve this with **minimal changes**?
4. **Does my solution actually connect the dots?** (e.g., empty callbacks won't work)

Look for:
- **Architectural patterns**: How are similar features implemented?
- **State management**: What state solution is used? (Jotai, Redux, Context, Refs)
- **Component patterns**: How are components organized?
- **API patterns**: How are API calls structured?
- **Type definitions**: Where are types defined?
grep -r "useBorrowContext" packages/ --include=".ts" --include=".tsx" grep -r "borrowRefreshReservesRef" packages/ --include=".ts" --include=".tsx"

**关键提示：在提出重构方案前，请先问自己：**
1. 是否存在可扩展的**现有机制**？
2. 最简单的解决方案是什么？
3. 能否通过**最小变更**解决问题？
4. 我的方案是否真正打通了所有环节？（例如：空回调无法生效）

需要关注：
- **架构模式**：相似功能是如何实现的？
- **状态管理**：使用了哪种状态管理方案？(Jotai, Redux, Context, Refs)
- **组件模式**：组件是如何组织的？
- **API模式**：API调用的结构是怎样的？
- **类型定义**：类型定义存储在何处？

Step 4: Research Best Practices

步骤4：研究最佳实践

For unfamiliar domains, search for best practices.
对于不熟悉的领域，搜索相关最佳实践。

Step 5: Design Solution Architecture

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

CRITICAL: Consider Multiple Solutions

关键要求：提供多种解决方案

Before settling on a solution, ALWAYS present multiple options:
  1. Minimal Change Solution - What's the absolute smallest change that could work?
  2. Medium Effort Solution - Balanced approach with some refactoring
  3. Comprehensive Solution - Full architectural overhaul
Example:
Problem: Data doesn't refresh after operation

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

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

Option 3 (Comprehensive): Migrate to Jotai Context pattern
  - Changes: 10+ files, new atoms/actions
  - Risk: High
  - Time: 2-3 days
Ask user BEFORE writing PRD:
  • Which option do you prefer?
  • Are you open to larger refactoring?
  • What's your tolerance for change?
在确定最终方案前，务必提供多个选项：
  1. 最小变更方案 - 能解决问题的最小改动是什么？
  2. 中等工作量方案 - 平衡重构需求与实现成本的方案
  3. 全面解决方案 - 完整的架构升级方案
示例:
问题：操作后数据未刷新

选项1（最小变更）：挂钩现有pendingTx计数减少逻辑
  - 改动范围：1-2个文件
  - 风险：低
  - 选定：✓

选项2（中等工作量）：通过现有上下文添加刷新回调
  - 改动范围：3-5个文件
  - 风险：中

选项3（全面方案）：迁移到Jotai Context模式
  - 改动范围：10+个文件，新增atoms/actions
  - 风险：高
  - 耗时：2-3天
生成PRD前请询问用户：
  • 您倾向于哪个选项？
  • 您是否接受大规模重构？
  • 您对变更的容忍度如何？

Architecture Design Principles

架构设计原则

  1. Simplicity First: Choose the simplest solution that meets requirements
  2. Progressive Enhancement: Start with MVP, extend iteratively
  3. Separation of Concerns: UI, logic, and data should be separated
  4. Reusability: Design components that can be reused
  5. Testability: Design for easy testing
  1. 简洁优先：选择满足需求的最简单方案
  2. 渐进增强：从MVP开始，逐步迭代扩展
  3. 关注点分离：UI、逻辑与数据应相互分离
  4. 可复用性：设计可复用的组件
  5. 可测试性：为易于测试而设计

Document Trade-offs

记录权衡决策

For each major decision, document:
OptionProsConsSelected
Approach APro1, Pro2Con1✓
Approach BPro1Con1, Con2
针对每个主要决策，记录：
选项优势劣势是否选定
方案A优势1、优势2劣势1✓
方案B优势1劣势1、劣势2

Step 6: Generate PRD Document

步骤6：生成PRD文档

IMPORTANT: Always write PRD to the project's 
docs/
directory, never to plan files or hidden locations.
Output location: 
{PROJECT_ROOT}/docs/{feature-name}-prd.md
Example:
  • If project root is 
    /Users/user/my-project/
    , write to 
    /Users/user/my-project/docs/feature-name-prd.md
  • Use kebab-case for filename: 
    borrow-refresh-logic-refactoring-prd.md
重要提示：务必将PRD写入项目的
docs/
目录，切勿写入计划文件或隐藏位置。
输出路径：
{PROJECT_ROOT}/docs/{feature-name}-prd.md
示例：
  • 若项目根目录为 
    /Users/user/my-project/
    ，则写入 
    /Users/user/my-project/docs/feature-name-prd.md
  • 文件名使用短横线命名法：
    borrow-refresh-logic-refactoring-prd.md

Step 7: Validate with User

步骤7：与用户确认验证

Before finalizing:
  1. Review success criteria - Do they align with user goals?
  2. Check constraints - Are all constraints addressed?
  3. Verify completeness - Can another agent implement from this PRD?
  4. Confirm with user - Get explicit approval before finalizing
最终确定前：
  1. 审查成功标准 - 是否与用户目标一致？
  2. 检查约束条件 - 是否所有约束都已考虑？
  3. 验证完整性 - 其他Agent能否直接基于此PRD实现？
  4. 用户确认 - 最终确定前获得明确批准

PRD Quality Checklist

PRD质量检查清单

Content Quality

内容质量

  • Problem statement is clear and specific
  • Success criteria are measurable
  • Functional requirements are unambiguous
  • Non-functional requirements are specified
  • Constraints are documented
  • Trade-offs are explained
  • 问题陈述清晰具体
  • 成功标准可衡量
  • 功能需求明确无歧义
  • 非功能需求已定义
  • 约束条件已记录
  • 权衡决策已说明

Implementation Readiness

实施就绪度

  • Architecture is clearly defined
  • File structure is specified
  • API contracts are defined (if applicable)
  • Data models are specified
  • Edge cases are considered
  • Testing approach is outlined
  • 架构定义清晰
  • 文件结构已指定
  • API契约已定义（如适用）
  • 数据模型已指定
  • 边缘情况已考虑
  • 测试方法已概述

Agent-Friendliness

Agent友好性

  • Another agent can implement without clarification
  • Code examples are provided where helpful
  • File paths use forward slashes
  • Existing code references are accurate
  • 其他Agent无需额外澄清即可实现
  • 复杂模式提供代码示例
  • 文件路径使用正斜杠
  • 现有代码引用准确

Root Cause Analysis Checklist (CRITICAL)

根本原因分析清单（关键）

For bugs and refresh issues, ALWAYS verify:
  • Existing mechanism already exists - Does a working solution exist elsewhere?
  • Why existing solution doesn't work - Timing? Scope? Not connected?
  • Each hook/component instance is independent - They don't share state unless explicitly connected
  • Callback chain is complete - Trace from trigger to effect, every link must work
  • Empty callbacks are called - If 
    onRefresh
    is provided, is it actually implemented?
  • Polling/refresh timing - What are the intervals? When do they fire?
Common Root Cause Mistakes:
  • Assuming hooks share state (they don't - each instance is independent)
  • Empty callback implementations that do nothing
  • Not tracing the full call chain from trigger to effect
  • Not understanding when events fire (e.g., 
    revalidateOnFocus
    requires actual focus change)
针对Bug与刷新问题，务必验证：
  • 现有机制已存在 - 是否已有可行的解决方案？
  • 现有方案失效原因 - 时机问题？范围问题？未打通环节？
  • 每个Hook/组件实例独立 - 除非显式连接，否则不共享状态
  • 回调链完整 - 从触发器到效果，每个环节都必须正常工作
  • 空回调已调用 - 如果提供了
    onRefresh
    ，是否实际实现了逻辑？
  • 轮询/刷新时机 - 间隔是多少？何时触发？
常见根本原因错误:
  • 假设Hook共享状态（实际并非如此 - 每个实例都是独立的）
  • 空回调实现无任何逻辑
  • 未追踪从触发器到效果的完整调用链
  • 不理解事件触发时机（例如：
    revalidateOnFocus
    需要实际的焦点变化）

Migration Scope Completeness

迁移范围完整性

  • ALL existing state is accounted for: List every piece of state being migrated
    • What states are being migrated? (e.g., reserves, market, reservesLoading, swapConfig, pendingTxs)
    • What's the migration strategy for each? (direct move / transform / deprecate)
  • ALL consumers are identified: Find every file that uses the code being changed
    bash
    # Must run: grep -r "import.*ModuleName" packages/
# Must run: grep -r "useHookName" packages/
  • Provider usage points are covered: Every file using the Provider is updated
    • Root Provider → Mirror Provider migration
    • All pages/components using the provider
  • 所有现有状态已覆盖：列出所有待迁移的状态
    • 待迁移的状态有哪些？（例如：reserves、market、reservesLoading、swapConfig、pendingTxs）
    • 每个状态的迁移策略是什么？（直接迁移/转换/弃用）
  • 所有消费者已识别：找出所有使用待修改代码的文件
    bash
    # 必须执行：grep -r "import.*ModuleName" packages/
# 必须执行：grep -r "useHookName" packages/
  • Provider使用点已覆盖：所有使用Provider的文件都已更新
    • 根Provider → 镜像Provider迁移
    • 所有使用该Provider的页面/组件

State/Data Flow Validation

状态/数据流验证

  • No orphaned state: Every piece of state has a clear source and consumer
  • No dead state: Every new state/state variable has a defined purpose and consumer
  • No undefined references: All imports/references resolve to existing code
  • Complete call chain documented: From trigger → callback → effect, show every step
  • All related operations covered: If module has Supply/Withdraw/Borrow/Repay/Claim, test all of them
  • 无孤立状态：每个状态都有明确的来源与消费者
  • 无无用状态：每个新状态/状态变量都有明确的用途与消费者
  • 无未定义引用：所有导入/引用都指向现有代码
  • 完整调用链已记录：从触发器→回调→效果，展示每个步骤
  • 所有相关操作已覆盖：如果模块包含Supply/Withdraw/Borrow/Repay/Claim操作，需全部测试

React/Hook Rules Compliance

React/Hook规则合规性

  • No conditional hooks: Never call hooks conditionally (e.g., 
    isBorrowType ? useHook() : null
    )
    • Hooks MUST be called at the top level, unconditionally
    • If conditional logic is needed, use early return or conditional rendering
  • Ref usage is correct: If using ref pattern, access via 
    .current
    • Check: 
      useBorrowActions().current
      not 
      useBorrowActions()
  • 无条件Hook调用：切勿条件性调用Hook（例如：
    isBorrowType ? useHook() : null
    ）
    • Hook必须在顶层无条件调用
    • 如需条件逻辑，使用提前返回或条件渲染
  • Ref使用正确：如果使用Ref模式，需通过
    .current
    访问
    • 检查：
      useBorrowActions().current
      而非 
      useBorrowActions()

Provider Pattern Completeness

Provider模式完整性

  • Root Provider is defined: Main Provider component exists
  • Mirror Provider is defined: Mirror Provider for modal/overlay contexts exists
  • All usage points wrapped: Every page/component using the provider is wrapped
    bash
    # Must verify: Each page that uses the context has the Provider wrapper
  • 根Provider已定义：主Provider组件已存在
  • 镜像Provider已定义：为模态框/覆盖层上下文提供的镜像Provider已存在
  • 所有使用点已包裹：所有使用该Provider的页面/组件都已被包裹
    bash
    # 必须验证：每个使用上下文的页面都已包裹Provider

Auto-mount/System Integration

自动挂载/系统集成

  • Enum registration: Added to appropriate enum (e.g., 
    EJotaiContextStoreNames
    )
  • Switch case registration: Added to auto-mount switch statement
  • Store initialization: Store initialization logic is complete
  • No duplicate registrations: Verify no conflicts with existing entries
  • 枚举已注册：已添加到相应枚举（例如：
    EJotaiContextStoreNames
    ）
  • Switch case已注册：已添加到自动挂载switch语句
  • Store初始化完成：Store初始化逻辑完整
  • 无重复注册：验证与现有条目无冲突

Backward Compatibility

向后兼容性

  • Existing consumers work: Code using the old pattern still works during migration
  • Migration path is clear: How do consumers migrate to the new pattern?
  • Deprecation timeline: When is the old pattern removed?
  • 现有消费者可正常工作：使用旧模式的代码在迁移期间仍可正常运行
  • 迁移路径清晰：消费者如何迁移到新模式？
  • 弃用时间线：旧模式何时移除？

Code Examples

代码示例

  • Before/After comparisons: Show code changes clearly
  • Type definitions are accurate: TypeScript types match the implementation
  • Import paths are correct: All imports use correct workspace paths
  • 前后对比：清晰展示代码变更
  • 类型定义准确：TypeScript类型与实现一致
  • 导入路径正确：所有导入使用正确的工作区路径

Common Anti-Patterns to Avoid

常见反模式规避

Anti-PatternBetter Approach
"Optimize the code""Reduce render time from 100ms to 16ms by memoizing expensive calculations"
"Make it faster""Implement caching to reduce API calls from 5 to 1 per session"
"Clean up the code""Extract duplicate logic into shared utility functions"
"Fix the bug""Handle null case in getUserById when user doesn't exist"
"Refactor to use Jotai""Migrate from Context+Ref to Jotai: <detailed state list and migration strategy>"
Over-engineeringStart with simplest solution, extend only if needed
反模式更佳方案
"优化代码""通过缓存昂贵计算将渲染时间从100ms减少到16ms"
"让它更快""实现缓存将每个会话的API调用从5次减少到1次"
"清理代码""将重复逻辑提取到共享工具函数中"
"修复Bug""处理getUserById在用户不存在时的空值情况"
"重构为使用Jotai""从Context+Ref迁移到Jotai：<详细状态列表与迁移策略>"
过度设计从最简单的方案开始，仅在需要时扩展

Over-Engineering Warning (Critical Lesson)

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

The Problem with Jumping to Complex Solutions

直接选择复杂方案的问题

Real Case Study:
  • PRD Proposed: Full Jotai Context migration (10+ files, 2-3 days)
  • Actual Solution: Hook into existing pendingTx count decrease (1-2 files, 1 hour)
  • Lesson: Always look for the simplest solution first
真实案例研究:
  • PRD提案：完整的Jotai Context迁移（10+文件，2-3天）
  • 实际解决方案：挂钩现有pendingTx计数减少逻辑（1-2个文件，1小时）
  • 经验教训：始终优先寻找最简单的解决方案

Signs You Might Be Over-Engineering

过度设计的迹象

  • ❌ Proposing new patterns when existing ones could work
  • ❌ Creating new state management before exhausting current options
  • ❌ Multiple new files when one file change could suffice
  • ❌ "Best practice" justification without considering practicality
  • ❌ 现有模式可满足需求时仍提出新模式
  • ❌ 未穷尽当前方案就创建新的状态管理
  • ❌ 本可修改一个文件却新增多个文件
  • ❌ 脱离实际情况用“最佳实践”作为理由

Questions to Ask Before Writing PRD

生成PRD前需问自己的问题

  1. Is there an existing mechanism that does 80% of what we need?
  2. Can we extend/modify existing code instead of creating new patterns?
  3. What's the absolute minimum change to solve THIS problem?
  4. Does the user actually want a major refactor?
  5. Does my solution's callback actually do something? (Empty callbacks are bugs!)
  6. Have I traced the complete call chain? (Trigger → ... → Effect)
  1. 是否存在能满足80%需求的现有机制？
  2. 能否通过扩展/修改现有代码解决问题，而非创建新模式？
  3. 解决当前问题的绝对最小变更是什么？
  4. 用户是否真的需要大规模重构？
  5. 我的方案中的回调是否真正执行了逻辑？（空回调是Bug！）
  6. 我是否追踪了完整的调用链？（触发器→...→效果）

When Comprehensive Solutions ARE Appropriate

适合采用全面解决方案的场景

  • Current architecture is fundamentally broken
  • Technical debt is blocking all new features
  • Team has explicitly decided to modernize
  • Problem will recur if not properly addressed
Key: Comprehensive solutions should be a CHOICE, not the DEFAULT.
  • 当前架构存在根本性缺陷
  • 技术债务阻碍所有新功能开发
  • 团队已明确决定进行现代化改造
  • 不彻底解决问题会导致重复出现
关键提示：全面解决方案应该是主动选择，而非默认选项。

Patterns for Common Scenarios

常见场景模式

New Feature Implementation

新功能实现

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. 阅读相似功能的实现
2. 识别可复用模式
3. 设计组件层级
4. 定义状态管理方案
5. 指定API集成点
6. 列出所有待创建的新文件
7. 列出所有待修改的现有文件

Refactoring Existing Code

现有代码重构

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
1. 分析当前实现
2. 找出所有消费者（grep -r 导入语句）
3. 识别痛点与技术债务
4. **提供多种解决方案**（最小变更→全面方案）
5. **获得用户对方案的批准**
6. 规划迁移策略（分阶段 vs 一次性迁移）
7. 定义回滚方案
8. 列出迁移检查清单

CRITICAL: Start with the simplest solution!

关键提示：从最简单的方案开始！

Only propose comprehensive refactoring if user explicitly wants it.

仅当用户明确要求时才提出全面重构方案。

undefined
undefined

Bug Fix Investigation

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
1. 理解预期行为与实际行为的差异
2. 在代码中定位根本原因
3. 识别受影响的范围
4. 设计修复方案
5. 指定回归测试方法

Reference Materials

参考资料

  • PRD Template: Look at existing PRDs in the project's 
    docs/
    folder
  • Similar Implementations: Reference similar features/modules in the codebase
  • PRD模板：查看项目
    docs/
    文件夹中的现有PRD
  • 相似实现：参考代码库中的相似功能/模块

Tips for Effective PRDs

高效PRD编写技巧

  1. Be Specific: "Improve performance" → "Reduce API response time from 2s to 500ms"
  2. Show Context: Explain why a decision was made, not just what was decided
  3. Include Examples: Show code snippets for complex patterns
  4. Think About Edge Cases: What happens when API fails? User has no data?
  5. Consider Migration: For refactoring, how do we move from A to B safely?
  6. List ALL Changes: For refactoring, list every file that changes
  7. Validate Imports: Verify all import paths exist and are correct
  8. Check Hook Rules: Ensure no conditional hooks, proper hook dependencies
  1. 具体化：将“提升性能”改为“将API响应时间从2s减少到500ms”
  2. 展示上下文：说明决策的原因，而非仅说明决策内容
  3. 包含示例：为复杂模式提供代码片段
  4. 考虑边缘情况：API失败时会发生什么？用户无数据时会怎样？
  5. 考虑迁移：对于重构，如何安全地从A过渡到B？
  6. 列出所有变更：对于重构，列出所有待修改的文件
  7. 验证导入：确保所有导入路径存在且正确
  8. 检查Hook规则：确保无条件Hook调用，Hook依赖正确

Accuracy & Completeness (Critical Lessons from Real PRD Reviews)

准确性与完整性（来自真实PRD评审的重要经验）

Technical Terms - Be Precise

技术术语 - 务必精准

WrongCorrectWhy
"Shared state""Each instance polls independently"Hooks don't share state unless explicitly connected
"Pending changes""Pending count decreases"Code checks 
!isPending && prevIsPending
(true→false)
"Triggers refresh""Calls navigation.goBack() which triggers..."Show the complete chain
错误表述正确表述原因
"共享状态""每个实例独立轮询"除非显式连接，否则Hook不共享状态
"待处理变更""待处理计数减少"代码检查
!isPending && prevIsPending
（true→false）
"触发刷新""调用navigation.goBack()，进而触发..."展示完整调用链

Call Chain Documentation - Don't Skip Steps

调用链文档 - 切勿跳过步骤

Bad: "onRefresh triggers data refresh" Good:
onRefresh() → navigation.goBack() → BorrowHome focused
  → usePromiseResult (revalidateOnFocus: true) fires
  → refreshReserves() → handleRefresh()
  → fetchReserves() + refreshBorrowRewards() + refreshHealthFactor()
Include file paths and line numbers for each step!
不良示例："onRefresh触发数据刷新" 良好示例:
onRefresh() → navigation.goBack() → BorrowHome获得焦点
  → usePromiseResult（revalidateOnFocus: true）触发
  → refreshReserves() → handleRefresh()
  → fetchReserves() + refreshBorrowRewards() + refreshHealthFactor()
请为每个步骤包含文件路径与行号！

Test Coverage - Cover ALL Operations

测试覆盖 - 覆盖所有操作

If module has 5 operations (Supply/Withdraw/Borrow/Repay/Claim), test all 5. Don't just test the 2 you're focused on.
如果模块包含5种操作（Supply/Withdraw/Borrow/Repay/Claim），需全部测试。不要仅测试你关注的2种。

Timeline Analysis for Refresh/Timing Issues

刷新/时机问题的时间线分析

Draw out the timeline:
0s  ---- Modal opens, user starts Supply
10s ---- Transaction submitted, pending: 0→1
15s ---- Modal closes
        └─ BorrowHome's hook last polled at 5s
        └─ Next poll at 35s (25s away!) ❌
This shows WHY it doesn't work.
绘制时间线：
0s  ---- 模态框打开，用户开始Supply操作
10s ---- 交易提交，pending: 0→1
15s ---- 模态框关闭
        └─ BorrowHome的Hook最后一次轮询在5s
        └─ 下一次轮询在35s（还有25s！）❌
这直观展示了问题所在。

Common PRD Mistakes

常见PRD错误

MistakeExampleFix
Empty callback
onRefresh: () => {}
Implement actual logic or remove
Incomplete root cause"It doesn't refresh"Explain WHY: timing/scope/disconnected
Missing call chain"Somehow triggers refresh"Document every step with file:line
Incomplete testingOnly test Supply/WithdrawAlso test Borrow/Repay/Claim
Assumptions as facts"revalidateOnFocus fires on modal close"Verify: only fires on actual focus change
Wrong trigger condition"Pending changes"Code shows: 
!isPending && prevIsPending
(decreases)
错误示例修复方案
空回调
onRefresh: () => {}
实现实际逻辑或移除
根本原因分析不完整"数据未刷新"解释具体原因：时机/范围/未打通环节
调用链记录缺失"以某种方式触发刷新"记录每个步骤并包含文件:行号
测试覆盖不完整仅测试Supply/Withdraw同时测试Borrow/Repay/Claim
假设为事实"revalidateOnFocus在模态框关闭时触发"验证：仅在实际焦点变化时触发
触发条件错误"待处理变更"代码显示：
!isPending && prevIsPending
（计数减少）