senior-architect

シニアアーキテクト

十分な情報に基づく技術的な意思決定に役立つ、アーキテクチャの設計・分析ツールです。

目次

• クイックスタート
• ツールの概要
  • アーキテクチャ図ジェネレーター
  • 依存関係アナライザー
  • プロジェクトアーキテクト
• 意思決定のワークフロー
  • データベースの選択
  • アーキテクチャパターンの選択
  • モノリスとマイクロサービスの比較
• リファレンスドキュメント
• 技術スタックの対応状況
• よく使うコマンド

---

クイックスタート

# Generate architecture diagram from project
python scripts/architecture_diagram_generator.py ./my-project --format mermaid

# Analyze dependencies for issues
python scripts/dependency_analyzer.py ./my-project --output json

# Get architecture assessment
python scripts/project_architect.py ./my-project --verbose

---

ツールの概要

1. アーキテクチャ図ジェネレーター

プロジェクト構成から、複数の形式でアーキテクチャ図を生成します。

解決する課題：「ドキュメント作成やチームでの議論のために、システムアーキテクチャを可視化したい」

**入力：**プロジェクトディレクトリのパス **出力：**図のコード（Mermaid、PlantUML、または ASCII）

対応する図の種類：

• component - モジュールとその関係を表示します
• layer - アーキテクチャのレイヤー（プレゼンテーション、ビジネス、データ）を表示します
• deployment - デプロイ構成を表示します

使用方法：

# Mermaid format (default)
python scripts/architecture_diagram_generator.py ./project --format mermaid --type component

# PlantUML format
python scripts/architecture_diagram_generator.py ./project --format plantuml --type layer

# ASCII format (terminal-friendly)
python scripts/architecture_diagram_generator.py ./project --format ascii

# Save to file
python scripts/architecture_diagram_generator.py ./project -o architecture.md

出力例（Mermaid）：

graph TD
    A[API Gateway] --> B[Auth Service]
    A --> C[User Service]
    B --> D[(PostgreSQL)]
    C --> D

---

2. 依存関係アナライザー

プロジェクトの依存関係を分析し、結合度、循環依存、古いパッケージを確認します。

解決する課題：「依存関係ツリーを把握し、潜在的な問題を特定したい」

**入力：**プロジェクトディレクトリのパス **出力：**分析レポート（JSON または人が読みやすい形式）

分析項目：

• 依存関係ツリー（直接依存および推移的依存）
• モジュール間の循環依存
• 結合度スコア（0～100）
• 古いパッケージ

対応するパッケージマネージャー：

• npm/yarn（package.json）
• Python（requirements.txt、pyproject.toml）
• Go（go.mod）
• Rust（Cargo.toml）

使用方法：

# Human-readable report
python scripts/dependency_analyzer.py ./project

# JSON output for CI/CD integration
python scripts/dependency_analyzer.py ./project --output json

# Check only for circular dependencies
python scripts/dependency_analyzer.py ./project --check circular

# Verbose mode with recommendations
python scripts/dependency_analyzer.py ./project --verbose

出力例：

Dependency Analysis Report
==========================
Total dependencies: 47 (32 direct, 15 transitive)
Coupling score: 72/100 (moderate)

Issues found:
- CIRCULAR: auth → user → permissions → auth
- OUTDATED: lodash 4.17.15 → 4.17.21 (security)

Recommendations:
1. Extract shared interface to break circular dependency
2. Update lodash to fix CVE-2020-8203

---

3. プロジェクトアーキテクト

プロジェクトの構成を分析し、アーキテクチャパターン、コードの不吉な臭い、改善の機会を検出します。

解決する課題：「現在のアーキテクチャを把握し、改善すべき箇所を特定したい」

**入力：**プロジェクトディレクトリのパス **出力：**アーキテクチャ評価レポート

検出項目：

• アーキテクチャパターン（MVC、レイヤード、ヘキサゴナル、マイクロサービスの兆候）
• コードの構成上の問題（巨大クラス、関心事の混在）
• レイヤー違反
• 不足しているアーキテクチャコンポーネント

使用方法：

# Full assessment
python scripts/project_architect.py ./project

# Verbose with detailed recommendations
python scripts/project_architect.py ./project --verbose

# JSON output
python scripts/project_architect.py ./project --output json

# Check specific aspect
python scripts/project_architect.py ./project --check layers

出力例：

Architecture Assessment
=======================
Detected pattern: Layered Architecture (confidence: 85%)

Structure analysis:
  ✓ controllers/  - Presentation layer detected
  ✓ services/     - Business logic layer detected
  ✓ repositories/ - Data access layer detected
  ⚠ models/       - Mixed domain and DTOs

Issues:
- LARGE FILE: UserService.ts (1,847 lines) - consider splitting
- MIXED CONCERNS: PaymentController contains business logic

Recommendations:
1. Split UserService into focused services
2. Move business logic from controllers to services
3. Separate domain models from DTOs

---

意思決定のワークフロー

データベース選択のワークフロー

新しいプロジェクトでデータベースを選ぶときや、既存データを移行するときに使用します。

ステップ 1：データの特性を確認する

特性	SQL を選ぶ目安	NoSQL を選ぶ目安
構造化され、リレーションがある	✓
ACID トランザクションが必要	✓
柔軟に変更できるスキーマ		✓
ドキュメント指向のデータ		✓
時系列データ		✓（特化型）

ステップ 2：スケール要件を評価する

