Project Architecture Integration

概要

プロジェクト固有のアーキテクチャ設計原則に基づいてエージェント設計を支援するスキル。Clean Architectureの依存関係ルールとHybrid Architecture（shared/features）パターンを統合し、プロジェクト構造に準拠したファイル生成、データベース設計、API連携を実現する。

ワークフロー

Phase 1: アーキテクチャ分析

目的: プロジェクト構造とアーキテクチャ要件を分析し、適用すべきパターンを特定

アクション:

1. エージェントの役割と責務を分析し、ドメイン依存性を判定
2. 生成対象ファイルの種類を特定（UI/ビジネスロジック/データアクセス層）
3. 既存プロジェクト構造を確認し、shared/とfeatures/の現状を把握
4. 依存関係ルールに基づいて配置先を決定

Task: agents/architecture-analysis.md を参照

Phase 2: 準拠性検証

目的: 生成されたファイルやエージェント設計がアーキテクチャ原則に準拠しているか検証

アクション:

1. ファイル配置の妥当性を検証
2. 依存方向の正当性を確認（shared/ → features/ 禁止、features/ → features/ 禁止）
3. scripts/check-architecture-compliance.mjs で自動検証
4. 違反項目をリストアップし、修正提案を作成

Task: agents/compliance-check.md を参照

Phase 3: 統合と記録

目的: アーキテクチャ原則をエージェント設計に統合し、実行記録を保存

アクション:

1. 検証済みアーキテクチャ設計をエージェント仕様に統合
2. アーキテクチャドキュメントを更新
3. scripts/log_usage.mjs で使用記録を保存

Task: agents/integration.md を参照

Task仕様ナビ

詳細仕様: 各Taskの詳細は agents/ ディレクトリの対応ファイルを参照

ベストプラクティス

すべきこと

• エージェントがプロジェクト構造に準拠したファイルを生成する時に適用
• データベース操作、API連携、テスト実行、デプロイ関連エージェント設計時に使用
• shared/ と features/ の配置判断に迷った時は必ず Task を起動
• 依存関係ルールの違反チェックを必ず実行
• ドメイン非依存のコード（汎用UI、ユーティリティ）は shared/ に配置
• ビジネスロジックは features/ に配置し、Bounded Contextで分離

避けるべきこと

• shared/ から features/ への依存（循環依存の原因）
• features/ 間の直接依存（shared/ を経由すること）
• ドメインロジックを shared/ に配置しない
• アーキテクチャ検証をスキップしない
• 曖昧な命名（utils/、helpers/など）を避ける

リソース参照

references/（詳細知識）

scripts/（決定論的処理）

assets/（テンプレート）

クイックスタート

# 1. 基礎知識を理解
cat references/basics.md
cat references/hybrid-architecture-guide.md

# 2. アーキテクチャ分析 Task を起動（詳細は agents/architecture-analysis.md）
# Task内で配置先と依存関係を決定

# 3. 準拠性チェックを実行
node scripts/check-architecture-compliance.mjs --path <target-files>

# 4. 使用記録を保存
node scripts/log_usage.mjs --result success --phase integration

学習パス

# 初心者向け
cat references/basics.md              # 基本概念
cat references/hybrid-architecture-guide.md  # 構造理解

# 中級者向け
cat references/patterns.md            # 実装パターン
node scripts/check-architecture-compliance.mjs --help  # 検証ツール

# 上級者向け
cat references/Level3_advanced.md     # 複雑なパターン適用

# 専門家向け
cat references/Level4_expert.md       # カスタムパターン設計

依存関係ルールまとめ

✅ 許可される依存

• features → shared: ビジネスロジックが汎用コンポーネントを使用
• features → features（同一フィーチャー内）: フィーチャー内の内部依存
• pages → features: ページが機能を使用
• pages → shared: ページが汎用コンポーネントを使用

❌ 禁止される依存

• shared → features: 循環依存を引き起こす
• features → features（異なるフィーチャー間）: 境界を破壊する

解決策: 共通ロジックをshared/に移動し、依存方向を一方向に保つ

変更履歴