review-software-architecture

ソフトウェアアーキテクチャのレビュー

システムレベルでソフトウェアアーキテクチャを評価し、品質特性、設計原則への準拠、長期的な保守性を確認します。

使用するタイミング

• 実装開始前に提案されたアーキテクチャを評価する場合
• スケーラビリティ、保守性、セキュリティの観点から既存システムを評価する場合
• プロジェクトのアーキテクチャ決定記録（ADR）をレビューする場合
• 技術的負債を評価する場合
• 大幅な規模拡大や機能拡張に向けて、システムの準備が整っているかを評価する場合
• 変更内容をプルリクエスト単位で確認する、行単位のコードレビューと区別する場合

入力

• 必須：システムのコードベースまたはアーキテクチャドキュメント（図、ADR、README）
• 必須：システムの目的、規模、制約に関する情報
• 任意：非機能要件（レイテンシ、スループット、可用性の目標）
• 任意：チームの規模とスキル構成
• 任意：技術上の制約または希望
• 任意：既知の課題または懸念事項

手順

ステップ 1：システムのコンテキストを把握する

システムの境界とインターフェースを整理します。

## System Context
- **Name**: [System name]
- **Purpose**: [One-line description]
- **Users**: [Who uses it and how]
- **Scale**: [Requests/sec, data volume, user count]
- **Age**: [Years in production, major versions]
- **Team**: [Size, composition]

## External Dependencies
| Dependency | Type | Criticality | Notes |
|-----------|------|-------------|-------|
| PostgreSQL | Database | Critical | Primary data store |
| Redis | Cache | High | Session store + caching |
| Stripe | External API | Critical | Payment processing |
| S3 | Object storage | High | File uploads |

期待される結果： システムの機能と依存先が明確に把握できていること。 失敗時： アーキテクチャドキュメントがない場合は、コードの構成、設定、デプロイファイルからコンテキストを導き出します。

ステップ 2：構造的な品質を評価する

結合度の評価

モジュール間の依存関係がどの程度強いかを確認します。

• 依存関係の方向：依存関係は一方向（レイヤー構造）に流れていますか、それとも循環していますか？
• インターフェースの境界：モジュールは定義済みのインターフェース／コントラクトを介して接続されていますか、それとも実装を直接参照していますか？
• 共有状態：モジュール間で可変状態が共有されていますか？
• データベースの結合：複数のサービスが同じテーブルを直接読み書きしていますか？
• 時間的結合：明示的なオーケストレーションなしに、操作を特定の順序で実行する必要がありますか？

# Detect circular dependencies (JavaScript/TypeScript)
npx madge --circular src/

# Detect import patterns (Python)
# Look for deep cross-package imports
grep -r "from app\." --include="*.py" | sort | uniq -c | sort -rn | head -20

凝集度の評価

各モジュールに、明確な単一の責務があるかを評価します。

• モジュール名：モジュール名は、その機能を正確に表していますか？
• ファイルサイズ：ファイルやクラスが過度に大きくありませんか（500行を超える場合、複数の責務を持つ可能性があります）？
• 変更頻度：関連のない機能のために、同じモジュールを変更する必要がありますか？
• ゴッドオブジェクト：あらゆるものが依存しているクラスやモジュールはありませんか？

結合度	説明	例
低（良好）	モジュールがインターフェースを介して通信する	サービス A がサービス B の API を呼び出す
中	モジュールがデータ構造を共有する	共有 DTO／モデルライブラリ
高（懸念あり）	モジュールが互いの内部を参照する	モジュールをまたいだデータベースへの直接アクセス
病的	モジュールが互いの内部状態を変更する	グローバルな可変状態

期待される結果： コードベースの具体例を挙げて、結合度と凝集度が評価されていること。 失敗時： コードベースが大きすぎて手動でレビューできない場合は、主要なモジュールを3～5個と、変更頻度が最も高いファイルをサンプリングします。

