Claude Code スキルの自動最適化 — テキスト勾配で「職人芸プロンプト」を工学に変える

「プロンプトは職人芸」——そんな時代が終わりつつあります。

@yusuke_post さん が発表した X 記事 では、プロンプトエンジニアリングを自動化する研究を応用して Claude Code の Skills を自動最適化する手法が紹介されています。ヒアリングメモから SaaS 導入提案書を生成するスキルを題材に、4 イテレーションで 13.6 点のスコア改善を達成しました。

@kgsi さん も「この取り組みすごい、ナレッジが溜まっている企業や組織ほどこの仕組みで効果が出そう」と反応しています。

全体像：何がどう繋がっているのか

この記事で扱う内容を先に俯瞰します。

課題

Claude Code の Skills（SKILL.md）は、タスクの手順を定義する「指示書」です。しかし、良い指示書を書くのは難しく、試行錯誤が属人的になりがちです。

graph LR
    A["人間が SKILL.md を書く"] --> B["実行"]
    B --> C["結果がイマイチ"]
    C --> D["🤔 勘で修正<br/>（= 職人芸）"]
    D --> B
    style D fill:#f9c74f,color:#000

解決策：テキスト勾配による自動改善ループ

深層学習がパラメータを自動で最適化するように、SKILL.md を自動で最適化するのがテキスト勾配です。

graph TD
    A["① SKILL.md（現在の指示書）で実行"] --> B["② 出力を正解データと比較<br/>（人間の過去の成果物）"]
    B --> C["③ AI が差分を分析し改善点を言語化<br/>= テキスト勾配"]
    C --> D["④ テキスト勾配に従って<br/>SKILL.md を改訂"]
    D --> E["⑤ 改訂版で再実行"]
    E --> B

    C -.- F["例: 優先度の整理ステップが欠如している"]

    style C fill:#4ecdc4,color:#000
    style F fill:#f0f0f0,color:#555,stroke-dasharray: 5 5

4 回繰り返すだけで 13.6 点のスコア改善を達成。

一言でいうと

SKILL.md も結局は「プロンプト」です。人間が手で書くと主観や経験に依存する「職人芸」になってしまいます。そこで、スキルの利用結果をフィードバックとして、AI（LLM）自身に SKILL.md を改善させるのがこの手法の核心です。

「テキスト勾配」は深層学習そのものではない

「テキスト勾配」という名前から深層学習を直接使う印象を受けますが、実際には異なります。深層学習の「勾配降下法」という最適化ループの考え方だけを借用し、実際の改善処理は LLM が自然言語で行います。

graph LR
    subgraph DL["深層学習"]
        direction LR
        D1["数値の勾配"] --> D2["パラメータ（数値）を<br/>自動更新"]
    end

    subgraph TG["テキスト勾配"]
        direction LR
        T1["言葉のフィードバック"] --> T2["SKILL.md（文章）を<br/>LLM が自動改訂"]
    end

    DL -.- Note["借りているのは<br/>ループ構造だけ"]
    TG -.- Note

    style Note fill:#f0f0f0,color:#555,stroke-dasharray: 5 5

数学的な勾配計算は一切ありません。「出力のどこがダメだったか」を LLM に言語化させ、その指摘に基づいて SKILL.md を書き直す——これを繰り返すだけです。

深層学習との対比

要するに、「人間の過去の仕事を教師データに、AI が AI 用の指示書を自動で育てる」 仕組みです。以下のセクションでは、この仕組みの技術的背景、具体的な手法、実践方法を詳しく解説します。

背景：プロンプト最適化は何が難しいのか

2 つの根本的困難

プロンプトエンジニアリングには、2 つの本質的な課題があります。

1. LLM の不透明性: プロンプトが LLM にどのような影響を与えるのかを正確に把握することが難しい
2. 探索空間の広さ: 自然言語プロンプトの表現パターンは無限に近く、最適な表現の発見が困難

人手による試行錯誤では、再現性が低く、属人化しやすいという問題もあります。

既存のアプローチ

プロンプト自動最適化の研究は、大きく 4 つのパラダイムに分類されます。

@yusuke_post さんが採用したのは、3 番目のテキスト勾配ベースのアプローチです。

テキスト勾配とは何か

深層学習の勾配との類比

深層学習では、損失関数の勾配を計算し、パラメータを「誤差が減る方向」に更新します。テキスト勾配はこれと同じ考え方を自然言語に適用します。

