pev-harness

pev-harness

Claude Code に「計画 → 実装 → 検証」の型を与える plugin。

/pev "タスク" と投げるだけで、 曖昧な依頼は 質問して仕様化 し、 実装は 安いモデルに委譲 し、 完成したかどうかは 実装者とは別の verifier がテストを回して判定 します。 高いモデルは判断だけ、 安いモデルは作業だけ — この役割分担で、 素の Claude Code より 壊れにくく・検証付きで・安く なります。

コマンド名について: plugin として install した場合、 実際のコマンドは plugin namespace 付きの /pev-harness:pev です (/pev-init → /pev-harness:pev-init 等も同様)。 本 README では以降、 読みやすさのため /pev と略記します。

⭐ 役に立ったら star をお願いします。

3 行でいうと

1. 勝手に作らない — 仕様が曖昧なら実装前に質問が返ってくる (対話できない実行では、 根拠付きのデフォルトを明示して確定)
2. 自己申告を信じない — 「できました」ではなく、 独立した verifier がテストを書いて exit code で PASS/FAIL を判定。 FAIL なら自動で直して再検証 (最大 3 回)
3. 金額を設計する — 指揮と計画は Opus 5、 実装/検証は Sonnet か Codex。 トークンの重い仕事ほど安いモデルに落ちる

実測: 同じ「マイクラ作って」を投げると

同一プロンプトを 4 構成に投げた実測 (2026-07、 詳細は 費用モデルと全 findings):

つまり: Fable 級の品質を約 4 割引きで、 しかも検証付きで 出すのがこの harness の現在地です。 (実測は v4.2 構成 = 指揮層 Fable 時のもの。 v5.1 で指揮層は等価な判断品質と実測された Opus tier の最新世代 Opus 5 に切替済みで、 指揮層の単価はさらに半分になっています — 根拠: F_v19_10 と再検討メモ)

仕組み

  あなた: /pev "タスク"
       ↓
  指揮層 (Opus 5) … 各フェーズの起動と進行判定だけを行う。 実装ファイルは読まない
       ↓
  [0] TRIAGE  (Sonnet)  計画が要るタスクか 1 ターンで判定
       ↓ 要る場合のみ
  [1] PLAN    (Opus)    仕様の穴を質問 or 根拠付きデフォルトで確定 → plan.md
       ↓ ここで人間のレビュー (Gate A: 設定が default なら必ず停止)
  [2] EXECUTE (Sonnet or Codex CLI)  plan 通りに実装 → execute.log
       ↓
  [3] VERIFY  (Sonnet)  実装者とは別タスクで起動、 テストを実行して verify.json に PASS/FAIL
       ↓
  PASS → 完了    FAIL → 自動で再計画 → 再実装 → 再検証 (最大 3 回、 超えたら人間へ)

押さえどころは 3 つ:

• Gate A (人間の承認ポイント): 計画が立った直後、 permissionMode が default なら必ず止まって plan.md を見せます。 軽いタスクは auto で素通し、 重要な変更だけレビュー、 という運用ができます
• 検証の独立性: verifier は実装した agent と別のタスクとして起動され、 実装側のテストを鵜呑みにせず自分でテストを書くことも許可されています。 「実装者の自己採点で PASS」 は構造的に起きません
• コスト規約: 指揮層 (Opus 5、 上位単価 + 会話が全フェーズを跨いで累積) は artifacts の読み書きと指示だけ。 実装ファイルを読む・コードを書くのは常に安い層の仕事です

Quick start

A) 個人 install (全 project で使える)

# 1) install
claude plugin marketplace add myksyut/pev-harness
claude plugin install pev-harness@pev-harness

# 2) project の初期化 (team-conventions.md / .gitignore / 言語検知を 1 コマンドで)
cd <your-project>
claude
> /pev-harness:pev-init

# 3) 最初のタスク
> /pev-harness:pev "Add a /healthz endpoint that returns {status: 'ok'}"

B) team 共有 install (project に固定)

cd <your-project>
claude plugin marketplace add myksyut/pev-harness
claude plugin install pev-harness@pev-harness --scope project
git add .claude/settings.json && git commit -m "chore: adopt pev-harness team-wide"

