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

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

skills

# エージェントファイルを読む
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: 進化要件を収集する

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

analyze-api-security

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

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

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

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

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

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

<agent>-advanced

<agent>-<specialty>

.md

agents/

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

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

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

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

ステップ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

失敗時：

sed

source_commit

npm run translate:scaffold -- agents

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

セマンティックバージョニングに従ってフロントマターの

version

また以下も更新する:

• 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

  — 説明的なメッセージで進化したエージェントをコミットする