---
name: improve-agent
description: エージェントファイルを静的解析・実行シミュレーションで改善する。実プロジェクトを動かさずにトークン効率・役割純粋性・命令明瞭性を評価し、具体的な改善案を提示する。
---

# /improve-agent

対象エージェントを「コールドスタートの Claude が実行する」視点でレビューし、改善案を提示する。
実プロジェクトを動かさないため、低トークンで反復改善が可能。

## 使い方

- `/improve-agent <ファイルパス>` — 指定エージェントを改善する
- `/improve-agent` — 引数なしの場合はファイルパスをユーザーに確認する

---

## 手順

### ステップ 1: 対象ファイルの特定と読み込み

```
IF 引数でファイルパスが指定されていない:
  ASK USER: 対象エージェントのパスを教えてください（"all" で .claude/agents/ 全件）
  WAIT_FOR: ユーザーの回答
ENDIF

IF 引数が "all":
  LIST: .claude/agents/ 内の全 .md ファイルを対象にする
  PROCESS: 以降のステップ2〜4を全ファイルに対して実行する。
           ステップ5では全ファイルの提案を "#<ファイルindex>-<提案番号>" 形式で表示し、
           ユーザーに "1-1 2-3 / all / skip" 形式で選択させる
  SKIP TO: ステップ5
ENDIF

READ: <対象エージェントファイル>  ← 引数で指定されたパス or ASK回答のパス

IF ファイルが存在しない:
  REPORT: "ファイルが見つかりません: <パス>"
  STOP
ENDIF

EXTRACT（以降の評価に使う）:
  - 役割の宣言（## Role / ## 役割、または冒頭の "You are..." 文）
  - model と tools の設定（frontmatter の tools: / model: フィールド）
  - プロセスのステップ数・構造
  - 出力フォーマットの定義
  - ルールの内容と数
  - 他エージェントへの言及（intake / planner / designer など）
```

---

### ステップ 2: 5次元の静的評価

各次元を 1〜5 で採点し、問題箇所を行番号付きで列挙する。

```
EVALUATE:

[A] トークン効率
  CHECK: 同じ内容が複数セクション（役割・プロセス・ルール）に重複していないか
  CHECK: 削除しても意味が変わらない前置き・例示・まとめがないか
  CHECK: テーブル・コードブロックに不要な行・列がないか
  CHECK: ルールがプロセスの言い換えになっていないか（どちらかで十分）

[B] 役割の純粋性
  CHECK: 役割宣言に「何をしないか」が明記されているか
  CHECK: 他エージェントの担当領域（例：planner がすべき計画）をこのエージェントが侵食していないか
         （判断基準: そのステップを削除してもこの役割の目的が達成できるなら侵食）
  CHECK: プロセスのステップが役割の範囲内に収まっているか
  CHECK: 完了報告で「次は XX エージェントを呼び出して」と誘導しているか
  CHECK: 「侵食しかけている」グレーゾーン（役割と隣接する処理が同一エージェントに
         混在しているが、まだ逸脱とは言い切れない箇所）がないか

[C] 命令の明瞭性
  CHECK: 各ステップが1通りにしか解釈できないか
  CHECK: 「適切に」「必要に応じて」などの曖昧な副詞が使われていないか
  CHECK: 出力フォーマットに「何を書くか」が具体的に示されているか
  CHECK: 条件分岐（ヒアリング要否・スキップ条件など）の基準が明確か

[D] tools / model の適切性
  CHECK: 使用していない可能性が高いツールが tools に含まれていないか
    （副作用ツール Bash / Write / Edit は特に慎重に）
  CHECK: model の選択が役割に見合っているか
    （計画・複雑推論 → opus / 標準 → sonnet / 軽量・高速 → haiku）
  CHECK: tools が不足していて目的を達成できない可能性がないか

[E] 出力設計
  CHECK: 出力フォーマットが定義されているか（フリーテキストになっていないか）
  CHECK: フォーマットの各セクションに過不足がないか
  CHECK: 下流エージェントが読むファイルを生成する場合、ファイルパスが明記されているか
  CHECK: 成功時・失敗時・スキップ時の出力が区別されているか
```

---

### ステップ 3: Adversarial Trace（実行シミュレーション）

```
PERSONA: コールドスタートの Claude（このエージェントを初めて実行する）

GOAL: 各ステップを「意図的に誤解しやすい解釈」で読み、
      スコープ逸脱・手抜き・誤動作が起きる箇所を探す

TRACE TARGETS:
  - 「役割外のことをやってもよさそう」と感じた箇所
  - 「このステップは省略してもよさそう」と思えた箇所
  - 「どのファイルを読めばいい？」と迷った箇所
  - 「この出力フォーマット、どこまで埋めればいい？」と判断できなかった箇所
  - 「このルールとプロセスが矛盾している」と感じた箇所
  - 「完了の基準が分からない」と詰まった箇所

OUTPUT: 誤解・スコープ逸脱・手抜きが起きやすい箇所のリスト（行番号・理由付き）
```

---

### ステップ 4: 改善案の生成

```
FOR EACH 問題箇所（ステップ2・3の結果を統合）:
  GENERATE 改善提案:
    分類: [A〜E]
    優先度: HIGH（動作に影響）/ MEDIUM（品質に影響）/ LOW（読みやすさ）
    場所: L<行番号> または セクション名
    Before: <現在の記述>
    After:  <改善後の記述>
    理由:   <1行>

SORT BY 優先度（HIGH → MEDIUM → LOW）
```

---

### ステップ 5: ユーザー確認 & 適用

```
SHOW USER:
  スコアサマリー（5次元の採点）
  改善提案リスト（番号付き、優先度順）

FORMAT:
  ── スコア ──────────────────────────────────
  [A] トークン効率      : X/5
  [B] 役割の純粋性      : X/5
  [C] 命令の明瞭性      : X/5
  [D] tools/model適切性 : X/5
  [E] 出力設計          : X/5
  ────────────────────────────────────────────

  ── 改善提案 ────────────────────────────────
  #1 [B] HIGH — L12: <問題の概要>
  Before: ...
  After:  ...
  理由: ...
  ────────────────────────────────────────────
  #2 ...

RECOMMEND:
  優先度 HIGH の提案から、最小変更で最大効果の上位 3 件を明示する。
  例: "#1 #3 #5 を最初に適用することを推奨します（理由: ...）"

ASK USER:
  "適用する改善案を選んでください（例: 1 3 5 / all / skip）"

WAIT_FOR: ユーザーの選択
PROHIBITED: ユーザーの選択なしにファイルを書き換えること

FOR EACH 承認された番号:
  EDIT: 対象エージェントファイルの該当箇所を改善後の記述に置き換える

REPORT:
  "X 件の改善を適用しました: <ファイルパス>"
  "再度 /improve-agent を実行すると次のサイクルを行えます。"
```

---

## 評価の限界（検出できないもの）

- 実際のヒアリング品質（ユーザーの回答次第で変わる動作）
- 他エージェントとの連携時の実際の出力品質
- model の応答特性の差異（sonnet と opus で解釈が変わる場合）
- エージェント設計の意図に依存する正しさ（役割境界・ツール選択の妥当性は設計思想による）