everything-claude-codeの設計思想 — 五層アーキテクチャを読み解く

はじめに

本記事は「2026年4月 AIエージェント開発の最前線」シリーズの一部として執筆している。シリーズ全体の概観はこちらの記事を参照してほしい。

---

入門編では、ECC の全体像——多数のエージェント・スキル・コマンドの概観とマルチハーネス対応のセットアップ方法を紹介した。

本記事はシリーズ第2弾として、ECC の設計の核心に踏み込む。「なぜこの構造なのか」「各レイヤーはどう連携するのか」を、実際のソースコードを参照しながら解説する。特に以下の3点を重点的に扱う。

• 三層アーキテクチャ（agents / skills / hooks）とそれを補完する rules / commands の役割分担
• フックシステムの設計思想：32フック・7イベントタイプの全体像と run-with-flags.js ラッパー
• クロスハーネスアダプタ：Cursor の DRY パターン、OpenCode の TypeScript プラグイン、Codex の instruction-based 補完

なお、本記事は入門編を読んでいることを前提とする。ECC のインストール方法や基本概念は入門編を参照してほしい。

注記: 本記事の情報は2026年4月時点のものであり、各リポジトリの機能・数値は変動する可能性がある。数値は v1.10.0 HEAD（commit: 125d5e6）時点で検証した。最新の情報は各リポジトリの README を参照してほしい。

ECC の五層構造

ECC のコアは「三層」（agents / skills / hooks）と説明されることが多いが、実際にはこれに rules と commands を加えたコア三層 + 補助二層 = 五層構造で成り立っている。

レイヤー	ファイル数（v1.10.0 HEAD）	役割
agents/	47 ファイル	目的特化サブエージェント
skills/	181 ディレクトリ	ワークフロー定義と知識
rules/	14 ディレクトリ	常時適用ルール
commands/	79 ファイル	レガシースラッシュコマンド shim
hooks/	hooks.json（32フック定義）+ 34 スクリプト（含共通ライブラリ）	自動実行ガードレール

commands/ は現在 skills/ への移行が進んでおり、README には「Existing slash-style command names still work while ECC migrates off commands/」と明記されている。将来的には skills が唯一の primary workflow surface となる。

エージェント設計（agents/）

YAML frontmatter の構造

各エージェントは Markdown ファイルで定義される。ファイル先頭の YAML frontmatter に name、description、tools、model の4フィールドを持つ。

# agents/planner.md（実際のファイルより抜粋）
name: planner
description: Expert planning specialist for complex features and refactoring. Use PROACTIVELY when users request feature implementation...
tools: ["Read", "Grep", "Glob"]
model: opus

この設計の要点は tools フィールドによるツールアクセス制限だ。planner は Read/Grep/Glob（読み取り専用）しか持たず、実装は行わない。一方、e2e-runner は Playwright へのアクセスを持ち、ライブアプリをブラウザテストする。エージェントの責務をツールレベルで強制する設計思想が、ここに表れている。

4段階計画策定プロセス（planner の例）

planner.md は以下の4フェーズを定義している。

1. Requirements Analysis — 機能要求の完全理解、成功基準・制約の特定
2. Architecture Review — 既存コードベースの構造分析、影響コンポーネントの特定
3. Step Breakdown — ファイルパス・依存関係・リスク付きの詳細ステップ
4. Implementation Order — 依存関係優先、段階的テストが可能な順序

計画書フォーマットには Phase ごとに「Action / Why / Dependencies / Risk」の4項目が必須となっており、AI が生成しがちな曖昧な計画を構造的に防いでいる。

エージェントの5カテゴリ

47エージェントを機能別に分類すると次のようになる。

カテゴリ	エージェント例	特徴
ワークフロー系	planner, architect, code-reviewer, tdd-guide, loop-operator	開発サイクル全体をカバー
言語別レビュアー + ビルドエラー解決	typescript-reviewer, go-reviewer, rust-build-resolver 等	言語固有の品質チェック
セキュリティ・品質系	security-reviewer, database-reviewer, e2e-runner	横断的な品質保証
ドメイン特化	GAN（3体）、OSS（3体）、healthcare-reviewer	専門ドメインへの特化
インフラ・運用系	harness-optimizer, performance-optimizer	ハーネス自体の最適化

