← 投資Library / まなびの時間 / EMPIRICAL PROMPT TUNING
ACCURACY CURVE
ITER 0
0%
ITER 1
75%
ITER 2
88%
ITER 3
88%
EMPIRICAL PROMPT TUNING · CASE STUDY

Claude Code スキル群を
empirical-prompt-tuning で堅牢化した実録

4 ITERATIONS · 8 DISPATCHES · 13 MIN

プロンプトの品質は書いた本人には分からない。
バイアスを排した実行者に動かしてもらい、
両面で評価して反復する ― その実測記録。

QUICK START
⚡ 結論（5行） 📈 測定データ 🐞 発見バグ3件 ⚠ 過適合の罠 🧩 応用法
現在地 YOU ARE HERE
📚投資Library
📂まなびの時間
📝empirical-prompt-tuning 実録
📄Claude Code Setup
📄記憶を設計する
📄メモの複利
📄話し方で変わる
📖 APPROX. 15 MIN READ
目次 CONTENTS
  1. 00この記事で分かること
  2. 01結論 — ビフォーアフター
  3. 02empirical-prompt-tuning とは
  4. 03対象と初期状態
  5. 04Iter 0→3 の測定データ
  6. 05発見された critical バグ 3件
  7. 06過適合の罠と Red flags
  8. 07あなたの応用法
  9. 08導入手順 — 今日始める
00

この記事で分かること

プロンプトや AI スキルを書いたあと、「これで伝わるか」を正しく評価する方法はあるのか。
結論から言うと、ある。自分で読み直すのではなく、別の AI に白紙で読ませて、両面で評価する。これが mizchi 氏が公開している empirical-prompt-tuning スキルの核だ。

GOAL OF THIS ARTICLE
1. empirical-prompt-tuning が「書き手の自己評価」と構造的にどう違うか分かる
2. 実測データ（精度・tool_uses・duration）で 4 イテレーションの変化を追える
3. 見つかった critical バグ 3 件・過適合 1 件の具体例が見える
4. 自分のプロンプト・スキル・CLAUDE.md に今日から応用できる

対象は筆者の brand-context.md と ~/.claude/rules/ 配下 6 ファイル。
よくある「改善したつもり」ではなく、成功/失敗・精度・ステップ数・所要時間を毎回記録した。数字はすべてこの記事で公開する。

01

結論 — 5行でわかるビフォーアフター

細かい話は後に譲り、何が起きたのかだけ先に示す。

TL;DR
1. rules 系は critical 基準で 0/8 → 7/8（87.5%）に改善、連続クリアで収束
2. brand-context は 2/7 → 6/7 まで上がったが、Iter 3 で 5/7 にリグレッション（過適合）
3. 所要時間は合計 約 13 分（subagent dispatch 8 回・tool_uses 合計 32）
4. 修正の 60% は「軸名から推測した修正が判定文言に届かない」ゼロ振れパターンで、閾値文言レベルで紐付けが必須と判明
5. 自作プロンプトは例外なく 「自分では読めない」ことが数字で出た
BEFORE — 審査前
「自分で読み直せば問題ない」
「これで伝わるはず」
数字は存在しない。主観の自己採点。
critical 要件の ほぼ全てに抜けがあった。
AFTER — 4イテレーション後
別エージェントが実測で判定。
rules 系は 8 項目中 7 項目クリア・連続収束。
どの修正が何に効いたか行単位で追える。
「直感で書いた」箇所が全て可視化された。
02

empirical-prompt-tuning とは何か

mizchi 氏が公開した Claude Code スキル。プロンプトや skill を「バイアスを排した実行者」に動かしてもらい、両面で評価して反復するためのプロトコル集。

プロンプトの品質は書いた本人には分からない。
書き手が「明瞭だ」と思うものほど、別エージェントが読むと詰まる。
— empirical-prompt-tuning SKILL.md 冒頭

やっていることは単純だ。ただし、独りでは絶対に到達できない構造になっている。

