# Evolve Agent

> 既存のエージェント定義をそのペルソナをその場で改良するか、上級バリアントを 作成することで進化させる。現在のエージェントのベストプラクティスに対する 評価、進化要件の収集、スコープ（改良 vs バリアント）の選択、スキル、 ツール、機能、制限事項への変更の適用、バージョンメタデータの更新、 レジストリとクロスリファレンスの同期をカバーする。エージェントのスキル リストが古くなっている場合、ユーザーフィードバックが機能のギャップを 明らかにした場合、ツール要件が変わった場合、元のエージェントと並んで 上級バリアントが必要な場合、または実際の使用後にエージェントのスコープを 調整する必要がある場合に使用する。

- Skill: `pjt222/evolve-agent-3` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pjt222/evolve-agent-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/evolve-agent-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/evolve-agent-3

---


# 既存のエージェントを進化させる

`create-agent` で元々作成されたエージェントを改善、拡張、または上級バリアントを作成する。この手順はエージェントライフサイクルのメンテナンス面をカバーする: ベストプラクティスに対するギャップの評価、ペルソナ定義への的を絞った改善の適用、バージョンのバンプ、レジストリとクロスリファレンスの同期。

## 使用タイミング

- 新しいスキルがライブラリに追加された後にエージェントのスキルリストが古くなった場合
- ユーザーフィードバックが欠けている機能、不明確な目的、または弱い例を明らかにした場合
- ツール要件が変わった（新しいMCPサーバー、ツールが削除された、権限削減が必要）場合
- エージェントのスコープを調整する必要がある — 別のエージェントと重複しているか広すぎる
- 元のエージェントと並んで上級バリアントが必要（例: `r-developer` と `r-developer-advanced`）
- 関連するエージェントまたはチームが追加されて「参照」のクロスリファレンスが古くなった場合

## 入力

- **必須**: 進化させる既存のエージェントファイルへのパス（例: `agents/r-developer.md`）
- **必須**: 進化のトリガー（フィードバック、新しいスキル、ツール変更、スコープの重複、チーム統合、発見された制限事項）
- **任意**: ターゲットバージョンバンプの大きさ（パッチ、マイナー、メジャー）
- **任意**: 現場での改良ではなく上級バリアントを作成するかどうか（デフォルト: 現場での改良）

## 手順

### ステップ1: 現在のエージェントを評価する

既存のエージェントファイルを読み、`guides/agent-best-practices.md` の品質チェックリストに対して各セクションを評価する:

| セクション | 確認事項 | 一般的な問題 |
|---|---|---|
| フロントマター | 必須フィールドすべて存在（`name`、`description`、`tools`、`model`、`version`、`author`）| `tags` 欠落、古い `version`、間違った `priority` |
| 目的 | 一般的な「Xを助ける」ではない具体的な問題ステートメント | 曖昧または別のエージェントと重複 |
| 機能 | 太字のリードインを持つ具体的で検証可能な機能 | 一般的（「開発を処理する」）、グループ化なし |
| 利用可能なスキル | フロントマターの `skills` リストと一致し、すべてのIDがレジストリに存在 | 古いID、新しいスキルの欠落、不必要にデフォルトスキルを一覧 |
| 使用シナリオ | 呼び出しパターンを含む2〜3の現実的なシナリオ | プレースホルダーテキスト、非現実的な例 |
| 例 | ユーザーリクエストとエージェントの動作を示す | 欠落または些細な例 |
| 制限事項 | 3〜5の正直な制約 | 少なすぎる、曖昧すぎる、または完全に欠落 |
| 参照 | エージェント、ガイド、チームへの有効なクロスリファレンス | 名前変更または削除されたファイルへの古いリンク |

```bash
# Read the agent file
cat agents/<agent-name>.md

# Check frontmatter parses
head -20 agents/<agent-name>.md

# Verify skills in frontmatter exist in registry
grep "skills:" -A 20 agents/<agent-name>.md

# Check if agent is referenced by any team
grep -r "<agent-name>" teams/*.md
```

**期待結果：** セクションごとに整理された具体的なギャップ、弱点、または改善の機会のリスト。

**失敗時：** エージェントファイルが存在しないかフロントマターがない場合、このスキルは適用されない — 代わりに `create-agent` を使用してゼロから作成する。

### ステップ2: 進化要件を収集する

進化をトリガーしたものを特定して分類する:

