Document Reviewer

ドキュメントファイルを詳細にレビューし、品質と完全性に関するフィードバックを提供するスキルです。

このスキルは、doc-reviewer-agent サブエージェントを呼び出して、以下の処理を実行します。

処理内容

1. ドキュメントファイルの検出と選択

•docs/ 配下のマークダウンファイルを自動検出
•ユーザーにファイル候補を一覧表示
•番号またはパス指定でレビュー対象を選択

2. ドキュメント種類の自動判定

以下の種別を自動判定し、適切なレビュー観点を選択：

種別	判定条件	例
PRD	`requirements.md`	`docs/requirements.md`
DESIGN	`*-design.md`	`docs/backend-design.md`
ARCHITECTURE	`architecture`, `infrastructure*`	`docs/infrastructure-design.md`
PLAN	`implementation-plan.md`	`docs/implementation-plan.md`
ISSUE_SPEC	`docs/issues/` 配下	`docs/issues/7-login-endpoint.md`
PROPOSAL	`docs/idea/` 配下	`docs/idea/doc-reviewer.md`
GUIDELINE	`.claude/rules/` 配下	`.claude/rules/cdk.md`
GENERAL	上記以外	その他のドキュメント

3. レビュー観点に基づく評価

全ドキュメント共通観点

観点	チェック内容
完全性	必要なセクションが揃っているか
明確性	曖昧な表現がないか、用語が明確か
一貫性	表記揺れ、矛盾がないか
構造	階層構造が適切で読みやすいか
実装可能性	実装者が理解できる具体性があるか
わかりやすさ	対象読者の視点で理解しやすいか、前提知識への配慮
メンテナンス性	同じ値の複数箇所記載、実装コード全文記載がないか
図表の活用	Mermaid/テーブルの積極活用
対象読者と目的	冒頭に明記されているか（不記載の場合は減点対象）
目次	500行以上の場合に記載されているか

設計書特有観点

観点	チェック内容
設計の理由・背景	「なぜこの設計にしたのか」が記載されているか
技術選定の根拠	「なぜこの技術を選んだのか」の説明
トレードオフの明示	メリット・デメリットの記載
シーケンス図の妥当性	Mermaid構文、autonumber、Note、参加者定義
API設計	リクエスト/レスポンス例の具体性
セキュリティ考慮事項	セキュリティ関連の記載

4. 詳細レポート生成

以下の形式でレビュー結果を出力：

•総合評価: 各観点のスコア（3点満点）
•良い点: ポジティブなフィードバック
•改善が必要な点: 必須/推奨/提案の3段階で分類
•プロジェクトルールへの準拠: CLAUDE.md、.claude/rules/ のチェック
•次のステップ: 優先度付きのアクションアイテム

使用方法

基本的な実行

code

/doc-reviewer

このコマンドを実行すると、doc-reviewer-agent サブエージェントが起動し、以下の処理を自動実行します：

•docs/ 配下のマークダウンファイルを検出
•ファイル候補を表示し、ユーザーに選択を促す
•ドキュメント種類を自動判定
•適切なレビュー観点でレビューを実行
•詳細レポートをコンソールに出力

ユーザー選択フロー

code

=== Document Review ===

Found 27 documentation files:

📁 Root Level
  1. docs/requirements.md
  2. docs/backend-design.md
  3. docs/frontend-design.md
  ...

📁 Issues
  10. docs/issues/7-login-endpoint.md
  ...

Enter file number to review (1-27), or file path directly:

レビューの姿勢

レビューは以下の姿勢で実行されます：

•建設的: 批判ではなく、改善のための提案
•具体的: 「どこが」「なぜ」「どう改善するか」を明示
•バランス: 悪い点だけでなく、良い点も必ず指摘
•実用的: 実際に実行可能な改善案を提示
•根拠: 改善提案には必ず理由を添える

スコープ

ドキュメント内容のみをレビュー：

•✅ ドキュメント内のテキスト、図表、構造をレビュー
•✅ ドキュメント内のコード例（サンプルコード）をレビュー
•❌ 実装コードとの整合性チェックは対象外（/validate-design で実行）
•❌ シーケンス図と実際の実装の整合性は対象外

使用技術

項目	詳細
ファイル検出	Glob（`docs/*/.md`）
内容読み取り	Read
キーワード検索	Grep
履歴確認	Bash（git log）
判定ロジック	ファイル名・ディレクトリ・セクション構造の複合判定

詳細なエージェント仕様

レビューの実行・分析・出力の詳細は、.claude/agents/doc-reviewer-agent/ で定義されています。

実行指示（Claude Code への指示）

このスキルが呼び出されたら、以下を厳格に実行すること：

1. エージェントの起動

Task ツールを使用して doc-reviewer-agent サブエージェントを起動：

code

subagent_type: "doc-reviewer-agent"
prompt: "ドキュメントレビューを実行してください"

2. 出力の表示

エージェントが完了したら、その出力をそのまま全文表示すること。

重要: 以下の行為は禁止：

•❌ エージェントの出力を要約する
•❌ エージェントの出力を加工する
•❌ エージェントの出力にコメントを追加する
•❌ エージェントの出力を解釈して説明する

許可される行為:

•✅ エージェントの出力を全文そのまま表示する