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

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の正直な制約	少なすぎる、曖昧すぎる、または完全に欠落
参照	エージェント、ガイド、チームへの有効なクロスリファレンス	名前変更または削除されたファイルへの古いリンク

# エージェントファイルを読む
cat agents/<agent-name>.md

# フロントマターの解析を確認する
head -20 agents/<agent-name>.md

# フロントマターのスキルがレジストリに存在するか確認する
grep "skills:" -A 20 agents/<agent-name>.md

# エージェントがいずれかのチームによって参照されているか確認する
grep -r "<agent-name>" teams/*.md

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

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

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

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

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

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

- フロントマター: スキルリストに `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

バリアントの場合

# 元のものを出発点としてコピーする
cp agents/<agent-name>.md agents/<agent-name>-advanced.md

# バリアントを編集する:
# - `name` を `<agent-name>-advanced` に変更
# - `description` を上級スコープを反映するように更新
# - 必要に応じて `model` を上げる（例: sonnet → opus）
# - `version` を "1.0.0" にリセット
# - 上級ユースケースのためにスキル、機能、例を拡張
# - 元のエージェントを「参照」でよりシンプルな代替として参照

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

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

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

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

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

# 既存の翻訳を確認する
ls i18n/*/agents/<agent-name>.md 2>/dev/null

翻訳が存在する場合

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

SOURCE_COMMIT=$(git rev-parse HEAD)

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

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

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

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

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

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

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 の既存のエントリを改訂されたフロントマターに一致するように更新する:

# エージェントのレジストリエントリを見つける
grep -A 10 "id: <agent-name>" agents/_registry.yml

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

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

# いずれかのチームがこのエージェントを参照しているか確認する
grep -r "<agent-name>" teams/*.md

# いずれかのガイドがこのエージェントを参照しているか確認する
grep -r "<agent-name>" guides/*.md

バリアントの場合

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

  - 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 で元のコンテンツの偶発的な削除がないことを確認

# フロントマターを確認する
head -20 agents/<agent-name>.md

# スキルが存在するか確認する
for skill in skill-a skill-b; do
  grep "id: $skill" skills/_registry.yml
done

# ディスク上のエージェント数 vs レジストリ
ls agents/*.md | grep -v template | wc -l
grep total_agents agents/_registry.yml

# すべての変更を確認する
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 — 説明的なメッセージで進化したエージェントをコミットする