graph LR
    subgraph DL["深層学習"]
        direction LR
        D1["損失関数<br/>Loss = 0.85"] --> D2["数値勾配<br/>∂L/∂w"]
        D2 --> D3["パラメータ更新<br/>w := w - α∇L"]
    end

    subgraph TG["テキスト勾配"]
        direction LR
        T1["評価結果<br/>要件定義が不足"] --> T2["テキスト勾配<br/>要件定義セクションを<br/>追加すべき"]
        T2 --> T3["プロンプト更新<br/>SKILL.md を改訂"]
    end

ProTeGi のアルゴリズム

ProTeGi（Prompt Optimization with Textual Gradients）は、Pryzant et al., EMNLP 2023 で提案された手法です。

graph TD
    subgraph Forward["Step 1: Forward（順伝播）"]
        F1["現在のプロンプトでタスク実行"] --> F2["出力を生成"]
    end

    subgraph Backward["Step 2: Backward（逆伝播）"]
        B1["Judge LLM が出力の<br/>失敗理由を言語化"] --> B2["テキスト勾配を生成"]
    end

    subgraph Update["Step 3: Update（更新）"]
        U1["勾配の反対方向に<br/>プロンプトを編集"]
    end

    subgraph Select["Step 4: Select（選択）"]
        S1["ビームサーチ/バンディットで<br/>最良の候補を選択"]
    end

    Forward --> Backward
    Backward --> Update
    Update --> Select
    Select -->|"次のイテレーション"| Forward

    style Backward fill:#4ecdc4,color:#000

• Forward: 現在のプロンプトでタスクを実行し、出力を生成する
• Backward: 別の LLM（Judge）が出力の失敗理由を自然言語で記述する。これが「テキスト勾配」
• Update: テキスト勾配の「反対方向」にプロンプトを編集する（指摘された欠陥を補う）
• Select: 複数の候補プロンプトからビームサーチやバンディットアルゴリズムで最良のものを選択

テキスト勾配の例:

「現在のプロンプトは、ヒアリング内容の優先度判定を指示していないため、顧客の主要課題と副次的要望が混在した提案書が生成されている。優先度に基づく整理ステップを追加すべき。」

TextGrad: PyTorch ライクな実装

TextGrad は ProTeGi の概念を PyTorch 風の API で実装したフレームワークです。

1
2
3
4
5
6

# TextGrad の概念的な使い方
variable = Variable(system_prompt, learnable=True)
output = llm(variable, input_data)
loss = evaluate(output, expected_output)
loss.backward()       # テキスト勾配を生成
optimizer.step()      # プロンプトを更新

loss.backward() がテキストによるフィードバックを生成し、optimizer.step() がそのフィードバックに基づいてプロンプトを書き換えます。

Skills の自動最適化：@yusuke_post さんのアプローチ

着想

既存のプロンプト自動最適化研究は「数文のプロンプト」を対象にしていました。@yusuke_post さんは、これをより長い構造化ドキュメントである Claude Code Skills（SKILL.md） に適用しました。

前提：Claude Code Skills とは

Skills は、SKILL.md ファイルにタスクの手順を定義すると、Claude Code がそれを参照して作業してくれる仕組みです。

.claude/skills/proposal-generator/
├── SKILL.md           # タスク手順（最適化対象）
└── references/
    └── template.md    # 出力テンプレート

最適化の仕組み

核心のアイデアはシンプルです。

「人間が過去に作成した成果物を正解データとして、実際にスキルを実行し、生成結果と正解データの差分を自動分析して、スキルを継続的に改善する」

graph TD
    A["1. 初版 SKILL.md でタスク実行"] --> B["2. 出力と正解データを比較"]
    B --> C["3. 6 軸で定量評価<br/>（テキスト勾配生成）"]
    C --> D["4. 勾配に基づいて<br/>SKILL.md を改訂"]
    D --> E["5. 改訂版で再実行"]
    E --> B

    style C fill:#4ecdc4,color:#000

題材：ヒアリングメモ → SaaS 導入提案書

実験の題材は、「ヒアリングメモから SaaS 導入提案書を自動生成する」スキルです。

• 入力: 顧客ヒアリングの議事録
• 正解データ: 人間が過去に作成した提案書
• 出力: スキルが自動生成した提案書

6 軸評価フレームワーク

テキスト勾配を定量化するために、以下の 6 軸（各 0〜100 点）で評価を実施しています。

4 イテレーションの結果

4 回の反復改善で 13.6 点のスコア改善 を達成しました。

