ln-21-documentation-auditor

ドキュメント監査

目標： ドキュメントを読み取り専用の証拠システムとして監査します。新しいコントリビューター、運用担当者、ユーザー、コーディングエージェントが、適切な情報源を見つけ、その記述を信頼し、隠れた前提知識なしに行動できるかを確認します。単独のドキュメントに加え、公開情報や運用上の知識を担うコードコメントも確認します。

実行上の取り決め： 順番に並んだチェックボックスを完了の定義とします。各項目を内部で PENDING、具体的な証拠がある場合は PROVEN、該当条件が存在しない証拠がある場合は CLEARED、不足がある場合は UNPROVEN として追跡します。読むこと、作業を委任すること、ツールが失敗することは、証明にはなりません。各セクションの後に項目の状態を見直してください。回答を返す前に、すべての PENDING を解消し、PROVEN と CLEARED のみを数え、各不足についてスキルの判定基準と承認ルールを適用してください。 ユーザーの意図、範囲、既存の承認内容を維持してください。承認済みの作業は続行し、重大な選択が未解決の場合、または外部承認が必要な場合に限って質問してください。確認の深さは対象のリスクに応じて調整し、確認項目を黙って省略しないでください。依存関係と安全性に関する順序を維持し、それ以外は各要件に適した検証方法を選んでください。

ツールの使い分け

必要な確認	優先するツール	使用する場面	代替手段
ドキュメントの一覧と階層	対象を絞ったパターンを使った標準のファイル一覧表示	ドキュメントの範囲、生成領域、ナビゲーション構造を把握する	リポジトリツリーと既知の主要ドキュメント
リンク、繰り返し使われる用語、主張、矛盾	標準のテキスト検索の後、対象を絞って読み込む	参照、古い名称、重複したガイダンス、パス、コマンド、設定キーを探す	ドキュメント間の手動比較
コードと設定の正確性	標準のコード検索、マニフェスト、スキーマ、直接のファイル読み込み	ドキュメントに記載されたパス、オプション、エンドポイント、動作、デフォルトの存在を確認する	テキストだけでは不十分な場合、安全な確認コマンドを実行する
最新性と管理責任	Git のログ、blame、diff	主張がいつ変更されたか、ドキュメントが現行コードに追随しているか、慣例の管理者が誰かを確認する	現在のコードと明示的な管理責任を示すファイル
コマンドと例	変更を加えない、またはドライランでのシェル実行	ヘルプテキスト、コマンドの存在、設定の解析、生成された出力、例の構文を確認する	コマンドの登録箇所とテストを調べる。実行時の証明ができない場合はその旨を記録する
外部情報	公式ドキュメント、仕様、リリースノート	現在の外部 API、バージョン、標準、プラットフォームの動作が正確性に影響する	一次情報源のウェブ調査。それもできない場合は UNVERIFIED と記録する

公開、移行、デプロイ、本番環境の状態変更、ドキュメントの書き換えを行うコマンドは実行しないでください。生成キャッシュは、許可されており、開示される場合に限って使用できます。

証拠に関するルール

主張の種類	必要な証拠
リポジトリのパス、シンボル、コマンド、設定、エンドポイント、デフォルト	現在のリポジトリ、または安全なコマンドの出力
外部 API、バージョン、標準、互換性に関する記述	該当するバージョンに対応する公式情報源
件数またはカバレッジに関する記述	対象範囲と除外項目を示す再現可能なクエリ
歴史的な経緯	現在の意思決定記録、または実装と今も一致する履歴
推奨事項	実証された読者のつまずき、矛盾、保守コスト、運用リスク

ドキュメントがないことを指摘事項とするのは、実際の読者に不足している知識が必要な場合に限ります。古いガイダンスや不足しているガイダンスは、それによって生じる読者のつまずきや損害に基づいて評価してください。

チェックリスト

1. 対象範囲と読者を定める

• 対象範囲に含めるドキュメントの入口、公開ドキュメント、メンテナー向けドキュメント、運用ランブック、生成されたリファレンス、例、コードコメントを特定します。
• 想定読者と、その読者が実行する具体的なタスク（理解、インストール、設定、運用、トラブルシューティング、拡張、検証）を特定します。
• 適用されるリポジトリの指示を読み、ドキュメントの所有者、生成コマンド、言語ポリシー、正本の規約を確認します。
• 不備を評価する前に、作成されたドキュメントと、生成されたコンテンツ、ベンダー提供のコンテンツ、アーカイブ、一時的なコンテンツ、サンプルを区別します。
• 各対象を、入口／索引、リファレンス、ハウツー、解説、意思決定記録、生成物、例に分類します。ナビゲーションだけのファイルより、正本となるドキュメントや、重要な主張を多く含むドキュメントを優先します。
• ドキュメントの主張を検証する際に使用できるコード、設定、スキーマ、テスト、外部仕様を明確にします。
• 監査は読み取り専用で行い、利用できないソース、コマンド、環境があれば制約として記録します。