ステップ 3：SOLID 原則を評価する

原則	質問	危険信号
Single Responsibility（単一責任）	各クラス／モジュールを変更する理由は 1 つだけですか？	無関係な関心事に関する public メソッドが 5 個を超えるクラス
Open/Closed（開放／閉鎖）	既存のコードを変更せずに動作を拡張できますか？	新機能のたびにコアクラスを頻繁に変更している
Liskov Substitution（リスコフの置換）	動作を損なわずに、サブタイプを基底型に置き換えられますか？	コンシューマーコードのあちこちに型チェック（instanceof）が散在している
Interface Segregation（インターフェース分離）	インターフェースは目的が明確で、最小限ですか？	利用者が未使用のメソッドまで実装する「肥大化した」インターフェース
Dependency Inversion（依存性逆転）	上位モジュールは詳細ではなく抽象に依存していますか？	ビジネスロジックでインフラストラクチャクラスを直接インスタンス化している

## SOLID Assessment
| Principle | Status | Evidence | Impact |
|-----------|--------|----------|--------|
| SRP | Concern | UserService handles auth, profile, notifications, and billing | High — changes to billing risk breaking auth |
| OCP | Good | Plugin system for payment providers | Low |
| LSP | Good | No type-checking anti-patterns found | Low |
| ISP | Concern | IRepository has 15 methods, most implementors use 3-4 | Medium |
| DIP | Concern | Controllers directly instantiate database repositories | Medium |

期待される結果： 各原則について、具体例を少なくとも 1 つ挙げて評価します。 失敗時： すべてのアーキテクチャスタイルに、すべての原則が同じように当てはまるわけではありません。原則の関連性が低い場合（例：関数型コードベースでは ISP の重要性が低い場合）は、その旨を記載します。

ステップ 4：API 設計をレビューする

API（REST、GraphQL、gRPC）を公開するシステムでは、次の点を確認します。

• 一貫性： 命名規則、エラー形式、ページネーションのパターンが統一されている
• バージョン管理： 方針が定められ、適用されている（URL、ヘッダー、コンテントネゴシエーション）
• エラー処理： エラーレスポンスが構造化され、一貫性があり、内部情報が漏えいしない
• 認証／認可： API レイヤーで適切に適用されている
• レート制限： 不正利用への対策がある
• ドキュメント： OpenAPI／Swagger、GraphQL スキーマ、または protobuf 定義が維持されている
• 冪等性： 変更を伴う操作（POST／PUT）で、再試行を安全に処理できる

## API Design Review
| Aspect | Status | Notes |
|--------|--------|-------|
| Naming consistency | Good | RESTful resource naming throughout |
| Versioning | Concern | No versioning strategy — breaking changes affect all clients |
| Error format | Good | RFC 7807 Problem Details used consistently |
| Auth | Good | JWT with role-based scopes |
| Rate limiting | Missing | No rate limiting on any endpoint |
| Documentation | Concern | OpenAPI spec exists but 6 months out of date |

期待される結果： 一般的な標準に照らして API 設計をレビューし、具体的な所見を示します。 失敗時： API を公開していない場合は、このステップを省略し、内部モジュールのインターフェースに焦点を当てます。

ステップ 5：スケーラビリティと信頼性を評価する

• ステートレス性： アプリケーションを水平スケールできますか（ローカル状態がない）？
• データベースのスケーラビリティ： クエリにインデックスが設定されていますか？ スキーマはデータ量に適していますか？
• キャッシュ戦略： 適切なレイヤー（データベース、アプリケーション、CDN）でキャッシュが適用されていますか？
• 障害処理： 依存先が利用できない場合、どうなりますか（サーキットブレーカー、再試行、フォールバック）？
• オブザーバビリティ： ログ、メトリクス、トレースが実装されていますか？
• データの一貫性： 結果整合性で許容できますか、それとも強整合性が必要ですか？

