shunk031-manage-agent-guidance

メモ

この SKILL.md を読んだ後、「🧭 I read shunk031-manage-agent-guidance.」と言ってください。

エージェント向けガイダンスの管理

永続的な指示はそれぞれ単一の信頼できる情報源に置き、薄いアダプターを通じて利用できるようにします。

ワークフロー

1. 変更を提案する前に、該当するガイダンスを読みます。
2. 要求されたルールを、ユーザーレベル、リポジトリレベル、サブツリーレベル、タスク限定、カスタムエージェント、またはスキルのガイダンスに分類します。要求で指定されたファイル名は、上位レベルの指示、管理対象のソース、シンボリックリンク、インポート、ラッパー、アダプターで確認できるまでは仮説として扱います。
3. 影響を受ける利用者を調べ、既存の所有者を探します。所有権や重複が不明瞭な場合は、利用者マップを作成します。自己完結した編集では、影響を受ける可能性のあるソースと読み手だけを記録します。
4. 信頼できる情報源を1つ編集します。共有される動作ルールはユーザースコープに、リポジトリの手順はリポジトリスコープに、サブツリーのルールはサブツリースコープに、再利用可能な専門的手順は既存のスキルに置きます。アダプターは薄く保ち、表現が似ているという理由だけでルールを重複させないでください。
5. 編集前に、スコープ、信頼できる情報源、既存の所有権、未解決の利用者について、根拠を示します。既存の所有者がなく、その手順が実質的で再利用可能な場合に限り、スキルを作成します。
6. 最終差分を確認し、スコープの不一致、所有権の重複、シークレット、一時的な情報、アダプターのずれがないか調べます。影響を受けるリポジトリで実際に定められているゲートを実行します。フック、スキップ変数、モデルゲートを独自に作らないでください。

スコープ、信頼できる情報源、既存の所有権、影響を受ける利用者を確認するまで、草案の作成や編集を始めないでください。根拠が得られない場合は、指定されたファイルを既定の対象とするのではなく、不足している情報源を報告し、調査方法を提案してください。

永続化の品質

• インシデントを超えて一般化でき、再利用可能な根本原因への対策を示す、簡潔で実行可能な予防策のみを永続化します。
• シークレット、タスク固有の事実、一時的な状態、インシデントの経緯、未検証の前提は含めません。
• 永続的なガイダンスで、課題／PR番号、移行の追跡状況、その他の期限切れになる事実に言及してはいけません。ガイダンスファイルは期限なく読み込まれますが、こうした情報には期限があります。課題はクローズされ、移行は完了し、単独の番号は追跡システムの外では特定できなくなります。その結果、後から読む人には確認も実行もできないルールだけが残ります。期限のある事実は、課題トラッカーまたは日付付きの調査メモに記録してください。

指示の移行

実際に移動または削除する場合は、移行元と、そのルールを機械的に適用する所有者を調べ、影響を受ける各ルールの移行元、移行先、アダプター、または承認済みの削除とその理由を記録し、変更後に利用者を確認します。通常の編集では移行記録を作成せず、対応付けも承認もされていないルールを削除しないでください。

リポジトリの検証

• ゲートを挙げる前に、影響を受けるリポジトリの現在の Makefile、pre-commit 設定、CI を調べます。
• 文書化されている静的ゲートを実行し、必須の所有権チェックを維持します。他のリポジトリのフック ID やスキップ変数をそのまま使えると想定しないでください。
• ライブモデル評価は、タスクとリポジトリで明示的に求められている場合にのみ実行します。不足しているゲートを新たなフレームワークで置き換えないでください。

リポジトリの構成

• リポジトリの規約はルートの AGENTS.md に記載し、ユーザーレベルのルールを重複して記載しないでください。
• ルートの CLAUDE.md は、ファイルのコピーやインポート用スタブではなく、AGENTS.md への相対シンボリックリンクにしてください。
• リポジトリ内のスキルは .agents/skills/<name>/SKILL.md に配置し、必要に応じて相対 .claude/skills シンボリックリンクを使って Claude から利用できるようにしてください。
• 長い共有カスタムエージェント指示は ~/.agents/agents/<name>.md に配置してください。エージェントを共有元へ誘導する、薄い Claude または Codex ラッパー内に、ツール固有のメタデータを保持してください。
• プライベートなインフラストラクチャ、認証情報、内部エンドポイント、環境固有の起動設定を公開ガイダンスに含めないでください。
• 共有指示を TOML や Markdown に重複させるための Markdown パーサーやジェネレーターは、その仕組みが明示的に必要になるまで導入しないでください。