GAN ハーネスの設計

ドメイン特化エージェントの中でもとりわけユニークなのが GAN（Generative Adversarial Network）を模したハーネスだ。3エージェントが協調して動作する。

• gan-planner — ブリーフからスペックと評価ルーブリックを生成
• gan-generator — コードを生成し、開発サーバーを起動したまま待機
• gan-evaluator — Playwright MCP でライブアプリを直接テスト

gan-evaluator.md のスコアリング基準は design 0.3 + originality 0.2 + craft 0.3 + functionality 0.2 の重み付き合計で、7.0/10 が合格閾値だ。

評価エージェントの設計指針に「AI-slop を明示的に減点せよ」という記述がある点が興味深い。具体的には「generic gradients、stock layouts」を採用したデザインへのペナルティが定められており、AIが生成しがちな没個性なUIを評価段階で弾く仕組みになっている。

スキル設計（skills/）

SKILL.md の標準構造

各スキルは独立したディレクトリで構成され、中心に SKILL.md を持つ。YAML frontmatter に name、description、origin、version を定義し、本文は3セクション構成が標準だ。

When to Activate  — 発動条件
How It Works      — 動作の詳細
Examples          — 具体例

言語3点セットと言語別レビュアーの連動

主要言語には以下3つのスキルが揃っている。

スキル種別	役割
{lang}-patterns	言語イディオムとベストプラクティス
{lang}-testing	テスト戦略・フレームワーク別の書き方
{lang}-security	言語固有の脆弱性パターンと対策

この3点セットは言語別レビュアーエージェントと組み合わせて使うことが意図されている。たとえば typescript-reviewer は typescript-patterns や typescript-testing の知識を活用し、TypeScript固有の観点でコードを評価する想定だ。

コンテキストによる動的モード切替

contexts/ ディレクトリに3つのコンテキスト定義ファイルがある。

コンテキスト	方針	利用ツール
dev.md	コードを先に書け、説明は後	Edit / Write / Bash
research.md	広く読んでから結論を出せ	Read / Grep / Glob / WebSearch
review.md	severity 優先（critical > high > medium > low）	Read / Grep

タスクの性質に合わせてコンテキストを切り替えることで、エージェントの動作モードを動的に変更できる。

ビジネス系スキルの存在

ECC はコーディング支援に留まらない。skills/ には以下のビジネス系スキルが含まれている。

• article-writing — 「具体物で始めよ：成果物、例、出力、数値、コード。説明は後」。AI テンプレ表現を明示禁止
• market-research — 「意思決定を支える調査、調査劇場ではない」。投資家DD・競合分析・市場規模の3モード
• investor-materials — 投資家向け資料生成
• brand-voice — ブランドボイスの一貫性維持

Commands → Skills 移行

現在 commands/ は「legacy」と位置づけられており、skills/ が「primary workflow surface」として扱われている。スラッシュコマンド形式の名前はまだ動作するが、新規ワークフローは skills に実装されていく方針だ。

フックシステム（hooks/）

フックシステムは ECC の「ガードレール」を担うレイヤーだ。エージェントやスキルが「何をするか」を決めるのに対し、フックは「いつ自動で検証・記録するか」を決める。v1.10.0 HEAD 時点で 32フックが以下の7イベントタイプに配置されている。

イベントタイプ	フック数	主な用途
PreToolUse	11	git --no-verify ブロック、コミット品質、観測
PostToolUse	11	コマンドログ、PR追跡、品質ゲート、継続学習
Stop	6	フォーマット/型チェック、コスト追跡、通知
SessionStart	1	コンテキスト復元 + Instinct 注入
PreCompact	1	コンパクション前の状態保存
PostToolUseFailure	1	MCP ヘルス追跡・再接続
SessionEnd	1	セッション終了ライフサイクルマーカー

フック実行は scripts/hooks/run-with-flags.js で一元管理され、ECC_HOOK_PROFILE 環境変数で3段階のプロファイル（minimal / standard / strict）を切り替える。module.exports + run パターンのフックはプロセス生成なしで直接ロードされるため、32フックが積み重なっても実用的な速度を維持できる。

32フック全件のリファレンス、run-with-flags.js の2パス実行モデルの詳細、主要フックのコード解説、カスタムフック作成パターンはフック実践ガイドで全量カバーする。

