autoresearch

スキルの自動研究

ほとんどのスキルは、約70％の確率でうまく機能します。残りの30％では、使いものにならない出力が生成されます。解決策は、スキルを一から書き直すことではありません。エージェントに何十回も実行させ、出力をすべて評価し、その30％がなくなるまでプロンプトを調整することです。

このスキルは、Andrej Karpathy の自動研究手法（自律的な実験ループ）を Claude Code のスキルに応用したものです。ML のトレーニングコードを最適化する代わりに、スキルのプロンプトを最適化します。

---

中核となる作業

既存のスキルを選び、「良い出力」とはどのようなものかを二択のチェック項目で定義してから、自律的なループを実行します。

1. テスト入力を使ってスキルから出力を生成する
2. すべての出力を評価基準に照らして採点する
3. 失敗を修正するようにスキルのプロンプトを変更する
4. スコアを改善する変更は残し、それ以外は破棄する
5. スコアが上限に達するか、ユーザーが停止するまで繰り返す

出力： 改善された SKILL.md、results.tsv のログ、試した変更をすべて記録した changelog.md、およびブラウザーで確認できるライブ HTML ダッシュボード。

---

開始前：コンテキストを確認する

停止してください。以下のすべての項目がユーザーに確認できるまで、実験を実行しないでください。不足している項目があれば、先に確認してください。

1. 対象スキル — どのスキルを最適化しますか？（SKILL.md の正確なパスが必要です）
2. テスト入力 — スキルをテストするために、どのような異なるプロンプトやシナリオを3～5個用意しますか？（多様性が重要です。特定のシナリオに過剰適合しないよう、異なるユースケースをカバーする入力を選んでください）
3. 評価基準 — 良い出力を定義する二択のチェック項目を3～6個挙げてください。（これらは「テスト質問」です。適切な評価項目の作成方法については、eval-guide.md を参照してください）
4. 実験ごとの実行回数 — 変更ごとにスキルを何回実行しますか？デフォルト：5回。（実行回数が多いほどスコアの信頼性は高まりますが、時間とコストが増えます。ほとんどのスキルでは5回が適切です）
5. 実行間隔 — 実験サイクルをどのくらいの頻度で実行しますか？デフォルト：2分ごと。（間隔が短いほど反復は速くなりますが、コストも増えます）
6. 予算上限 — 任意。停止するまでの実験サイクルの最大数です。デフォルト：上限なし（停止するまで実行します）。

---

ステップ1：スキルを読む

何も変更する前に、対象スキルをすべて読み、内容を理解してください。

1. SKILL.md ファイルを最後まで読む
2. スキルが参照している references/ 内のファイルを読む
3. スキルの中核となる作業、手順、出力形式を特定する
4. スキルに既存の品質チェックやアンチパターンがあれば記録する

この手順を省略しないでください。改善する前に、スキルの機能を理解する必要があります。

---

ステップ2：評価スイートを作成する

ユーザーの評価基準を、構造化されたテストに変換します。各チェック項目は二択にしてください。合格か不合格のみとし、段階評価は使いません。

各評価項目の形式：

EVAL [number]: [Short name]
Question: [Yes/no question about the output]
Pass condition: [What "yes" looks like — be specific]
Fail condition: [What triggers a "no"]

適切な評価項目のルール：

• 二択のみ。はいかいいえで答えられるものにします。「1～7で評価する」のような尺度は使いません。尺度はばらつきを増幅させ、信頼できない結果につながります。
• 一貫した判定ができる程度に具体的にします。「文章は読みやすいですか？」では曖昧すぎます。「すべての単語のスペルが正しく、文が途中で途切れていないか？」であれば検証できます。
• スキルが評価項目を攻略できるほど狭くしないでください。「200語未満であること」とすると、ほかのすべてを犠牲にして簡潔さを最適化することになります。
• 評価項目は3～6個が適切です。これを超えると、スキルは実際に改善するのではなく、評価基準をそのまま繰り返し始めます。

適切な評価項目と不適切な評価項目の詳細な例については、eval-guide.md を参照してください。

最大スコアの計算：

max_score = [number of evals] × [runs per experiment]

