everything-claude-codeの先進機能 — Instinct学習・AgentShield・Eval-Driven Development

はじめに

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

入門編では ECC の全体像——多数のエージェント・スキル・コマンドとマルチハーネス対応のアーキテクチャ——を整理した。アーキテクチャ編では五層構造の設計思想を、フック実践ガイドではフックの全容と run-with-flags.js の実行モデルを深掘りした。

本記事はシリーズ第4弾として、ECC の中でも特に先進的な3つの機能を取り上げる。

• Instinct（直感）システム v2.1 — 使うほどプロジェクト固有の知識を蓄積するフック観測型継続学習
• AgentShield — Cerebral Valley x Anthropic ハッカソン発のエージェント設定セキュリティ監査ツール
• eval-harness と Eval-Driven Development — 「eval は AI 開発のユニットテスト」という設計思想

自律ループの6パターンと ECC 2.0 Alpha については次回の自律ループ編で扱う。

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

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

Instinct（直感）システム v2.1 — フック観測型の継続学習

v1 から v2 への転換: hook-first 観測

ECC の Instinct システムは、開発セッションを観察してプロジェクト固有のパターンを自動学習する継続学習基盤だ。

v1 では Stop フック（セッション終了時）でパターンを抽出していた。しかしセッションが異常終了した場合や会話がコンパクションされた場合に観測が抜け落ちるという問題があった。v2 以降では観測タイミングを PreToolUse / PostToolUse フックに変更し、ツール呼び出しの前後でイベントを捕捉する設計になった（skills/continuous-learning-v2/SKILL.md の記述に基づく）。ツール境界を経由しない活動は観測対象外だが、セッション終了に依存しなくなった分、v1 より観測の抜け落ちが起きにくくなっている。

v2.1 でさらにプロジェクトスコープが追加された。詳細は後述する。

Instinct のデータモデル

Instinct は1つのトリガーと1つのアクションからなる「原子的な」学習単位だ。

---
id: prefer-functional-style
trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
source: "session-observation"
scope: project
project_id: "a1b2c3d4e5f6"
project_name: "my-react-app"
---

# Prefer Functional Style

## Action
Use functional patterns over classes when appropriate.

## Evidence
- Observed 5 instances of functional pattern preference
- User corrected class-based approach to functional on 2025-01-15

信頼度スコアの意味（v1.10.0 HEAD 時点、instinct-cli.py より。閾値は将来変更される可能性がある）:

バックグラウンドのパターン検出には Haiku モデルが使われる。メインのコンテキストを圧迫せずに継続的な観測を可能にする設計だ。

v2.1: プロジェクトスコープによる分離

v2.1 の核心はプロジェクトスコープの導入だ。React プロジェクトで学んだパターンが Python プロジェクトに混入する、という「クロスプロジェクト汚染」を防ぐ。

プロジェクトは git remote get-url origin を SHA256 でハッシュして識別される。同じリポジトリであれば異なるマシンでも同じ12文字のプロジェクト ID が生成されるため、チーム間でのポータビリティが保たれる。

ストレージ構造は以下のように整理される。

~/.claude/homunculus/
├── projects/
│   ├── a1b2c3d4e5f6/          # プロジェクト固有 (git remote ハッシュ)
│   │   ├── observations.jsonl
│   │   └── instincts/personal/
│   └── f6e5d4c3b2a1/          # 別プロジェクト
├── instincts/personal/         # グローバルスコープ
└── evolved/                    # スキルへ昇格済み

/promote と /prune — スコープ管理コマンド

v2.1 で追加された2つのコマンドがある。

# プロジェクト instinct → global 昇格
# 条件: 2つ以上のプロジェクトで観測済み + confidence >= 0.8
/promote

# 不要・低信頼度 instinct の整理
/prune

# プロジェクト一覧と各 instinct 数を確認
/projects

/promote の昇格条件（2+ プロジェクトでの観測 & 信頼度 0.8 以上）は慎重に設計されている。特定プロジェクトのみで有効なパターンを誤ってグローバル化しないための閾値だ。

Instinct のライフサイクル全体

セッション活動（git リポジトリ内）
      │
      │ PreToolUse / PostToolUse フックが観測（ツール呼び出し境界で捕捉）
      │ + プロジェクトコンテキスト検出（git remote ハッシュ）
      ▼
 observations.jsonl に蓄積
      │
      │ バックグラウンドエージェント（Haiku）がパターン検出
      ▼
 projects/<hash>/instincts/ または instincts/（グローバル）
      │
      │ /evolve — 関連 instinct をクラスタリング
      ▼
 skills / commands / agents に昇格
      │
      │ /promote — 2+ プロジェクト & confidence >= 0.8 で global 昇格
      ▼
 instincts/（グローバル）← チーム全体で共有可能

