cold-read

コールドリード

すべてのドキュメントは、いずれ、その作成に至る会話に参加していない誰か（人間またはエージェント）に読まれます。その読者に向けて、現在の状態を、説明がなくても理解できる形で、余計なことを含めずに書いてください。

書き始める前に、その読者の立場で考えてください。行動するために何が必要か、知り得ないことは何か、どの行について質問せざるを得ないか。読者の立場で考えたときに通用しない文はすべて、単独で意味が通るように書き直すか、削除してください。

ルール

• 現在の状態のみ。 以前はどうだったか、何を移行または廃止したか、何がもう使われていないかは、ドキュメントには含めません。過去との対比でしか意味を持たない事実は重要ではありません。
• 経緯を知らないと理解できない参照はしない。 過去の会話でしか説明されない名前、コードネーム、決定は、読者自身が適用できる一般的なルールに置き換えるか、削除してください。一般化に、誰も書き残していない事実が必要なら、その行を削除して担当者に伝えてください。理由をでっち上げてはいけません。
• 当たり前のことは書かない。 読者が誰も違反しないような警告はノイズです。代わりに、.gitignore、リンター、CI などで機械的に強制し、何も書かないでください。
• メタコメントはしない。 ドキュメントの書き方や、作成過程で合意したことには触れず、ルールそのものを記載してください。
• 使う場所で説明する。 変数、シークレット、定数は、それを使用する場所（スキル、モジュール、設定）で説明してください。中央のドキュメントには、それらの入手元と取得方法だけを記載してください。
• 英語。 ただし、データそのものは例外です。外部の実体（データベース、プロパティ、ページ）の名前は、そこで使われている表記のままにしてください。

スキルについては、次のとおりです。

• 説明はマニュアルではなく、起動条件です。スキルの内容と、どのような場合に起動するかを記載してください。実装の詳細は本文に記載し、使用時にのみ読み込まれるようにしてください。
• スキルは AGENTS.md ／ CLAUDE.md に記載しません。スキル自身の説明を通じて認識されます。

実際に検証する

作成者には、自分自身の見落としが見えません。すでに経緯を知っている人には、どの行も当たり前に読めるからです。初めて読む人は、数分で不足に気づきます。そのため、実際に読まれる状況でドキュメントを試してください。新しいサブエージェントを起動し、そのドキュメントだけを読ませてから、次のことを行います。

1. シナリオ形式の質問（「X を頼まれたら、どう進めますか」）を与え、正しい行動にたどり着くかを確認します。
2. 何が分かりにくかったか、必要なのに見つからなかった情報は何か、読んだものの不要だった情報は何かを尋ねます。

誤読された箇所を修正し、別の新しい読者で修正内容を再検証してください。サブエージェントを利用できない場合は、ドキュメントを読み直し、見知らぬ人がドキュメント自体から出典をたどれない事実をすべて列挙して、代わりの自己点検を行ってください。