agents-context-management

エージェントのコンテキスト管理

これらの指示がスラッシュまたはドル記号による呼び出しですでに会話に含まれている場合は、そのまま従ってください。 スキルツールを使ってこのスキルを再度呼び出さないでください。

リポジトリ内のコンテキストを、一貫したシステムとして作成または改善します。対象には、人間向けの README.md ファイル、エージェント向けの AGENTS.md ファイルとそれに対応する CLAUDE.md シンボリックリンク、.agents/skills にインストール済みの既存プロジェクトスキル、コンテキストドキュメントが含まれます。コンテキストドキュメントとは、規約、コマンド一覧、データ形式のルール、ワークフローの手順書、参考資料など、エージェントまたは人間向けの永続的なガイダンスを含む、名前やディレクトリを問わないその他の Markdown ファイルです。

成功とは、選択したすべての対象がリポジトリ内の根拠に基づき、対象読者と適用範囲に即し、エージェントのコンテキストを行動を変えるガイダンスだけに使い、リポジトリで定義された最小範囲の検証に合格することです。変更内容（完了または予定）、検証結果、阻害要因を報告したら終了してください。

モデルとコンテキストの最適化

README.md は人間向けの明確なドキュメントとして保ちつつ、スキルやその他のエージェント向けコンテキストを GPT-5.6 と Claude Fable 5 に合わせて最適化します。複雑な作業、長時間に及ぶ作業、複数ツールを使う作業、またはオーケストレーションを多用する作業に着手する前に、最新の GPT-5.6 のプロンプトガイダンス と Claude Fable 5 のプロンプトガイダンス を読んでください。推奨事項は変わる可能性があります。

• エージェント向けコンテンツには、判断を変えるもの、根拠のある誤りを防ぐもの、または容易に見つけられない制約を示すものだけを残します。一般論、チュートリアル、歴史、一覧、何もしない説明、スクリプト、レシピ、スキーマ、設定ですでに適用されている仕組みは削除します。
• それぞれの意味は、効果的な読み込みチェーン内で一度だけ述べます。共有ガイダンスは親に置き、子には差分または上書きだけを記載します。個別に読み込まれる成果物が自己完結している必要がある場合は、繰り返しを残します。
• 信頼できる最も狭い読み込み範囲を選びます。普遍的なガイダンスはインラインで、パス固有のガイダンスはネストしたコンテキストに、まれな手順は必要に応じて参照するコンテキストドキュメントやスキルに置きます。必須のガイダンスを、確実にたどれないポインターの先に隠さないでください。
• 禁止事項を列挙するより、簡潔で肯定的な判断ルールを優先します。最小限の例は、厳密な要件を示す場合、または測定された失敗を正す場合にのみ残します。ツールやコマンドの説明は、振り分け、入力、副作用、出力、失敗の兆候が重要な場合にのみ残します。
• 権限、セーフティ、重要な例外、意味上の成功基準、機械が読み取る正確なテキスト、読みやすい文章を維持します。人間向けの README.md は、エージェントのトークンを減らすことだけを目的に短縮しないでください。ただし、その内容がエージェントのコンテキストにも含まれる場合は除きます。
• ドキュメントのみを変更できる権限があっても、ヘルパーやスキーマを新規作成または変更してよいことにはなりません。該当するものがない場合は、正確な内容を最小限の文章で維持し、対象範囲を広げずに抽出可能な機会として報告してください。

ワークフローを選択する

ワークフローを1つだけ選択し、そのリファレンスのみを参照してください。

ユーザーの意図	ワークフロー	リファレンス
コンテキストを更新、リフレッシュ、同期、整理、調整、修復、または修正する	polish	references/brain-polish.md
コンテキストファイルを作成、初期化、生成、または再生成する	create	references/create-docs.md
編集せずに監査、確認、レビュー、調査、または変更を提案する	--dry-run モードの polish	references/brain-polish.md
スキルを作成またはひな形から作成する	中止	skills/skill-writing を参照
スキルをインストール、検索、削除、または名前変更する	中止	専用のスキル管理ワークフローを使用

意図が不明確な場合は、--dry-run モードの polish を選択し、役に立つ最小限の変更予定を報告してください。

権限

• 作成、更新、調整、修復、修正などの明示的な意図があれば、対象範囲内でのローカル書き込みが許可されます。調査のみの意図と --dry-run では許可されません。
• README.md、AGENTS.md、CLAUDE.md、またはコンテキスト文書の対象を削除する前に、明示的な確認を求めてください。--force が許可するのは、文書化された上書きであり、削除ではありません。
• 広範囲の書き込み依頼は、依頼された範囲への許可とみなします。それ以外の場合は、ファイルが数個を超える変更予定をプレビューし、書き込み前に停止してください。
• ドキュメント作業の範囲を超えて、ソースの変更、スキルの作成、外部への書き込みを行わないでください。

引数

• path：リポジトリ相対のサブツリーを任意で指定します。ドキュメント、パッケージルート、プロジェクトスキル、コンテキスト文書の検索をそのサブツリーに限定します。
• target ...：polish 実行時の任意のフィルターです。既存の .agents/skills/<name>/ スキル名、または特定のコンテキスト文書を選択するリポジトリ相対の Markdown パスを指定します。
• --root-only：ルートの README.md、AGENTS.md、CLAUDE.md のみを対象にします。target で明示的に選択されない限り、プロジェクトスキルとコンテキスト文書は除外します。
• --dry-run：ファイルを変更せずに、予定する書き込みと簡潔な差分を報告します。
• --preserve：polish 実行時に、正確なユーザー作成の文章と構成を維持し、ずれや明らかなノイズだけを修正します。
• --minimal：完了基準を満たす、最小限のコンテキストを作成します。
• --thorough / --full：リポジトリ固有の情報を持続的に保持できる場合に限り、より詳細に分析します。
• --force：create 実行時に、既存の README.md または AGENTS.md の対象を確認なしで再生成します。スキルや削除には適用されません。

