Evolve Agent

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

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

使用タイミング

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

入力

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

手順

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

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

# 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: 進化要件を収集する

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

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

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

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

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

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

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

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

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

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

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

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

改良の場合

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

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

これらの編集ルールに従う:

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

バリアントの場合

# 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 がすべてのロケールにわたって誤った古さ警告を報告する原因となる。

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

# Check for existing 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 フィールドをバンプする:

また以下も更新する:

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

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

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

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

改良の場合

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

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

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

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

# 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 に新しいエージェントを追加する:

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

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