• レコード数が 100 万未満、単一リージョン → PostgreSQL または MySQL
• レコード数が 100 万～1 億、読み取り中心 → 読み取りレプリカを備えた PostgreSQL
• レコード数が 1 億超、グローバル分散 → CockroachDB、Spanner、または DynamoDB
• 書き込みスループットが高い（>10K/sec）→ Cassandra または ScyllaDB

ステップ 3：一貫性要件を確認する

• 強い一貫性が必要 → SQL または CockroachDB
• 結果整合性を許容できる → DynamoDB、Cassandra、MongoDB

ステップ 4：決定を文書化する 次の内容を含む ADR（アーキテクチャ決定記録）を作成します。

• 背景と要件
• 検討した選択肢
• 決定内容と根拠
• 受け入れたトレードオフ

クイックリファレンス：

PostgreSQL → Default choice for most applications
MongoDB    → Document store, flexible schema
Redis      → Caching, sessions, real-time features
DynamoDB   → Serverless, auto-scaling, AWS-native
TimescaleDB → Time-series data with SQL interface

---

アーキテクチャパターン選定ワークフロー

新しいシステムを設計するとき、または既存のアーキテクチャをリファクタリングするときに使用します。

ステップ 1：チームとプロジェクトの規模を評価する

チームの規模	推奨される出発点
開発者 1～3 人	モジュラーモノリス
開発者 4～10 人	モジュラーモノリスまたはサービス指向
開発者 10 人以上	マイクロサービスを検討

ステップ 2：デプロイ要件を評価する

• 単一のデプロイ単位で問題ない → モノリス
• 独立したスケーリングが必要 → マイクロサービス
• 混在（スケーリング要件が異なるサービスがある） → ハイブリッド

ステップ 3：データ境界を考慮する

• データベースの共有が問題ない → モノリスまたはモジュラーモノリス
• 厳格なデータ分離が必要 → 個別の DB を使用するマイクロサービス
• イベント駆動型の通信が適している → イベントソーシング／CQRS

ステップ 4：要件にパターンを合わせる

要件	推奨パターン
MVP の迅速な開発	モジュラーモノリス
チームごとの独立したデプロイ	マイクロサービス
複雑なドメインロジック	ドメイン駆動設計
読み取り／書き込み比率の差が大きい	CQRS
監査証跡が必要	イベントソーシング
サードパーティとの統合	ヘキサゴナル／ポート＆アダプター

パターンの詳細な説明については、references/architecture_patterns.md を参照してください。

---

モノリスとマイクロサービスの選択

モノリスを選ぶ場合：

• チームが小規模（開発者 10 人未満）
• ドメイン境界が明確でない
• 迅速な反復が優先事項
• 運用の複雑さを最小限に抑える必要がある
• データベースの共有が問題ない

マイクロサービスを選ぶ場合：

• チームがサービスをエンドツーエンドで担当できる
• 独立したデプロイが不可欠
• コンポーネントごとに異なるスケーリング要件がある
• 技術の多様性が必要
• ドメイン境界が十分に把握されている

ハイブリッドアプローチ： モジュラーモノリスから始めます。以下の場合にのみサービスを切り出します。

1. モジュールで大きく異なるスケーリング要件がある
2. チームが独立したデプロイを必要としている
3. 技術的な制約により分離が必要である

---

参考ドキュメント

詳細情報を確認するには、以下のファイルを読み込んでください。

ファイル	内容	ユーザーから次の質問があった場合に読み込む
references/architecture_patterns.md	トレードオフ、コード例、利用場面を含む 9 つのアーキテクチャパターン	「どのパターン？」「マイクロサービスとモノリスの比較」「イベント駆動型」「CQRS」
references/system_design_workflows.md	システム設計タスクの 6 つのステップ別ワークフロー	「どう設計する？」「キャパシティプランニング」「API 設計」「移行」
references/tech_decision_guide.md	技術選択のための判断マトリックス	「どのデータベース？」「どのフレームワーク？」「どのクラウド？」「どのキャッシュ？」

---

技術スタックの対象範囲

言語： TypeScript、JavaScript、Python、Go、Swift、Kotlin、Rust フロントエンド： React、Next.js、Vue、Angular、React Native、Flutter バックエンド： Node.js、Express、FastAPI、Go、GraphQL、REST データベース： PostgreSQL、MySQL、MongoDB、Redis、DynamoDB、Cassandra インフラストラクチャ： Docker、Kubernetes、Terraform、AWS、GCP、Azure CI/CD： GitHub Actions、GitLab CI、CircleCI、Jenkins

---

よく使うコマンド

# Architecture visualization
python scripts/architecture_diagram_generator.py . --format mermaid
python scripts/architecture_diagram_generator.py . --format plantuml
python scripts/architecture_diagram_generator.py . --format ascii

# Dependency analysis
python scripts/dependency_analyzer.py . --verbose
python scripts/dependency_analyzer.py . --check circular
python scripts/dependency_analyzer.py . --output json

# Architecture assessment
python scripts/project_architect.py . --verbose
python scripts/project_architect.py . --check layers
python scripts/project_architect.py . --output json

---

ヘルプの利用

1. 使用方法を確認するには、任意のスクリプトを --help 付きで実行します
2. 詳細なパターンとワークフローについては、参考ドキュメントを確認します
3. 詳細な説明と推奨事項を表示するには、--verbose フラグを使用します