normalize-agent-for-claude

すべての書き換えの判断は、Claude Code のエージェントランタイムに基づいて行う必要があります。

必ず守るルール：

1. 計画または書き換えの前に、references/claude-agent-runtime.md を読んでください。
2. ユーザーが今すぐ書き換えるよう明示的に求めていない限り、既定では --mode plan を使用してください。
3. Markdown 本文全体がエージェントのシステムプロンプトになるため、本文は簡潔に保ってください。
4. 説明文を増やす前に、ランタイム制御にはフロントマターを使用してください。
5. 十分にスリム化され、その必要性が確認されていない限り、大量のスキルをエージェントのフロントマターに事前読み込みしないでください。
6. エージェントにスキル専用のフロントマターを追加しないでください。allowed-tools、argument-hint、arguments、when_to_use、disable-model-invocation、user-invocable、context、agent、shell、paths はエージェントではなくスキルに属します。

Claude 向けエージェントの正規化

入力

• $target：エージェントのディレクトリ、または AGENT.md への直接パス
• $mode：任意。plan または rewrite。既定値：plan

目標

役割と制約が明確で、フロントマターを意図的に使用し、スキルや共有ルールに含めるべき手順の冗長な記述でプロンプトの予算を浪費しない、Claude Code 向けに最適化されたエージェントを作成します。

手順 1：対象を特定する

1. エージェントのディレクトリ、または AGENT.md への直接パスを受け付けます。
2. エージェントのルートに正規化し、AGENT.md が存在することを確認します。
3. モードを判定します。
   • --mode rewrite は、計画してから同じ実行内で書き換えることを意味します。
   • モードが指定されていない場合は plan とします。
4. 現在のエージェントを調査します。
   • AGENT.md の行数
   • 既存のフロントマターフィールド
   • 本文のセクション構成
   • 明らかに重複しているグローバルポリシーや巨大な知識カタログ

成功基準：対象のエージェント、モード、現在のプロンプト構成におけるリスクを正確に把握していること。

手順 2：Claude Code エージェントランタイムの基準資料を読む

推奨事項を検討する前に、references/claude-agent-runtime.md を最後まで読んでください。

参照資料から、次の制約を確認します。

• エージェントの description は whenToUse になります。
• Markdown 本文全体がシステムプロンプトになります。
• Claude は、ほとんどのカスタムエージェントが使用しているものより豊富なエージェント用フロントマターに対応しています。
• エージェントの skills: はスキルの内容全体を事前読み込みします。
• ツールの許可リストと拒否リストはランタイムで適用されます。
• リポジトリ全体に適用されるプロジェクトルールには、独立した指示の階層がすでにあります。
• エージェントの書き換えでは、スキル専用ヘッダーではなく、エージェント専用のフロントマターを使用する必要があります。

このリポジトリに claude-code-source/ がある場合は、特殊なフロントマターや分離に関する判断を検証するため、参照資料で指定されている正確なソースファイルを使用してください。

成功基準：計画する変更のすべてが、Claude の具体的なランタイム動作に基づいていること。

Step 3: 現在のエージェントを Claude のランタイムに照らして監査する

次のチェックリストを使って、対象のエージェントを評価します。

1. アイデンティティと手順
   • どの内容が本質的な役割のアイデンティティですか？（役割の定義、専門知識の箇条書き、判断のヒューリスティクス、ドメイン知識、特性）
   • 実際にはワークフローであり、スキルに置くべき内容はどれですか？（手順ごとのプロセス、シェルコマンド、テンプレート、チェックリスト）
   • 役割に固有の専門知識リストと判断のヒューリスティクスは IDENTITY です。本文に残します。スキルまたはリファレンスに移すのは 手順 のみです。
2. プロンプトの分量
   • 現在のエージェントが、不足しているスキルや共有ルールを補うためだけに持っている、大きなセクションはどれですか？
3. フロントマターの活用機会
   • disallowedTools、skills、initialPrompt、hooks、permissionMode、maxTurns、background、memory、isolation は、ランタイムの動作を改善しますか？
   • 削除するか、明示的に使用を避けるべき、スキル専用のヘッダーはありますか？
4. ツールの範囲
   • ツールのリストは、役割に実際に必要な範囲を超えていますか？
5. スキルのプリロードによるリスク
   • フロントマターにスキルを追加すると、そのスキルがまだ大きすぎるためにプロンプトが肥大化しますか？
6. 指示の重複
   • Claude がプロジェクトメモリを別途読み込むにもかかわらず、リポジトリ全体に適用されるルールがここで重複していますか？