例：評価項目4個 × 5回の実行 = 最大スコア20。

ステップ 3：ライブダッシュボードを生成する

実験を実行する前に、autoresearch-[skill-name]/dashboard.html にライブ HTML ダッシュボードを作成し、ブラウザーで開きます。

ダッシュボードには以下を表示する必要があります。

• 10 秒ごとに自動更新する（results.tsv を読み込みます）
• スコアの推移を折れ線グラフで表示する（X 軸は実験番号、Y 軸は合格率 %）
• 各実験を色付きのバーで表示する：緑 = 維持、赤 = 破棄、青 = ベースライン
• すべての実験を次の項目とともに表で表示する：実験番号、スコア、合格率、ステータス、説明
• 評価項目ごとの内訳を表示する：全実行を通じて最も合格数の多い／少ない評価項目
• 現在のステータスを表示する：「実験 [N] を実行中...」または「待機中」
• 落ち着いた色使い（白背景、パステルカラーのアクセント、すっきりしたサンセリフフォント）で見やすくスタイリングする

CSS と JavaScript をインラインで記述した、単一の自己完結型 HTML ファイルとしてダッシュボードを生成します。折れ線グラフには CDN から読み込んだ Chart.js を使用します。JavaScript は results.json を取得して再描画する必要があります（results.json は各実験後に results.tsv とあわせて更新します）。

作成後、すぐにダッシュボードを開きます。macOS の場合は open dashboard.html を実行して、ユーザーがブラウザーで確認できるようにします。

ダッシュボードを最新の状態に保つため、各実験後に results.json を更新します。JSON の形式：

{
  "skill_name": "[name]",
  "status": "running",
  "current_experiment": 3,
  "baseline_score": 70.0,
  "best_score": 90.0,
  "experiments": [
    {
      "id": 0,
      "score": 14,
      "max_score": 20,
      "pass_rate": 70.0,
      "status": "baseline",
      "description": "original skill — no changes"
    }
  ],
  "eval_breakdown": [
    {"name": "Text legibility", "pass_count": 8, "total": 10},
    {"name": "Pastel colors", "pass_count": 9, "total": 10}
  ]
}

実行が終了したら（ユーザーが停止した場合、または上限に達した場合）、status を "complete" に更新して、ダッシュボードに最終サマリーと「完了」状態を表示します。

---

ステップ 4：ベースラインを確立する

変更を加える前に、スキルをそのまま実行します。これが実験 #0 です。

1. スキルのフォルダー内に作業ディレクトリー autoresearch-[skill-name]/ を作成します
2. ヘッダー行を含む results.tsv を作成します
3. results.json と dashboard.html を作成し、ダッシュボードをブラウザーで開きます
4. 元の SKILL.md を SKILL.md.baseline としてバックアップします
5. テスト入力を使ってスキルを [N] 回実行します
6. すべての出力を、すべての評価項目に照らして採点します
7. ベースラインスコアを記録し、results.tsv と results.json の両方を更新します

results.tsv の形式（タブ区切り）：

experiment	score	max_score	pass_rate	status	description
0	14	20	70.0%	baseline	original skill — no changes

重要： ベースラインを確立した後、先に進む前にスコアをユーザーに確認します。ベースラインがすでに 90% 以上の場合、スキルの最適化は不要かもしれません。続行するかどうかをユーザーに確認してください。

---

ステップ 5：実験ループを実行する

これは自動リサーチループの中核です。開始したら、停止されるまで自律的に実行します。

ループ：

1. 失敗を分析する。 どの評価で最も多く失敗しているかを確認します。失敗した実際の出力を読みます。パターンを特定します。書式の問題ですか？指示の不足ですか？それとも指示が曖昧ですか？

2. 仮説を立てる。 変更することを1つ選びます。一度に5つ変更してはいけません。何が効果をもたらしたのか分からなくなります。

   効果的な変更：

   • 最も多い失敗に対処する具体的な指示を追加する
   • 曖昧な指示を、より明確に言い換える
   • 繰り返し発生するミスに対して、アンチパターン（「Xをしてはいけません」）を追加する
   • 埋もれている指示をスキル内のより上位に移動する（優先度 ＝ 位置）
   • 正しい動作を示す例を追加または改善する
   • 他のことを犠牲にして1つのことを過剰に最適化する原因となっている指示を削除する

   効果のない変更：

   • スキル全体を一から書き直す
   • 一度に新しいルールを10個追加する
   • 具体的な理由もなくスキルを長くする
   • 「改善してください」や「もっと創造的に」といった曖昧な指示を追加する