graph LR
    subgraph I1["Iter 1: 初版"]
        A1["ベーススコア"]
        G1["勾配: 要件定義が不足<br/>優先度の整理がない"]
    end

    subgraph I2["Iter 2: 要件整理追加"]
        A2["スコア改善"]
        G2["勾配: 具体的な<br/>数値目標が欠如"]
    end

    subgraph I3["Iter 3: KPI・ROI 追加"]
        A3["スコア改善"]
        G3["勾配: 導入スケジュールの<br/>詳細度が不足"]
    end

    subgraph I4["Iter 4: 段階的導入計画追加"]
        A4["最終スコア<br/>+13.6 点改善"]
    end

    I1 --> I2 --> I3 --> I4

    style I4 fill:#4ecdc4,color:#000

各イテレーションで SKILL.md が具体的に進化し、出力の品質が段階的に向上しています。

DSPy vs TextGrad：どちらを選ぶか

NTT ドコモの検証 では、カスタマーサポート分類タスクで両手法を比較しています。

Skills の自動最適化には、「人間が読める手順書を育てる」という性質上、TextGrad のアプローチが適しています。スキルは最終的に人間がレビュー・編集するものであり、TextGrad が生成する「判断アルゴリズムの言語化」はそのまま SKILL.md の改善に使えます。

実践：自分のスキルに適用するには

Step 1: 正解データを準備する

過去に人間が作成した成果物を 3〜5 件用意します。これがスキルの「教師データ」になります。

正解データの例:
├── sample_1.md  # 過去に作成した提案書 A
├── sample_2.md  # 過去に作成した提案書 B
└── sample_3.md  # 過去に作成した提案書 C

Step 2: 評価基準を定義する

タスクに応じた評価軸を設計します。重要なのは定量化できることです。

1
2
3
4
5

# evaluation-criteria.md
1. 構成（0-100）: 必須セクションがすべて含まれているか
2. 網羅性（0-100）: 入力情報が漏れなく反映されているか
3. 具体性（0-100）: 抽象的でなく実行可能な内容か
4. 整合性（0-100）: 論理的な矛盾がないか

Step 3: 初版スキルを作成・実行する

まず初版の SKILL.md を作成し、正解データと同じ入力で実行します。

Step 4: テキスト勾配を生成する

生成結果と正解データを Claude に比較させ、改善の方向性を言語化させます。

プロンプト例:
「以下の2つの文書を比較してください。
 [生成結果] と [正解データ] の差分を分析し、
 生成結果が正解データに近づくために
 SKILL.md にどのような指示を追加すべきか、
 具体的に提案してください。」

Step 5: SKILL.md を改訂して再実行

テキスト勾配に基づいて SKILL.md を修正し、再度実行します。3〜5 イテレーションで収束することが多いです。

この手法の本質：「経験の形式知化」

@kgsi さんが「ナレッジが溜まっている企業や組織ほどこの仕組みで効果が出そう」と指摘した通り、この手法の本質は組織に蓄積された暗黙知を、スキルという形式知に変換するプロセスです。

graph TD
    subgraph Before["従来"]
        direction LR
        B1["ベテラン社員の経験"] --> B2["属人化したノウハウ"] --> B3["引き継ぎ困難"]
    end

    subgraph After["テキスト勾配による自動最適化"]
        direction LR
        A1["ベテランの成果物<br/>（正解データ）"] --> A2["テキスト勾配で<br/>差分分析"]
        A2 --> A3["SKILL.md に<br/>手順として言語化"]
        A3 --> A4["誰でも同等品質の<br/>成果物を生成可能"]
    end

    style B3 fill:#ff6b6b,color:#fff
    style A4 fill:#4ecdc4,color:#000

応用可能な業務例

注意点

テキスト勾配の不安定性

NTT ドコモの検証で TextGrad が Step 12 で 70% に低下したように、テキスト勾配は必ずしも単調に改善するとは限りません。過学習（特定のサンプルに過剰適応）のリスクがあるため、複数の正解データで評価することが重要です。

「Prompt Improver のプロンプト設計が重要」

Algomatic の検証 でも指摘されている通り、テキスト勾配を生成する LLM 自身のプロンプト設計が結果を大きく左右します。「どう改善すべきか」の指示が曖昧だと、有効な勾配が生成されません。

スキルの肥大化に注意

イテレーションを重ねるとスキルが肥大化しがちです。Claude Code の公式ドキュメントでは SKILL.md を 500 行以下 に保つことが推奨されています。詳細な判断基準は references/ に分離しましょう。