| トリガー | 例 | 典型的なスコープ |
|---|---|---|
| ユーザーフィードバック | 「エージェントがレビューでXSSを見逃した」| スキルまたは機能の追加 |
| 新しいスキルが利用可能 | ライブラリが `analyze-api-security` を獲得 | スキルリストの更新 |
| ツール変更 | 新しいMCPサーバーが利用可能 | ツール/mcp_serversへの追加 |
| スコープの重複 | 2つのエージェントが両方とも「コードレビュー」を主張 | 目的と制限事項を明確にする |
| チーム統合 | エージェントが新しいチームに追加された | 参照の更新、機能の確認 |
| モデルのアップグレード | タスクがより深い推論を必要とする | モデルフィールドの変更 |
| 権限削減 | エージェントがBashを持つが読み取りのみのファイル | 不必要なツールを削除 |

編集する前に必要な特定の変更を文書化する。各変更をエージェントファイルの特定のセクションにマップする:

```text
- フロントマター: スキルリストに `new-skill-id` を追加
- 機能: 「APIセキュリティ分析」機能を追加
- 利用可能なスキル: 説明とともに `new-skill-id` を追加
- 制限事項: 欠落しているスキルに関する古い制限事項を削除
- 参照: このエージェントを含む新しいチームへのリンクを追加
```

**期待結果：** 具体的な変更のリストで、それぞれがエージェントファイルの特定のセクションにマップされている。

**失敗時：** 変更が不明確な場合、進める前にユーザーに確認を求める。曖昧な進化目標は曖昧な改善を生む。

### ステップ3: 進化スコープを選択する

この意思決定マトリックスを使用して、現場での改良とバリアントの作成のどちらにするかを決める:

| 基準 | 改良（現場での） | 上級バリアント（新しいエージェント） |
|---|---|---|
| エージェントID | 変更なし | 新しいID: `<agent>-advanced` または `<agent>-<specialty>` |
| ファイルパス | 同じ `.md` ファイル | `agents/` の新しいファイル |
| バージョンバンプ | パッチまたはマイナー | 1.0.0から開始 |
| モデル | 変わる場合がある | しばしばより高い（例: sonnet → opus）|
| レジストリ | 既存のエントリを更新 | 新しいエントリを追加 |
| 元のエージェント | 直接変更される | そのまま、「参照」にクロスリファレンスを追加 |

**改良**: スキルの更新、ドキュメントの修正、スコープの調整、またはツールの変更時に選択する。エージェントはそのアイデンティティを保持する。

**バリアント**: 進化したバージョンが実質的に異なる聴衆に提供し、異なるモデルを必要とし、または元のエージェントを広くしすぎる機能を追加する場合に選択する。元のエージェントはより単純なユースケース用にそのまま残る。

**期待結果：** 根拠を持つ明確な決定 — 改良またはバリアント。

**失敗時：** 不明確な場合、改良をデフォルトにする。後でバリアントを抽出できるが、元に戻すのは難しい。

### ステップ4: エージェントファイルに変更を適用する

#### 改良の場合

既存のエージェントファイルを直接編集する:

- **フロントマター**: 必要に応じて `skills`、`tools`、`tags`、`model`、`priority`、`mcp_servers` を更新
- **目的/機能**: 新しいスコープまたは追加された機能を反映するように改訂
- **利用可能なスキル**: 説明とともに新しいスキルを追加し、非推奨のものを削除
- **使用シナリオ**: 新しい機能を示すシナリオを追加または改訂
- **制限事項**: 適用されなくなった制約を削除し、新しい正直な制約を追加
- **参照**: 現在のエージェント/チーム/ガイドのランドスケープを反映するようにクロスリファレンスを更新

これらの編集ルールに従う:
- 既存のすべてのセクションを保持する — コンテンツを追加し、セクションを削除しない
- 利用可能なスキルセクションをフロントマターの `skills` リストと同期させる
- エージェントの方法論の核心でない限り、デフォルトスキル（`meditate`、`heal`）をフロントマターに追加しない
- 各スキルIDが存在することを確認する: `grep "id: skill-name" skills/_registry.yml`

#### バリアントの場合

```bash
# Copy the original as a starting point
cp agents/<agent-name>.md agents/<agent-name>-advanced.md

# Edit the variant:
# - Change `name` to `<agent-name>-advanced`
# - Update `description` to reflect the advanced scope
# - Raise `model` if needed (e.g., sonnet → opus)
# - Reset `version` to "1.0.0"
# - Expand skills, capabilities, and examples for the advanced use case
# - Reference the original in See Also as a simpler alternative
```

**期待結果：** エージェントファイル（改良または新しいバリアント）がステップ1の評価チェックリストをパスする。

**失敗時：** 編集でドキュメント構造が壊れた場合、`git diff` で変更を確認し、`git checkout -- <file>` で部分的な編集を元に戻す。

### ステップ4.5: 翻訳済みバリアントを同期する

