docs-guard

Docs Guard

リリース前に、生成または変更されたドキュメントをレビューします。最初のドキュメント作成後のガードパスとして、以下のルールを適用してください。基本原則は、ドキュメントとはコードベースに関する主張の集まりであり、その主張はすべて検証可能であるということです。あなたの役目は、それらを確認することです。

AI エージェントが目の前のコードではなく、API が「通常どのようなものか」という記憶をもとにドキュメントを書くため、これらのルールが設けられています。公開された研究によると、プログラミングに関する AI の回答の半数には誤った情報が含まれ、モデルは使用頻度の低い API に対して、正しい呼び出しを生成できるのはわずか 3 分の 1 程度です。それでも、どちらの場合も文章は断定的に聞こえます。読者には、検証済みのドキュメントと幻覚によるドキュメントを見分けられません。ソースを確認できるあなたなら見分けられます。

このスキルの使い方

ガードパスモード（推奨）：ドキュメントまたは docstring の生成・編集後に、ソースと照合してすべての主張を検証し、提出前にセルフチェックを実行します。

ライブモード（明示的）：ドキュメントを書く前にユーザーがこのスキルを呼び出した場合は、執筆前に検証します。実際の実装を読み、その動作をドキュメントに記述します。提出前にセルフチェックを実行します。

レビューモード（ユーザーからドキュメントのレビュー、監査、ファクトチェックを依頼された場合）：対象ドキュメントに対してreferences/review-checklist.mdを順に確認し、ファイル名と行番号を根拠として、指摘事項のレポートを作成します。依頼がない限り、レビューモードでは書き直しを行いません。

まずプロジェクトに合わせる

1. プロジェクトのエージェント向け指示（CLAUDE.md、AGENTS.md）と、ドキュメントのスタイルガイドを読みます。矛盾する場合は、プロジェクトの規約を優先します。
2. 連動して更新する必要があるドキュメントの対象を特定します：README、リファレンスドキュメント、docstring、変更履歴、サンプル、設定例。通常、いずれかを変更した場合は、ほかの対象も更新する必要があります（ルール 6）。
3. ドキュメントに記載されたバージョンポリシーを確認します。プロジェクトがサポートするバージョンと、機能にバージョンタグを付ける場所を把握します。

ルール

正確性 — 必ず修正

1. 参照されているシンボルはすべて実在する必要があります。 ドキュメントに記載された関数、メソッド、クラス、フック、CLI コマンド、フラグ、エンドポイント、設定キー、環境変数、ファイルパスはすべて、記憶に頼るのではなく、実際のソース、CLI ヘルプ出力、ルートテーブル、またはスキーマを読んで確認します。検証手順はreferences/verification.mdにあります。検証できない参照はリリースしません。

2. すべてのコードサンプルが動作する必要があります。 インポート先が解決でき、API がドキュメントに記載されたシグネチャ（名前、引数の順序、デフォルト値、戻り値の形式）で存在し、サンプルが作成者のマシン以外でも実行できる必要があります。ハードコードされたローカルパス、実際の認証情報、暗黙の事前状態は使いません。サンプルのルールについてはreferences/code-samples.mdを参照してください。

3. 意図された動作ではなく、コードの実際の動作を記述します。 説明する前に実装を読みます。コードとコメント／仕様が食い違う場合は、コードを事実として扱い、どちらかを黙って選ぶのではなく、相違点をユーザーに指摘します。

4. 検証できない主張はしません。 パフォーマンス数値、互換性マトリクス、規模の上限、「本番環境対応」といった主張には、リポジトリ内の根拠（ベンチマークスクリプト、CI マトリクス、変更履歴の項目）が必要です。根拠がなければ削除します。「高速」は宣伝文句です。「bench/sort.md でベンチマーク済みの O(n log n)」ならドキュメントです。

バージョン管理と乖離

5. バージョンを明記します。 プロジェクトがバージョンを追跡している場合、機能、フラグ、動作には、それが導入されたバージョンを記載します。前提条件は固定するか範囲を指定し、「最新」とは記載しません。非推奨の項目にはその旨と代替手段を記載します。

6. コードの変更にはドキュメントの変更が伴います。 ドキュメントに記載された動作に関わるコード（名前の変更、シグネチャの変更、デフォルト値の変更、フラグの削除など）を編集した場合、同じ変更内でそれについて記載しているすべてのドキュメントを更新します。完了前に、ドキュメント全体を検索して古いシンボルが残っていないか確認します。