関連記事との位置づけ：プロンプトからコンテキスト、そして自動最適化へ

本記事の内容は、以下の 2 つの記事と一本の線で繋がっています。

進化の 4 段階

graph TD
    L1["Level 1: プロンプトエンジニアリング<br/>質問の仕方を工夫する<br/>（手動・属人的）"]
    L2["Level 2: コンテキストエンジニアリング<br/>何を知った状態で考えさせるかを設計する<br/>（手動・体系的）"]
    L3["Level 3: コンテキストの制御基盤<br/>コンテキストをシステムとして管理する<br/>（自動・インフラ層）"]
    L4["Level 4: コンテキストの自動最適化<br/>コンテキスト自体を自動的に改善する<br/>（自動・最適化層）"]

    L1 --> L2 --> L3 --> L4

    L2 -.- R2["コンテキストエンジニアリング記事"]
    L3 -.- R3["ハーネス記事<br/>Reduce / Offload / Isolate"]
    L4 -.- R4["本記事"]

    style L4 fill:#4ecdc4,color:#000
    style R2 fill:#f0f0f0,color:#555,stroke-dasharray: 5 5
    style R3 fill:#f0f0f0,color:#555,stroke-dasharray: 5 5
    style R4 fill:#f0f0f0,color:#555,stroke-dasharray: 5 5

コンテキストエンジニアリング記事との接点

コンテキストエンジニアリング記事では、AI 活用の核心を「指示の出し方ではなくどんな文脈を渡しているか」と定義し、4 つの柱（構成・優先順位・最適化・オーケストレーション）を提示しました。さらに「6 つの実践テクニック」の 6 番目にフィードバックループを挙げています。

「AI の出力を評価し、次のコンテキストに反映する。」

本記事のテキスト勾配による Skills 自動最適化は、このフィードバックループを体系化・自動化したものです。人手で「AI が間違えたらルールを追記する」のではなく、正解データとの差分を自動分析して SKILL.md を反復改訂します。

ハーネス記事との接点

ハーネス記事では Bitter Lesson（「作り込むほどモデル進化で不要になる」）を踏まえ、「賢く作るな、シンプルに作り直せるようにしろ」という設計原則を導きました。

テキスト勾配による自動最適化は、一見「作り込み」に見えますが、実際には人間の職人芸を排除してプロセスを機械化するものです。これは Bitter Lesson の「汎用的な計算手法が手作りの賢さに勝つ」という原則そのものであり、ハーネス記事の設計思想と整合しています。

3 記事を統合した見方

結局、3 つの記事は「AI に渡すコンテキストをいかに良くするか」という同一の問題に対して、設計思想（コンテキストエンジニアリング）、実行基盤（ハーネス）、自動改善（テキスト勾配）という 3 つの角度から答えています。

まとめ

• テキスト勾配 は、出力の失敗理由を自然言語で記述し、プロンプトを「誤差が減る方向」に改訂する手法
• @yusuke_post さんは、この手法を Claude Code Skills（SKILL.md）の自動最適化 に応用
• ヒアリングメモ → SaaS 導入提案書のスキルで 4 イテレーション、13.6 点の改善 を達成
• 核心は「人間の過去の成果物を正解データとして、スキルを反復的に改善する」こと
• TextGrad は「人間が読めるマニュアルの育成」に適しており、Skills との相性が良い
• ナレッジが蓄積された組織 ほど、この仕組みで暗黙知の形式知化に効果を発揮

「プロンプトは書く」から「プロンプトは育てる」へ——テキスト勾配による自動最適化は、スキル開発の次のステージです。

参考

• @yusuke_post のポスト — Skills の自動最適化
• @kgsi のポスト — ナレッジ蓄積組織での応用
• Automatic Prompt Optimization with “Gradient Descent” and Beam Search（ProTeGi）— Pryzant et al., EMNLP 2023
• A Better Approach to Prompt Engineering: Textual Gradient Based Prompt Optimisation — Tailored AI
• プロンプトエンジニアリングはどう変わる？ DSPy / TextGrad による自動最適化の実力検証 — NTT ドコモ
• 自動プロンプト最適化をやってみた — Algomatic Tech Blog
• プロンプトエンジニアリングの自動化: プロンプト最適化手法の最前線 — codemajin
• スキルで Claude を拡張する — Claude Code 公式ドキュメント
• コンテキストエンジニアリング — AI を「使う人」と「使いこなす人」の違い
• AI エージェントの勝負所は「モデル性能」ではなく「ハーネス設計」にある