repair-agent

エージェントの修復

既存の Claude Code エージェントをゴールドスタンダードに照らして監査し、改善します。ゼロから生成する create-agent とは異なり、このスキルでは違反を診断するだけでなく、問題点、不足している点、品質を高めるためにできることも特定します。出力は、エージェント設計のあらゆる側面を網羅した、体系的な改善計画です。

フェーズ 1：エージェントを読み込む

$ARGUMENTS に指定されたエージェントファイルをインラインで読み込みます。

@$ARGUMENTS

$ARGUMENTS のディレクトリを確認し、agents/ 内にあること（skills/ 内ではないこと）を検証します。上記のフロントマターに記載された skills: のプリロードを特定します。

ファイルが SKILL.md である場合、または skills/ ディレクトリ内にある場合は、処理を断り、代わりに repair-skill を使うようユーザーに伝えます。パスが見つからない、または曖昧な場合は、続行する前に AskUserQuestion を使って確認します。

フェーズ 2 の前に、次のリファレンスファイルを読み込みます。

1. ${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/references/agent-anatomy.md — システムプロンプトの構成、文体の規則、サイズの不変条件、命名規則、skills: プリロードのパターン、ギャップ分析チェックリストに関するゴールドスタンダードです。ディメンション 3、5、6、7 で必須です。
2. ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/agent-frontmatter.md — フロントマターの全フィールド一覧、有効な値、ツール選択の枠組み、色の意味、実行モディファイアを網羅しています。ディメンション 1 と 2 で必須です。

エージェントファイルが対象範囲内であることを確認し、リファレンスファイルを読み込んだら、フェーズ 2 に進みます。

フェーズ 2：監査

各ディメンションを個別に評価します。各指摘について、ディメンションコード、問題点または不足している点、違反している原則またはゴールドスタンダードに達していない点、必要な具体的変更を記録します。7 つすべてのディメンションを評価したら、フェーズ 3 に進みます。

指摘の種類：

• 違反 — ルールに反する記述が存在する
• ギャップ — 記述がなく、ゴールドスタンダードに照らしてエージェントの改善につながるもの
• 改善 — 現状でも機能しているが、意味のある改善が可能なもの

重大度：

• クリティカル — 起動を妨げる、または毎回の呼び出しでエージェントの誤動作を引き起こす
• 重大 — 起動精度、システムプロンプトの信頼性、自律性に関する安全性を損なう
• 軽微 — 磨き上げのための指摘。エージェントは機能するが、さらに改善できる

---

ディメンション 1 — 説明の品質

説明はルーティングモデルがこのエージェントを起動するタイミングを判断するために読み込むもので、主要な起動メカニズムであり、常にコンテキスト内にあります。違反だけでなく、ギャップも監査します。

違反：

• 表現：説明は「Use this agent when...」で始まっていますか？誤っている場合はクリティカルです。
• 説明の冗長さ：説明は簡潔な > の折り返しスカラーで、50～70 トークンにします。<example> ブロックは、ルーティングの改善につながらずコンテキストを浪費するため、含めません。例が含まれている場合、または説明が約 80 トークンを超える場合は重大です。
• スカラー型：>（折り返し）を使います。XML ブロックを使わずに | を使っている場合は軽微です。
• プロアクティブヒントの欠如：イベント後に起動するエージェントの場合、説明に「Recommended PROACTIVELY after...」が含まれていますか？プロアクティブな意図があるのにヒントがない場合は軽微です。

ギャップ：

• 起動しない条件：対象範囲が重複する隣接エージェントがある場合、起動すべきでない条件を説明に記載していますか？隣接エージェントがあるのに区別がない場合は軽微です。

ディメンション 2 — フロントマターの修飾子

フィールドの完全な一覧、ツール選択フレームワーク、色の意味については、agent-frontmatter.md を参照してください。デフォルトが適用される場合、フィールドを省略してもエラーではありません。監査では、不一致（違反）とエージェントの改善につながる設定の不足（ギャップ）を確認してください。

違反：

• tools に、フルシェルアクセスを必要としないエージェント向けのスコープ指定なしの Bash が含まれていますか？エージェントは人間が介在しない状態で自律的に実行されるため、制限のない Bash は影響範囲が最も大きい権限付与です。重大。
• sonnet で対応できるタスクに model: opus が設定されていますか？コストは起動ごとに直接増加します。重大。
• エージェントが Git の状態を変更しないのに isolation: worktree が設定されていますか？不要な分離はオーバーヘッドを増やします。軽微。
• disallowedTools に、システムプロンプトで必要とされるツールが含まれていますか？致命的。

ギャップ：

• color がありませんか？UI で視覚的な識別情報を示すと、マルチエージェントのワークフローで、どのエージェントがアクティブかをユーザーが把握しやすくなります。軽微。
• 読み取り専用の分析エージェントに tools がありませんか？最小権限の原則に従うには、自律型エージェントに明示的な許可リストが必要です。省略すると、制限付きアクセスで十分な場合にもフルアクセスが付与されます。分析専用エージェントでは重大。
• 完了までの見通しが立つタスクに maxTurns がありませんか？上限のないエージェントは、曖昧な入力に対してループする可能性があります。完了範囲が定まったタスクでは軽微。
• ドメイン固有の知識が必要なエージェントに skills がありませんか？ドメイン参照情報をシステムプロンプトに直接埋め込むと、起動のたびにプロンプトが膨らみます。skills: を使えば、必要なときに読み込めます。システムプロンプトに埋め込みの参照データが 300 行を超える場合は重大。
• 作業ツリー内のファイルを変更するエージェントに isolation: worktree がありませんか？分離しない場合、実行中の変更は即座に反映され、元に戻せません。重大。
• セッションをまたいだ学習が役立つエージェントに memory がありませんか？コードレビュー、パターン監査、プロジェクト知識の蓄積を行うエージェントには、永続メモリ（デフォルトの推奨値は project）を使用してください。memory が設定されている場合、システムプロンプトにメモリの維持に関する指示が含まれていますか？指示がなければ、エージェントはナレッジベースを積極的に更新しません。エージェントの担当領域にパターンの蓄積が含まれる場合は重大。
• コスト重視のエージェント、または複雑さが変動するエージェントに effort がありませんか？高速な分類タスクには effort: low、高度な推論タスクには effort: high が適しています。軽微。
• --agent での使用を想定したセッションモードのエージェントに initialPrompt がありませんか？これがないと、エージェントは自動で開始せず、ユーザーの入力を待ちます。該当する場合は軽微。

---

ディメンション 3 — システムプロンプトの語り口

エージェントファイルの Markdown 本文は、システムプロンプトです。語り口、ペルソナ、構成上の慣例によって、そのエージェントが専門家として振る舞うか、汎用アシスタントとして振る舞うかが決まります。語り口の慣例と標準となる構成については、agent-anatomy.md を参照してください。

違反：

• 一人称表現： 本文に「I will」「I'll」「I am」やその他の一人称表現が含まれていますか？ 重大 — システムプロンプトはエージェントへの指示です。一人称表現は、指示に従うのではなく、エージェントが自分の計画を語っているように読めます。二人称（「You will analyze...」）と、プロセスの手順で主語を省いた命令形（「Analyze...」）はどちらも正しい慣例です。一人称表現だけがこの原則に反します。
• 三人称による自己説明： 本文でエージェントを三人称（「This agent will analyze...」「The agent should...」）で説明していますか？ 重大 — 本文では、外部から説明するのではなく、エージェントに直接指示する必要があります。
• ペルソナの記述がない： 最初の文で役割と専門分野が示されていますか？ それがないと、後続の判断を導く専門家としてのアイデンティティがエージェントにありません。 重大。
• 番号付きのプロセス手順がない： 構造化されていない文章の指示では、呼び出しごとに挙動がばらつきます。 構造化されていない場合は重大。
• 出力形式がない： Output Format セクションがありますか？ 呼び出し元である人間やオーケストレーションスキルが結果を扱うには、予測可能な構造が必要です。 存在しない場合は重大。

不足事項：

• エッジケースの記載がない： 事前に対処方法を定めておくことで、再試行が必要になるタスク途中の失敗を防げます。よくあるケース：入力がない、入力が曖昧、対象が見つからない、結果が空。 軽微。
• 判断手順に基準がない： 「状況を分析する」「品質を評価する」といった手順に、考慮すべき事項や望ましい結果の基準が明示されていません。 基準がない判断手順ごとに重大。

---

ディメンション 4 — エージェント的処理と決定論的処理の分担

このディメンションを監査する前に ${CLAUDE_PLUGIN_ROOT}/skills/create-skill/references/script-patterns.md を読み込んでください。 同じ5つのシグナルパターンが、スキルと同様にエージェントにも適用されます。

エージェントは、LLM による推論（エージェント的処理）と決定論的な操作を組み合わせます。その分担は意図的に設計する必要があります。agent-anatomy.md の「自由度」表を参照してください。

違反：

• 決定論的なコードのインライン化： 呼び出しのたびに同じ内容を再生成するコードブロックは、システムプロンプトではなく scripts/ に配置します。 重大。
• 曖昧なスクリプト参照： 「必要に応じて検証スクリプトを実行する」では、パス、実行条件、出力の解釈方法が示されていません。 軽微。

不足事項 — 各プロセス手順に5つのシグナルパターンを適用してください：

• シグナル 1（生成の繰り返し）： 構造は同じでパラメーターが異なる場合 → スクリプトにします。 重大。
• シグナル 2（ツール選択の不明確さ）： 脆弱な複数ツールの手順 → 手順をスクリプトにします。 重大。
• シグナル 3（厳格な契約）： この手順に対して --help を書ける場合 → CLI の候補です。 軽微。
• シグナル 4（多目的利用）： エージェントの外でも役立つ場合 → 適切な CLI として設計します。 軽微。
• シグナル 5（一貫性が重要）： 同一の出力が必須の場合 → LLM ではなくスクリプトにします。 重大。

---

Dimension 5 — システムプロンプトの効率性

エージェント本文の各行は、エージェントが起動するたびにコンテキストに読み込まれます。ドメインの参照データやルックアップテーブルは、本文に直接埋め込まず、skills: のプリロードに含めてください。重大度の判断には、agent-anatomy.md のサイズに関する不変条件を参照してください。

違反：

• 曖昧な表現：「「検討してみるとよいでしょう」「一般的に言えば」「試してみてもよいでしょう」などです。直接的な命令形に置き換えてください。1 件ごとに軽微です。
• **本文にルーティングの指針がある：**エージェントをいつ起動するかを説明するセクションは、description フィールドに含めてください。本文は起動後に読み込まれるため、そこにルーティングの指針を記載しても起動判断には一切役立たず、起動のたびにコンテキストを消費します。重大です。
• **ドメインの参照情報を 100 行を超えて埋め込んでいる：**特定のステップでのみ必要なルックアップテーブル、オプションカタログ、フィールド定義は、すべての呼び出しでコンテキストを膨らませます。代わりに skills: のプリロードを使用してください。重大です。
• システムプロンプトが約 400 行を超えている：skills: のプリロードに含めるべきコンテンツが埋め込まれている可能性を示しています。重大です。

不足：

• **skills: によりシステムプロンプトのサイズを削減できますか？**特定のサブタスクでのみ必要なセクションを特定してください。抽出可能なコンテンツがあり、システムプロンプトが 300 行を超える場合は重大です。

---

Dimension 6 — プロセスの完全性

完全なエージェントプロセスは、順序立てられた明示的なステップで構成され、各ステップの完了条件が定義されています。ワークフローに問題がないかだけでなく、役立つ構造が欠けていないかも監査してください。

違反：

• **番号付きのステップがない：**ステップ番号を付けずにプロセスを文章で説明すると、エージェントは進捗を追跡したり、現在のステップを把握したりできません。重大です。
• **ステップに終了条件がない：**複数ステップのプロセスには、ステップごとの明示的な完了条件が必要です。これがないと、エージェントがループしたり、早まって次に進んだりする可能性があります。欠けている場合は重大です。
• **考慮が不十分なステップ：**実行内容や評価基準を指定せず、意図のみを説明しているフェーズです。該当するステップごとに重大です。
• **入力の処理方法がない：**入力が欠落している、不明瞭である、または形式が正しくない場合、エージェントはどう対応しますか？対応方法が定められていない場合は軽微です。

不足：

• **出力形式のセクションがない：**呼び出し元は、明示されていない出力構造を安定して利用できません。エージェントが構造化データを返す場合は重大です。
• **検証チェックリストがない：**プロセスの最後にセルフチェックを行うことで、文章の指示だけでは見逃すエラーを検出できます。軽微です。

---

Dimension 7 — 構成の完全性

エージェントは通常、単一のファイルで構成されますが、そのエコシステムには skills: のプリロードや、任意のコンパニオンスクリプトも含まれます。この観点では、宣言された構成が必要性に合致しているかを確認します。

欠けている要素ごとに、agent-anatomy.md のギャップ分析チェックリストを参照してください。

違反：

• **フロントマターに skills: が記載されているが、プロセス内で参照されていない：**使用されないプリロードは、活用されないまま起動のたびにコンテキストを膨らませます。軽微です。
• **命名規則に違反している：**汎用的な用語（helper、assistant、agent）、アンダースコア、50 文字を超える名前、先頭または末尾のハイフンが該当します。軽微です。

不足：

• **ドメイン知識を多く必要とするエージェントに skills: のプリロードがない：**外部化できる大規模な参照カタログがシステムプロンプトに埋め込まれています。本文が 300 行を超える場合は重大です。
• **一貫性が重要なステップにコンパニオンスクリプトがない：**同じ入力に対して、毎回同一の出力を生成する必要があるステップがプロセスに記述されています。重大です。
• **color がない：**複数のエージェントを表示する UI で視覚的な識別要素がありません。軽微です。
• **パターンを蓄積するエージェントに memory がない：**コードレビュー、品質監査、プロジェクト知識の蓄積を行うエージェントに、永続的なメモリが設定されていません。蓄積したコンテキストによってエージェントの価値が高まる場合は重大です。

---

フェーズ 3：改善レポート

調査結果を構造化されたレポートとして提示します。違反と不足事項を分けてください。レポート形式の完全な例と修正前後のセッションについては、 ${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/examples/sample-repair.md を参照してください。

AGENT IMPROVEMENT REPORT: <agent-name>
System prompt: [N] lines | Description: [N] tokens | Tools: [listed / unrestricted]

VIOLATIONS
──────────
CRITICAL
  [D1] Description does not start with "Use this agent when..." — routing model cannot
       match. Fix: rewrite opening as "Use this agent when [trigger conditions]."

MAJOR
  [D3] Body uses first-person throughout ("I will analyze...") — system prompt must be
       second-person because it is an address to the agent, not a narration of intent.
       Fix: rewrite as "Analyze the input and identify..." throughout.
  [D2] `tools` omitted for a read-only analysis agent — omission grants full tool access;
       least-privilege for autonomous agents requires an explicit allowlist.
       Fix: add tools block sequence (Read, Grep, Glob)

MINOR
  [D2] `color` not set — no visual identity in multi-agent UI.
       Fix: add color: blue (analysis/review semantic).

GAPS (what would improve this agent)
─────────────────────────────────────
MAJOR
  [D7] System prompt is 380 lines of embedded domain reference. Extract to a skill file
       and preload via `skills:` frontmatter to reduce per-spawn context cost.

MINOR
  [D6] No edge cases section — what happens when the agent receives no input?
       Improvement: add "Edge Cases: No input provided — ask the user to share the target."

違反事項を重大度別にまとめ、その後に不足事項を重大度別にまとめます。それぞれについて、ディメンションコード、問題点または不足している点、満たしていない原則、具体的な修正内容を示します。

次のように尋ねます：「重大および中程度の項目をすべて適用しますか？ それとも特定の項目を選択しますか？」

ユーザーが適用する項目を示したら、フェーズ 4 に進みます。

---

フェーズ 4：改善の適用

確認済みの項目を次の順に適用します：重大な違反 → 中程度の違反 → 中程度の不足事項 → 軽微な違反 → 軽微な不足事項。

各項目について：

• 何を、なぜ変更するのかを説明します（単に「依頼されたから」ではなく、原則を参照します）
• 編集を行います
• 変更が周囲の内容と整合していることを確認します

選択の理由を説明する

適用後：

• 何を変更し、なぜ変更したか — 原則を参照します：「システムプロンプトはエージェントへの指示であるため、本文を二人称に書き換えました。一人称では指示に従うという契約に反します」
• 何を追加し、なぜ追加したか — 「読み取り専用のエージェントであり、自律実行における最小権限の原則では明示的な許可リストが必要なため、tools ブロックにツール（Read、Grep、Glob）を追加しました」
• 何を変更せず、なぜ変更しなかったか — 「タスクの範囲が未確定のため、maxTurns は未設定のままにしました」
• ユーザーに残されていること — ドメイン知識が必要な項目

確認済みの項目がすべて適用され、説明が提示され、検証チェックリストに合格すると、フェーズ 4 は完了です。

---

検証

すべての改善を適用した後：

1. 構造バリデーターを実行します：

   python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/validate_agent.py \
     <agent-file> --output json
   

   終了コード 0 は構造に問題がないことを示します。終了コード 1 の場合は、errors 配列を解析し、最終結果を提示する前に、各項目の field、message、severity を報告します。

2. ${CLAUDE_PLUGIN_ROOT}/skills/repair-agent/references/quality-checklist.md を読み込み、品質基準の確認に続けて、項目ごとのチェックリストを実行します。最終結果を提示する前に、不合格となった項目を報告します。