内容 — 修正すべき点

7. 水増しや冗長な記述を避けます。 次の記述は削除してください。シグネチャを言い換えただけの docstring（get_user_by_id の上にある「ID でユーザーを取得します」など）、見出しの内容を繰り返すセクション、技術的な文章における宣伝文句（「高性能」「シームレス」「驚異的な速さ」など）、導入部の水増し（「このセクションでは、〜を見ていきます」など）。docstring を記載する価値があるのは、シグネチャでは表現できない契約を補足する場合です。単位、範囲、エラー条件、副作用、スレッド処理や順序に関する保証などが該当します。

8. 上流ドキュメントを言い換えないでください。 外部ドキュメントの内容を繰り返すのではなく、リンクしてください。上流ドキュメントを言い換えると、上流の変更と同時に内容が古くなります。ドキュメントに記載するのは、外部の要素との関係に限ってください（使用するサブセット、異なる設定など）。

9. 例では失敗時の処理も説明してください。 成功例しか示さないチュートリアルでは、API の半分しか説明していません。実際にコードが送出するエラー型を使って（ルール 1 に従って確認してください）、エラーの見え方と呼び出し側が取るべき対応を示してください。

構成 — 留意すべき点

10. ナビゲーションは実態を反映してください。 見出しは各セクションの内容を表し、目次は実際の見出しと一致し、内部リンクとアンカーは正しく解決され、公開済みドキュメントに TODO の仮置きや「近日公開」セクションがない状態にしてください。未執筆のセクションは公開を約束するのではなく、削除してください。

提出前のセルフチェック

1. ドキュメントで言及しているシンボル、フラグ、エンドポイント、設定キー、パスをすべて列挙してください。このセッションで、記憶に頼らず、それぞれをソースと照合しましたか？
2. コードサンプルはすべて、クリーンな環境で実行できますか？各インポートとシグネチャを確認しましたか？
3. リポジトリ内で検証可能な根拠がない数値、互換性に関する主張、最上級表現はありませんか？
4. この変更でコードに手を加えた場合、古い名称が残っていないか、すべてのドキュメントを grep で検索しましたか？
5. シグネチャを繰り返しただけの docstring や、見出しの内容を繰り返したセクションはありませんか？
6. 内部リンクとアンカーはすべて正しく解決されますか？

どれか 1 つでも「いいえ」なら、ユーザーに見せる前に修正してください。

報告形式（レビュー時）

**Rule N violation** in `docs/path.md:<line or section>`
- Claim: <what the docs say>
- Reality: <what the code/CLI/schema actually has, with file:line>
- Fix: <one sentence>

まずルール 1〜4 に関する指摘（誤った主張）、次に内容の乖離、最後に内容面の指摘を示してください。問題のないドキュメントについては、正確さも評価に値するため、一行でその旨を伝えてください。

重大度の目安

• 必ず修正： ルール 1〜4 — 誤ったドキュメントは、ないよりも有害です。読者はその内容に基づいて行動します。
• 修正すべき： ルール 5〜9 — 内容の乖離による負債や、重要な情報を埋もれさせる不要な記述です。
• 留意すべき： ルール 10 — ナビゲーションと仕上がりに関する項目です。

参考資料

• references/verification.md — 主張の抽出、シンボル、シグネチャ、CLI フラグ、エンドポイント、設定キー、リンクの検証に関する具体的な手順
• references/code-samples.md — 提出可能なサンプルの条件：実行可能性、現実的なデータ、シークレットの取り扱い、エラー処理
• references/docstrings.md — docstring／PHPDoc／JSDoc 固有のルール：記載が妥当なケース、必須内容、言い換えの検出
• references/review-checklist.md — レビュー時に使用する、手順に沿ったチェックリスト
• references/sources.md — 調査資料とスタイルガイドの URL。出典を引用する場合にのみ参照してください

このスキルで対応しないこと

• コードそのもののレビュー — これは clean-code-guard の担当範囲です。このスキルでは、ドキュメントがコードについて何を主張しているかをレビューします。
• ドキュメント戦略や情報アーキテクチャの一からの作成 — このスキルでは、正確さと内容を確認します。対象範囲の決定は行いません。
• 文章のスタイルガイドの適用 — 文体はプロジェクトに委ねられます。内容の正確さはこのスキルの責任です。