3. 変更を加える。 SKILL.md を編集し、対象を絞った変更を1つ加えます。

4. 実験を実行する。 同じテスト入力でスキルを [N] 回実行します。

5. 採点する。 すべての出力をすべての評価にかけます。合計スコアを計算します。

6. 採用するか破棄するかを決める。

   • スコアが向上した → 採用。 記録します。これを新たなベースラインとします。
   • スコアが変わらなかった → 破棄。 SKILL.md を以前のバージョンに戻します。変更によって複雑さが増しただけで、改善はありませんでした。
   • スコアが低下した → 破棄。 SKILL.md を以前のバージョンに戻します。

7. 結果を results.tsv に記録する。

8. 繰り返す。 ループのステップ1に戻ります。

絶対に停止しないでください。 ループを開始したら、続けるべきかユーザーに確認するために一時停止してはいけません。ユーザーがコンピューターから離れている可能性があります。次のいずれかに該当するまで、自律的に実行します。

• ユーザーが手動で停止する
• 予算の上限（設定されている場合）に達する
• 95％以上の合格率を実験3回連続で達成する（効果が逓減するため）

アイデアが尽きた場合： 失敗した出力をもう一度読みます。以前の惜しい変更を2つ組み合わせてみます。同じ問題にまったく異なるアプローチを試します。追加するのではなく、削除してみます。スコアを維持したまま単純化できれば成功です。

---

ステップ 6：変更履歴を書く

採用・破棄にかかわらず、実験のたびに changelog.md に追記します。

## Experiment [N] — [keep/discard]

**Score:** [X]/[max] ([percent]%)
**Change:** [One sentence describing what was changed]
**Reasoning:** [Why this change was expected to help]
**Result:** [What actually happened — which evals improved/declined]
**Failing outputs:** [Brief description of what still fails, if anything]

この変更履歴は、最も価値のある成果物です。今後のエージェント（または将来のより賢いモデル）が引き継いで続行できる、調査記録です。

---

ステップ 7：結果を提示する

ユーザーが戻ったとき、またはループが停止したとき、次の内容を提示します。

1. スコアの概要： ベースラインスコア → 最終スコア（改善率）
2. 実行した実験の合計数： 試した変更の数
3. 採用率： 採用した変更と破棄した変更の数
4. 特に効果があった変更トップ3（変更履歴から）
5. 残っている失敗パターン（スキルがまだ間違える点があれば）
6. 改善済みの SKILL.md（すでに所定の場所に保存済み）
7. 参照用の results.tsv と changelog.md の場所

---

出力形式

このスキルは autoresearch-[skill-name]/ に4つのファイルを作成します。

autoresearch-[skill-name]/
├── dashboard.html       # live browser dashboard (auto-refreshes)
├── results.json         # data file powering the dashboard
├── results.tsv          # score log for every experiment
├── changelog.md         # detailed mutation log
└── SKILL.md.baseline    # original skill before optimization

さらに、改善済みの SKILL.md を元の場所に保存します。

results.tsv の例：

experiment	score	max_score	pass_rate	status	description
0	14	20	70.0%	baseline	original skill — no changes
1	16	20	80.0%	keep	added explicit instruction to avoid numbering in diagrams
2	16	20	80.0%	discard	tried enforcing left-to-right layout — no improvement
3	18	20	90.0%	keep	added color palette hex codes instead of vague "pastel" description
4	18	20	90.0%	discard	added anti-pattern for neon colors — no improvement
5	19	20	95.0%	keep	added worked example showing correct label formatting

---

例：図表生成スキルの最適化

収集したコンテキスト：

