agents-progressive-disclosure

エージェント向け段階的開示

このスキルを使用して、長いエージェント指示ファイルを、焦点を絞ったドキュメントファイルへ誘導する要点重視のエントリーポイントに変換します。目標は、常に読み込まれるコンテキストを減らしながら、ルールを維持することです。

基本モデル

ルートの指示ファイルは、ルールの保管庫ではなく、ルーターとして扱います。

• エントリーファイルには、適用頻度が高く、長期間有効で、常に適用すべきルールだけを残します。
• タスク固有の詳細なルールは docs/ ファイルに移します。
• エントリーファイルには、「どのようなときにこのドキュメントを読むか」が明確に分かるインデックスを含めます。
• エージェントは、現在のタスクに関連するドキュメントだけを読み込みます。

ワークフロー

1. 対象となる指示ファイルを特定します。

   • ユーザーが別のファイルを指定していない場合は、現在のディレクトリにある AGENTS.md を優先します。
   • CLAUDE.md、GEMINI.md、またはプロジェクト固有の同等ファイルにも対応します。
   • 候補が複数あり、ユーザーが指定していない場合は、候補を報告し、現在のエージェント設定で最も広く使われているファイルを選びます。その選択が不明確、またはリスクを伴う場合に限り、ユーザーに確認します。

2. 既存の構成を確認します。

   • 対象ファイルを最後まで読みます。
   • 既存の docs/ ファイルがあれば一覧にします。
   • 編集前にバックアップの有無を確認します。

3. 分類する前に矛盾を検出します。

   • 文体のルール、パッケージマネージャーの選択、テストコマンド、安全上の境界、優先順位の記述、または異なる表現で重複しているルール間の矛盾を探します。
   • 明示的なユーザー指示、最も近い指示ファイルの優先順位、または明確なローカルの根拠に基づいて、可能な場合は矛盾を解消します。
   • 矛盾がリファクタリングに影響し、入手できる情報から解消できない場合に限り、ユーザーに確認します。

4. ルールを分類します。

   • エントリーポイントに残すもの：言語の既定値、安全上の境界、ツールの優先順位、競合時の優先順位、常に従うべき重要なルール。
   • ドキュメントへ移すもの：コマンド一覧、検索方法、フレームワーク固有の指示、パッケージマネージャーのルール、環境設定、Git ワークフロー、デプロイ、テスト、ドキュメントの文体、分野固有の用語、長い例。

5. ドキュメントマップを設計します。

   • プロジェクトに既存のエージェント向けドキュメント規約があれば、それを優先します。なければ、エージェント間の移植性を考慮して docs/ を既定とします。
   • 既存の規約には、.claude/、.claude/rules/、.cursor/rules/、またはその他のエージェント向けドキュメントディレクトリが含まれる場合があります。
   • 既存のドキュメント名が適切であればそのまま使用し、そうでなければ元のルール群に基づいて内容を絞った名前を付けます。
   • プラットフォーム固有のファイル形式、必須のフロントマター、インポート、パスのグロブ、ファイル拡張子を維持します。
   • 複数のドキュメントを案内する必要がある場合に限り、docs/README.md を作成します。

6. 保守的に編集します。

   • 対象ファイルを置き換える前に、同じディレクトリに、既存ファイルを上書きしない名前でバックアップを作成します。
   • エントリーポイントを、以下を含む簡潔なルーターとして書き直します。
     • 対象範囲の説明
     • 基本原則
     • 必要に応じて読むドキュメントのインデックス
     • 常に適用する安全・ツールのルール
     • 優先順位のルール
   • 詳細なルールは意図を変えずにドキュメントへ移します。
   • 同じ長いルールを複数箇所に重複して記載しないようにします。

7. 維持できていることを検証します。

   • 元のルールの各カテゴリについて、移動先、確認用のキーワードまたは見出し、合否を対応づけた簡潔な維持チェックリストを作成します。
   • このチェックリストは一時的な検証作業として扱い、ユーザーから求められた場合、またはプロジェクトに既存の移行記録の慣例がある場合を除き、リポジトリには書き込みません。
   • 変更前後の行数を比較します。
   • 元のファイルから選んだチェックリストのキーワードが、新しいエントリーポイントと、振り分け先のドキュメントまたはルールファイルに含まれているかを検索します。
   • エントリーポイントで、各ドキュメントを読むタイミングが案内されていることを確認します。
   • どのドキュメントもエントリーポイントと矛盾していないことを確認します。

エントリーポイントの推奨構成

# Agent Instructions

> Scope: This file is the entrypoint. It keeps only always-on rules; task details live in docs/.

## Core Principles

- [language/default behavior]
- [safety boundary]
- [primary tool or evidence policy]
- [this file is a router, not a warehouse]

## Read-On-Demand Index

| Task type | Read first | Trigger |
| --- | --- | --- |
| [rule cluster] | `[focused-doc]` | [when to read it] |
| [rule cluster] | `[focused-doc]` | [when to read it] |

## Always-On Rules

- [short critical rules]

## Priority

1. User's current explicit instruction.
2. Nearest project instruction file.
3. This file.
4. Routed docs details.

検証コマンド

実際の対象ファイル、振り分け先の docs／rules ファイル、保持チェックリストのキーワードに置き換えて、現在の環境と互換性のあるコマンドを使用してください。以下の例では POSIX スタイルのシェルコマンドを使用しています。必要に応じて、Windows やその他のシェル向けに調整してください。

find <docs-dir> -maxdepth 1 -type f -print | sort
wc -l <target-file> <routed-docs...>
rg -n '<checklist-keyword>|<another-checklist-keyword>' <target-file> <routed-docs...>
sed -n '1,180p' <target-file>

チェックリストのキーワードは、このテンプレートではなく、ソースファイルから選んでください。

ガードレール

• 冗長であるという理由だけでルールを削除せず、適切なドキュメントに移してください。
• 安全上重要なルールを、振り分け先のドキュメントにだけ記載しないでください。
• 役割が重複する細かなドキュメントを多数作成しないでください。
• ユーザーから求められない限り、ソースファイルにないプロジェクト固有の見解を追加しないでください。
• 実際にスキルをアクティブなスキルディレクトリにコピーまたはインストールして検証していない限り、Codex にインストールしたと主張しないでください。