2. 構成と見つけやすさを確認する

• ルートの入口ドキュメントで、読者に応じて、目的、サポート対象の使い方、前提条件、インストール手順、ナビゲーションが説明されていることを確認します。
• 階層、見出し、目次、内部ナビゲーション、相互リンク、アンカー、関連情報の配置が予測しやすいかを確認します。
• 大文字と小文字の区別を含め、ローカルパスとアンカーを確認し、外部リダイレクトの遷移先が誤っていないか、利用可能かを調べます。意図的なリダイレクトが正常に機能している場合は、不備ではありません。
• 孤立したドキュメント、重複する入口、循環するナビゲーション、階層の深いリンクチェーン、リポジトリ検索でしか見つからない重要なコンテンツを特定します。
• 各概念に正本となるドキュメントが1つあることを確認し、二次ドキュメントでは規則、しきい値、手順を分岐させず、リンクするようにします。
• 生成されたドキュメントに生成ツールが明記され、上書きされる手編集を促していないことを確認します。
• 安全に作業するために必要な手順や背景情報を損なわずに、大きなドキュメントを分割または簡潔にできるかを確認します。

3. 関連性、網羅性、一貫性を確認する

• 各ドキュメントのタイトル、対象範囲の説明、想定読者を実際の内容と照らし合わせます。
• ドキュメントの種類に応じて内容を評価します。インデックスは詳細を重複させずに適切な場所へ案内し、リファレンスは正確な情報をすばやく見つけられるようにし、ハウツーガイドは安全な順序で手順を示し、解説は適切なメンタルモデルを構築し、意思決定記録は背景、決定事項、代替案、結果を残します。
• 想定読者の判断や行動に役立たない埋め草、要約の繰り返し、推測に基づく説明、汎用的な生成文、形式的なだけのセクションを指摘します。
• コピーされた実装やビジネスロジックよりも、長期にわたって有効な意図、契約、制約、運用を優先します。安全に行動するために必要な、検証済みのコード例やコマンド例だけを最小限残します。
• 話題から外れた内容、対象範囲の拡大、説明のない前提条件、隠れた前提、現在進行中のタスクを支えなくなったセクションを特定します。
• 該当する場合は、公開される動作、設定、デプロイ、移行、障害復旧、セキュリティ上慎重な操作、拡張ポイントが網羅されているか確認します。
• ドキュメント間で要件やアーキテクチャに関する記述をたどり、矛盾や曖昧な責任範囲を報告します。黙って一方を選ぶことは避けます。
• 古くなった将来計画、完了済みの TODO、削除された機能、レガシー互換性に関する案内、古いディレクトリ構成、古いスクリーンショットや例を見つけます。
• 用語、エンティティ名、識別子、大文字・小文字、ライフサイクルの状態が、コードおよび各ドキュメント間で一貫しているか確認します。
• 警告、前提条件、破壊的操作、ロールバック手順、障害発生時の結果が、読者に必要な箇所に記載されているか確認します。
• 常時読み込まれるエージェント向け指示では、ツールによってすでに適用される冗長な書式に関する説明と、サポート対象のスコープ付きファイルに移動できるパス固有の詳細を特定します。発見に必要な情報、明白でない要件、ホストとの互換性に関する情報は残します。

4. 事実と例を検証する

• パス、ファイル、シンボル、バージョン、件数、コマンド、フラグ、環境変数、設定キー、ポート、エンドポイント、スキーマ、デフォルト値に関する重要な記述を抽出します。
• 検証前に正規化した主張台帳を作成し、繰り返し登場する主張を対象ごとにまとめます。これにより、リポジトリを一度確認するだけで、古い記述のコピーとドキュメント間の矛盾の両方を明らかにできます。
• 各主張を、現在のリポジトリ内の根拠または安全なコマンドで検証します。検証に使った正確な情報源と範囲を記録します。
• 外部ドキュメントを参照したり、現在のサポート状況を述べたりする前に、マニフェストとロックファイルでインストール済みのバージョンを確認します。
• 外部 API、非推奨化、セキュリティ標準、プラットフォームの制限、互換性に関する記述には、公式情報源を使用します。
• 例は安全なローカル環境または破棄可能な環境でのみ実行します。それ以外の場合は、構文解析、テスト、想定出力を確認し、静的に検証したことを明記します。
• 例に不足しているインポート、実際の値のように示されたプレースホルダー、無効なパス、安全でないシークレット、古い構文、動作と一致しなくなった出力がないか確認します。
• 例、テンプレート、将来計画、外部参照は、明示された文脈に沿って解釈します。現在無効になっている場合でも、サポート対象の前提条件について記載された条件付きの案内を検証します。仮定上の例をデプロイ済みの動作として評価しないでください。
• 数値の件数は、除外項目を明記した再現可能なクエリで検証します。自動化されない限り、変動する集計件数を残すことは避けます。
• 変更されやすいバージョン、パス、デフォルト値、一覧、生成された出力、状態のスナップショットは、実用上可能な場合、信頼できるコード、設定、生成元へ移すことを推奨します。それが難しい場合は、古い情報が気づかれないまま残るのを防ぐため、必要な情報源、対象範囲、担当者、または生成・更新の契機を特定します。
• 調査結果から対応へ進むための基準を適用します。外部の情報は、リポジトリ内の具体的な欠陥またはリスクを示す場合に限り、指摘事項とします。