クロスハーネスアダプタ

ECC が Claude Code だけでなく複数のハーネスに対応できる理由は、各ハーネス向けのアダプタが適切な抽象化レベルで実装されているためだ。

対応ハーネス一覧

ハーネス	対応レベル	実装方式	特記事項
Claude Code	ネイティブ（主対象）	Node.js / Markdown	フル機能
Cursor	フルサポート	DRY アダプタ	ECC スクリプトを再利用
OpenCode	フルサポート	TypeScript ESM プラグイン	多数のイベント対応
Codex	ファーストクラス	instruction-based	フックなし、MCP で補完
Kiro	拡張サポート	JSON .kiro.hook	IDE + CLI フック
Gemini	限定的	GEMINI.md のみ	プロジェクトローカル指示のみ
Trae	限定的	install.sh + README	最小限
CodeBuddy	限定的	install.js + install.sh	最小限
Antigravity	インストーラ対応	install.sh --target	.agent/ に展開

Cursor: DRY アダプタパターン

.cursor/hooks/adapter.js が Cursor の stdin JSON を Claude Code フォーマットに変換し、scripts/hooks/*.js を呼び出す。フック実装を一切複製せず、変換ロジックだけを持つ設計だ。

// .cursor/hooks/adapter.js（実際のファイルより抜粋）
function transformToClaude(cursorInput, overrides = {}) {
  return {
    tool_input: {
      command: cursorInput.command || cursorInput.args?.command || '',
      file_path: cursorInput.path || cursorInput.file || cursorInput.args?.filePath || '',
      ...overrides.tool_input,
    },
    tool_output: {
      output: cursorInput.output || cursorInput.result || '',
      ...overrides.tool_output,
    },
    transcript_path: cursorInput.transcript_path || // ...,
    _cursor: { /* ... */ },
  };
}

変換後は runExistingHook() で ECC の既存スクリプトに委任する。3段階プロファイルシステムも同一のものを再利用する。Cursor は Claude Code より多くのフックイベントタイプを持つが、このアダプタにより実装の重複なく対応できている。

OpenCode: TypeScript ESM プラグイン

.opencode/ には OpenCode 向けの TypeScript プラグイン実装がある。opencode.json で設定を定義し、plugins/ecc-hooks.ts（フック実装）と index.ts（プラグインエントリポイント）で TypeScript ESM モジュールとして実装する。

多数のイベントタイプに対応しており、Claude Code のイベントを OpenCode のイベントにマッピングする（例: PreToolUse → tool.execute.before）。また、OpenCode 向けにネイティブツールを提供する。

ネイティブツール	役割
changed-files	変更ファイル一覧
git-summary	Git 状態サマリ
format-code	コードフォーマット
lint-check	リントチェック
security-audit	セキュリティ監査
run-tests	テスト実行
check-coverage	カバレッジ確認

npm パッケージ ecc-universal として配布されており、OpenCode ユーザーは npm install ecc-universal で導入できる。

Codex: instruction-based 補完

Codex はフック機能を持たないため、AGENTS.md（ルート）の共有と .codex/config.toml の設定で補完する。

# .codex/config.toml（構造のみ示す）
[mcp_servers]  # アクティブ MCP サーバーを設定
[permissions]  # ファイルシステム・ネットワーク権限

.codex/agents/ には explorer・reviewer・docs-researcher の3ロールが定義されており、フックの代わりに指示ベースで品質を担保する設計だ。

Kiro: JSON .kiro.hook

.kiro/hooks/ ディレクトリには .kiro.hook 形式のフック定義が用意されている。代表的なものを挙げると：

• auto-format.kiro.hook — 保存時の自動フォーマット
• quality-gate.kiro.hook — 品質ゲートチェック
• typecheck-on-edit.kiro.hook — 編集時の型チェック

このほか code-review-on-write、tdd-reminder、git-push-review など計10個のフックが定義されている。Kiro の IDE フックと CLI フックを組み合わせ、ECC のエージェント定義（.kiro/agents/）・スキル（.kiro/skills/）・steering（.kiro/steering/）も完備している。

ルールシステム（rules/）

rules/ は Claude Code の設定ファイルに常時適用されるルール集だ。14ディレクトリ構成で、common（汎用）+ 13言語エコシステムをカバーする。