基本コマンドフロー

# 学習済み直感の確認（プロジェクトスコープ + グローバル）
/instinct-status

# 関連 instinct のクラスタリングとスキル昇格
/evolve

# チーム共有用エクスポート
/instinct-export

# チームメンバーの知識をインポート
/instinct-import instincts-2026-04-11.json

# プロジェクト一覧と instinct 数
/projects

シニアエンジニアが数週間で蓄積した「このプロジェクトの暗黙知」を、新メンバーが /instinct-import で初日から使い始めるというオンボーディング活用が典型的なユースケースだ。

AgentShield — エージェント設定の専門セキュリティ監査

AgentShield とは

AgentShield は 別リポジトリ（affaan-m/agentshield） として公開されているセキュリティ監査ツールだ。ECC 本体には skills/security-scan/SKILL.md で AgentShield のラッパースキル（/security-scan）が定義されているが、AgentShield のコード自体は ECC リポジトリには含まれていない。そのため、本リポジトリのコードでは AgentShield の内部実装を検証できない点に留意してほしい。

AgentShield は「Cerebral Valley x Anthropic, Feb 2026」ハッカソンで開発された（README の "Security" セクションより）。npm パッケージとして ecc-agentshield の名称で配布されている。

なぜエージェント設定専用のセキュリティスキャナが必要か

背景には、エージェントハーネスの普及に伴い顕在化した固有リスクがある。ECC のセキュリティガイド（the-security-guide.md）では、公開スキルへのプロンプトインジェクション混入（Snyk ToxicSkills 調査）やエージェントインスタンスの露出（Hunt.io 報告）など、複数の外部調査が引用されている¹。汎用のシークレットスキャナでは検出できないエージェント設定特有のリスクが存在することが示唆されている。

スキャン対象5カテゴリ

skills/security-scan/SKILL.md に記載されたスキャン対象:

基本的な使い方

# 基本スキャン（カレントディレクトリの .claude/ を対象）
npx ecc-agentshield scan

# 自動修正モード（安全な修正のみ自動適用）
npx ecc-agentshield scan --fix

# JSON 出力（CI/CD 統合）
npx ecc-agentshield scan --format json

--fix フラグが自動修正する対象は、ハードコードされたシークレットの環境変数参照への置換や、ワイルドカード権限のスコープ限定など、「auto-fixable」とマークされた項目のみだ。人間によるレビューが必要な指摘（手動オンリー）は修正しない。

出力グレードと CI 組み込み

GitHub Actions での組み込みパターンは GitHub Action（affaan-m/agentshield@v1）として提供されている（AgentShield README の記載に基づく。利用前に公開状況を確認してほしい）。

- uses: affaan-m/agentshield@v1
  with:
    path: '.'
    min-severity: 'medium'
    fail-on-findings: true

Opus マルチエージェントモード: レッドチーム / ブルーチーム構成

AgentShield README によると、--opus フラグを付けると3つの Claude Opus エージェントがパイプラインを組む。

# Opus 深層分析（ANTHROPIC_API_KEY が必要）
npx ecc-agentshield scan --opus --stream

Attacker（Red Team）→ Defender（Blue Team）→ Auditor（Final Verdict）

• Attacker: 設定の弱点を積極的に探し、悪用シナリオを列挙
• Defender: Attacker が発見した問題に対して現在の保護策を評価
• Auditor: 両エージェントの知見を統合し、優先度付きのリスクアセスメントを生成

--stream フラグで3者のやり取りをリアルタイムに確認できる。

既知の脆弱性とリスク背景

AgentShield のようなツールが必要とされる背景として、ECC のセキュリティガイド（the-security-guide.md）は以下の CVE を挙げている。ただし以下は ECC ドキュメントの記載内容であり、筆者が独自に脆弱性の詳細や影響範囲を検証したものではない。

• CVE-2025-59536（CVSS 8.7）: trust dialog の承認前にプロジェクトコードが実行される問題
• CVE-2026-21852: ANTHROPIC_BASE_URL 環境変数のオーバーライドによる API キー漏洩の可能性

正確な影響範囲や修正状況は NIST NVD などの公式データベースで確認してほしい。

AgentShield 以外の防御策として、ECC セキュリティガイドでは以下が推奨されている。

