architecture

アーキテクチャスキル

バージョン： 3.0 ソース： アーキテクチャ原則＋プロジェクト構造プロファイル

プロジェクトの構造化方法について説明します。論理的な構造（モジュール設計、依存関係の流れ）と物理的な構造（フォルダーレイアウト、命名、種類別の規約）の両方を扱います。

課題

AI エージェントは、前回のセッションで何をどこに置いたかを覚えていません。明示的な構造がなければ、セッションごとに独自のフォルダーレイアウト、モジュール境界、依存関係のパターンが作られ、ファイルの散在、循環インポート、作成したセッションでしか理解できないアーキテクチャにつながります。これらの標準では、すべてのセッションが同じ場所に構築できるよう、構造を統一します。

利用方法

• ビルダー： ファイルやフォルダーを作成する前に ## Builder Checklist を読みます。対象に合ったプロジェクトタイプのプロファイルに従います。
• リファクタリング担当者： ## Enforced Rules を使って構造上の違反を見つけます。移行方法については説明セクションを読みます。
• 両方： 説明セクションが正式な標準です。チェックリストとルール表は、同じ内容を簡潔にまとめたものです。

---

範囲と境界

このスキルの対象： モジュール設計、依存関係の流れ、フォルダー構造、命名規約、プロジェクトタイプ固有のレイアウト。

このスキルの対象外： ファイル内のコード品質（code-quality を参照）、ドキュメントの標準（documentation を参照）、ビルド／デプロイの設定。

他のスキルとの関係：

• code-quality（ファイルレベルの規約）および documentation（ドキュメントの標準）と連携します
• clean-team の :audit コマンドで使用されます（フォーカス：structure）
• clean-team、implement-team、diagnose-team の各エージェントから参照されます

---

北極星

目標： 小さな変更は局所的にとどまります。

一般的な機能は、1～2 個のモジュールに変更を加えるだけで迅速にリリースでき、システム全体にわたる調整された編集を必要としないはずです。単純な変更のために複数のレイヤーにまたがる 5 個以上のファイルを編集している場合は、設計上の問題の兆候です。

---

基本原則

1. マジックより明示性を優先する

規約に過度に依存するフレームワークより、読みやすい接続を優先します。コードを読む人が制御フローをすぐに理解できるようにします。何が何に依存しているかを隠す @AutoInject() デコレーターは使わず、コンストラクターのパラメーターを明示します。

2. 境界を厳守する

モジュール間のやり取りは、コントラクト（API、props、イベント）を通じてのみ行います。他のモジュールの内部に踏み込んではいけません。インポートにはモジュールの公開 API を使い、内部ファイルからはインポートしません。

3. データの所有権を明確にする

各モジュールが独自のスキーマ／状態を所有します。他のモジュールは API または props を介してデータを読み取り、直接アクセスはしません。OrderModule がユーザーデータを必要とする場合は、users テーブルを直接クエリするのではなく、UserModule.getUserById() を呼び出します。

4. リファクタリングしやすさを重視する

コードの移動や名前の変更が難しい場合は、設計上の問題の兆候です。疎結合により、安全なリファクタリングが可能になります。

---

3 つのレイヤー

01-presentation/  →  02-logic/  →  03-data/

レイヤー	責務	例
プレゼンテーション	ユーザーが目にし、操作するもの	コンポーネント、ページ、スタイル
ロジック	どのように構築するか、ビジネスルール	サービス、ユースケース、バリデーション
データ	データの永続化方法、外部データソース	リポジトリ、モデル、アダプター

有効な依存関係の流れ

Presentation → Logic → Data ✅
Data → Logic ❌ (blocked)
Logic → Presentation ❌ (blocked)
Presentation → Data ❌ (blocked — no layer skipping)

---

モジュール境界

モジュールとは、明確な公開 API、隠蔽された実装、定義済みの依存関係を持つ、まとまりのある単位です。

モジュールのルール

