Architecture MCP

🚀 アーキテクチャブループリント

AIを搭載したシステムで、GitHubリポジトリを分析し、そのアーキテクチャを学習し、MCPを介したAIコーディングエージェントによってそれを強制実行します。

🚀 クイックスタート

git clone https://github.com/your-org/architecture-blueprints.git
cd architecture-blueprints
./run

以上です。1つのコマンドです。./run がすべてを処理します。

1. 不足している場合、Docker、Python、Node.jsをインストールします。
2. Dockerを介してPostgreSQL (pgvector付き) + Redisを起動します。
3. backend/.env.local と frontend/.env.local を適切なデフォルト値で作成します。
4. Anthropic APIキーの入力を求めます (スキップも可能で、アプリは起動しますが警告が表示されます)。
5. Python仮想環境を作成し、バックエンドの依存関係をインストールします。
6. フロントエンドの依存関係をインストールします。
7. データベースのマイグレーションを実行し、プロンプトをシードします。
8. バックエンド (http://localhost:8000)、フロントエンド (http://localhost:4000)、およびARQワーカーを起動します。

以降の実行では、./run は変更を自動検出し、新しい依存関係、古いプロンプト、スキーマの変更などを起動前に処理します。手動で再インストールや再シードする必要はありません。

必要なもの

Anthropic APIキー です。初回実行時にスクリプトが入力を求めます。スキップして後で backend/.env.local に追加することもできます。

回復方法

./run --reset    # 完全な再セットアップを強制実行します (環境ファイルを再作成、依存関係を再インストール、データベースを再シード)

問題が発生した場合や破壊的な変更をプルした後に --reset を使用します。

データベースオプション

旧スクリプト

setup.sh と start-dev.sh はまだ存在しますが、単に ./run にリダイレクトします。直接 ./run を使用してください。

✨ 主な機能

Claude Codeはコードを読み取ります。アーキテクチャブループリントはアーキテクチャを理解します。

AIエージェントは動作するコードを書きますが、アーキテクチャ的に盲目です。各セッションで数ファイルを読み、推測します。50回のAI支援PRの後、何をどこに配置し、どのパターンを使用するかについて50通りの解釈ができます。

アーキテクチャブループリントはこの問題を解決します。

• 深い分析 - 7 - 9回のAIフェーズでコードベース全体をスキャンします。レイヤー、命名、通信パターン、実装パターンなどです。数秒でなく数分間の構造化された分析を行います。
• フォルダごとのコンテキスト - 重要なフォルダごとに、アーキテクチャガイダンス、コーディングパターン、重要なファイルガイド、一般的なタスクが記載された CLAUDE.md が作成されます。AIエージェントはどのフォルダに入ってもすぐにルールを理解します。
• リアルタイムの強制実行 - MCPツールは、エージェントが行動する前に呼び出されます。where_to_put、check_naming、how_to_implement は提案ではなく具体的な回答を返します。
• 唯一の真実の源 - CLAUDE.md、Cursorルール、AGENTS.md、およびMCPツールはすべて同じブループリントから派生しています。ツールを切り替えたり、誰かをオンボードしたりしても、同じルールが適用されます。
• 増分再分析 - いくつかのフォルダを変更しましたか？増分モードでは、変更されていないフォルダのキャッシュされたAIエンリッチメントを再利用し、再分析時間を大幅に削減します。
• 機能するものを再利用 - 良好なアーキテクチャのプロジェクトを分析しましたか？そのブループリントを新しいプロジェクトの参照アーキテクチャとして適用します。最良のコードベースが再利用可能なテンプレートになり、すべてのAIエージェントが従います。実績のあるパターンが再発明されることはありません。

🔧 技術詳細

  GitHub Repo
       |
       v
  1. Clone & Extract    -- ファイルツリー、依存関係、設定、コードサンプルを抽出
       |
       v
  2. RAG Index           -- コードをチャンク化し、sentence-transformersで埋め込み、pgvectorに保存
       |                     ファイルレベルの検索では完全なファイルが返されます (断片ではなく)
       |                     フェーズ固有のチャンクタイプの優先順位により、関連性が向上します
       v
  3. Phased AI Analysis  -- 7 - 9回のClaude API呼び出し、それぞれが前の呼び出しを基に構築
       |                     (観察 -> スマートなファイル読み取り -> 発見 ->
       |                      レイヤー -> パターン -> 通信 -> テクノロジー ->
       |                      [フロントエンド] -> 実装分析 -> 合成)
       |                     ファイルレジストリがすべてのフェーズのプロンプトに注入されます
       |                     リポジトリのサイズに基づいた動的なファイル読み取り予算
       v
  4. StructuredBlueprint -- 単一のJSON形式の真実の源 (Pydanticモデル)
       |
       v
  5. Intent Layer        -- フォルダごとのCLAUDE.md生成
       |                     フォルダ階層に対する決定論的なブループリントマッピング
       |                     オプションのAIエンリッチメント (パターン、重要なファイルガイド、
       |                     一般的なタスク、アンチパターン、コード例)
       |                     CODEBASE_MAP.mdによる横断的なナビゲーション
       |                     増分モードでは変更されていないフォルダをスキップ
       |
       |---> CLAUDE.md (root)    -- プロジェクトルートのAIエージェント指示
       |---> src/api/CLAUDE.md   -- フォルダごとのコンテキスト (すべての重要なフォルダ)
       |---> CODEBASE_MAP.md     -- 迅速な参照用のフラットなアーキテクチャ概要
       |---> .claude/rules/      -- Claude Codeルールファイル
       |---> .cursor/rules/      -- Cursor IDE統合
       |---> AGENTS.md           -- マルチエージェントシステムガイダンス
       |---> MCP Server          -- リアルタイムのwhere_to_put、check_naming
       \---> Delivery to GitHub  -- PRまたは直接コミットによる出力のプッシュ (非破壊的マージ)

IDE内のAIエージェントはMCPサーバーに接続します。ファイルを作成する前に where_to_put を呼び出し、クラスを命名する前に check_naming を呼び出します。チェックに失敗した場合、エージェントは続行する前に違反を修正します。

💻 使用例

基本的な使用法

git clone https://github.com/your-org/architecture-blueprints.git
cd architecture-blueprints
./run

高度な使用法

./run --reset    # 完全な再セットアップを強制実行します (環境ファイルを再作成、依存関係を再インストール、データベースを再シード)

📚 ドキュメント

GitHubトークン

リポジトリを分析するためにはGitHubパーソナルアクセストークンが必要です (アプリ自体を実行するためには必要ありません)。github.com/settings/tokens -> 新しいトークン (クラシック) を生成 -> repo + read:user スコープを選択します。

UIで入力するか、backend/.env.local で GITHUB_TOKEN を設定することができます。

初回：分析 + 同期

./run でアプリを起動した後、2つのことを行う必要があります。リポジトリを 分析 し、出力をリポジトリに 同期 することです。これはリポジトリごとに1回限りのセットアップで、その後はAIエージェントが完全なアーキテクチャ認識を持ちます。

1. リポジトリを分析する

1. http://localhost:4000 を開きます。
2. GitHubトークンで認証します。
3. リポジトリのURLを入力し、分析を開始します。
4. 段階的な分析が完了するのを待ちます (通常1 - 3分)。
5. 生成されたブループリント、フォルダごとのCLAUDE.mdファイル、および分析データを確認します。

2. 出力をリポジトリに同期する

これは重要なステップです。分析だけでは、出力がリポジトリに反映されない限り、AIエージェントには役に立ちません。

1. ブループリントビューから、 Delivery パネルを開きます。
2. プッシュする出力を選択します (CLAUDE.md、フォルダごとのコンテキスト、AGENTS.md、Cursorルール、MCP設定、CODEBASE_MAP.md、Claudeフック)。
3. 戦略を選択します。PR (ブランチ + プルリクエストを作成) または commit (デフォルトブランチに直接)。
4. デリバリーパイプラインは非破壊的にマージされます。既存のコンテンツは保持されます。

3. コーディングエージェントから使用する

以上です。3番目のステップはありません。出力がリポジトリに反映されると、コーディングエージェントは自動的にそれらを取得します。

• Claude Code - ネイティブで動作します。各セッションで自動的に CLAUDE.md と .claude/rules/ を読み取ります。設定は必要ありません。
• その他のエージェント (Cursor、Windsurfなど) - MCPを介して接続します。IDE設定にサーバーを追加すると、エージェントは where_to_put、check_naming、how_to_implement および完全なブループリントにアクセスできます。

これでエージェントはアーキテクチャを認識します。作成するすべてのファイルは適切な場所に配置され、命名規則に従い、既存のパターンを再利用します。各セッションでコードベースを説明する必要はありません。

変更後の再分析

すでにブループリントがあるリポジトリを再分析する場合、UIには2つのオプションが提供されます。

• 増分 (高速) - 変更されていないフォルダのキャッシュされたAIエンリッチメントを再利用します。
• 完全 - パイプライン全体を最初から再実行します。

再分析後、更新された出力をプッシュするために再度同期します。

MCPサーバーをIDEに接続する

IDE設定 (.mcp.json または .cursor/mcp.json) にMCPサーバーを追加します。

{
  "mcpServers": {
    "architecture-blueprints": {
      "url": "http://localhost:8000/mcp/sse"
    }
  }
}

MCPサーバーは以下のツールを公開しています。

自動検証 (Claude Code)

claude_hooks をデリバリー出力に含めると、Claude Codeには自動的に実行される2つのフックが追加されます。

• セッション開始時 - ローカルのCLAUDE.mdファイルがブループリントと比較して古いかどうかを確認し、警告を表示します。
• 各応答後 - 変更されたファイルを収集し、AIを介してアーキテクチャルールに照らして検証し、古いCLAUDE.mdファイルを即座に再生成します。

これにより、コーディング中にアーキテクチャドキュメントが最新の状態に保たれます。ブループリント自体はフックによって再生成されることはありません。既存のブループリントからCLAUDE.mdファイルのみが再レンダリングされます。アーキテクチャが根本的に変更された場合は、UIから再分析してください。

テストの実行

cd backend
PYTHONPATH=src python -m pytest tests/unit/ -v

詳細な技術ドキュメント、アーキテクチャの内部構造、およびAPIリファレンスについては、docs/ARCHITECTURE.md を参照してください。