#	ディレクトリ	言語
1	common/	言語共通（10ファイル）
2-13	typescript/ ... dart/	各言語（各5ファイル）
14	web/	HTML/CSS/a11y（7ファイル）

各言語ディレクトリには5ファイルが統一配置されている。

coding-style.md   — コーディングスタイル
hooks.md          — フック連携ルール
patterns.md       — 設計パターン
security.md       — セキュリティルール
testing.md        — テスト戦略

web/ のみ design-quality.md と performance.md が追加され、フロントエンド固有の品質基準をカバーする。

インストールマニフェスト

ECC のインストールは install.sh（Shell ラッパー）が scripts/install-apply.js（Node.js）に委任し、manifests/ 配下の3つの JSON ファイルで構成を管理する。

3階層の粒度制御

プロファイル
  └── モジュール（19種）
        └── コンポーネント（45+種）

5つのプロファイル（manifests/install-profiles.json）

プロファイル	説明
core	最小構成（rules-core, agents-core, commands-core, hooks-runtime, platform-configs, workflow-quality）
developer	エンジニア向け標準構成（core + framework-language, database, orchestration）
security	セキュリティ重視構成（core + security モジュール）
research	リサーチ・コンテンツ向け（core + research-apis, business-content, social-distribution）
full	全19モジュール込み

ハーネス選択（--target フラグ）

# Claude Code 向けにフルインストール
./install.sh --target claude --profile full

# Cursor 向けに開発者プロファイル
./install.sh --target cursor --profile developer

# 特定コンポーネントを追加・除外
./install.sh --profile developer --with eval-harness --without media-generation

対応ターゲット: claude、cursor、codex、opencode、gemini、antigravity、codebuddy

モジュールの設計

manifests/install-modules.json の各モジュールには以下のフィールドがある。

{
  "id": "agents-core",
  "kind": "agents",
  "description": "Agent definitions and project-level agent guidance.",
  "paths": [".agents", "agents", "AGENTS.md"],
  "targets": ["claude", "cursor", "antigravity", "codex", "codebuddy"],
  "defaultInstall": true,
  "cost": "light",
  "stability": "stable"
}

targets フィールドでモジュールがどのハーネスに適用されるかを制御している。たとえば hooks-runtime モジュールは claude/cursor/antigravity に適用され、フックシステムを持たない codex には適用されない。

まとめ

ECC のコア三層（エージェント・スキル・フック）と補助二層（rules・commands）——五層構造の設計を見てきた。

各レイヤーの役割を整理すると：

• agents/: 「誰がやるか」を定義。ツール制限で責務を強制
• skills/: 「どうやるか」を定義。ワークフローと知識の再利用単位
• hooks/: 「いつ自動で検証するか」を定義。開発サイクルにガードレールを埋め込む
• rules/: 「常に守るべき約束」を定義。全セッションに適用
• commands/: 後方互換性のための shim（skills へ移行中）

この構造が「ハーネス最適化」を実現するのは、各レイヤーが独立して進化できるからだ。新しい言語を追加するには rules/ と skills/ に数ファイルを足すだけでよい。新しいハーネスへの対応はアダプタ層の追加を起点に進められる（ただし、ハーネス間のイベントモデル差・権限モデル差の吸収は別途必要になる）。フックの挙動はプロファイルと環境変数で実行時に変更できる。

先進機能編では、ECC の独自概念である Instinct システム（継続学習）、AgentShield（セキュリティ監査）、eval-harness を解説している。dmux-workflows（並列エージェントオーケストレーション）と Rust 製コントロールプレーン ECC 2.0 Alpha は自律ループ編で取り上げる。

参考リンク

リソース	説明
everything-claude-code	本記事で解説したメインリポジトリ（MIT ライセンス）
ECC README	インストール手順・コンポーネント一覧・Cross-Tool Parity 表
hooks/hooks.json	フック定義の全体（32フック）
scripts/hooks/run-with-flags.js	フック実行ラッパー（3段階プロファイル・2パス実行）
manifests/install-profiles.json	インストールプロファイル定義（5プロファイル）
AgentShield	ECC のセキュリティ監査レイヤー（別リポジトリ）
Claude Code 公式ドキュメント	Claude Code のフック・エージェント仕様