評価シナリオと要件チェックリストを事前に固定
シナリオ 2〜3 本（中央値 1 + edge 1〜2）と、成果物が満たすべき 3〜7 項目を事前に決める。後から動かさない。要件には必ず [critical] タグ付き項目を最低 1 つ含める。
白紙の subagent を dispatch
対象プロンプトを 新規 subagent に Task tool で渡す。自己再読は禁止（直前に書いた文章を客観視することは構造的に不可能）。同一 subagent の再利用も禁止（前回の改善を学習している）。
両面評価 — 自己申告 + 指示側メトリクス
subagent が返す「不明瞭点」「裁量補完」「再試行」を抽出。Task tool の usage メタから tool_uses と duration_ms を取る。成功判定は [critical] 項目が全て ○のときだけ。
1 イテレーション 1 テーマで差分適用
不明瞭点を潰す最小修正を入れる。複数テーマを一気に触らない。修正前に「この修正が判定文言のどれを満たすか」を明示する（軸名から推測した修正は届かないことが多い）。
連続 2 回クリアで収束判定
新規不明瞭点 0 件・精度改善 +3 ポイント以下・ステップ数 ±10% 以内・duration ±15% 以内を 連続 2 回満たせば停止。重要度が高いものは 3 連続。
WHY THIS WORKS
自分で書いた文章を自分で評価すると、文脈を補完して読めてしまう。白紙の subagent は補完できない。だから「本当に伝わる文章」と「書き手の脳内でだけ伝わる文章」の差が数字で出る。この差を 4 回潰すだけで、プロンプトは別物になる。
03

チューニング対象と初期状態

筆者が Claude Code の運用で毎日使っている自作プロンプト群のうち、特に重要度が高い 2 系統を対象にした。

対象 A: brand-context.md 7 要件
X 発信用エージェントチーム全体のブランド設定。ペルソナ・トーン・コンテンツピラー・投稿スケジュール・禁止事項を定義。他の全エージェントが参照する基盤ファイル。ここが曖昧だと下流全体がぶれる。
対象 B: ~/.claude/rules/ 配下 6 ファイル 8 要件
セッション開始・3 点保存・引継ぎ・コミュニケーション・プロンプト最適化・コンテキスト監視。Claude Code が起動するたびに読み込まれる行動ルール。ここが壊れるとセッション全体が事故る。

初期状態は、率直に言って 「自分では読めたつもりで書いたもの」だった。Iter 0（静的整合チェック）で、すでに次のような問題が顕在化した。

ITER 0 — 初期問題点
brand-context.md: コンテンツピラー数が本文冒頭で「4 本柱」、末尾で「5 本柱」と矛盾。トーン定義は「丁寧」と「断言」が並置されたまま、どう両立するかのルール無し。禁止事項は抽象語のみで NG/OK 対比なし。

rules 配下: 「引継ぎトリガー」が「必要に応じて」とだけ書いてあり、定量的な発火条件なし。3 点保存の「3 点」がどの 3 箇所を指すかファイルによって解釈が違う。相対パスと絶対パスが混在。「往復」の定義が context-monitor と handoff で食い違っていた。
04

Iter 0→3 の測定データ（全数字公開）

4 イテレーション分を両面評価プロトコルで回した結果がこれだ。数字はすべて subagent の Task tool usage メタからの実測で、筆者の主観採点は含まない。

A. BRAND-CONTEXT.MD (7 REQUIREMENTS)

イテレーション 要件達成 critical tool_uses duration 判定
Iter 02/7×1≈ 60s×
Iter 14/7○1≈ 60s○
Iter 26/7○1≈ 60s○
Iter 35/7○1≈ 60s↓ 過適合
BRAND-CONTEXT — ACCURACY %
ITER 0
28.5%
ITER 1
57.1%
ITER 2
85.7%
ITER 3
71.4%
Iter 3 でリグレッション。subagent の要求粒度が回を追うごとにインフレし、過剰に厳しい基準で判定した影響（詳細は 06）。

B. RULES/ 配下 (8 REQUIREMENTS)

イテレーション 要件達成 critical tool_uses duration 判定
Iter 00/8×7≈ 60s×
Iter 16/8○7≈ 88s○
Iter 27/8○7≈ 76s○
Iter 37/8○7≈ 441s○ 収束
RULES — ACCURACY %
ITER 0
0%
ITER 1
75%
ITER 2
87.5%
ITER 3
87.5%
rules 系は連続 2 回クリア（Iter 2-3）で収束判定。Iter 3 の duration 441s は並列 dispatch 負荷の影響で、改善失速ではない。
TOOL_USES の質的解釈
注目すべきは tool_uses が全イテレーションで安定していること。brand-context は 1 固定、rules は 7 固定。これは 「自己完結性が高い」シグナルだ。シナリオ間で 3〜5 倍以上のブレがあると、実行者が references を横断探索している＝skill 自体の構造欠陥の証拠になる。今回はその欠陥は無かった。
05

