architecture-review

アーキテクチャレビューのスキル

アーキテクチャレビューのスキル - システム設計をベストプラクティスに照らして評価し、アンチパターンを特定するとともに、アーキテクチャ上の意思決定が非機能要件（スケーラビリティ、保守性、セキュリティ、パフォーマンス）に沿っているかを確認します。 - システムアーキテクチャ設計のレビュー - アンチパターンとアーキテクチャ上の問題点の特定 - SOLID、DRY、YAGNI の原則への準拠確認 - 非機能要件の評価 - アーキテクチャの改善案の提案

ステップ 1：アーキテクチャのコンテキストを把握する

以下の方法で、現在のアーキテクチャを理解します。

1. プロジェクト構造を読む：Glob を使ってディレクトリ構造を把握します
2. 主要なコンポーネントを特定する：エントリーポイント、サービス、データレイヤーを見つけます
3. 依存関係を確認する：package.json、インポート、モジュールグラフを確認します
4. データフローを理解する：システム内のリクエストをたどります

ステップ 2：設計原則への準拠を評価する

基本原則への準拠状況を確認します。

SOLID の原則：

• Single Responsibility（単一責任）：各クラス／モジュールに変更理由は 1 つだけですか？
• Open/Closed（オープン／クローズド）：変更せずに振る舞いを拡張できますか？
• Liskov Substitution（リスコフの置換）：サブタイプを基底型と置き換えられますか？
• Interface Segregation（インターフェース分離）：インターフェースは目的が明確で最小限ですか？
• Dependency Inversion（依存性逆転）：上位モジュールは抽象に依存していますか？

その他の原則：

• DRY：ロジックが不必要に重複していませんか？
• YAGNI：未使用または先回りして追加された機能はありませんか？
• 関心の分離：責任は適切に分割されていますか？

ステップ 3：アンチパターンを確認する

よくあるアンチパターンを特定します。

• God Class／Module：処理を抱え込みすぎているクラス
• Spaghetti Code：複雑に絡み合い、追いにくいロジック
• 循環依存：相互に参照するモジュール
• Feature Envy：他クラスのデータを過剰に利用するクラス
• Shotgun Surgery：変更のたびに多くのファイルに手を入れる必要がある状態
• Leaky Abstractions：実装の詳細が利用側に漏れている状態

ステップ 4：非機能要件を評価する

非機能要件（NFR）に照らして評価します。

• スケーラビリティ：負荷の増加に対応できますか？
• 保守性：変更や拡張はどの程度容易ですか？
• テスト容易性：コンポーネントを個別にテストできますか？
• セキュリティ：潜在的な脆弱性はありますか？
• パフォーマンス：明らかなボトルネックはありますか？
• 可観測性：システムを効果的に監視できますか？

ステップ 5：レビュー報告書を作成する

以下の項目を含む構成化された報告書を作成します。

1. 要約：全体的な評価と主な所見
2. 強み：アーキテクチャの優れた点
3. 懸念事項：対応が必要な問題（優先順位付き）
4. 推奨事項：理由を添えた具体的な改善案
5. トレードオフ：妥当な設計上のトレードオフを明記

</execution_process>

<best_practices>

1. 建設的に伝える：批判ではなく改善に焦点を当てます
2. 問題に優先順位を付ける：すべての問題が同じ重要度とは限りません
3. コンテキストを考慮する：制約やトレードオフを理解します
4. 代替案を提案する：問題を指摘するだけにしません
5. パターンを参照する：該当する場合は、確立されたパターンを挙げます

</best_practices>

**レビュー依頼の例**：

Review the architecture of src/services/ for scalability and maintainability

回答の構成例：

## Architecture Review: src/services/

### Summary

The service layer follows a reasonable structure but has some coupling issues...

### Strengths

- Clear separation between API handlers and business logic
- Good use of dependency injection

### Concerns

1. **High Priority**: UserService has 15 methods (God Class)
2. **Medium Priority**: Circular dependency between OrderService and InventoryService
3. **Low Priority**: Some magic numbers in validation logic

### Recommendations

1. Split UserService into UserAuthService and UserProfileService
2. Introduce EventBus to decouple Order and Inventory
3. Extract validation constants to configuration

</usage_example>

アーキテクチャの鉄則

1. 複雑または大規模な実装を始める前に、必ずアーキテクチャをレビューしてください — 実装後に発覚したアーキテクチャ上の問題は、修正コストが10〜100倍になります。設計フェーズでレビューしてください。
2. 文書化されていない単一障害点があるアーキテクチャは、決して承認しないでください — すべてのSPOFを明示的に特定し、文書化された緩和計画を用意する必要があります。
3. 必ず非機能要件に照らして評価してください — パフォーマンス、セキュリティ、スケーラビリティ、保守性、可観測性は必須です。NFRに準拠していない場合、機能的に正しくても不完全です。
4. アーキテクチャ上のトレードオフを暗黙のものとして扱わないでください — すべてのトレードオフを根拠とともに明示的に文書化する必要があります。隠れたトレードオフは、将来の予期せぬ問題や、担当者のいない技術的負債につながります。
5. 設計を承認する前に、必ず循環依存がないか確認してください — モジュール間の循環依存があると、テスト、リファクタリング、デプロイの順序が予測困難になり、解消も次第に難しくなります。

アンチパターン

アンチパターン	問題となる理由	適切な対応
NFRを評価しない	設計は機能テストに合格しても、規模拡大時や攻撃を受けた際に失敗する可能性があります	パフォーマンス、セキュリティ、スケーラビリティ、可観測性を必ず評価する
正常系のみをレビューする	システムは正常系ではなく、エラー発生時に失敗します	障害モード、リトライの動作、サーキットブレーカーをレビューする
トレードオフを文書化せずに承認する	隠れたトレードオフは、将来の予期せぬ問題につながります	すべてのトレードオフを根拠とともに明示的に文書化する
単一障害点を文書化せずに残す	システムの脆弱性が見過ごされ、負荷がかかったときに表面化します	すべてのSPOFを洗い出し、それぞれに緩和計画を必須とする
アンチパターンのカタログを確認せずにSOLIDだけをチェックする	原則を遵守していても、アンチパターンがないとは限りません	原則と具体的なアンチパターン（God Class、Shotgun Surgeryなど）の両方を確認する
実装開始後にアーキテクチャをレビューする	大規模なやり直しなしに、構造上の問題を修正するには遅すぎます	コードを書く前に、設計フェーズでレビューする

ルール

• 常に、実行可能な推奨事項を含む建設的なフィードバックを提供する
• 問題を影響度と修正に必要な労力に基づいて優先順位付けする
• 既存の制約とトレードオフを考慮する

関連ワークフロー

このスキルには、複雑なマルチエージェントのシナリオに対応するワークフローがあります。

• ワークフロー: .claude/workflows/architecture-review-skill-workflow.md
• ワークフローを使用する場合: 複数のエージェント（開発者、アーキテクト、セキュリティアーキテクト、コードレビュアー）の連携が必要な包括的な監査や複数フェーズの分析
• スキルを直接使用する場合: 簡易レビューまたは単一エージェントでの実行

メモリプロトコル（必須）

開始前:

cat .claude/context/memory/learnings.md

完了後:

• 新しいパターン → .claude/context/memory/learnings.md
• 発見した問題 → .claude/context/memory/issues.md
• 下した決定 → .claude/context/memory/decisions.md

中断を想定してください。コンテキストがリセットされることがあります。メモリに記録されていなければ、実行されていないものとして扱われます。