analyzing-architecture

name: analyzing-architecture description: バックエンド・フロントエンド・インフラのアーキテクチャパターン選択と設計ドキュメント作成を支援。「アーキテクチャを設計したい」「システム構成を検討したい」「レイヤード/ヘキサゴナル/クリーンどれが適切か」「CQRS を導入すべきか」「フロントエンドのアーキテクチャを決めたい」といった場面で発動する。アーキテクチャを早期に設計することで、開発フェーズでの技術的負債の蓄積を防ぐ。

アーキテクチャ設計

業務領域とデータ構造の複雑さに基づき、バックエンド・フロントエンド・インフラの各アーキテクチャパターンを選択し設計ドキュメントを作成する。

アーキテクチャは後から変えるコストが最も高い設計判断。要件定義の段階で適切なパターンを選定することで、開発全体の方向性を確定し、手戻りを最小化する。

参照ドキュメントとテンプレート

種類	パス	備考
ガイド	@docs/reference/アーキテクチャ設計ガイド.md	アーキテクチャ設計の進め方詳細
テンプレート	@docs/template/設計.md	編集禁止。コピーして使用する
入力	@docs/requirements/requirements_definition.md	要件定義
入力	@docs/requirements/business_usecase.md	ビジネスユースケース
入力	@docs/requirements/system_usecase.md	システムユースケース
入力	@docs/requirements/user_story.md	ユーザーストーリー
成果物	`docs/design/architecture_backend.md`	バックエンドアーキテクチャ
成果物	`docs/design/architecture_frontend.md`	フロントエンドアーキテクチャ
成果物	`docs/design/architecture_infrastructure.md`	インフラストラクチャアーキテクチャ

バックエンドアーキテクチャ設計

業務ロジックの複雑さに応じてパターンを選択する。単純な CRUD ならレイヤードで十分だが、ドメインが複雑な場合はヘキサゴナルやクリーンアーキテクチャを採用せよ。

アーキテクチャパターンの選択: レイヤード、ヘキサゴナル、クリーン等から要件に最適なものを選定する
CQRS/イベントソーシングの適用判断: 読み書きの特性が大きく異なる場合に検討する。過剰適用は複雑さを増すだけなので慎重に判断せよ
API 設計方針: REST/GraphQL/gRPC の選択基準を明確にする

フロントエンドアーキテクチャ設計

ユーザー体験とチームのスキルセットを考慮して設計する。フレームワーク選定はプロジェクト全体に影響するため、ADR で判断根拠を残せ。

フレームワーク選定: プロジェクト要件に合ったフレームワークを選択する
状態管理パターン: アプリケーションの状態の複雑さに応じて適切なパターンを選定する
コンポーネント設計方針: 再利用性と保守性を両立する設計指針を定める

インフラストラクチャアーキテクチャ設計

非機能要件（可用性・スケーラビリティ）を実現するインフラ構成を設計する。運用コストとの兼ね合いも考慮せよ。

クラウド/オンプレミス選定: コスト・セキュリティ・運用負荷を総合的に判断する
コンテナ化戦略: コンテナ化の適用範囲とオーケストレーション方式を決定する
CI/CD パイプライン設計: ビルド・テスト・デプロイの自動化方針を定める

作成の進め方

入力ドキュメント（要件定義、ユースケース、ユーザーストーリー）を確認する。なければ基本情報をヒアリングする
@docs/reference/アーキテクチャ設計ガイド.md を読み込む
バックエンド→フロントエンド→インフラの順に設計する。各アーキテクチャの選定理由を明記せよ
重要な設計判断は ADR（Architecture Decision Record）で記録する

途中から再開する場合

既存の docs/design/architecture_*.md がある場合は、まずその内容を確認する。不足している領域や更新が必要な部分のみを修正する。

Example:

ユーザー: 「バックエンドはクリーンアーキテクチャで決めた。フロントエンドを設計したい」
回答: 既存の architecture_backend.md を確認し、
      バックエンドの API 設計方針を踏まえてフロントエンドアーキテクチャ設計に進む。
      フレームワーク選定→状態管理→コンポーネント設計の順で作成する。

注意事項

要件定義とユースケースが完了していることが前提。未完了でもプロジェクト情報から進めて構わない
アーキテクチャ決定は必ず ADR で記録する。「なぜその選択をしたか」が後で最も重要になる
業務の複雑さとチームのスキルセットを考慮して選択する。技術的に「正しい」選択よりチームが運用できる選択を優先せよ
タスク項目（リスト）の前には空行を入れる（Markdown Lint 準拠）