単一のエントリーポイント： 各モジュールは、index ファイルを通じて API を公開します。外部からのインポートは必ずこのファイルを経由します。

循環依存の禁止： モジュール間に循環する依存関係を作ってはいけません。共通コードの切り出し、イベントの利用、インターフェースの導入によって循環を解消します。

データの所有権を明確にする： 各モジュールが自身のデータを排他的に所有します。モジュールをまたぐデータには API を介してアクセスし、データベースに直接クエリしてはいけません。

結合のガイドライン

結合の種類	OK？
型のインポート	常に可
パブリック API 経由の関数呼び出し	通常可
直接のインスタンス化	慎重に
変更可能な状態の共有	避ける

詳細はこちら： references/module-boundaries.md — モジュール構造、境界ルール、通信パターン、結合レベル、リファクタリングのガイダンス

---

フォルダー構造

適切に整理されたプロジェクトは、単に整頓されているだけではありません。「これはどこに置けばいいのか」「あれはどこにあるのか」と尋ねる必要のないプロジェクトです。構造そのものが答えを示します。フォルダー構成がプロジェクトについての考え方に沿っていれば、検索に頼らず直感的に移動できます。探しているものを、最初から期待どおりの場所で見つけられます。

AI が関わる場合は、さらに重要です。AI はセッション間で記憶を保持しないため、人間のチームメイトのように時間をかけてプロジェクトの構成を学ぶことができません。セッションごとに毎回ゼロから始まります。明確で予測しやすい構造にしておけば、AI が検索に費やす時間を減らし、有用な作業により多くの時間を使えます。説明的なフォルダー名、一貫した規則、論理的なグループ分けは、AI がやり取りのたびに追加の手間なく読み取れるコンテキストです。

目標：直感だけを頼りに、どのファイルも 2～3 回の移動で見つけられることです。検索が必要なら、構造に問題があります。

階層内で機能ごとに整理する

3 層アーキテクチャを使用する Web プロジェクトでは、各階層の中で機能ごとに整理します。単一の機能をグローバルな models/、services/、controllers/ ディレクトリーに分散させないでください。

Within 02-logic/:
Prefer:                          Avoid:
02-logic/                        02-logic/
  users/                           models/
    user.model.ts                    user.model.ts
    user.service.ts                  order.model.ts
  orders/                          services/
    ...                              user.service.ts
                                     order.service.ts

機能ごとにグループ化すると、各階層内で関連するコードをまとめておけます。階層は依存関係の流れ（プレゼンテーション → ロジック → データ）を定め、機能フォルダーは各階層内の凝集性を高めます。この 2 つは互いに補完するものであり、矛盾するものではありません。

Web 以外のプロジェクト（CLI ツール、ライブラリー、スクリプト）で 3 層アーキテクチャを使用しない場合は、プロジェクトのルートレベルで機能ごとにグループ化します。

あらゆるプロジェクトに共通する構造原則

以下は、プロジェクトの種類を問わず適用されます。

命名規則の一貫性 — カテゴリーごとに大文字・小文字の規則を 1 つ選び、すべてに適用します。すべてのコンポーネントは PascalCase、すべてのユーティリティーは camelCase、すべての設定ファイルは kebab-case にします。一貫性があれば見つけやすくなります。規則が分かれば、確認する前にファイル名を予測できます。

論理的なグループ分け — 関連するファイルをまとめます。1 つを変更するときは、ほかのファイルも変更する可能性が高いものです。原則として同じ場所に配置します。明確な利点がある場合にのみ分けます。グループ分けの判断には、「X に取り組むとき、ほかに何を開く必要があるか？」と考えてください。

適切な階層の深さ — ルートからファイルまでの階層は 4 つ以内にします。ネストの各階層には、それに値する理由が必要です。フォルダーにサブフォルダーが 1 つだけあり、その中にファイルが 1 つしかない場合は、階層をなくしてまとめます。深いネストは整理ではなく、宝探しです。