• 対象スキル：~/.claude/skills/diagram-generator/SKILL.md
• テスト入力：「OAuth フロー図」、「CI/CD パイプライン」、「マイクロサービスアーキテクチャ」、「ユーザーオンボーディングファネル」、「データベーススキーマのリレーションシップ」
• 評価項目：（1）すべてのテキストが読みやすく、スペルも正しいか？（2）パステルカラー／柔らかな色だけを使用しているか？（3）左から右、または上から下への直線的なレイアウトか？（4）数字、序数、順序を示す表現がないか？
• 実験ごとの実行回数：10
• 最高スコア：40

ベースライン実行（実験 0）： 図を 10 点生成しました。それぞれを 4 つの評価項目で採点しました。結果：32/40（80%）。 よく見られた失敗：3 点の図に手順番号があり、2 点の図に鮮やかな赤の要素があり、3 点の図で小さな文字が読みにくくなっていました。

実験 1 — 採用（35/40、87.5%）： 変更：「図に手順番号、序数（1st、2nd）、または順序を示す数値表現を絶対に含めないでください」をアンチパターンのセクションに追加しました。 結果：番号に関する失敗が 3 件から 1 件に減りました。他の評価項目は維持されました。

実験 2 — 破棄（34/40、85%）： 変更：「すべての文字のフォントサイズを最低 14px にしてください」を追加しました。 結果：読みやすさは 1 点改善しましたが、色の遵守度が 2 点低下しました。変更を元に戻しました。

実験 3 — 採用（37/40、92.5%）： 変更：「パステルカラー」という曖昧な指示を、具体的な 16 進数カラーコードに置き換えました：#A8D8EA, #AA96DA, #FCBAD3, #FFFFD2, #B5EAD7。 結果：色の評価が 8/10 から 10/10 に上がりました。他の評価項目は維持されました。

実験 4 — 破棄（37/40、92.5%）： 変更：「赤（#FF0000）、オレンジ（#FF8C00）、またはネオングリーン（#39FF14）を使わないでください」というアンチパターンを追加しました。 結果：変化なし。実験 3 のカラーコードですでに色の問題が解決していました。スキルをシンプルに保つため、変更を元に戻しました。

実験 5 — 採用（39/40、97.5%）： 変更：適切に書式設定されたラベル（数字なし、パステルカラーの塗りつぶし、左から右への流れ、読みやすい文字）を備えた正しい図の作成例を追加しました。 結果：39/40 に到達しました。残った失敗は、複雑な図でラベルが重なった 1 件です。改善効果が薄れてきたため、ここで終了しました。

最終結果：

• ベースライン：32/40（80%）→ 最終：39/40（97.5%）
• 実験 5 回、採用 3 回、破棄 2 回
• 主な変更点：色の具体的な 16 進数コード、番号を禁止する明確なルール、作成例
• 残った問題：非常に複雑な図では、まれにラベルが重なることがあります（失敗率 1/40）

---

他のスキルとの連携

autoresearch に入力されるもの：

• 最適化が必要な既存のスキル
• ユーザー定義の評価基準（または評価ガイドを使った評価項目の定義支援）

autoresearch から出力されるもの：

• 改善されたスキルが元のスキルに置き換わります
• 変更履歴を将来のモデルに渡し、最適化を続けることができます
• 評価スイートは、スキルを更新するたびに再利用できます

---

テスト

優れた autoresearch の実行では、次のことが行われます。

1. ベースラインから開始する — 開始時点を測定する前に、何も変更しません
2. 二値の評価項目だけを使う — 尺度や主観的な評価、「1〜10 で評価してください」は使いません
3. 一度に 1 つだけ変更する — どの変更が効果をもたらしたのかを正確に把握できます
4. 完全なログを残す — 採用・破棄にかかわらず、すべての実験を記録します
5. スコアを改善する — ベースラインから最終結果まで、測定可能な改善を実現します
6. 過学習しない — 特定のテスト入力に合格するだけでなく、スキルが実際のタスクをより適切にこなせるようにします
7. 自律的に実行する — 実験の合間に許可を求めて停止しません

スキルがすべての評価項目に「合格」しても、実際の出力品質が改善していない場合は、スキルではなく評価項目に問題があります。手順 2 に戻り、より適切な評価項目を作成してください。