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 を使用してください。このスキルは、プロジェクトの docs/ フォルダーに PRD 以外のアーキテクチャおよびソリューション関連の成果物を作成します。

ワークフロー

このチェックリストをコピーし、進捗を記録してください。

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 に作成します
• ファイル名にはケバブケースを使用します：data-refresh-logic-refactoring-solution.md

ステップ 7：ユーザーと検証する

最終確定の前に：

1. 成功基準を確認する - ユーザーの目標に合致していますか？
2. 制約を確認する - すべての制約に対応していますか？
3. 完全性を検証する - 別のエージェントがこのソリューションドキュメントをもとに実装できますか？
4. ユーザーに確認する - 最終確定の前に明示的な承認を得てください

---

ソリューション品質チェックリスト

内容の品質

• 問題の説明が明確かつ具体的である
• 成功基準が測定可能である
• 機能要件に曖昧さがない
• 非機能要件が指定されている
• 制約が記録されている
• トレードオフが説明されている

実装の準備状況

• アーキテクチャが明確に定義されている
• ファイル構成が指定されている
• API コントラクトが定義されている（該当する場合）
• データモデルが指定されている
• エッジケースが考慮されている
• テスト方針の概要が示されている

エージェントにとっての使いやすさ

• 別のエージェントが確認を求めずに実装できる
• 必要に応じてコード例が提示されている
• ファイルパスにスラッシュが使用されている
• 既存コードへの参照が正確である

---

根本原因分析チェックリスト（重要）

バグ、状態、更新、またはライフサイクルの問題について、以下を確認します。

• 既存の仕組み - 別の場所にすでに動作する解決策はありませんか？
• 因果関係の欠落 - 既存の解決策がここで適用されないのはなぜですか？タイミング、スコープ、所有権、または配線の不足が原因ですか？
• 状態の所有権 - 各状態遷移を所有するインスタンスまたはサービスはどれですか？
• イベントチェーン全体 - トリガー → ハンドラー → 状態変更 → 観測可能な効果をたどります。
• 実装済みの境界 - 各コールバック、アダプター、キュー、登録ポイントが実際に処理を行うことを確認します。
• タイミングのセマンティクス - 間隔、再試行、フォーカス／ライフサイクルイベント、キャンセル動作を特定します。

よくある間違いには、別々のインスタンスが状態を共有すると想定すること、何もしないコールバックを残すこと、チェーンの最初のリンクだけを確認すること、イベントの登録をイベントが発生した証拠と混同することなどがあります。

---

移行スコープの網羅性

• 既存の状態をすべて把握している：移行する状態をすべて列挙します

  • どの状態を移行しますか？（例：items、summary、isLoading、filters、pendingRequests）
  • それぞれの移行戦略は何ですか？（直接移動／変換／廃止）

• すべての利用箇所を特定している：変更対象のコードを使用するファイルをすべて見つけます

  rg -n "ModuleName|PublicInterfaceName" .
  

• 依存関係の利用箇所を網羅している：変更するインターフェースの利用側をすべて特定します

  • 主な実行時の構成
  • オーバーレイ、ワーカー、ジョブ、テストなどの二次的なコンテキスト（存在する場合）

状態／データフローの検証

• 孤立した状態がない：すべての状態に明確なソースと利用側がある
• 未使用の状態がない：新しい状態／状態変数すべてに、明確な目的と利用側がある
• 未定義の参照がない：すべてのインポート／参照が既存のコードに解決される
• 呼び出しチェーン全体を記録している：トリガー → コールバック → 効果まで、すべての手順を示す
• 関連する操作をすべて網羅している：モジュールに作成／編集／削除／インポート／エクスポートがある場合は、すべてをテストする

フレームワークの不変条件（該当する場合）

• ライフサイクルのルールを守る：実際のフレームワークにおける順序、登録、ティアダウンの要件を確認します。
• 参照セマンティクスを守る：リポジトリのフレームワークに従って、可変ハンドル、値のスナップショット、依存関係のライフタイムを確認します。
• 条件付きの動作が許容される：フレームワークが安定した順序を求める場合、プリミティブを条件付きで登録しないでください。

依存関係の構成が完全であること

• 構成の所有者が定義されている：リポジトリにおける実際の依存関係の所有者を特定します。
• 二次コンテキストを網羅している：該当する場合は、モーダル、オーバーレイ、ワーカー、テスト、並列ランタイムを確認します。
• すべての使用箇所に接続されている：すべての利用側に必要な依存関係が渡されます。
• ランタイム登録を確認している：関連するプロバイダー、コンテナー、レジストリ、またはアダプターが、必要なすべてのコンテキストに存在します。

フレームワーク／システムとの統合

