# Review Docs

> Review documentation for broken links and cross-document consistency issues. Trigger when the user says: "ドキュメントレビュー", "docs review", "review docs", "リンク切れ確認", "ドキュメントの整合性", or similar phrases requesting documentation review.

- Skill: `kompiro/review-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kompiro/review-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kompiro/review-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: kompiro (https://skillmd.com/u/kompiro)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kompiro/review-docs

---


# Review Docs Skill

`docs/` 以下のドキュメント全体を走査し、リンク切れと整合性問題を検出してレポートを出力する。

## アーキテクチャ

このスキルは処理を2つのサブエージェントに分担させることでメインのコンテキストを節約する。

```
/review-docs（メインエージェント）
├── Explore エージェント A: リンク切れチェック（並列起動）
├── Explore エージェント B: 整合性チェック（並列起動）
└── メインエージェント: 両結果を受け取りレポート生成
```

## 手順

### 1. サブエージェントを並列起動する

以下の2つの Explore エージェントを **同時に（1メッセージで）** 起動する。

---

#### サブエージェント A — リンク切れチェック

**プロンプト（要旨）**:

> `docs/**/*.md` および `CLAUDE.md` 全件を読み込み、各ファイルに含まれる Markdown リンク `[text](path)` と画像参照 `![alt](path)` を抽出せよ。
>
> チェック対象:
> - 相対パス参照 → リポジトリルートから解決して実ファイルの存在確認
> - アンカー付きリンク `[text](file.md#anchor)` → 対象ファイルに該当見出し（`# ...`, `## ...` 等）が存在するか確認
> - `/` 始まりの絶対パス → リポジトリルートから存在確認
>
> チェック対象外:
> - `http://`, `https://` で始まる外部リンク
>
> 結果は以下の形式で返せ:
>
> ```
> BROKEN_LINK|ファイルパス|行番号|リンク記述|理由
> BROKEN_LINK|docs/requirements.md|125|[コアコンセプト](design/concepts.md)|ファイルが存在しない
> OK_LINK_COUNT|32
> TOTAL_FILES|18
> ```

---

#### サブエージェント B — 整合性チェック

**プロンプト（要旨）**:

> `docs/` 以下のすべての Markdown ファイルを読み込み、以下の観点で整合性を確認せよ。
> 各観点は対応するディレクトリ・ドキュメントが存在する場合のみ実行し、無ければスキップする。
>
> **1. CLAUDE.md ドキュメント表**
> `CLAUDE.md` 内に「ドキュメント」表（または同等のパス一覧）が存在する場合、記載されたファイルパスが実在するか確認する。
>
> **2. ADR ↔ Design Doc の対応**（`docs/adr/` がある場合のみ）
> - ADR に「関連」として記載された Design Doc のパスが実在するか
> - Design Doc のステータスが「ADR化」の場合、対応する ADR ファイルが存在するか
>
> **3. Design Doc のステータスと実装状態の乖離**（`docs/design/` がある場合のみ）
> - ステータスが「完了」の Design Doc に対応する ADR が存在しないもの（警告）
> - ステータスが「ドラフト」「検討中」のまま実装されていそうなもの（git history は見なくてよい、判断できる範囲で）
>
> **4. Design Doc ↔ AT の対応**（`docs/design/` と `docs/acceptance/` の両方がある場合のみ）
> - 各 Design Doc に対応する AT（`docs/acceptance/`）が存在するか（なければ警告のみ）
>
> **5. AT 番号の重複**（`docs/acceptance/` がある場合のみ）
> - `docs/acceptance/<番号>-*.md` の番号プレフィックスが重複しているものがないか
> - 採番は Issue 番号 → PR 番号 → ローカル採番（既存最大+1）の優先順位。**同一 Issue / 同一 PR に複数 AT**（例: `42-login-form.md`, `42-login-error.md`）は許容されるため WARN にしない
> - 異なる採番ソース同士の衝突（例: Issue #5 と ローカル採番 `5-` の併存）のみ **WARN** として報告する（ERROR にしない）
>
> **6. AT に記載された実装ファイルの存在確認**（`docs/acceptance/` がある場合のみ）
> - AT の bash コードブロック内に登場するソースパス（プロジェクト内の相対パス）のファイルが実在するか
>
> 結果は以下の形式で返せ:
>
> ```
> ERROR|カテゴリ|説明
> WARN|カテゴリ|説明
> OK|カテゴリ|説明
> TOTAL_FILES|N
> ```
>
> 例:
> ```
> ERROR|AT番号重複|docs/acceptance/0007-qa-skill.md と docs/acceptance/0007-deployment-diagram.md が同じ番号
> WARN|Design Doc ステータス|docs/design/deployment-diagram.md: ステータス「完了」だが対応する ADR が存在しない
> OK|CLAUDE.md ドキュメント表|全エントリ実在
> ```

---

### 2. 両エージェントの結果を受け取る

サブエージェント A・B それぞれの出力を解析し、以下に整理する:

- **リンク切れ一覧**（ファイル・行番号・内容・理由）
- **整合性エラー一覧**（ERROR 行）
- **整合性警告一覧**（WARN 行）
- **問題なしカテゴリ一覧**（OK 行）

### 3. レポートの生成

以下の形式で `docs/review/YYYY-MM-DD-review.md` を生成する（今日の日付を使用）。
`docs/review/` ディレクトリが存在しない場合は作成する。

```markdown
# Docs Review — YYYY-MM-DD

## Summary

- Broken links: N (errors)
- Consistency issues: N (errors), N (warnings)
- Total documents reviewed: N

---

## Broken Links

### docs/requirements.md

- Line 125: `[コアコンセプト](design/concepts.md)` → ファイルが存在しない

---

## Consistency Issues (Errors)

### AT 番号重複

...

---

## Consistency Issues (Warnings)

### Design Doc ステータスと ADR の不整合

...

---

## No Issues Found

（問題がなかったカテゴリはここに列挙）

---
*Generated by /review-docs skill — do not commit this file*
```

### 4. 結果の報告

生成したファイルのパスをユーザーに伝える。
検出した問題件数をカテゴリ別にサマリーとして表示する。
問題がゼロの場合は「問題なし」と明記する。

## 出力先

- `docs/review/YYYY-MM-DD-review.md`（git には追加しない、`.gitignore` 対象）

## 注意事項

- サブエージェントは必ず **同時に（単一メッセージで）** 起動して並列処理を活かす
- 外部 URL（`https://` 等）の到達性チェックは行わない（CI 環境依存を避けるため）
- 同じ問題が複数箇所で検出される場合は重複せず、最初の出現箇所のみ記録する
- ファイルパスはリポジトリルートからの相対パスで表記する
- 警告（望ましいが必須ではない）とエラー（明確な問題）を区別して表記する
  - エラー: リンク切れ、存在しないファイル参照
  - 警告: 対応 AT がない Design Doc、ステータス乖離など
- AT 番号は GitHub Issue 番号 → PR 番号 → ローカル採番の優先順位で付与する。外部参照を保つため再採番（リネーム）は提案しない。異なる採番ソース同士の衝突のみ WARN として報告する