205kスターのECCに学ぶエージェントハーネス最適化と安全な導入手順

Posted at 2026-06-06

はじめに

GitHub で 205k スターを集めている affaan-m/ECC というリポジトリをご存じでしょうか。「The agent harness performance optimization system」を名乗る、Claude Code・Codex・Cursor・OpenCode など複数のエージェントハーネスを横断する設定・スキル・フックの集大成です。

筆者は以前から Martin Fowler の「Agent = Model + Harness」という整理（ハーネスエンジニアリング）に注目してきましたが、ECC はまさにその思想を 10ヶ月以上の実運用から体系化した OSS と言えます。本記事では ECC のリポジトリを読み解き、以下を整理します。

この記事で分かること: ECC の構成要素（agents / skills / hooks / rules / instincts）、導入時の落とし穴、部分採用の戦略
対象読者: Claude Code などのコーディングエージェントを日常的に使っていて、設定やスキルの体系化に興味があるエンジニア
前提知識: Claude Code の基本操作（スラッシュコマンド、プラグイン、MCP の概念）

なお、本記事はリポジトリの README・ドキュメント（v2.0.0-rc.1 時点）を一次情報として読み解いたものです。全コンポーネントを動かして検証したわけではない点はご了承ください。

背景・課題：なぜ「ハーネス最適化」が体系化されるのか

コーディングエージェントを使い込むと、誰もが似た問題に行き着きます。

毎セッション同じ指示を繰り返している（コンテキストが永続しない）
MCP サーバーを足し続けた結果、コンテキストウィンドウが圧迫される
プロジェクトごとのルールやレビュー観点が暗黙知のまま散逸する
セッションで得た学び（このリポジトリではこうする、という勘所）が翌日には消える

ECC はこれらを「ハーネスの性能問題」として捉え、skills（ワークフロー）、instincts（学習された勘所）、memory（セッション間の記憶）、security（設定の脆弱性検査）、research-first（調査優先の開発） という5本柱で解決を図ります。設定ファイル集ではなく「システム」を名乗るのはこのためです。

ECC の全体像

リポジトリの規模感はかなりのもので、公称で 63 agents / 249 skills / 79 legacy command shims が含まれます。主要ディレクトリを図にすると次の通りです。

agents：委譲先のサブエージェント

planner（実装計画）、code-reviewer（品質レビュー）、security-reviewer（脆弱性分析）といった汎用エージェントに加え、java-reviewer や kotlin-build-resolver など言語特化のレビュアー・ビルドエラー解決エージェントが揃っています。各エージェントは次のような frontmatter 付き Markdown で定義されます。

---
name: code-reviewer
description: Reviews code for quality, security, and maintainability
tools: ["Read", "Grep", "Glob", "Bash"]
model: opus
---

You are a senior code reviewer...

エージェント定義が「使うツールの制限」と「使うモデルの指定」を含む点は、自前のサブエージェント設計でも参考になります。レビュー用途に強いモデルを割り当て、ツールを読み取り系に絞るという設計です。

skills：ワークフローの第一級市民

ECC は「Skills are the primary workflow surface（スキルが主要なワークフロー面）」と明言しており、新規のワークフロー開発はまず skills/ に置く方針です。スラッシュコマンドは互換層（さらに古いものは legacy-command-shims/）として維持されています。コマンド中心からスキル中心への移行は、Claude Code 本体の進化とも歩調が合っています。

中身は TDD ワークフロー、フレームワーク別パターン集（Spring Boot / Django / Laravel / Quarkus など）、E2E テスト、API 設計と幅広いですが、筆者が面白いと感じたのは次の3つです。

search-first: コードを書く前に調査を強制する「research-before-coding」ワークフロー
iterative-retrieval: サブエージェントに渡すコンテキストを段階的に絞り込むパターン
strategic-compact: コンテキスト圧縮（compact）のタイミングを提案する仕組み

continuous-learning-v2：instinct という単位の継続学習

ECC で最も特徴的なのが「instinct（直感・勘所）」ベースの継続学習です。セッション終了時のフックでパターンを抽出し、確信度スコア付きの instinct として蓄積します。

/instinct-status        # 学習済み instinct を確信度付きで表示
/instinct-import <file> # 他者の instinct を取り込む
/instinct-export        # 自分の instinct を共有用にエクスポート
/evolve                 # 関連する instinct をクラスタリングしてスキル化

「セッションから自動でパターンを抽出し、確信度を付けて貯め、まとまったらスキルに昇格させる」という流れは、人間の暗黙知が形式知化されるプロセスのエージェント版と言えます。instinct のインポート・エクスポートでチーム間共有まで視野に入れている点も示唆的です。

hooks と memory-persistence：セッション間の記憶

SessionStart でコンテキストを読み込み、SessionEnd / PreCompact で状態を保存するフック群により、セッションをまたいだ記憶を実現しています。実装はクロスプラットフォーム対応のためすべて Node.js スクリプトに書き直されており、ECC_HOOK_PROFILE=minimal|standard|strict や ECC_DISABLED_HOOKS といった環境変数でランタイム制御できます。

# フックの厳格さプロファイル（デフォルト: standard）
export ECC_HOOK_PROFILE=standard