teammate は clone → claude 起動 → trust prompt に同意で自動 install。 詳細は ONBOARDING §1.2。

C) install せず試す

git clone https://github.com/myksyut/pev-harness.git
claude --plugin-dir ./pev-harness
> /pev-harness:pev-init
> /pev-harness:pev "..."

タスクの投げ方

一番効くのは 最初のプロンプトに以下を入れる ことです (欠けていても動きます — planner が質問で埋めます):

Goal: 達成したいこと
Constraints: やってはいけないこと・依存制約
Acceptance Criteria: 成功の判定方法
Files: 既知の関連パス (任意)

よく使う flag

品質の自動切替

• 業務コード / 既存 codebase: 仕様の穴は質問で確認、 grey-zone は保守的に (勝手に機能を盛らない)
• ゼロから作る体験モノ (ゲーム・デモ等): 対話できない実行では「動くだけの最小版」に倒さず、 テクスチャ・操作 UI・FPS 表示・環境演出まで AC に含めて作ります (v4.2.1 の rich 品質バー。 上の実測はこれ)

実行ログ (session telemetry、 v4.3+)

各 task の実行記録が .pev-artifacts/session.json に自動で残ります — user prompt 原文 / 実行時 git 状態 (再現テスト用) / phase ごとの timing / token 消費 (概算) / user 入力 chat log / 任意の session 評価。 完了時に ~/.claude/pev/telemetry/ へ archive されるので、 「素の Claude Code に同じタスクを投げて比較する」 ベンチマーク dataset として蓄積できます。 local file のみで外部送信はしません。 不要なら PEV_TELEMETRY=off。

Optional integrations

core 機能は単体で動きます。 使う分だけ:

install しない場合は該当機能が warning 付きで skip されるだけで、 pipeline は止まりません。

Components

モデル構成 (v5.1+)

最上位の判断品質が必要な長大タスクでは .claude/settings.local.json で "model": "claude-fable-5" に override すると指揮層だけ Fable 5 (10 / 50、 ZDR org では利用不可) に上げられます。

Documentation

• SPEC.md — 完全仕様 (12 章 + ADR 11 件)
• ONBOARDING.md — Installation, troubleshooting, FAQ
• experiments/ — 設計判断の根拠実験 (harness-effect-v1〜v19)
• CHANGELOG.md — version history
• CONTRIBUTING.md / SECURITY.md

Design philosophy

What this harness does NOT do

• 言語別ヘルパーの追加 (プロジェクト側の tooling を使う)
• 自動 git commit (人間が境界を決める)
• 自動フォーマット (プロジェクト側の formatter)
• 50 個の specialized agent (agent 4 個でミニマルに完結)

v4.x からの移行 (v5.0 breaking changes)

• artifacts/ → .pev-artifacts/: 作業 dir を汚さない dot-prefix + pev 由来の明示 (社内 feedback)。 進行中 task があれば mv artifacts .pev-artifacts、 .gitignore の artifacts/ 行を .pev-artifacts/ に書き換え (新規は /pev-init が自動)
• コマンド統合 (9 → 6): /pev-init-e2e → /pev-init --e2e、 /pev-init-codex → /pev-init --codex、 /pev-verify-e2e → /pev-verify --e2e
• pev-task-budget skill / PEV_TASK_BUDGET env を削除: token 見積もり機能は提供しない (「いくら掛かっても結局実行する」 — 社内 feedback)。 実測は telemetry (session.json) が担う
• CrossRepo 対応 (new): multi-repo workspace root から起動しても、 対象 repo 直下に .pev-artifacts/ が置かれ、 /pev-status / hooks は階層をまたいで発見する

Roadmap (抜粋)

全履歴は CHANGELOG.md、 各 release の根拠実験は experiments/ 参照。

Contributing

Bug report / feature request は Issues、 質問は Discussions へ。 詳細は CONTRIBUTING.md。 脆弱性は SECURITY.md の手順で private に。

License

MIT — see LICENSE.

Note: pev-harness は trusted developer の local 環境 で動作する開発支援 plugin として設計されています。 SaaS / 共有環境での運用には追加の sandbox / isolation が必要です。 詳しくは SECURITY.md の threat model 参照。