---

name: doc-review description: 既存ドキュメントを DOCUMENTATION.md の方針に照らしてレビューする。構造の一貫性、情報の重複、配置の適切さ、テンプレート準拠をチェックする。

ドキュメントレビュー

意図

ドキュメントが docs/DOCUMENTATION.md の方針に沿っているかを体系的にレビューし、改善点を特定する。 ドキュメントは仕様の一部であり、その品質はライブラリの使いやすさに直結する。

レビューは 双方向 である。ドキュメントが方針に合っているかだけでなく、方針がドキュメントの実態に合っているかも問う。

レビュー手順

1. 対象の特定

引数でファイルパスやパッケージ名が指定されていればそれを対象にする。 指定がなければ、以下の優先順で対象を決める:

• 直近の変更（git diff）に関連するドキュメント
• 指定がなければ全体レビュー

2. DOCUMENTATION.md の方針を読む

docs/DOCUMENTATION.md を読み、現在の方針・テンプレートを確認する。

3. チェック観点

テンプレート準拠

パッケージ README:

• セクション順序: タイトル → (Philosophy) → Installation → Usage → API → (Module Structure)
• 必須セクション（Installation, Usage, API）が揃っているか
• API セクションの形式（関数シグネチャ → インターフェース → 説明）

Showcase README:

• セクション順序: タイトル → 機能 → 実装のポイント → 実行
• 「実装のポイント」がコード例付きで説明されているか
• 躓きポイントが記述されているか

情報の配置

• API 仕様がパッケージ README にあるか（showcase README に混入していないか）
• 実装パターンが showcase README にあるか（パッケージ README に混入していないか）
• 同じ情報が複数箇所に存在していないか

実装との整合性

• README に書かれた API が実装に存在するか
• 型シグネチャが最新か
• 使用例のコードが実際に動作するか

日英同期（ルート README）

• README.md と README.ja.md の内容が一致しているか
• セクション構成、コード例、順序が揃っているか

JSDoc

• 公開 API に JSDoc が付いているか
• @param, @returns が記述されているか

方針自体の妥当性

レビューの過程で、以下のような摩擦に気づいたら記録する:

• テンプレートに合わせると不自然になる箇所 → テンプレートの見直しが必要かもしれない
• 配置ルールで判断に迷う情報 → 配置基準が不十分かもしれない
• 同じ指摘が複数ドキュメントで繰り返される → 方針の記述が不明確かもしれない
• テンプレートにない構造が自然に使われている → テンプレートの拡張が妥当かもしれない

これらは「ドキュメントの問題」ではなく「方針の問題」である可能性がある。

4. 報告フォーマット

対象: <ファイルパス>

観点	状態	詳細
テンプレート準拠	OK / 要改善	具体的な指摘
情報の配置	OK / 要改善	重複や配置ミス
実装との整合性	OK / 要改善	乖離している箇所

方針へのフィードバック（該当する場合のみ）:

レビュー中に方針側の改善が必要だと感じた点があれば、ここに記載する。 「ドキュメントを方針に合わせるべき」か「方針をドキュメントに合わせるべき」かの判断も含める。

現時点の方針

• 実装との乖離は必ず指摘する（仕様の信頼性に直結）
• テンプレートからの軽微な逸脱は「推奨」として報告
• 新パッケージや新 showcase 追加時は特に厳密にテンプレート準拠を確認
• レビュー中に感じた方針への摩擦は、報告に含める（ドキュメントの問題か方針の問題かを区別する）

今後の検討事項

• ドキュメントの自動チェック（セクション構造の lint など）
• README から型情報を自動抽出して整合性チェック
• JSDoc カバレッジの定量レポート
• レビューで蓄積された方針フィードバックの定期的な振り返り