# 特定フックだけ無効化
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

# SessionStart で注入する追加コンテキストの上限（デフォルト 8000 文字）
export ECC_SESSION_START_MAX_CHARS=4000

フックを「全部入り」で配るのではなく、プロファイルと個別無効化で調整可能にしている設計は、フック数が増えたときの現実解だと感じます。

AgentShield：エージェント設定そのものを検査する

セキュリティ面では、CLAUDE.md・settings.json・MCP 設定・フック・エージェント定義を静的解析する AgentShield が用意されています（102 ルール、シークレット検出 14 パターン）。

# インストール不要のクイックスキャン
npx ecc-agentshield scan

# 安全な問題の自動修正
npx ecc-agentshield scan --fix

「エージェントの設定ファイル自体が攻撃面になる」という問題意識は 2026 年のエージェントセキュリティの中心テーマであり、プロンプトインジェクションを仕込まれた hooks や MCP 設定を CI で検査できるのは実用的です。critical な検出で exit code 2 を返すため、ビルドゲートにも組み込めます。

導入手順と落とし穴

ECC の README で最も紙幅が割かれているのが、実は「インストール方法を混ぜるな」という警告です。これは導入を検討する上で重要なので整理します。

インストール経路は1つだけ選ぶ

推奨はプラグイン経由です。

# マーケットプレイス追加
/plugin marketplace add https://github.com/affaan-m/ECC

# プラグインインストール
/plugin install ecc@ecc

ここで注意すべきは次の3点です。

1. プラグインと手動インストーラを重ねない。 最も多い壊れ方が「/plugin install の後に install.sh --profile full を実行する」パターンで、スキルとフックが二重登録されます。

2. rules はプラグインで配布できない。 Claude Code のプラグインシステムは rules の配布に対応していないため（公式ドキュメントにも記載のある制限）、必要な言語ディレクトリだけ手動コピーします。

mkdir -p ~/.claude/rules/ecc
cp -R rules/common ~/.claude/rules/ecc/
cp -R rules/typescript ~/.claude/rules/ecc/   # 使う言語だけ

3. hooks.json を settings.json に手動コピーしない。 Claude Code v2.1+ はプラグインの hooks/hooks.json を自動ロードするため、手動コピーすると二重実行になります。実際にこのリポジトリでは plugin.json への hooks 宣言を巡って fix/revert が繰り返された歴史があり、現在は回帰テストで再発防止されています。

コンテキスト圧迫への処方箋

FAQ には「MCP サーバーの入れすぎで 200k のコンテキストウィンドウが実質 70k まで減る」という生々しい注意があり、MCP は 10 個以下・アクティブツール 80 個以下 という目安が示されています。ECC 自体が大量のコンポーネントを持つだけに、「全部入れる」のではなく npx ecc consult "security reviews" --target claude のような付属アドバイザーで必要なものだけ選ぶ運用が前提です。

筆者の見立て：どう部分採用するか

正直なところ、249 スキル・63 エージェントをそのまま導入するのは、コンテキスト管理の観点でもメンテナンスの観点でも現実的ではないと筆者は考えます。読み解いた範囲では、次の順での部分採用が良さそうです。

rules/common だけまず読む: コーディングスタイル・git ワークフロー・テスト方針などの言語非依存ルールは、自分の CLAUDE.md を書く際の網羅性チェックリストとして優秀です
memory-persistence と strategic-compact の設計を真似る: フックでセッション状態を保存・復元する仕組みは、自前のハーネスにも移植しやすい考え方です
AgentShield は独立して使える: npx ecc-agentshield scan は ECC 本体を入れなくても動くため、既存の Claude Code 設定の健康診断として試す価値があります
continuous-learning-v2 は思想を学ぶ: instinct → 確信度 → スキル昇格というパイプラインは、チームの知見管理の設計図として読めます

Fowler のハーネスエンジニアリングが「概念の整理」だとすれば、ECC は「実装カタログ」です。概念と実装例を行き来しながら、自分の規模に合ったハーネスを組むのが現実的な使い方でしょう。

ハマりどころ

インストール経路の混在: 前述の通り最頻出の事故です。重複したら再インストールではなく node scripts/uninstall.js --dry-run → 単一経路で入れ直しが正解です
識別子が3つある: GitHub リポジトリは affaan-m/ECC、プラグイン識別子は ecc@ecc、npm パッケージは ecc-universal と、文脈によって名前が違います
multi- コマンドは追加ランタイムが必要*: /multi-plan などは npx ccg-workflow で別途ランタイムを初期化しないと動きません
rules はディレクトリ単位でコピーする: ファイル単位でコピーすると相対参照が壊れます

まとめ

ECC は「エージェントの性能はモデルではなくハーネスで決まる」という思想を、10ヶ月以上の実運用から体系化した OSS です。全部入りで使うものというより、ハーネス設計のリファレンス実装として読むのが筆者のおすすめです。特に instinct ベースの継続学習、セッション間メモリのフック実装、設定ファイルのセキュリティスキャンの3点は、規模を問わず持ち帰れる知見だと感じました。

スター数の大きさに気後れせず、まずは rules/common と AgentShield あたりから小さく触ってみてはいかがでしょうか。

参考

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up