03. アーキテクチャと仕組み

Claude Codeの全体アーキテクチャ

┌─────────────────────────────────────────────────┐
│  Claude Code CLI（非公開ソース）                 　│
│  @anthropic-ai/claude-code                      │
│                                                 │
│  機能：                                          │
│  - ユーザープロンプトの処理                         │
│  - ツール実行エンジン（Bash, Read, Edit等）         │
│  - ファイル操作、Git連携                           │
│  - Claude API呼び出し                            │
│  - プラグインローダー                              │
└─────────────────┬───────────────────────────────┘
                  │
                  │ プラグインをロード
                  │
        ┌─────────┴─────────┐
        │                   │
        ▼                   ▼
┌───────────────┐   ┌──────────────┐
│  コマンド      │   │  エージェント   │
│  (.md)        │   │  (.md)       │
├───────────────┤   ├──────────────┤
│ - スラッシュ    │   │ - サブタスク   │
│   コマンド定義  │   │   実行        │
│ - 動的コマンド  │   │ - 専門化した   │
│   実行         │   │   プロンプト   │
│ - ツール制限    │   │ - ツール権限   │
│               │   │   制御        │
└───────────────┘   └──────────────┘
        │                   │
        └─────────┬─────────┘
                  │
                  ▼
          ┌──────────────┐
          │  フック       │
          │  (.json+.py) │
          ├──────────────┤
          │ - イベント監視 │
          │ - スクリプト   │
          │   実行        │
          │ - stdin/stdout│
          │   処理        │
          └──────────────┘

プラグインシステムの動作原理

1. プラグインのロード

起動時:
  claude コマンド実行
     ↓
  カレントディレクトリをスキャン
     ↓
  .claude-plugin/ を検出
     ↓
  marketplace.json を読み込み
     ↓
  各プラグインディレクトリをロード
     ↓
  コマンド、エージェント、フックを登録

2. コマンド実行フロー

ユーザー: /commit と入力
     ↓
CLI: plugins/commit-commands/commands/commit.md を検索
     ↓
CLI: YAMLフロントマターを解析
     ↓
CLI: !`git status` などの動的コマンドを実行
     ↓
CLI: 結果をマークダウンテンプレートに埋め込み
     ↓
CLI: 完成したプロンプトをClaude APIに送信
     ↓
CLI: allowed-toolsで許可されたツールのみ実行可能に制限
     ↓
Claude: タスクを実行（git add, git commitなど）

3. エージェント実行フロー

メインプロンプト: "code-explorerエージェントを起動"
     ↓
CLI: agents/code-explorer.md を読み込み
     ↓
CLI: YAMLフロントマターから設定を取得
     - name: code-explorer
     - tools: Glob, Grep, Read, ...
     - model: sonnet
     ↓
CLI: サブプロセスとしてエージェントを起動
     ↓
エージェント: 専門的なシステムプロンプトで実行
     ↓
エージェント: 制限されたツールセットのみ使用可能
     ↓
エージェント: 結果をメインプロセスに返却
     ↓
メインプロセス: 結果を受け取り、次のステップへ

4. フック実行フロー

ユーザーがEditツールを使おうとする
     ↓
CLI: PreToolUseフックをチェック
     ↓
CLI: security-guidance/hooks/hooks.json を発見
     {
       "hooks": {
         "PreToolUse": [{
           "matcher": "Edit|Write|MultiEdit",
           "command": "python3 .../security_reminder_hook.py"
         }]
       }
     }
     ↓
CLI: matcherでツール名をチェック（Edit → マッチ）
     ↓
CLI: Pythonスクリプトを実行
     - stdinにツールパラメータをJSON形式で渡す
     ↓
Pythonスクリプト: ファイルパスを解析
     ↓
Pythonスクリプト: セキュリティパターンをチェック
     ↓
Pythonスクリプト: stdoutに警告メッセージを出力
     ↓
CLI: フックの出力をプロンプトに追加
     ↓
Claude: 警告を考慮してコードを書く

プラグインの3つの構成要素

1. コマンド（Commands）

役割: スラッシュコマンドの定義

ファイル形式: Markdown + YAMLフロントマター

例: commands/commit.md

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a git commit
---