--minimal と --thorough / --full の両方が指定された場合は、書き込みを行わず、どちらを選ぶかユーザーに確認してください。認識されないフラグは報告してください。スコープ、安全性、書き込み動作に影響しない場合に限り、続行してください。

リポジトリのガードレール

検索や書き込みを行う前に実行してください。

cwd="$(pwd -P)"
case "$cwd" in
  /) printf 'abort: refusing to run at the filesystem root\n' >&2; exit 1 ;;
esac
repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || {
  printf 'abort: not inside a git repository\n' >&2; exit 1; }
managed_skill_root=
case "$repo_root" in
  /|"$HOME") printf 'abort: unsupported repo root: %s\n' "$repo_root" >&2; exit 1 ;;
  "$HOME/.agents"|"$HOME/.codex"|"$HOME/.claude") managed_skill_root="$repo_root/skills" ;;
  "$HOME/.agents/"*|"$HOME/.codex/"*|"$HOME/.claude/"*)
    printf 'abort: repo root is nested under an agent configuration repository: %s\n' "$repo_root" >&2; exit 1 ;;
esac
if [ -n "$managed_skill_root" ]; then
  case "$cwd" in
    "$managed_skill_root"|"$managed_skill_root/"*)
      printf 'abort: installed skills must be edited in their source catalog: %s\n' "$cwd" >&2; exit 1 ;;
  esac
fi

managed_skill_root が設定されている場合、そのリポジトリ内の他の場所にある README.md、AGENTS.md、CLAUDE.md の作業は許可しますが、すべてのワークフローでインストール済みの skills/ ツリー全体を除外してください。検索、正規化、またはシンボリックリンクのたどり処理より前に除外を適用してください。path、target、または明示的な依頼がそのツリー内を対象とする場合は、そこへの書き込みを行わず、スキルはソースカタログで編集する必要があることを報告してください。--force でもこの境界は上書きできません。

広範な編集の前に git status --short のスナップショットを取得してください。無関係な既存の変更は保持し、ジェネレーターや広範なコマンドを実行した後は、想定されるパスを再確認してください。

共通の制約

解決されたリポジトリの範囲内にとどまり、無関係な変更を保持してください。選択したワークフローのリファレンスは、README.md、AGENTS.md、CLAUDE.md、およびプロジェクトスキルの動作に関する正式な指針です。ここでファイル固有のルールを繰り返したり、拡大したりしないでください。

検出とツールのルーティング

Git を考慮して検出し、候補はすべて repo_root 配下に正規化したうえで、VCS、依存関係、環境、ビルド出力を除外します。プロジェクトのスキルが選択されている場合に限り、無視対象の .agents/skills/*/SKILL.md を意図的に含めます。fd を優先し、結果が不自然に少ない場合は一度だけフォールバックし、書き込み前に独立したリポジトリの証拠を統合します。

README.md、AGENTS.md、CLAUDE.md、SKILL.md ファイルから Markdown リンクをたどってコンテキスト文書を検出し、その後、内容が条件を満たす残りの追跡対象 Markdown ファイルをスキャンします。分類はファイル名や場所ではなく、内容に基づいて行います。変更履歴、ライセンス、法務およびポリシーに関する通知、生成された文書やベンダー提供の文書、ガイダンスではなく製品コンテンツである文章は除外します。分類が不確かな場合は対象範囲から外し、候補として報告します。

完了とレポート

書き込み後、リポジトリで定義された Markdown のフォーマット処理やチェックがあれば実行します。カタログ内でスキルの frontmatter または agents/openai.yaml が変更された場合は、呼び出しメタデータのチェックを実行します。変更された CLAUDE.md のシンボリックリンクが、同じディレクトリにある AGENTS.md を参照していることを検証します。--dry-run では、予定ファイルに依存するコマンドを実行せず、報告します。

書き込みと必須の検証に合格した場合に限り、先頭に ### ✅ コンテキストを更新しました を記載します。ファイルは書き込まれたものの必須チェックに失敗した場合は ### ⚠️ コンテキストを更新しました — 検証に失敗、ドライランの場合は ### 🔎 コンテキストのプレビュー — ファイルは書き込まれていません、書き込み前に処理を停止した場合は ### ⛔ コンテキストをブロックしました — ファイルは書き込まれていません を記載します。その後、次の項目のみを報告します。

1. 🧭 モードと範囲：ワークフロー、ドライランの状態、対象件数、相対パスを簡潔な表にまとめます。
2. 📦 変更：完了した変更または予定している変更をディレクトリごとにまとめます。パスの対応関係がわかりやすくなる場合はツリーを使用します。
3. 🧪 検証：正確なコマンド、結果、正当な理由によるスキップを表にまとめます。
4. ⚠️ ブロッカーとリスク：競合、注意事項、認識されないフラグを記載します。該当する項目がなければ省略します。

パス、コマンド、ガードレールのエラー、シンボリックリンクの参照先、ユーザーが作成した内容は、正確かつ装飾なしで記載します。空の詳細は省略し、選択された対象が完了基準を満たした時点で終了します。

参照資料

• polish：references/brain-polish.md を読みます。
• create：references/create-docs.md を読みます。