• 登録箇所：必要なレジストリ、ルート、依存関係コンテナー、またはプラグインマニフェストを更新します。
• 初期化：起動とティアダウンが、リポジトリで既存のライフサイクルに従っています。
• 登録の重複がない：既存のエントリーとの競合がないことを確認します。
• 適用可能性：リポジトリで該当する仕組みを使用していない場合は、フレームワーク固有の確認を省略します。

後方互換性

• 既存の利用側が動作する：移行中も、以前のパターンを使用するコードが動作します。
• 移行手順が明確である：利用側が新しいパターンに移行する方法を示します。
• 非推奨化のスケジュール：古いパターンをいつ削除するかを示します。

コード例

• 変更前／変更後の比較：コードの変更を明確に示します。
• 型定義が正確である：TypeScript の型が実装と一致します。
• インポートパスが正しい：すべてのインポートで正しいワークスペースパスを使用します。

---

よくあるアンチパターンを避ける

アンチパターン	より良いアプローチ
「コードを最適化する」	「コストの高い計算をメモ化し、レンダリング時間を100msから16msに短縮する」
「もっと速くする」	「キャッシュを実装し、セッションあたりのAPI呼び出しを5回から1回に減らす」
「コードを整理する」	「重複したロジックを共有ユーティリティ関数に切り出す」
「バグを修正する」	「ユーザーが存在しない場合に、getUserByIdでnullのケースを処理する」
「状態レイヤーをリファクタリングする」	「Context+Refから一元管理されたストアに移行する：<詳細な状態一覧と移行戦略>」
過剰な設計	最もシンプルな解決策から始め、必要な場合にのみ拡張する

---

過剰な設計への警告（重要な教訓）

複雑な解決策に飛びつくことの問題

教訓の例： 操作の完了後に更新するという要望は、新しい共有状態サブシステムではなく、既存の完了シグナルだけで対応できる場合があります。より広範な抽象化を提案する前に、現在のライフサイクルをたどってください。

過剰な設計をしている可能性を示す兆候

• ❌ 既存のパターンで対応できるのに、新しいパターンを提案する
• ❌ 現在の選択肢をすべて検討する前に、新しい状態管理を作成する
• ❌ 1つのファイルの変更で済むのに、複数の新しいファイルを作成する
• ❌ 実用性を考慮せず、「ベストプラクティス」を根拠にする

解決策を書く前に確認すること

1. 必要な機能の80%を満たす既存の仕組みはありますか？
2. 新しいパターンを作成する代わりに、既存のコードを拡張／変更できますか？
3. この問題を解決するための、絶対に必要最小限の変更は何ですか？
4. ユーザーは本当に大規模なリファクタリングを望んでいますか？
5. 解決策のコールバックは実際に何かをしていますか？（空のコールバックはバグです！）
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.

バグ修正の調査

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 の応答時間を 2 秒から 500 ミリ秒に短縮する」
2. 背景を示す：決定事項だけでなく、その決定に至った理由を説明してください
3. 例を含める：複雑なパターンでは、コードスニペットを示してください
4. エッジケースを考慮する：API が失敗した場合はどうなりますか？ユーザーにデータがない場合はどうなりますか？
5. 移行を考慮する：リファクタリングでは、A から B に安全に移行する方法を説明してください
6. 変更をすべて列挙する：リファクタリングでは、変更するファイルをすべて列挙してください
7. インポートを検証する：すべてのインポートパスが存在し、正しいことを確認してください
8. フックのルールを確認する：条件付きフックがなく、フックの依存関係が適切であることを確認してください

---

正確性と完全性（実際のソリューションレビューから得た重要な教訓）

技術用語は正確に

誤り	正しい表現	理由
「共有状態」	「各インスタンスが独立してポーリングする」	明示的に接続されていない限り、フックは状態を共有しません
「保留中の変更」	「保留中の件数が減少する」	コードでは !isPending && prevIsPending（true→false）を確認します
「更新をトリガーする」	「navigation.goBack() を呼び出し、それが……をトリガーする」	処理の連鎖全体を示してください

呼び出しチェーンのドキュメント化：手順を省略しない

悪い例：「onRefresh がデータ更新をトリガーする」 良い例：

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

各手順について、ファイルパスと行番号を含めてください！

テストカバレッジ：すべての操作を網羅する

モジュールに 5 つの操作（Create/Edit/Delete/Import/Export）がある場合は、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: () => {}	実際の処理を実装するか、削除してください
根本原因の説明が不完全	「更新されない」	理由（タイミング／スコープ／接続されていない）を説明してください
呼び出しチェーンの欠落	「何らかの方法で更新をトリガーする」	すべての手順を file:line の形式で記録してください
テストが不完全	Create/Edit のみをテスト	Delete/Import/Export もテストしてください
仮定を事実として扱う	「revalidateOnFocus はモーダルを閉じると発火する」	確認してください：実際のフォーカス変更時にのみ発火します
トリガー条件の誤り	「保留中の変更」	コードでは !isPending && prevIsPending（減少）を示しています

---