発見された critical バグ 3件

Iter 1 で subagent が次々と返してきた指摘のうち、critical タグが付いた最低ラインをブレイクしていた 3 件を抜粋する。いずれも 筆者の自己再読では発見できなかったものだ。

Bug #1: 3 点保存のスコープが曖昧 CRITICAL
症状: 「3 点保存」が指す 3 箇所が、更新対象のファイル種別によって異なるのに、ルール本文では全て同じように扱われていた。subagent は「設定ルール更新」と「運用ノート更新」で保存先が違うことに気づけず、誤った 3 箇所を選んだ。
修正: A. 設定・ルール系 と B. 運用ノート系 の 2 スコープに分割。それぞれの 3 箇所を明示。メタノート不在時のフォールバック（「新規作成しますか？」→却下時は 1・2 のみで完了）も追加。
Bug #2: 引継ぎトリガーが未定量 CRITICAL
症状: 「必要に応じて引継ぎ保存」としか書いておらず、subagent は「どの時点で発火するか」を判断できなかった。結果、保存タイミングが毎回ばらつくか、保存忘れが発生する。
修正: 4 トリガー条件を定量化 ―明示指示 / 200k 近接通知 / 30 往復超 + 残タスク有 / 大型リサーチで重くなった。「往復」の定義も context-monitor.md と統一してユーザーメッセージ数で自己カウント、と明示。
Bug #3: コンテンツピラー個数不一致 CRITICAL
症状: brand-context.md の冒頭で「コンテンツピラー 4 本柱」と宣言しておきながら、末尾のピラー一覧では 5 本が列挙されていた。subagent は「何本柱として扱えばよいか」で完全に詰まった。
修正: 「5 本柱」に統一。投稿スケジュールも曜日別ローテーションに具体化。ピラー間の比率（核 60% / 教養 20% / 実践 10% / 記録 10% など）も明示。
COMMON PATTERN
3 件とも共通して、「筆者の脳内で勝手に補完されていた文脈」が原因だ。書いた本人は「当然 A のことだ」と分かる。しかし白紙の subagent は A か B か決定できない。これが empirical 評価でしか発見できない欠陥の典型例。
06

過適合の罠と Red flags 実例

empirical-prompt-tuning は万能ではない。本事例でも brand-context の Iter 3 で精度が 6/7 → 5/7 に落ちるリグレッションが起きた。SKILL.md が事前に警告していた「過適合」の典型パターンだ。

観測された過適合 — brand-context Iter 3 REGRESSION
Iter 2 まで subagent は「明示されていれば OK」と判定していた要件について、Iter 3 では「さらに具体的な NG/OK 対比が必要」「ポスター文例まで含めるべき」と要求粒度が急にインフレした。結果、Iter 2 で ○ だった項目が Iter 3 で × に転落。

これは subagent 側の評価基準が回を追うごとに厳しくなる現象で、過適合の一類型。SKILL.md の「過適合チェック」節が警告していた挙動がそのまま起きた。対処は hold-out シナリオを追加して baseline 設計に戻すこと。

スキル自身が警告していた Red flags と、今回実際に遭遇したパターンの対応表がこれ。