> **翻訳が存在する場合に必須。** このステップは、この手順に従う人間の著者とAIエージェントの両方に適用される。スキップしない — 古い `source_commit` 値は、`npm run validate:translations` がすべてのロケールにわたって誤った古さ警告を報告する原因となる。

進化したエージェントの翻訳が存在するかどうかを確認し、新しいソース状態を反映するように更新する:

```bash
# Check for existing translations
ls i18n/*/agents/<agent-name>.md 2>/dev/null
```

#### 翻訳が存在する場合

1. 現在のソースコミットハッシュを取得する:

```bash
SOURCE_COMMIT=$(git rev-parse HEAD)
```

2. 各翻訳ファイルのフロントマターで `source_commit` を更新する:

```bash
for locale_file in i18n/*/agents/<agent-name>.md; do
  sed -i "s/^source_commit: .*/source_commit: $SOURCE_COMMIT/" "$locale_file"
done
```

3. 影響を受けるロケールをコミットメッセージに含めて、再翻訳のためにファイルにフラグを立てる:

```text
evolve-agent(<agent-name>): <変更の説明>

Translations flagged for re-sync: de, zh-CN, ja, es
Changed sections: <変更されたセクションをリストする>
```

4. 翻訳ステータスファイルを再生成する:

```bash
npm run translation:status
```

#### 翻訳が存在しない場合

アクション不要。ステップ5に進む。

#### バリアントの場合

新しいバリアントの翻訳は、バリアントが安定するまで（1〜2バージョン）延期する。v1.2までに大幅に変わる可能性のあるv1.0バリアントを翻訳するのは労力の無駄だ。バリアントが少なくとも1回は改良された後で翻訳を追加する。

**期待結果：** すべての翻訳ファイルで `source_commit` が現在のコミットに更新されている。コミットメッセージには、どのロケールで再翻訳が必要か、どのセクションが変更されたかが記載されている。`npm run translation:status` は0で終了する。

**失敗時：** `sed` がフロントマターフィールドにマッチしない場合、翻訳ファイルが非標準のフォーマットになっている可能性がある。手動で開き、YAMLフロントマターに `source_commit` があることを確認する。フィールドが欠落している場合、ファイルは正しく足場作りされていない — `npm run translate:scaffold -- agents` で再度足場作りする。

### ステップ5: バージョンとメタデータを更新する

セマンティックバージョニングに従ってフロントマターの `version` フィールドをバンプする:

| 変更タイプ | バージョンバンプ | 例 |
|---|---|---|
| タイポ修正、言い回しの明確化 | パッチ: 1.0.0 → 1.0.1 | 不明確な制限事項を修正 |
| 新しいスキル追加、機能拡張 | マイナー: 1.0.0 → 1.1.0 | ライブラリから3つの新しいスキルを追加 |
| 目的の再構築、モデルの変更 | メジャー: 1.0.0 → 2.0.0 | スコープを絞り、opusにアップグレード |

また以下も更新する:
- `updated` 日付を現在の日付に
- エージェントのドメインカバレッジが変わった場合の `tags`
- 目的が実質的に異なる場合の `description`
- 他のエージェントに対する相対的な重要性が変わった場合の `priority`

**期待結果：** フロントマターの `version` と `updated` が変更の大きさと日付を反映している。新しいバリアントは `"1.0.0"` から始まる。

**失敗時：** バージョンをバンプするのを忘れた場合、次の進化では現在の状態と以前の状態を区別する方法がない。常にコミット前にバンプする。

### ステップ6: レジストリとクロスリファレンスを更新する

#### 改良の場合

`agents/_registry.yml` の既存のエントリを改訂されたフロントマターに一致するように更新する:

```bash
# Find the agent's registry entry
grep -A 10 "id: <agent-name>" agents/_registry.yml
```

`description`、`tags`、`tools`、`skills` フィールドをエージェントファイルに一致するように更新する。カウントの変更は不要。

エージェントの機能または名前が変わった場合、他のファイルのクロスリファレンスを更新する:

```bash
# Check if any team references this agent
grep -r "<agent-name>" teams/*.md

# Check if any guide references this agent
grep -r "<agent-name>" guides/*.md
```

#### バリアントの場合

アルファベット順の位置に `agents/_registry.yml` に新しいエージェントを追加する:

```yaml
  - id: <agent-name>-advanced
    path: agents/<agent-name>-advanced.md
    description: One-line description of the advanced variant
    tags: [domain, specialty, advanced]
    priority: normal
    tools: [Read, Write, Edit, Bash, Grep, Glob]
    skills:
      - skill-id-one
      - skill-id-two
```

次に:
1. レジストリの先頭の `total_agents` をインクリメントする
2. バリアントを指すクロスリファレンスを元のエージェントの「参照」に追加する
3. 元のエージェントを指すクロスリファレンスをバリアントの「参照」に追加する
4. `agents/` へのシンリンクである `.claude/agents/` はバリアントを自動的に発見可能にする