## Context

- Current git status: !`git status`
- Current git diff: !`git diff HEAD`

## Your task

Create a single git commit based on the above changes.

特徴:

• allowed-tools: 使用可能なツールを制限（正規表現サポート）
• !`{command}` : 実行時に動的にコマンドを実行して結果を埋め込む
• マークダウン本文がプロンプトになる

2. エージェント（Agents）

役割: 専門的なサブタスクを実行する独立プロセス

ファイル形式: Markdown + YAMLフロントマター

例: agents/code-explorer.md

---
name: code-explorer
description: Deeply analyzes existing codebase features
tools: Glob, Grep, Read, TodoWrite
model: sonnet
color: yellow
---

You are an expert code analyst...

特徴:

• tools: エージェントが使用できるツールのリスト
• model: 使用するモデル（sonnet, opus, haiku）
• color: ターミナル表示時の色
• マークダウン本文がシステムプロンプトになる

3. フック（Hooks）

役割: 特定のイベントでスクリプトを実行

ファイル形式: hooks.json + 実行スクリプト（.py, .sh等）

例: hooks/hooks.json

{
  "description": "Security reminder hook",
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [{
          "type": "command",
          "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/security_reminder_hook.py"
        }],
        "matcher": "Edit|Write|MultiEdit"
      }
    ]
  }
}

フックタイプ:

• SessionStart: セッション開始時
• PreToolUse: ツール実行前
• PostToolUse: ツール実行後（将来的に追加予定）

入出力:

• stdin: ツールパラメータ（JSON形式）
• stdout: プロンプトに追加されるメッセージ
• stderr: デバッグログ

データフロー図

コマンドの実行

┌──────────┐
│  ユーザー  │ /commit
└─────┬────┘
      │
      ▼
┌─────────────────────────┐
│  CLI                    │
│  1. コマンドファイル検索  │
│  2. YAML解析            │
│  3. 動的コマンド実行     │
│  4. プロンプト生成       │
└─────┬───────────────────┘
      │ プロンプト
      ▼
┌─────────────────────────┐
│  Claude API             │
│  - ツール実行（制限付き） │
│  - git add, commit等    │
└─────┬───────────────────┘
      │ 結果
      ▼
┌──────────┐
│  ユーザー  │ コミット完了
└──────────┘

エージェントの実行

┌──────────┐
│メインプロセス│ code-explorerを起動
└─────┬────┘
      │
      ▼
┌─────────────────────────┐
│  CLI                    │
│  1. エージェントファイル  │
│     読み込み             │
│  2. サブプロセス起動     │
│  3. ツール制限設定       │
└─────┬───────────────────┘
      │
      ▼
┌─────────────────────────┐
│  エージェントプロセス     │
│  - 専門プロンプトで実行   │
│  - Glob, Grep, Read使用 │
│  - コードベース分析      │
└─────┬───────────────────┘
      │ 分析結果
      ▼
┌──────────┐
│メインプロセス│ 結果を受け取り
└──────────┘

プラグインディレクトリ構造

標準的なプラグイン構造：

plugin-name/
├── .claude-plugin/
│   └── plugin.json              # メタデータ（名前、バージョン、作者）
│
├── commands/                     # スラッシュコマンド（任意）
│   ├── command1.md
│   └── command2.md
│
├── agents/                       # 専門エージェント（任意）
│   ├── agent1.md
│   └── agent2.md
│
├── hooks/                        # イベントフック（任意）
│   ├── hooks.json               # フック定義
│   ├── hook_script.py           # 実行スクリプト
│   └── hook_script.sh
│
└── README.md                     # ドキュメント

設定ファイルの役割

.claude-plugin/marketplace.json

• 全プラグインの中央レジストリ
• プラグイン名、バージョン、作者情報
• マーケットプレイス表示用メタデータ

.claude-plugin/plugin.json（各プラグイン）

• 個別プラグインのメタデータ
• 名前、バージョン、説明、作者

.claude/settings.local.json

• プロジェクト固有の設定
• ローカルでの動作カスタマイズ

次のステップ

• プラグインシステム詳解 - 各要素の詳細仕様
• 実例集 - 具体的な実装例