合理化（やりがちな言い訳） 本事例で実際に起きたこと
「自分で読み直せば同じ効果がある」 Iter 0 の時点で rules 系は 0/8。自己再読では critical バグ 3 件どれも検出できていなかった。
「1 シナリオで充分」 brand-context は 7 要件のうち、edge ケース要件で Iter 1 から Iter 2 にかけて +2 改善。中央値シナリオだけなら見えなかった。
「不明瞭点ゼロが 1 回出たから終わり」 Iter 2 で rules が 7/8 クリア。ここで止めず Iter 3 を追加した結果、Iter 2 が偶然ではなく構造的に収束していることが確定した。
「複数の不明瞭点を一気に潰そう」 初回は誘惑に負けて複数修正を束ねかけたが、「何が効いたか追えない」と SKILL.md が警告していたので 1 テーマに絞った。結果、修正の寄与度が分離できた。
「メトリクスが良いから質的フィードバックは無視」 Iter 3 は精度こそ Iter 2 と同じ 87.5% だが、subagent の不明瞭点リストは新規項目ゼロで収束確定。メトリクスだけ見ていたら判定できなかった。
「書き直した方が早い」 rules 系は 0/8 から始まったが、差分修正だけで 7/8 まで到達した。書き直し衝動が来るのは 3 回以上不明瞭点が減らなかったときだけ、という SKILL.md の記述が実測で裏付けられた。
ZERO-SHIFT の頻度
SKILL.md が「修正の波及パターン」として示した 3 類型（保守 / 上振れ / ゼロ振れ）のうち、本事例で最も多かったのは 「軸名から推測した修正が判定文言に届かない」ゼロ振れ。つまり「これを直せば伝わるはず」という直感は、閾値文言レベルで紐付けないと約 60% が外れる。修正前に subagent に「この修正が判定のどれを満たすか」を言語化させるのが唯一の対策。
07

あなたの応用法 — クリエイター / 投資家 / 発信者向け

empirical-prompt-tuning はエンジニア専用ツールではない。AI に指示を渡す人すべてに効く。具体的にどう使えるか、3 パターン紹介する。

応用 1: X 発信の投稿テンプレ堅牢化 CREATOR
X 投稿作成プロンプトに「白紙の subagent が読んでも同じトーン・文字数・ハッシュタグ方針で投稿できるか」をシナリオ化する。要件は 5 項目前後（文字数 / トーン / 核心 / ハッシュタグ / 禁止ワード）。重要度の高いテーマ（自分の核コンテンツ）は 3 連続クリアまで回せば、代筆させても品質が揺らがない。
応用 2: 投資分析レポートの定型化 INVESTOR
決算レポート生成プロンプトに「財務 3 表からの引用位置」「主要指標の計算式」「結論セクションの粒度」を要件化。critical はデータの取り違え（前期比 vs 前年同期比など）に置く。手作業でやると年 1 度しか改訂しないプロンプトも、4 イテレーション回せば別物になる。
応用 3: CLAUDE.md / ルール設計の健全化 EVERYONE
今回の筆者ケースそのもの。「セッション開始時の動作」「保存ルール」「引継ぎ条件」を subagent に実行させて、詰まった箇所を可視化する。ここが曖昧だと他の全プロンプトが不安定化する基盤層なので、投下工数の ROI が極めて高い。
「いい指示が書けているか」という問いには、
主観では答えられない。数字で答える方法がある。
08

導入手順 — 今日から始める

empirical-prompt-tuning は 1 ファイルの Skill として Claude Code に組み込める。導入後に最初にやるべきことを最短ルートで示す。

skill 本体を入手
mizchi/chezmoi-dotfiles の SKILL.md をコピー。~/.claude/skills/empirical-prompt-tuning/SKILL.md に配置。
対象プロンプトを 1 つ選ぶ
「毎日使うけど挙動がブレる」プロンプトが最初の候補。CLAUDE.md の一節、発信用テンプレ、データ集計スクリプトの指示文など。重要度の低いものから始めず、頻繁に使うものから。
シナリオ 2 本＋要件チェックリストを事前に固定
紙に書き出してから Claude Code セッションを開く。セッション中に要件を追加・削除すると評価の妥当性が崩れる。要件には必ず [critical] タグを 1 つ以上。
Claude に「empirical-prompt-tuning で回して」と依頼
Skill が読み込まれていれば、Claude が subagent dispatch・両面評価・差分適用のループを自走する。人間は「修正案を採用するか」だけ判断すればよい。
連続 2 回クリアで止める
収束したら次のプロンプトへ。1 つのプロンプトを永遠に磨き続けない（リソース打ち切り＝80 点で出す判断）。
YOUR FIRST HALF-DAY
0〜15 分: skill 配置 + 対象プロンプト選定
15〜60 分: シナリオ 2 本 + 要件 5〜7 項目を紙に書く
60〜180 分: Iter 0→3 を Claude に回させる
180〜240 分: 差分修正を採用・3 点保存でルール系に反映

半日後、あなたの核プロンプト 1 本が「別物」になっている。
RELATED →
Claude Code を始める — 完全セットアップガイド
DEEPER →
話し方で変わる — プロンプト最適化の基本
REFERENCES & ATTRIBUTION