問題を次のように分類します。

• PROMPT：本文が大きすぎる、または不適切な内容を含んでいる
• RUNTIME：Claude のフロントマターが不足している、または誤用されている
• TOOLS：ツールの公開範囲が広すぎる、または曖昧すぎる
• DUPLICATION：プロジェクトポリシーがエージェント本文で重複している
• EXTRACTION：内容をスキルまたはリファレンスに移すべき

成功基準：何を残し、移動し、縮小すべきかを、具体的かつソースに基づいて説明できていること。

Step 4: エージェントごとの DAG 計画を作成する

次の 2 つの成果物を作成します。

• .ulpi/plans/agents/<agent-name>-normalize-for-claude.md
• .ulpi/plans/agents/<agent-name>-normalize-for-claude.json

計画には次の項目を含める必要があります。

1. 現在の状態
   • 行数
   • 現在のフロントマター
   • 大きすぎるセクション
   • 重複しているグローバルポリシー
2. Claude ランタイムの調査結果
   • 各調査結果を references/claude-agent-runtime.md の参照箇所に対応付ける
3. 目標とする状態
   • 最終的なフロントマターの形
   • 維持、削除、移動する本文のセクション
   • 代わりにエージェントが依存すべきスキルまたはリファレンス
4. DAG タスク
   • フロントマターの書き換え
   • プロンプト本文の縮小
   • 手順のスキルまたはリファレンスへの抽出
   • ツールの範囲の絞り込み
   • 検証
5. ガードレール
   • 維持すべきアイデンティティ
   • 外部へ移すべき内容
   • プリロードしてはならない内容
6. 検証
   • 最終的なエージェントの構造が適切であることを確認する具体的なチェック項目

各 DAG タスクには次の項目を含める必要があります。

• id
• title
• rationale
• filesToModify
• filesToCreate
• dependencies
• validation

成功基準：Markdown と JSON の計画で、安全な作業手順が同じように記述されていること。

ステップ 5：要求された場合にのみ書き換える

モードが plan の場合は、DAG の成果物を作成した時点で終了します。

モードが rewrite の場合：

1. まずフロントマターを書き換えます。
2. 本文を次の内容に絞ります。
   • 役割と専門知識（具体的なドメイン知識と能力に関する主張）
   • スコープ
   • 意思決定のヒューリスティクス（アプローチの選び方）
   • 失敗時の境界
   • 出力の契約
   • スキルへの簡潔な引き継ぎガイダンス
3. 繰り返し登場する手順や大きな例はエージェントから移動します。役割に関する専門知識の箇条書きと意思決定のヒューリスティクスは維持します。これらは手順ではなく、アイデンティティを示すものです。
4. 実行時の動作が実質的に変わる場合に限り、Claude ネイティブのフロントマターを追加します。
5. 汎用的なものではなく、役割に特化した内容にします。

書き換えで推奨される成果：

• エージェントの description を、明確な whenToUse にします。
• 本文を大幅に短くし、アイデンティティに焦点を当てます。
• 適切な場合は disallowedTools と、より絞り込んだ tools を使用します。
• skills: は、すでに簡潔なスキルに限り、必要最小限に使用します。
• 重複するプロジェクトルールは本文から削除します。
• 書き換え後のエージェントに、スキル専用の見出しを追加しません。

成功基準：書き換え後のエージェントがより簡潔で、精度が高く、Claude の実行時モデルに適合していること。

ステップ 6：結果を検証する

計画または書き換えの後、次の手順を実行します。

1. 最終版の AGENT.md を読み直します。
2. フロントマターに実際の実行時の判断が反映されていることを確認します。
3. 本文の大部分が、アイデンティティ、スコープ、ヒューリスティクス、境界に関する内容であることを確認します。
4. スキル専用の見出しが追加されていないことを確認します。
5. 大きな手順ブロックが削除されているか、移動先が明示されていることを確認します。
6. 変更の主な根拠となった Claude の情報源アンカーを、要約に記載していることを確認します。

成功基準：構成を変更した理由を再解釈しなくても、出力をすぐに使用できること。

出力の契約

必ず次の内容を報告します。

1. Agent: 対象パスと正規化されたルート
2. Mode: plan または rewrite
3. Top runtime issues: 重要度の高い Claude との不一致
4. Artifacts: 計画または書き換え後のファイルの正確なパス
5. Guardrails applied: Claude の実行時の動作に関連する箇条書き 3～5 項目

書き換えモードを使用した場合は、次の内容も報告します。

• 削除または移動したセクション
• 追加、削除、または意図的に省略したフロントマターのフィールド