evolve-agent

# 既存のエージェントを進化させる `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 npm run validate:translations ``` 2. 各翻訳ファイルのフロントマターで `source_commit` を更新する: ```bash npm run check:fence-propagation -- --id <agent-name> node tools/provenance-field.mjs --field fence_basis_commit --set $(git rev-parse --short HEAD) <mirror paths> ``` 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` — 説明的なメッセージで進化したエージェントをコミットする