明確なエントリーポイント — 初めてプロジェクトを開いた人が、10 秒以内にどこから始めればよいか分かるようにします。ルートの README でプロジェクトの概要を説明します。メインのエントリーファイルには慣例的な名前（index、main、app）を付けます。最上位のフォルダーを見れば、プロジェクトの内容が分かるようにします。

ルートをすっきり保つ — プロジェクトのルートには、エントリーポイント、最上位の設定、プロジェクトの構造を定義するフォルダーなど、そこに置く必要のあるものだけを含めます。ルートに置く必要のある設定ファイル（.gitignore、package.json、tsconfig.json）は例外として認めますが、無関係なスクリプト、ユーティリティー、一時的なファイルは置きません。迷ったら、より深い階層に移動します。ルートは第一印象を決める場所です。

名前で内容が分かるようにする — フォルダー名には使い方ではなく、中身を示します。formatters/、validators/、parsers/ は明確です。utils/、helpers/、misc/ は何でも放り込む場所になりがちです。共通のテーマがないファイルが 10 個以上あるフォルダーは、各ファイルの実際の役割に基づいて分割します。

---

プロジェクトタイプ別プロファイル

プロジェクトの種類ごとのフォルダー構造、命名規則、注意すべき兆候をまとめています。各プロファイルは単独で参照できます。

検出の決定木

Does the project contain...

  ├─ package.json + .tsx/.jsx/.css/.html files?
  │  └─ YES → Load references/web.md
  │
  ├─ Assets/ + .cs scripts + .unity scene files?
  │  ├─ VRChat SDK present? (Packages/com.vrchat.*, VRCSDK3, UdonSharp)
  │  │  └─ YES → Load references/vrchat.md (overrides Unity)
  │  └─ No VRC SDK
  │     └─ Load references/unity.md
  │
  ├─ .blend files + texture images?
  │  └─ YES → Load references/blender.md
  │
  ├─ .tf files / cdk.json / template.yaml?
  │  └─ YES → Load references/data-iac.md
  │
  └─ None of the above?
     └─ Use Universal Structural Principles above

優先ルール： 複数のプロファイルに該当する場合は、最も具体的なものを使用してください。VRChat は Unity より優先されます。アプリケーションコードと IaC の両方を含むプロジェクトでは、アプリにはアプリケーションプロファイルを使用し、インフラ部分については data-iac を参照してください。

利用可能なプロファイル

プロファイル	参照ファイル	最適な用途
Web（React/Node）	references/web.md	SPA、フルスタックアプリ、Node API、React プロジェクト
Unity	references/unity.md	Unity ゲーム、ツール、VRChat 以外の Unity プロジェクト
VRChat	references/vrchat.md	VRChat のワールドやアバター（Unity を拡張）
Blender	references/blender.md	3D モデリング、テクスチャリング、レンダリングのプロジェクト
データ/IaC（AWS）	references/data-iac.md	Terraform、CDK、CloudFormation のインフラ

使用方法

1. 上記の決定木を使ってプロジェクトの種類を検出します
2. references/ から一致するプロファイルを読み込みます
3. 実際の構造を想定されるレイアウトと比較します
4. assets/structure-evaluation-checklist.md のチェックリストを使って評価します
5. 相違点を指摘事項として報告し、重大な警告を最優先します

新しいプロファイルの追加

1. 次の標準テンプレートに従って references/<type>.md を作成します。
   • この構造が重要な理由 — 問題、メリット、無視した場合のコスト
   • 検出 — このプロジェクトの種類を識別するファイルパターン
   • 想定される構造 — 原則に関するコメント付きのディレクトリツリー
   • 命名規則 — 種類／規則／例の表
   • 重大な警告 — 3 列の表：警告 | 根本原因 | 修正方法
   • 再検討すべき場合 — 症状 → 問題 → 対応の表