期待される結果： 明示された非機能要件に照らして、スケーラビリティと信頼性を評価します。 失敗時： 非機能要件が文書化されていない場合は、まず要件を定義することを推奨します。

ステップ 6：技術的負債を評価する

## Technical Debt Inventory
| Item | Severity | Impact | Estimated Effort | Recommendation |
|------|----------|--------|-----------------|----------------|
| No database migrations | High | Schema changes are manual and error-prone | 1 sprint | Adopt Alembic/Flyway |
| Monolithic test suite | Medium | Tests take 45 min, developers skip them | 2 sprints | Split into unit/integration/e2e |
| Hardcoded config values | Medium | Environment-specific values in source code | 1 sprint | Extract to env vars/config service |
| No CI/CD pipeline | High | Manual deployment prone to errors | 1 sprint | Set up GitHub Actions |

期待される結果： 技術的負債を、重大度、影響、見積もり工数とともに一覧化します。 失敗時： 負債の一覧が膨大な場合は、影響度と工数の比率に基づいて上位 5 項目を優先します。

ステップ 7：アーキテクチャ決定記録（ADR）をレビューする

ADR がある場合は、次の点を評価します。

• 決定の背景（解決しようとしていた問題）が明確である
• 代替案が検討され、記録されている
• トレードオフが明示されている
• 決定が現在も有効である（文書化されないまま別の決定に置き換えられていない）
• 新たな重要な決定に ADR がある

ADR がない場合は、重要な決定について ADR を作成することを推奨します。

ステップ 8：アーキテクチャレビューを作成する

## Architecture Review Report

### Executive Summary
[2-3 sentences: overall health, key concerns, recommended actions]

### Strengths
1. [Specific architectural strength with evidence]
2. ...

### Concerns (by severity)

#### Critical
1. **[Title]**: [Description, impact, recommendation]

#### Major
1. **[Title]**: [Description, impact, recommendation]

#### Minor
1. **[Title]**: [Description, recommendation]

### Technical Debt Summary
[Top 5 debt items with prioritized recommendations]

### Recommended Next Steps
1. [Actionable recommendation with clear scope]
2. ...

期待される結果： レビューレポートに、優先順位付けされた実行可能な推奨事項が含まれています。 失敗時： レビューの時間が限られている場合は、確認した内容と未評価の内容を明確に示します。

検証

• システムのコンテキストを文書化する（目的、規模、依存関係、チーム）
• 具体的なコード例を用いて、結合度と凝集度を評価する
• 該当する場合は、SOLID 原則を評価する
• API 設計をレビューする（該当する場合）
• 要件に照らして、スケーラビリティと信頼性を評価する
• 技術的負債を一覧化し、優先順位を付ける
• ADR をレビューするか、存在しない場合はその旨を記載する
• 推奨事項を具体的かつ優先順位付きで、実行可能なものにする

よくある落とし穴

• アーキテクチャではなくコードをレビューする：このスキルの対象はシステムレベルの設計であり、行単位のコード品質ではありません。PR レベルのフィードバックには code-reviewer を使用してください。
• 特定のテクノロジーを押し付ける：アーキテクチャレビューでは、明確な技術的理由がない限り、特定のツールを必須にするのではなく、問題を特定してください。
• チームの状況を無視する：3 人のチームにとっての「最適な」アーキテクチャは、30 人のチームのものとは異なります。組織上の制約を考慮してください。
• 完璧主義：どのシステムにも技術的負債があります。実際に問題を引き起こしている、または今後の作業を妨げている負債に注力してください。
• 規模を決めつける：100 人のユーザー向けのアプリに分散システムを勧めないでください。実際の要件に合わせてアーキテクチャを選んでください。

関連スキル

• security-audit-codebase — セキュリティに重点を置いたコードと設定のレビュー
• configure-git-repository — リポジトリの構造と規約
• design-serialization-schema — データスキーマの設計と進化
• review-data-analysis — 分析の正確性のレビュー（補完的な視点）