agent-doc-discipline

エージェント向けドキュメントの規律

エージェントが行動する際に参照するドキュメントを作成または編集するときに、執筆時の規律を適用するためのスキルです。対象となるのは、5つのサーフェス（CLAUDE.md、GLOSSARY.md、docs/standards/、design-system/、.omc/skills/）、仕様書、チケット、スキルファイルです。ドキュメントが満たすべき基準は、新しいエージェントセッションが、読むだけでそれに基づいて行動できることです。

必須となる場面：drydock がサーフェスのひな形を生成するとき、および launch C5 sediment pass が教訓を所定の場所に書き込むときです。それ以外の編集では任意ですが、エージェント向けドキュメントを編集する場合は、この規則に従う必要があります。

使用しない場合

人間だけを対象に書かれたドキュメント：docs/business/ の説明文、ADR の意思決定の経緯、オンボーディング用の README です。負担なく従える範囲では規則を適用してもかまいませんが、この規律の対象ではありません。

規律

チャット履歴のない読者に向けて書きます。 ドキュメントは、それ自体で内容が分かるものにします。「前に話したとおり」、以前のセッション、誰かの頭の中にしかない知識に依存してはいけません。確認基準： 新しいエージェントセッションが、読むだけでドキュメントに基づいて行動できます。

すべてのルールは確認可能で、理由を伴うものにします。 「きれいに保つ」とは書かず、観察可能な条件とその理由を書きます。確認基準： エージェントがテキストだけで合否を判断でき、理由がルールのすぐそばに記されています。

1つの意味につき、定義する場所は1つです。 各ルールや定義には、権威ある場所を1つだけ設けます。重複は、内容の食い違いを招く原因になります。確認基準： 振る舞いの変更が1か所の編集で済みます。

環境を見れば分かることを、文書に書き直してはいけません。 パッケージスクリプト、ディレクトリ構成、--help の出力は、参照して確認するものであり、コピーして文書にすると古くなります。参照すれば見つかる情報ではなく、明文化されていない慣習、選択の背景にある理由、落とし穴だけを記載します。確認基準： すべての行について、「これはほかの場所を見れば分かるか？」と問い、見つからないことを確認できます。

手順を先に、参照情報を後に、まれに使う情報はポインターの先に置きます。 最初に、実行する作業を順番に示します。その下に必要に応じて参照するルールを置き、使用頻度の低い情報は、参照すべき状況を具体的に示すポインターの先に配置します。確認基準： 次に取るべき行動が、最初の画面内で見つかります。

各手順は完了基準で終わらせます。 完了と未完了を見分けられるようにします。曖昧な境界では、早まって完了と判断されます。確認基準： 各手順について、「何をもって完了と分かるか」の答えがテキストにあります。

2つを超える手順は番号付きにします。 番号は安定した参照先になります。読者は手順3を指定し、順番に従い、読み直さずに該当の手順へ移れます。手順が多いのに番号がないと、読者は順番を頭の中で覚えておかなければなりません。確認基準： 3つ以上の手順を含む手続きには、すべて番号が付いています。

リストは、読者が一目で把握できる長さに収めます。 読者が把握しきれない長さのリストは要点が見えなくなり、項目を見つけにくくなります。長い列挙は、表や小見出しなどの構造にするか、複数に分割します。この規則はドキュメントの書き方に適用されます。ゲートや一括判断の仕組みには適用されません。それらは文章ではなく、方法論に属するものです。確認基準： ドキュメント内のすべてのリストが一目で把握でき、長い列挙は構造化されています。

先送りまたは予定されている作業には、実施時期を記載します。 後の手順、セッション、リリースに作業を先送りする場合は、その作業のすぐそばに実施時期を記載します。読者が行動するには「いつ」が必要であり、時期が書かれていない先送りは、未着手と受け取られます。実施時期は文章にのみ記載し、方法論が意図的に後に設定したチェックポイントを変更してはいけません。確認基準： ドキュメント内のすべての先送りに、実施時期が記載されています。

読者が今すぐ始められる次の行動で締めくくります。 レポート、チケット、セッション終了時のポインターは、要約ではなく、読者が2分以内に始められる次の一手で終わらせます。行き先、ポインター、またはコマンドを示します。要約だけで締めくくると、読者は何から始めるかを改めて考えることになります。確認基準： 最後の行を読めば、上にスクロールしなくても「次に何をすればよいか」が分かります。 読者が戻ってくるたびに、現在の状況を述べ直してください。 読者が途中で触れる文書（長い仕様書、実行レポート、マップの Notes セクションなど）では、新しい内容を追加する前に、現在の状況（ステップ、フェーズ、決定事項の数など）を冒頭で示してください。確認方法: 初めて読む読者が、最新セクションの最初の 2 行で現在の状態を把握できること。

禁止ではなく目標の行動を示してください。 目標とする振る舞いを述べてください。禁止事項は厳格なガードレールにのみ使い、必ず目指す行動とセットで書いてください。確認方法: 文書中のすべての禁止事項に、代わりに行うべきことが明記されていること。

書き込み時に不要な残骸を取り除いてください。 文書に古い内容や重複した内容がある場合は、同じ編集の中で削除してください。ない場合は、必要な内容のみを追加し、削除を作り出さないでください。モデルが既定で従う文は、読み込みコストに見合わないため、文全体を削除してください。確認方法: 読み直したすべての行が「既定の振る舞いから変わるか」を基準に存在価値を持つこと、また編集中に見つかった古い内容や重複した内容がすべて除去されていること。

検証

文書の変更が完了したと報告する前に、次を確認してください:

• 新しいセッションが、人間に何も尋ねずに、その文書に基づいて行動できること
• すべてのルールが検証可能で、その理由が書かれていること。ルールが単なる参照情報の繰り返しになっていないこと
• 用語の意味は一箇所にまとめられ、参照先は分岐の条件を明示していること
• 編集中に見つかった古い内容や重複した内容は削除され、関係のない有効な内容は残されていること
• 締めくくりは、読者が今すぐ始められる次の行動で終わっていること。戻ってきた読者が、新しい内容より前に現在の状態を確認できること
• 3 ステップ以上の手順には番号が付いていること。リストは一目で把握できる長さであること。延期するものはすべて、いつ再開するかを明記していること