2. 上記の「利用可能なプロファイル」表に行を追加します
3. 検出の決定木に分岐を追加します
4. assets/structure-evaluation-checklist.md に種類固有のセクションを追加します

---

パターンの選択

パターン	使用する場面
純粋関数	ステートレスな変換
関数を含むモジュール	関連する関数のグループ化
クラス	状態または DI が必要な場合
ファクトリー	複雑なオブジェクトの生成
リポジトリー	データアクセスの抽象化

シンプルさを優先します： 関数 → モジュール → クラス → パターン

全カタログ： references/design-patterns.md — ファクトリー、ビルダー、アダプター、ファサード、デコレーター、ストラテジー、オブザーバー、コマンド、リポジトリー、Result 型

---

テスト戦略

種類	目的	対象範囲	量
単体	高速で決定論的、ドメインロジックを重視	単一の関数／コンポーネント	多い
統合	DB、API、外部サービス	モジュール境界	中程度
E2E	重要なユーザーパスのみ	フルスタック	最小限

単体テストを多く、統合テストを中程度、E2E テストを最小限にします。E2E テストが増えすぎると、壊れやすく実行時間の長いテストスイートにつながります。API の境界にはコントラクトテストを推奨します。

---

アンチパターン

コードアーキテクチャ

アンチパターン	症状	修正方法
神オブジェクト	500 行超、公開エクスポートが 10 個超	凝集性の高いサブモジュールに分割します
貧血ドメインモデル	ゲッター／セッターのみで、処理をサービスがすべて担う	エンティティに振る舞いを移します
ショットガン手術	フィールドの追加に 5 個以上のファイル変更が必要	カプセル化を改善します

プロジェクト構成

アンチパターン	症状	対処法
散らかったルート	プロジェクトのルートにファイルが15個以上あり、設定ファイルの隣に無関係なスクリプトが置かれている	エントリーポイントや必須の設定ファイル以外は、すべてフォルダーに移動します
何でも入ったフォルダー	1つのフォルダーにファイルが40個以上ある	ドメイン、機能、または役割ごとにグループ化します
存在意義のないフォルダー	ファイルがなく、明確な目的もない空のフォルダーがある	意図的なパターンの一部でない限り、削除します
命名規則の混在	UserProfile.tsx、order-utils.ts、payment_service.py のように、大文字・小文字の使い方が混在している	ファイルの種類ごとに規則を1つ選び、徹底します
孤立ファイル	どこからもインポート、参照されていないファイルがある	未使用であることを確認してから、削除します
深すぎる階層	1つのファイルにたどり着くまでにフォルダーが5階層以上ある	階層を浅くします。階層は実際の境界を反映するようにします
鏡像ツリー	src/ と tests/ の構成が同一になっている	単体テストはソースコードと同じ場所に置き、統合テスト／E2E テストのみ別のツリーにします
設定ファイルの乱立	ルートに設定ファイルが10個以上ある	可能な範囲で統合し、config/ に移動します

---

抽出するタイミング

まずはモジュラーモノリス（デプロイ可能な単一のアプリケーションで、内部の境界が明確な構成）から始めます。

次の理由がある場合に限り、別のサービスとして抽出します：

理由	例
スケール	一部のコンポーネントを独立してスケーリングする必要がある
チーム	別々のチームが独立したデプロイサイクルを必要としている
テクノロジー	コンポーネントが異なるランタイム／言語を必要としている

「構成をきれいにする」ためだけに抽出しないでください。メリットがないまま、運用の複雑さが増します。

---

オブザーバビリティの基本

構造化ログ： 文字列の連結ではなく、JSON を使います。メッセージ（'User ' + userId + ' logged in'）ではなく、コンテキスト（{ userId, timestamp }）を含めます。

相関 ID： 非同期処理をまたいでリクエストを追跡します。

エラーバウンダリー： エラーを捕捉して報告し、黙って握りつぶさないでください。

---

意思決定記録

重要なアーキテクチャ上の選択について、コンテキスト（問題）、決定（選択した内容）、代替案（検討した他の選択肢）、結果（トレードオフ）を記録します。

