「取得 → 分析 → 判定 → 白HTMLレポート → 自己改善ループ」型のハーネスを一流に設計するための、原則・名前付きパターン・標準手順・そのままコピーして使える計画テンプレート。Anthropic公式／海外フレームワーク／実務知見を統合。
迷ったらこの行に戻る。詳細は各原則へ。
優秀なハーネスを貫く中核原則。各原則に「実プロジェクトへの適用」を併記。
トークン数が増えるほどリコール精度が下がる「context rot」が起き、Transformerのn²注意関係で長文ほどアテンションが薄まる。崖でなく勾配的劣化。事前ロードでなくjust-in-time(軽量識別子→実行時動的ロード)を基本とし、コンパクション/構造化ノート/サブエージェント要約(1,000-2,000トークンに凝縮)で窓をまたぐ。
手順が予測でき一貫性が要るタスクは『ワークフロー』(LLM+ツールを事前定義コードパスで制御)、ステップ数を予測できず自律判断が要る問題は『エージェント』。エージェントは『LLMが次手を決める→決定論的コードが実行→結果を文脈に追記』のループとして自分で明示的に書く(Own Your Control Flow)。フレームワークのループに隠蔽させると80%の品質壁で詰まる。
差分判定・dedup・ランク・投票集計・予算管理・数値照合はコード/SQL(トークンゼロ・再現可能)で行い、LLMは言語化・要約・提案・クレーム抽出・口調生成に限定する。ツール呼び出しは特別な抽象でなく『構造化出力』に過ぎず、実行は決定論的コードが担う。エージェントはステートレスなreducer((状態+イベת)→(新状態+出力))として設計するとテスト容易性が上がる。
ドキュメント/プロンプトを書く前に評価を先に作る。スキルなしで代表タスクを走らせ失敗を文書化→最低3つの評価シナリオ作成→ベースライン測定→評価を通す最小限の指示を書く→反復。評価はパイプライン末尾の合格判定でなく、ライフサイクル全体を統御する継続機能(EDDOps)として開発時オフライン評価と運用時オンライン評価を一つの閉ループに統合する。
検証手段(テスト・終了コード・リンタ・スクリーンショット比較・E2E)がないと『完了っぽい』が唯一のシグナルになり人間がボトルネック化する。長期エージェントは包括的フィーチャーリストをJSON(steps+pass/fail、初期fail)で管理し検証後のみpasses:trueにする。ゲートの強度は段階的(プロンプト内→条件→Stopフック→検証サブエージェント)。フックは決定論的で毎回必ず起きるべきアクションに使う。
全APIエンドポイントをラップせず複数操作を統合(schedule_event一本、get_customer_context一括)。list_contactsでなくsearch_contacts。戻り値はUUID等でなく意味的に解釈可能な名前を返す。応答にconcise/detailed列挙。pagination/filter/truncationを妥当なデフォルトで(Claude Codeは応答25,000トークン制限)。Poka-yoke原則(絶対パス要求等)で誤用を防ぐ。関連ツールは共通prefixで名前空間化。
脆いハードコードif-elseも、共有文脈を誤前提する曖昧な高レベル指示も避け、行動を導くに足る具体性と強いヒューリスティクスを与える柔軟性のバランスを取る。XMLタグ/Markdown見出しで区切る。SKILL.md descriptionは三人称で『何をするか』と『いつ使うか(具体的トリガー・キーワード)』の両方、DO NOT triggerで隣接スキルと棲み分け。最良モデルで最小プロンプトをテストし失敗モードに基づき指示を追加する。
各新セッションは前回の記憶を持たない前提で設計する。継続性は人間可読な進捗ファイル(claude-progress.txt/NOTES.md)、説明的コミットを持つgit履歴、再現可能な環境を起動するinit.shで担保する。state.json/.state.jsonで進捗記録し中断→再開可能に。failed.log・処理痕跡を削除せず後から『なぜfailedか』を遡れるようにする(audit trail)。
最も洗練されたシステムでなくニーズに合った正しいシステムを作るのが成功。まずLLM API直接呼び出しや単一LLM+検索+例で足りることが多い。フレームワークを使う場合も内部コードを理解する(誤解はエラーの一般的原因)。マルチエージェント並列は単一スレッドより脆く(Flappy Bird例の前提食い違い)、Supervisorはナイーブ実装で『翻訳問題』により劣化しうる。
設計の共通語彙。左=Anthropic公式、右=海外フレームワーク／実務家／論文。
(1)プロンプトチェイニング=逐次ステップ+途中のprogrammatic gate、(2)ルーティング=入力分類→専門タスク振り分け、(3)並列化=Sectioning(独立分割)/Voting(同一タスク複数実行)、(4)オーケストレーター・ワーカー=中央LLMが動的に分解・委譲・統合、(5)評価者・最適化者=生成LLMと評価LLMの反復ループ。手順が予測できるならワークフロー、ステップ数を予測できないならエージェント。
各セッションは記憶を持たない『交代するシフトのエンジニア』前提。Initializer(init.sh・claude-progress.txt・初期gitコミット作成)とCoding Agent(1機能ずつ漸進実装、環境をmainマージ可能なクリーン状態に残す)を分離。フィーチャーリストをJSON(steps+pass/fail、初期fail)で管理、検証後のみpasses:true、テスト削除/編集禁止。セッション起動プロトコル(pwd→git log/進捗読込→最優先未完了選択→init.sh起動→E2Eサニティ)。
コンパクション(会話を高忠実要約に圧縮、推論コスト有、まずrecall最大化→precision反復)、ツール結果クリア(推論コストなしのサーバ側機械編集、keep/clear_at_least/exclude_toolsで設定、再取得可能ならロスレス)、メモリ(view/create/str_replace等のファイル操作、セッション越し永続)。発火順はトリガ値で制御(クリア先→コンパクション後→メモリ常時)。診断:tool_resultが50%超かつ再呼出可ならクリア、対話主ならコンパクション、越境知識ならメモリ。
(1)起動時に全スキルのname/descriptionメタデータのみプリロード、(2)関連時にSKILL.md本体読込、(3)必要時に個別ファイル/スクリプト読込。参照ファイルは実際に読むまでトークン消費なし。SKILL.md本体は500行未満、参照はSKILL.mdから1階層まで、100行超の参照には冒頭に目次。ユーティリティスクリプトは毎回生成より事前同梱が高信頼。
ドキュメントを書く前に評価を先に作る:スキルなしで代表タスク→失敗文書化→最低3評価シナリオ→ベースライン測定→通す最小指示→反復。スキル開発はClaude A(設計・改善する専門家)とClaude B(スキルで実作業する新規インスタンス)を交互に使い、Claude Bの実挙動を観察して仮定でなく観察に基づき反復する。
破壊的バッチ操作ではまずClaudeに構造化計画(changes.json)を作らせ、実行前にスクリプトで機械的に検証してから適用→検証する。タスクの脆弱性に応じて『自由度』を調整(複数正解=高自由度テキスト指示、脆く一貫性必須=低自由度固定スクリプト)。フックは決定論的で毎回必ず起きるべきアクションに(編集後eslint、migrations書込ブロック)。Stopフックは終了コード2でターン終了をブロック。
エージェントを『LLMが次手を決める→決定論的コードが実行→結果を文脈に追記』のループとして自分で明示的に書く(Own Your Control Flow)。ツール呼び出しは特別な抽象でなく構造化出力(Factor 4)。エージェントはステートレスreducer((状態+イベント)→(新状態+出力)、Factor 12)。小さく焦点を絞ったエージェントを組合せ(Factor 10)、エラーは圧縮して文脈追記(Factor 9)、コンテキスト窓を能動管理(Factor 3)、人間確認も通常ツール呼出と同じ仕組み(Factor 7)、launch/pause/resume(Factor 6)。
修正τ-bench(retail 100例+6妨害ドメイン×19無関係ツール)で単一/Swarm/Supervisorを比較。単一エージェントは妨害ドメイン2つ以上で性能急落・トークン増。Supervisor/Swarmはトークン横ばい。Supervisor劣化の主因は応答を言い換える『翻訳問題(telephone game)』で、forward_messageツール・ハンドオフメッセージ除去・ツール命名調整で約50%改善。多くの成功システムは依然カスタムアーキテクチャ。
ハンドオフはLLMにツールとして提示(transfer_to_<agent>)。行き先ごとに1ハンドオフを登録しモデルに選ばせる。input_filterで渡す履歴制御(remove_all_toolsで過去ツール呼出除去)、input_typeで構造化メタデータ生成。ガードレールは入力(最初のエージェント)/出力(最終出力)に分かれ、tripwire_triggeredで即停止。高速・安価なモデルで走らせ高価なモデルが動く前にブロック(ブロッキング実行でトークン/副作用を防ぐ)。ガードレールはエージェントに紐づける。
並列サブエージェントは前提が食い違い不整合な出力を生む(Flappy Bird例:片方Mario風背景・片方不一致の鳥スプライト、統合エージェントも救えない)。超長尺タスクで線形エージェントが溢れる場合は専用LLM(context compression)で会話履歴を主要決定・イベントに圧縮し時間的射程を延ばす。※『並列マルチより常に単一が優れる』という強い主張は他ソースの敵対検証で棄却済のため、本パターンは『前提共有が困難な並列協調作業を避ける』という限定で採用。
判定器自体にツール・メモリ・多段推論を与えると行動連鎖をステップ評価できる(Agent-as-a-Judge)。多エージェント判定はペルソナ多様性・モデル異種性を確保(同一だと利点消失・同バックボーン優遇)。コスト最適は『弱判定器+強ディベーター』可、ハイブリッド運用(自動LLMで一次フィルタ→上位のみ深掘り→人間はedge case)。信頼性は内部一貫性指標(McDonald omega)で測り併記。temperature=0でも単一出力は確率分布の1サンプルで固有ランダム性あり、下流メトリクスの分散も複数runで測る。
評価をパイプライン末尾の合格判定でなく、エージェントのライフサイクル全体を統御する継続機能として組み込む。開発時オフライン評価と運用時オンライン評価を一つの閉ループに統合(EDDOps)。LLMエージェントはopen-ended・確率的でシステムレベルの相互作用に形作られるため固定ベンチだけでは不十分。評価証跡がランタイム適応とガバナンス下の再開発を双方向に駆動する。
返却契約 → eval先行 → 各層 → 検証ゲート の逆算プロセス。
手順が予測でき一貫性が要るならワークフロー、ステップ数を予測できず自律判断が要るならエージェント、再利用可能な能力ならスキル(公式の明確な区別)。最初に『最も単純で足りるもの』を選ぶ。多くは単一LLM+検索+例で足り、複雑さは測定で成果改善が実証されたときだけ追加する。
公式のeval-driven development。ハーネスなしで失敗を文書化→3evalを作りベースライン測定→通す最小指示を書く、の順。戸野塚さんの最大ギャップを構造的に埋める。これがなければ『改善した』が証明できない。
workflow-architectの逆算ヒアリング(各問に推奨デフォルト付き、曖昧な項目だけ深掘り)に準拠。成果物仕様が実装を導く(form follows function)。grille-meで曖昧さ0まで詰めてから着手し、誤った問題を解くのを避ける。
事前全ロードはcontext rotを招く。ファイルパス/保存クエリ/CMKiller検索クエリを持ち実行時にロード(漸進的開示)。差分検出・dedup・集計はstate.db/SQLで決定的に。ツールは高インパクトなワークフローに絞り統合する(search_系・get_context一括)。
複利劣化(85%^10=20%)を防ぐ核心。脆く一貫性必須な操作は低自由度(固定スクリプト)、複数正解は高自由度(テキスト指示)。母数ガード(1000PV未満は判断しない)のような決定的ガードを入れる。
早すぎる完了宣言を防ぐ。破壊的操作はchanges.jsonを作り機械検証してから実行。lint/終了コード/E2E/スクリーンショット比較で検証ループを自律的に閉じ、公開ゲート手前に新鮮な文脈の敵対的レビュー(正しさに影響するギャップのみ報告)を挟む。フックで決定論的に強制。
戸野塚さんの既存の型を維持。ブランド一貫性とデータベース連携(frontmatter)を両立。ローカルmdが正本、RAG ingest/デプロイは追従(失敗時はpending resume)。
戸野塚さんの既存の強み。これに『運用時オンライン評価』を足してEDDOps化する。判断ログ・winning-copy・swipeを複利資産として蓄積し、評価証跡が次の開発の初期仮説とeval更新を駆動する閉ループにする。learner蒸留はclaude -p等の別インスタンスで行い出力のみ本体に反映(context保護)。
各セッションは記憶を持たない前提。進捗ファイル・git履歴・環境起動スクリプトで継続性を担保。ロック+PID checkでlaunchd多重起動を排除、failed.logで部分失敗を記録しつつ全体abortさせない。長期ハーネスにセッション起動プロトコルを定型化する。
戸野塚さんの既存原則と公式『複雑さは実証されたときだけ』が一致。並列マルチエージェント協調(翻訳問題・前提食い違い)は成果を実証してから。単一スレッド+state.db集約のroll-upで先に価値を出す。
新ハーネス着手時にコピーして埋める雛形。これを埋め切るまで実装に入らない。
---
harness_name: "<ハーネス名>"
purpose: "<1行: 誰のどの仕事を、どう変えるか>"
owner: "戸野塚蓮 (AIVEST)"
created: "<YYYY-MM-DD>"
status: "draft" # draft → eval-set → building → shipped
---
# ハーネス設計 計画 — <ハーネス名>
> **使い方:** `cp plan-template.md <案件名>-plan.md` で複製し、`<ここに記入>` を埋める。空欄が残っている = まだ着手してはいけない。
> 骨格は [`playbook.md`](./playbook.md) の方法論10ステップ。各ステップは「記入欄 → 記入のヒント → 落とし穴」の3点セット。
> 関連: 評価セットは [`eval-template/`](./eval-template/)、原則・アンチパターン全文は [`playbook.md`](./playbook.md)。
この計画は**逆算で埋める**。Step0で器を選び、返却契約とevalを先に固定し、そこから取得→判定→検証→出力→自己改善の順で設計する。実装(コードを書く)のはこの計画が埋まってから。
---
## Step0 適合判定 — ワークフロー / エージェント / スキル / 単発Agent
**選択（1つに丸を付ける）:** [ ] ワークフロー [ ] エージェント [ ] スキル [ ] 単発Agent
**理由:** `<なぜこの器か。下の判断基準のどれに当たるか>`
| 器 | いつ使う | 例 |
|---|---|---|
| **ワークフロー** (`.js`) | 手順が予測でき一貫性が要る。並列/順序/再開/予算を決定論的に回す | deep-research, x-article-gen |
| **エージェント** (対話/subagent) | ステップ数を予測できず自律判断が要る | 企画コンセプト探索, 重い壁打ち |
| **スキル** (`SKILL.md`) | 再利用可能な「能力」をトリガーで起動 | ad-research, cmkiller |
| **単発Agent** | 1回きりのタスク。再利用しない | ある記事1本の調査 |
判断軸: **手順は予測可能か → Yesならワークフロー寄り。自律判断が中核か → Yesならエージェント。再利用するか → Yesならスキル化。** 迷ったら**最も単純なもの**を選ぶ。多くは単一LLM+検索+例で足りる。複雑さ（並列マルチエージェント等）は**測定で成果改善が実証されたときだけ**足す。
> ⚠️ **落とし穴:** 最初から「司令塔が70体を並列オーケストレーション」のような大構成を選ばない。前提食い違い（翻訳問題・Flappy Bird問題）で劣化する。単一スレッド + state.db 集約のroll-upで先に価値を出してから複雑化する。
---
## 返却契約（最初に決める） — form follows function
> 出力が実装を導く。器を選んだら**真っ先にここを固める**。曖昧なまま着手すると「誤った問題」を解く。
- **最終成果物の形式:** [ ] 白ベースHTML [ ] Markdown [ ] JSON [ ] その他 `<>`
- **保存先（実体パス）:** `<例: themes/{theme}/reports/dashboard_YYYY-MM-DD.html>`
- **出力スキーマ（JSON/構造）:**
```
<ここに記入。例:
{ question, summary, findings[], sources[], stats{...} } >
```
- **frontmatter / 命名規則:** `<例: mtid命名、YYYYMMDD-slug、campaign_id>`
- **「誰がいつ何のために読むか」:** `<読み手と用途。これが粒度を決める>`
> ⚠️ **落とし穴:** HTMLは必ず白ベース（Notion/Stripe風・アクセント青1色）。スキーマを後付けにすると、サブエージェント間の唯一の共有手段＝型が崩れる。ローカル保存が正本、RAG ingest / デプロイは追従（失敗時は pending で resume）。
---
## Step1 eval先行 — 実装より先に「合格の定義」を書く
> **戸野塚ハーネス群の最大ギャップがここ。** ドキュメント/プロンプトを書く前に評価を作る。
> 手順: ハーネスなしで代表タスクを走らせ失敗を文書化 → 下の3シナリオを書く → 現状ベースラインを測る → 通す最小限の指示を書く → 反復。
> evalの置き場・記法は [`eval-template/`](./eval-template/) に従う。
### シナリオ① typical（典型ケース）
- **入力例:** `<実際に投げる入力をそのまま>`
- **合格基準:** `<何が出れば合格か。観測可能な形で。例: 出典3件以上・全主張に出典番号・白HTML>`
- **現状ベースライン:** `<ハーネスなし/現行で今どうなるか。スコア or 所要時間 or 失敗内容>`
### シナリオ② edge（エッジケース）
- **入力例:** `<境界条件。例: データが極端に少ない/多い、曖昧な質問、複数テーマ混在>`
- **合格基準:** `<崩れずに妥当な縮退をするか。例: 0ヒット時は『不明』と正直に出す>`
- **現状ベースライン:** `<>`
### シナリオ③ known-failure（既知の失敗例）
- **入力例:** `<過去に実際にやらかしたパターン。例: dpubをinternalで検索→0ヒット誤報>`
- **合格基準:** `<その失敗を再現しないこと。ゲートで弾けるか>`
- **現状ベースライン:** `<>`
> ⚠️ **落とし穴:** evalを飛ばすと「完了っぽい」が唯一のシグナルになり、改善したかを**証明できない**。最低3シナリオは必須。temperature=0でも単一runは確率分布の1サンプル。重要な判定器（採点系）は複数runで分散も見る。
---
## Step2 逆算設計の確定 — 入力源とトポロジー
> 返却契約（上）→ 品質基準（eval）→ **入力源** → **トポロジー** の順で確定済みのはず。ここに落とす。
- **品質基準（evalから導く合否ライン）:** `<例: ろじん5軸40/50以上、母数1000PV以上で判断>`
- **入力源（3層に分類）:**
- 正典（決定論・Files）: `<例: SOURCES.md / voice.md / claims-ledger>`
- 方法論（検索・RAG）: `<例: CMKiller松尾講座 collection / reference/>`
- 生データ: `<例: state.db / Neon / analytics / 文字起こし>`
- **トポロジー（段の並び・並列/順序）:** `<例: scope → 並列search×5 → fetch → 並列verify → synthesize>`
> ⚠️ **落とし穴:** grille-meで曖昧さ0まで詰めてから着手する。各問に推奨デフォルトを置き、初期説明から自答できる項目は埋め、曖昧な項目だけ深掘りする。
---
## Step3 取得層 — just-in-time（事前全ロード禁止）
- **何を、どう取りに行くか（軽量識別子→実行時ロード）:** `<例: ファイルパス/保存クエリ/CMKiller検索クエリを持ち、実行時に動的ロード>`
- **決定的処理（コード/SQLに降ろすもの）:** `<例: 差分検出 state.db、URL dedup、集計>`
- **ツール（高インパクトに絞る・統合する）:** `<例: search_系1本、get_context一括。全APIラップしない>`
> ⚠️ **落とし穴:** 全文プリロードは context rot（n²注意でリコール劣化）を招く。reference正典も「見出し＋検索」の漸進的開示に寄せる。list_系でなく search_系を選ぶ。
---
## Step4 判定層 — 決定的処理とLLM判断の分離
- **コード/SQLでやる決定的処理:** `<例: 勝ち判定（最低CPL&Lead≥1）、3票投票、差分判定、予算管理>`
- **LLMに任せる判断的処理:** `<例: 言語化・要約・クレーム抽出・口調生成・診断の文章化>`
- **自由度の設定（脆弱性に応じる）:** `<脆く一貫性必須=低自由度・固定スクリプト / 複数正解=高自由度・テキスト指示>`
- **決定的ガード:** `<例: 母数ガード「1000PV未満は判断しない」>`
> ⚠️ **落とし穴:** 差分判定・集計・勝ち判定・投票をLLMに任せると複利劣化（85%^10step=20%）で精度が崩壊する。**判定はコード、言語化だけLLM。** まだLLM任せの分類（認知レベル判定・tags分類等）はルール/辞書+閾値に降ろせないか検討する。
---
## Step5 検証ゲート — plan-validate-execute + 自己検証 + 敵対的レビュー
- **破壊的操作の事前検証:** `<例: changes.json を作り、適用前にスクリプトで機械検証>`
- **自己検証手段（人間に頼らず閉じる）:** [ ] 終了コード [ ] lint [ ] E2E [ ] スクリーンショット比較 [ ] スキーマ検証 [ ] 数値照合（claims-ledger）
- **敵対的レビュー・サブエージェント:** `<新鮮な文脈で差分+基準だけを見て、正しさ/明示要件に影響するギャップのみ報告。過剰エンジニアリング指摘は禁止>`
- **フック化（決定論的に毎回強制）:** `<例: PostToolUseで白HTMLテンプレ準拠チェック、Stopで検証通過まで終了ブロック>`
- **人間ゲート（最大1〜2点に絞る）:** `<例: 公開直前のみ>`
> ⚠️ **落とし穴:** 検証手段がないと「完了っぽい」が唯一のシグナルになり人間がボトルネック化する。**検証できないものは出荷しない。** 自己採点（同一バックボーン）は自分を優遇するバイアスがあるので、独立インスタンスの敵対的レビューを挟む。テストの削除/編集は禁止。
---
## Step6 出力層 — 白ベースHTML + MD
- **HTML仕様:** Notion/Stripe風ホワイトベース・アクセント青1色（既存テンプレ流用）
- **MD版の要否:** [ ] 必要 [ ] 不要 — `<frontmatter項目を列挙>`
- **正本とデプロイ:** ローカルmdが正本 → `<RAG ingest / Cloudflare Pages / Vercel への追従。失敗時pending resume>`
> ⚠️ **落とし穴:** 機密情報を外出ししない（.envはdotenvx暗号化・鍵はKeychain）。デプロイは承認後・後発。
---
## Step7 自己改善ループ — 三段昇格 + EDDOps
- **decisions（案件ログ）:** `<判断＋根拠＋人間FB＋修正＋状態 をどこに記録するか>`
- **learnings（横断ルール）への昇格条件:** `<同じ過ちを二度しないルール化のトリガー>`
- **reference（標準化）への昇格条件:** `<勝ち型をプレイブック/swipeへ>`
- **運用時オンライン評価（EDDOps）:** `<出稿後results・投稿後反応をどう次のeval/初期仮説に還流するか>`
- **learner蒸留:** `<別インスタンス（claude -p等）で蒸留し、出力のみ本体に反映。context保護>`
> ⚠️ **落とし穴:** 蒸留を本体セッション内でやるとcontextを汚す。入力（feedback蒸留）と出力（LEARNING.md更新）を分離する。評価証跡が「次の開発の初期仮説」と「evalの更新」を駆動する閉ループにする。
---
## Step8 冪等性・再開・監査
- **state管理:** `<state.json / .state.json に何を持つか。中断→再開できるか>`
- **環境起動:** `<init.sh 相当。1コマンドで再現可能な状態へ>`
- **セッション起動プロトコル:** `<pwd → 進捗ファイル読込 → 最優先未完了タスク選択 → init起動 → E2Eサニティ>`
- **多重起動防止:** `<ロック + PID check。launchd協調（1run上限・次回起動と衝突しない）>`
- **監査証跡:** `<failed.log は消さない。なぜfailedかを後から遡れる>`
> ⚠️ **落とし穴:** 各セッションは前回の記憶を持たない前提で設計する。部分失敗で全体をabortさせず、failed.logに記録して続行。長期ハーネスには人間可読な進捗サマリ（claude-progress.txt相当）を置く。
---
## Step9 段階推移 — オーガニック → automation
- **初回（手動・手探り）でやること:** `<>`
- **automation化のトリガー（パターン確定の判定）:** `<例: 同じ手順を3回成功で再現できたら>`
- **automation後の形:** `<launchd日次 / cron週次 / 対話オンデマンドの使い分け>`
> ⚠️ **落とし穴:** automation first は反復の敵。パターンが固まる前に自動化すると、間違った手順を高速で量産する。複雑化（並列マルチエージェント協調）は最後、成果実証後。
---
## プリフライト・チェックリスト（着手前ゲート）
> [`playbook.md`](./playbook.md) のアンチパターン自問。**1つでもYesなら設計に戻る。**
- [ ] フレームワークのループに制御フローを隠蔽させていないか？（→自分で明示的に書く）
- [ ] 決定的処理（差分・集計・勝ち判定・投票）をLLMに任せていないか？（→コード/SQLへ）
- [ ] コード検証も承認もない長いフルオート連鎖になっていないか？
- [ ] evalを書かずに実装に入ろうとしていないか？（→最低3シナリオ先に）
- [ ] 検証手段（終了コード/lint/E2E/敵対レビュー）なしで出荷しようとしていないか？
- [ ] CLAUDE.md / SKILL.md が肥大化していないか？（→500行ルール・1階層参照・各行「消すとミスするか？」）
- [ ] 全APIエンドポイントをツール化していないか？（→高インパクトに絞り統合）
- [ ] UUID等の低レベルIDをLLMに返していないか？（→意味的ラベルに解決）
- [ ] 成果を実証する前に並列マルチエージェントへ複雑化していないか？
- [ ] kitchen sink（無関係タスク混在）になっていないか？（→/clear、2回失敗で初期プロンプト書き直し）
- [ ] 同一ペルソナ・同一モデルの多エージェント判定になっていないか？（→多様性確保・信頼性測定）
- [ ] 脆いハードコードif-elseのプロンプトになっていないか？（→ヒューリスティクス+just-in-time検索）
---
## 完了の定義（Definition of Done）
- [ ] **evalが通る:** Step1の3シナリオ（typical/edge/known-failure）全てが合格基準を満たす
- [ ] **検証手段がある:** 人間に頼らず合否を判定できるコードゲート（lint/終了コード/E2E/敵対レビュー）が動く
- [ ] **冪等:** 中断→再実行しても壊れない。state管理・多重起動防止が効く
- [ ] **ドキュメント化:** この計画が埋まり、SKILL.md/READMEと実体パスが一致（report時に `find`/`ls` で確認）
---
## 付録: 記入例（広告リサーチHarness を当てはめた断片）
> 実在の ad-research を本テンプレに通した抜粋。粒度の参考に。
- **Step0 適合判定:** ☑ **スキル**（再利用する能力。定期差分リサーチで何度も起動）。理由＝手順は概ね固定（収集→解析→差分→レポート）で、内部の差分判定は決定論。
- **返却契約:** 白ベースHTMLレポート + MD版 + テーマ別swipeファイル（`themes/{theme}/swipe/`）+ 日次差分サマリー（`daily/YYYY-MM-DD.{md,html}`）。クリエイティブはPNG実体リンク。
- **Step1 eval:**
- typical = 「この訴求の競合を調べて」→ Meta+X横断取得し10項目カルテ化、勝ち判定が出る／合格＝出典クリエイティブPNGとカルテ10項目が全て埋まる。
- edge = kashikaセッション期限切れ／合格＝0件でも落ちず「ログイン要」を明示し部分結果を返す。
- known-failure = YouTube広告を取りに行こうとする／合格＝対応外（Meta+Xのみ）と正直に縮退。
- **Step4 判定層:** 差分判定は `diff_state.mjs` が state.db と突合し 🆕/✏️改訂/📈スケール/📉停止 を**コードで**決定。LLMはカルテの言語化のみ。
- **Step7 自己改善:** 勝ちクリエイティブ → `swipe/` 昇格（grep引き型・量増で価値↑）。週次は分析Harnessが `own-winners.md` に昇格 → 制作Harnessで再利用 → 複利ループ。
---
### 参照
- 方法論・原則・アンチパターン全文: [`playbook.md`](./playbook.md)
- 評価セットの記法: [`eval-template/`](./eval-template/)
- 出典（公式）: [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) / [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) / [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) / [Writing tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents) / [Agent Skills best-practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) / [Claude Code best-practices](https://code.claude.com/docs/en/best-practices)
- 出典（海外）: [12-Factor Agents](https://github.com/humanlayer/12-factor-agents) / [Benchmarking Multi-Agent Architectures](https://www.langchain.com/blog/benchmarking-multi-agent-architectures) / [Don't Build Multi-Agents](https://cognition.ai/blog/dont-build-multi-agents) / [EDDOps (arXiv 2411.13768)](https://arxiv.org/abs/2411.13768)
typical / edge / known-failure を実装前に書く（eval-driven development）。
# eval: <ハーネス/スキル名> — 3シナリオ評価 > コピーして使う雛形。`<...>` を置換し、まず3行(typical/edge/known-failure)を埋める。 > **着手前に記入 → ベースライン測定(初期は全 fail 想定) → 最小指示を書いて再測定**の順で回す。 > 詳しい運用は同ディレクトリの [`README.md`](./README.md) を参照。 - 対象: `<対象ハーネス/スキル/ワークフロー>` - 作成日 / 更新日: `<YYYY-MM-DD>` - ベースライン取得条件: `<素のモデル / 旧版コミットhash など>` - 現在の取得条件: `<対象のコミットhash / 日付>` --- ## シナリオ表 `合格基準` は **pass/fail が機械的に判定できる述語**で書く(コード/正規表現/件数範囲/スキーマ検証)。LLM-as-judge を使う場合は軸と閾値・run回数を明記。 | シナリオID | 種別 | 入力 | 期待される振る舞い | 合格基準(機械的 pass/fail) | ベースライン結果 | 現在の結果 | |-----------|------|------|------------------|---------------------------|----------------|-----------| | `EV-001` | typical | `<代表入力をそのまま>` | `<理想の振る舞いを具体的に>` | `<例: 出力JSONがスキーマvalid かつ findings>=3>` | `fail: <何が起きたか>` | `<pass / fail: 理由>` | | `EV-002` | edge | `<境界・空・上限超え・曖昧>` | `<壊れずに正しく扱う / 安全に断る>` | `<例: 0件入力で例外を出さず空配列+理由を返す>` | `fail: <…>` | `<…>` | | `EV-003` | known-failure | `<過去に実際に失敗した入力>` | `<その失敗をしないこと>` | `<例: 出力に絵文字・誇大表現が grep で0件>` | `fail: <再現した失敗>` | `<…>` | > known-failure 行は、人間FB・運用での事故(failed.log / decisions.md)が出るたびに `EV-004`, `EV-005`... と**追記して増やす**。これが回帰テスト資産。 --- ## 記入例(そのまま雛形として参考に / 初期は全 fail) 対象例: `deep-verify`(問い→観点分解→検証→Markdownレポート) | シナリオID | 種別 | 入力 | 期待される振る舞い | 合格基準(機械的 pass/fail) | ベースライン結果 | 現在の結果 | |-----------|------|------|------------------|---------------------------|----------------|-----------| | `EV-001` | typical | 「2026年の日本のHNWI世帯数は?」 | 観点分解→並列調査→出典付きで数値を1つ提示。両論ある場合は併記 | `report_markdown` が非空。`key_findings>=1`。全数値主張に `[n]` 出典番号が付き、`sources[]` に対応URLが存在(無出典主張が1つでもあれば fail) | `fail: 出典番号なしで数値を断定` | `pass` | | `EV-002` | edge | 「あれについて調べて」(対象が曖昧) | 曖昧と判定し、断定せず明確化を促す or `open_questions` に不足情報を列挙 | `stats.confirmed==0` のとき `open_questions>=1` を返す。曖昧入力で確定的主張を出したら fail(出力に「である」断定+confidence:high が同時に出ない) | `fail: 勝手に解釈して断定` | `pass` | | `EV-003` | known-failure | 「Xは100%安全」のような検証不能/誇大な命題を含む問い | 過半 refute で棄却し `refuted[]` へ。レポート本文に誇大表現を残さない | 当該主張が `refuted[]` に含まれ、`report_markdown` に「100%」「絶対」等の禁止語が正規表現で0件(残れば fail) | `fail: 誇大表現をそのまま要約に転記` | `pass` | ### LLM-as-judge を使う行の書き方(品質系のみ) | シナリオID | 種別 | 入力 | 期待される振る舞い | 合格基準(LLM-judge) | ベースライン結果 | 現在の結果 | |-----------|------|------|------------------|---------------------|----------------|-----------| | `EV-004` | typical | 「経営者向けX記事を生成」 | 戸野塚の声・論理の流れが一貫 | **別インスタンス**(`claude -p`)が5軸(滞在/完読/共有/翻訳/ブクマ 各0-10)で採点。**3 run の平均>=40/50 かつ 分散<=σ目安**。同一インスタンスでの自己採点は不可 | `fail: 平均34, 声が崩れる` | `pass: 平均42 (σ2.1)` | --- ## 実行ログ(任意) | 日付 | 取得条件(hash) | 変更内容 | pass数/全数 | 回帰の有無 | |------|---------------|---------|-----------|-----------| | `<YYYY-MM-DD>` | `<baseline>` | ベースライン測定 | `0/3` | — | | `<YYYY-MM-DD>` | `<hash>` | `<最小指示を追加>` | `<2/3>` | なし | > 過去に pass した行が fail に転じたら**回帰**。即修正してから他を進める。