progressive-disclosure

段階的な開示

長い指示ファイルは、その内容が不要なターンも含め、毎回読み込まれるためのコストが発生します。解決策は削除ではありません。内容には意味があります。重要なのは配置です。すべての実行で必要な内容はエントリーファイルに残し、一部の実行でのみ必要な内容は、関連する場合に参照されるようにします。このスキルでは、1つの成果物を再構成します。どの成果物に再構成が必要かを知るには、まず監査してください。

手順

1. 成果物全体を読み、分岐、つまり実行の進み方が実質的に異なる経路を特定します。ユーザーが検証を求めたときにのみ参照される検証セクションは分岐です。一方、毎回適用されるルールは分岐ではありません。
2. すべてのセクションを、すべての分岐で必要なものと、1つの分岐でのみ必要なものの2つに分類します。この区分が判断のすべてであり、通常は見た目ほど均等ではありません。ほとんどのファイルは、短い共通のコアを分岐ごとの詳細で包んだ構成です。
3. 共通のコアをエントリーファイルに残し、そのファイルだけでも筋が通る順序にします。子ファイルなしでは意味が通らなくなったエントリーファイルは、切り分け方が適切ではありません。
4. 各分岐を兄弟ファイルに移し、由来ではなく内容に基づいて名前を付けます。verification.md や glossary.md のように、ファイル名だけでいつ開けばよいかがわかるようにします。
5. ポインターの文言によって、その内容が参照されるかどうかが決まるため、慎重に記述します。条件とファイルをセットで示します。「変更がマイグレーションに触れる場合は、計画前に migrations.md を読んでください」のようにします。ファイル末尾にリンクを置くだけでは、ポインターになりません。
6. 各分岐を最初から最後までたどり、必要なものがすべて揃っていることを確認します。その後、移動した内容、残した内容、エントリーファイルの新しいサイズを報告します。

注意事項

• 分割は削除ではありません。あるセクションが本当に不要なら、その旨を明示して完全に削除してください。誰も開かないファイルに隠してはいけません。
• すべての分岐で必要な内容は分割しないでください。常に一緒に読まれる2つのファイルは、手順を増やしただけの1つのファイルです。
• 一度も使われないポインターは、内容を見えなくしてしまうため、インラインで残すよりも悪い結果になります。きっかけとなる条件を明確に表現できない場合は、そのセクションをそのまま残してください。
• 依存する前に、対象のハーネスが SKILL.md と一緒に兄弟ファイルも実際に同梱することを確認してください。インストーラーによって動作は異なるため、配布されなかったファイルへのポインターはスキルを破損させます。
• エントリーファイルが読みやすくなったら、そこで止めてください。それ以上の分割は、別の種類の読みにくさを生むだけです。