場所： Documentation/decisions/

テンプレート： assets/decision-record-template.md

---

スケーリングの原則

プロジェクトの規模	注力する項目
小規模	ノーススター、危険信号
成長中	テスト戦略、オブザーバビリティを追加
チーム	意思決定記録、モジュールのオーナーシップを追加

---

危険信号

次の兆候が見られたら、立ち止まって再検討してください：

問題の兆候	問題	対処法
shared/common/utils が何でも入れる場所になっている	オーナーシップが不明確で、際限なく肥大化する	所有するモジュールに移すか、目的を絞ったパッケージを作成します
モジュール間の直接インポート	密結合	API、イベント、または props を使います
モジュール間のデータベースへの直接アクセス	隠れた依存関係	読み取り API またはサービスを構築します
間違ったモジュールにある「ちょっとしたヘルパー」	境界違反	正しいオーナーのもとへ移します
制御フローを隠すフレームワークのマジック	デバッグもリファクタリングも難しい	明示的にします
1つの機能が無関係なファイルを5つ以上変更する	分離が不十分	境界をリファクタリングします

---

ビルダー用チェックリスト

モジュールやフォルダー構成を設計する前に、計画がこれらの制約に沿っていることを確認します。ビルダーはコードを書く前にこのセクションを読み、リファクタリング担当者は「適用ルール」表と説明全文を参照します。

構成

• 3層アーキテクチャ：01-presentation/ → 02-logic/ → 03-data/
• 逆方向の依存関係がない（data → logic、logic → presentation）
• 層を飛び越えない（presentation → data）
• ルートからファイルまでのフォルダー階層は最大4階層
• 整理されたルート — 最上位に置くのはエントリーポイントと必須の設定ファイルのみ

モジュール

• 各モジュールにエントリーポイント（インデックスファイル）が1つある
• モジュール間に循環依存がない
• 各モジュールが自分のデータを所有する — モジュール間でデータベースに直接アクセスしない
• 各層内で機能ごとに整理する（グローバルな models/、services/ フォルダーを作らない）

設計

• シンプルさを基本とします：関数 → モジュール → クラス → パターン
• 小さな変更は局所的に収めます（機能が触れるモジュールは1～2個とし、5個以上にしません）
• shared/common/utils のような、何でも詰め込む場所は作りません
• フォルダー名は中身を表すものにします（helpers/ や misc/ は使いません）

---

適用されるルール

これらのルールは check.js（clean-team）によって決定論的にチェックされます。これらの標準を更新する場合は、対応する check.js のルールも合わせて更新してください。その逆も同様です。

ルール ID	重大度	チェック内容
tier-imports	エラー	01→02→03の依存方向に違反するインポート
tier-structure	エラー	Web プロジェクトにおける3層フォルダー構造の欠落または不備

---

参考資料

• references/module-boundaries.md — モジュール構造、境界ルール、通信パターン
• references/design-patterns.md — Factory、Repository、Adapter、Strategy、Observer など
• references/migration-patterns.md — Strangler Fig、Branch by Abstraction、Parallel Implementations
• references/web.md — Web（React/Node）プロジェクトの構造プロファイル
• references/unity.md — Unity プロジェクトの構造プロファイル
• references/vrchat.md — VRChat プロジェクトの構造プロファイル（Unity を拡張）
• references/blender.md — Blender プロジェクトの構造プロファイル
• references/data-iac.md — データ／IaC（AWS）プロジェクトの構造プロファイル

アセット

• assets/architecture-checklist.md — アーキテクチャレビューの完全なチェックリスト
• assets/structure-evaluation-checklist.md — プロジェクト構造の評価チェックリスト（共通＋タイプ別）
• assets/decision-record-template.md — ADR テンプレート

スクリプト

• scripts/analyze_dependencies.py — 循環依存関係をマッピングし、レイヤー違反を検出します