• 専用エージェントアカウント（agent@yourdomain.com）で本番システムと分離する
• 信頼できないワークは devcontainer / Docker コンテナに閉じ込める
• capability を最小化し、no-new-privileges でデフォルト drop する
• エージェントの外部エンドポイント接続をネットワーク境界で制御する

eval-harness と Eval-Driven Development

「eval は AI 開発のユニットテスト」

ECC には skills/eval-harness/SKILL.md で定義された Eval-Driven Development（EDD）の概念がある。思想の核心は以下の一文だ。

"Eval-Driven Development treats evals as the 'unit tests of AI development'"

スキルやプロンプトを変更したとき「本当に効果があるか」を感覚ではなく数字で測る仕組みを「開発前に定義する」のが EDD の本質だ。

pass@k と pass^k: 2種類の信頼度指標

EDD では2種類のメトリクスを使い分ける。

pass@k — k回の試行のうち1回以上成功する確率

k回中1回でも成功すれば合格とする。「この機能が使えるか」という実用的な信頼度を測る。典型的な閾値は pass@3 で90%以上だ。

pass^k — k回全て成功する確率

k回すべて成功しなければ不合格とする。デプロイパイプラインや認証フローなど、信頼性が絶対条件の「クリティカルパス」向けの高い基準だ。リリースゲートでは pass^3 = 100% が推奨される。

3種のグレーダー

できる限り code-based グレーダーを使うべきで、model-based は決定論的評価が不可能な場合に限るのがベストプラクティスとして明記されている。

アーティファクトレイアウト

eval のアーティファクトはプロジェクト内に格納される。

.claude/
└── evals/
    ├── feature-xyz.md      # eval 定義（実装前に作成）
    ├── feature-xyz.log     # 実行履歴
    └── baseline.json       # 回帰テスト基準値

EDD の典型フロー

# 1. 実装前に eval 定義を作成
/eval define feature-name

# 2. 実装中に確認
/eval check feature-name

# 3. 実装後にレポート生成
/eval report feature-name

eval 定義では capability evals（「この機能が使えるか」）と regression evals（「既存機能を壊していないか」）を分けて定義する。capability は pass@3 で90%以上、regression はリリースクリティカルなパスで pass^3 = 100% が推奨閾値の目安だ。

具体的なシナリオで考えてみよう。あるスキルのプロンプトを改善したとする。変更前に /eval check を実行して pass@3 = 67%（3回中2回成功）だったものが、変更後に pass@3 = 100% に上がれば、プロンプト改善が機能の信頼性を向上させたと定量的に言える。一方、認証フローの回帰 eval が pass^3 = 100%（3回全成功）を下回った場合はリリースをブロックする——1回でも失敗するパスを本番に出さないための歯止めだ。

まとめ

本記事ではシリーズ第4弾として、ECC の先進機能3つを取り上げた。

Instinct システム v2.1 の本質は「暗黙知の形式知化」だ。v1 の Stop-hook から v2 の hook-first 観測（PreToolUse/PostToolUse）への転換で、セッション終了に依存しない観測が可能になった。v2.1 のプロジェクトスコープにより React パターンと Python パターンの混入が防がれ、/promote（v1.10.0 時点で 2+ プロジェクト観測 & confidence >= 0.8 が昇格条件）でチームのベストプラクティスを段階的に昇格させられる。

AgentShield は ECC とは別リポジトリ（affaan-m/agentshield）のツールだが、ECC がラッパースキルを提供することで統合されている。エージェント設定特有の5カテゴリ（CLAUDE.md / settings.json / mcp.json / hooks / agents）に特化したスキャンと、Attacker → Defender → Auditor の3エージェントパイプラインが特徴だ。ECC ドキュメントが引用する CVE や外部調査が示唆するように、エージェント設定のセキュリティはこれからさらに重要性を増す領域とみられる。

eval-harness と EDD は「eval は AI 開発のユニットテスト」という設計思想で、実装前に pass@k / pass^k の基準を定義することでスキル変更の効果を定量化する。

自律ループ編では、Sequential Pipeline から RFC 駆動 DAG オーケストレーションまでの6パターンと、Rust 製コントロールプレーン ECC 2.0 Alpha を取り上げる。

ECC を実践に取り入れるにあたっての実用的なヒントを一つ。Instinct システムは「蓄積期間」が必要だ。導入直後は通常のスキルセットとして使い、2〜3週間の実作業を経た後に /instinct-status を覗いてみてほしい。エージェントがプロジェクトの「やり方」を学び始めているはずだ。

参考リンク