**期待結果：** レジストリエントリがエージェントファイルのフロントマターと一致する。バリアントの場合、`total_agents` が実際のエージェントエントリ数と等しい。

**失敗時：** `grep -c "^  - id:" agents/_registry.yml` でエントリをカウントし、`total_agents` と一致することを確認する。

### ステップ7: 進化したエージェントを検証する

完全なバリデーションチェックリストを実行する:

- [ ] エージェントファイルが期待されるパスに存在する
- [ ] YAMLフロントマターがエラーなく解析される
- [ ] `version` がバンプされた（改良）か "1.0.0" に設定された（バリアント）
- [ ] `updated` 日付が今日を反映している
- [ ] 必須セクションすべてが存在する: 目的、機能、利用可能なスキル、使用シナリオ、例、制限事項、参照
- [ ] フロントマターのスキルが利用可能なスキルセクションと一致する
- [ ] すべてのスキルIDが `skills/_registry.yml` に存在する
- [ ] デフォルトスキル（`meditate`、`heal`）は方法論の核心でない限り一覧されていない
- [ ] ツールリストが最小権限原則に従っている
- [ ] レジストリエントリが存在しフロントマターと一致する
- [ ] バリアントの場合: `total_agents` カウントがディスク上の実際のカウントと一致する
- [ ] クロスリファレンスが双方向（元 ↔ バリアント）
- [ ] `git diff` で元のコンテンツの偶発的な削除がないことを確認

```bash
# Verify frontmatter
head -20 agents/<agent-name>.md

# Check skills exist
for skill in skill-a skill-b; do
  grep "id: $skill" skills/_registry.yml
done

# Count agents on disk vs registry
ls agents/*.md | grep -v template | wc -l
grep total_agents agents/_registry.yml

# Review all changes
git diff
```

**期待結果：** すべてのチェックリストアイテムがパスする。進化したエージェントはコミット準備が整っている。

**失敗時：** 各失敗したアイテムを個別に対処する。最も一般的な進化後の問題は、利用可能なスキルセクションの古いスキルIDと忘れられた `updated` 日付だ。

## バリデーション

- [ ] エージェントファイルが存在し、有効なYAMLフロントマターがある
- [ ] `version` フィールドが行われた変更を反映している
- [ ] `updated` 日付が現在
- [ ] すべてのセクションが存在し内部的に一貫している
- [ ] フロントマターの `skills` 配列が利用可能なスキルセクションと一致する
- [ ] すべてのスキルIDが `skills/_registry.yml` に存在する
- [ ] デフォルトスキルが不必要に一覧されていない
- [ ] レジストリエントリがエージェントファイルと一致する
- [ ] バリアントの場合: `agents/_registry.yml` に正しいパスで新しいエントリがある
- [ ] バリアントの場合: `total_agents` カウントが更新されている
- [ ] クロスリファレンスが有効（「参照」に壊れたリンクなし）
- [ ] `git diff` で偶発的なコンテンツ削除がないことを確認

## よくある落とし穴

- **バージョンのバンプを忘れる**: バージョンバンプなしでは、何が変わったか、いつ変わったかを追跡する方法がない。コミット前に常に `version` と `updated` をフロントマターで更新する。
- **スキルリストのずれ**: フロントマターの `skills` 配列と `## Available Skills` セクションは同期を保つ必要がある。一方を更新して他方を更新しないと、人間とツールの両方に混乱を引き起こす。
- **デフォルトスキルの不必要な一覧**: レジストリからすでに継承されている場合に `meditate` や `heal` をフロントマターに追加する。方法論の核心である場合（例: `mystic`、`alchemist`）にのみ一覧する。
- **進化中のツールの過剰プロビジョニング**: 「念のために」進化中に `Bash` や `WebFetch` を追加する。すべてのツール追加は特定の新しい機能によって正当化されるべきだ。
- **バリアント作成後の古くなった「参照」**: バリアントを作成するとき、元のエージェントとバリアントの両方がお互いを参照する必要がある。一方向の参照はグラフを不完全にする。
- **更新されないレジストリエントリ**: エージェントのスキル、ツール、または説明を変更した後、`agents/_registry.yml` エントリを一致するように更新する必要がある。古いレジストリエントリは発見とツールの失敗を引き起こす。

## 関連スキル

- `create-agent` — 新しいエージェントを作成するための基盤; evolve-agentは元々これが従われたと仮定する
- `evolve-skill` — SKILL.mdファイルを進化させるための並行手順
- `commit-changes` — 説明的なメッセージで進化したエージェントをコミットする