5. レビューコメントとレポートの作成

• コメントと docstring を確認し、有用な根拠、不変条件、契約、副作用、失敗時の動作、および自明でない制約があるか調べます。
• 公開インターフェースまたは自明でないインターフェースの docstring が、現在のシグネチャ、パラメータ、戻り値、発生するエラー、副作用、null 許容性、ライフサイクル上の義務と一致しているか照合します。
• 構文の説明、陳腐化した履歴、デッドコード、虚偽の約束、名前や型でより適切に表現できる情報にフラグを立てます。制約を今も説明している、または既知のリグレッションを防ぐ歴史的根拠は保持します。
• 公開インターフェースについて、言語またはエコシステムで求められるドキュメント、および実際の契約に一致する例があるか確認します。
• 報告する前に、意図的な対象読者向けの簡略化、フレームワークの慣例、生成された文章、受け入れ済みのレガシー制約を除外します。
• 対象範囲内のすべてのドキュメントまたはコメントの面を KEEP、ADD、UPDATE、DELETE、MERGE に分類します。削除または統合は、正規のカバレッジが必須の対象読者タスクと契約をすべて保持できる場合にのみ推奨します。
• 重要度ゲートを適用します。証拠に基づく規模で、読者の具体的な誤り、ブロックされたタスク、不安全な操作、矛盾、または反復的な保守コストを要求します。好み、理論上の純粋さ、一般的な慣行、仮定上の規模、妥当な代替案は却下します。望ましい実装ではなく、成果または制約を要求します。
• 外部の修正はバージョンが一致する公式契約に根拠を置き、未解決のトレードオフには一次エンジニアリング情報源を使用します。裏付けのあるメカニズムを引用します。ローカルの欠陥にはローカルの証拠で十分です。
• 誤った操作、操作不能、保守のドリフト、または軽微な摩擦によって生じる害に基づき、所見を P0～P3 に分類します。
• 安全性に重要な主張、必要な対象読者ジャーニー、または権威ある情報源が、信頼できる代替手段なしに検証できない場合は BLOCKED を使用します。証拠が不安全なガイダンス、操作不能な必須ジャーニー、または未解決の P0/P1 を証明する場合は FAIL を使用します。CONCERNS は、重大な非ブロッキングの信頼ギャップにのみ使用し、PASS は、必要な主張とジャーニーが検証され、重大な所見がない場合にのみ使用します。

セルフチェック

• 返す前に照合する。 項目レベルの証拠、要件のカバレッジ、矛盾、スコープ、判定、および該当するクリーンアップを確認します。レポートまたは承認された成果物を修正します。有効な証拠を再利用します。リポジトリを自動的に再スキャンしたり、成功したコマンドを再実行したりしないでください。関連する変更、失敗、または未解決の証拠がある場合にのみチェックを繰り返します。残っているギャップを開示します。

出力契約

ユーザーの言語で、この順序で報告します。5 つのフィールドをすべて保持し、各事実は一度だけ述べます。小規模な結果ではフィールドごとに 1 行を使用してかまいません。空のテーブルは省略し、リンクされた成果物をコピーしないでください。

1. 結果: スキル固有の判定と裏付けられた成果。
2. スコープ: レビュー済み/変更済みのスコープ、除外、ベースライン、および重要な前提。
3. 証拠: 以下に示すスキル固有のフィールド。事実、推論、未検証の主張を区別します。成果物をリンクし、役立つ場合はテーブルを使用します。
4. 検証: チェック/結果、利用できない証拠、および該当するクリーンアップ/外部状態。
5. 完了: Checklist: X/Y complete、Incomplete: None または各 UNPROVEN 項目の理由、成果への影響、および正確な次のアクション。残余リスクと必要な意思決定。

スキル固有の証拠: ドキュメントの対象読者とジャーニー。構造、カバレッジ、正確性、耐久性/SSOT、およびコメントの信頼性。対象範囲内の面ごとに KEEP / ADD / UPDATE / DELETE / MERGE を記録します。所見には、優先度、ドキュメントの場所、検証する証拠、影響を受ける対象読者、重大な影響、受け入れがたいトレードオフ、および最小限の修正または正規のオーナーが必要です。同等の構造を許容します。未検証の主張と証明された欠陥を区別します。