review-docs

k35o's avatarfrom k35o

ドキュメントとコードの乖離を監査。APIエンドポイント、スキーマ、設定ファイルとドキュメントを比較し、不整合をレポート。定期的なドキュメントヘルスチェックに使用。

⭐5stars🔀0forks📁View on GitHub🕐Updated Jan 1, 2026

When & Why to Use This Skill

The review-docs skill is an automated documentation auditing tool designed to eliminate the gap between source code and project documentation. It performs deep comparisons between actual code implementations (such as API endpoints, Zod schemas, and configuration files) and their descriptions in Markdown files. By identifying inconsistencies, outdated commands, and missing information, it ensures that your project's technical documentation remains a reliable 'single source of truth' and reduces technical debt caused by documentation rot.

Use Cases

  • API Documentation Synchronization: Automatically verify if documented REST API endpoints, HTTP methods, and request/response schemas match the actual implementation in the route files.
  • Pre-Pull Request Validation: Run a targeted audit before submitting code changes to ensure that updates to environment variables, dependencies, or logic are reflected in the relevant documentation.
  • Architecture & Setup Health Checks: Periodically audit ARCHITECTURE.md and README.md to ensure directory structures, tech stack versions, and installation steps are accurate.
  • DevOps & Config Alignment: Compare DEPLOYMENT.md and SECURITY.md against vercel.json, Dockerfiles, and environment templates to prevent deployment errors caused by outdated docs.
  • Developer Experience (DX) Maintenance: Keep CLAUDE.md and CONTRIBUTING.md updated by verifying that development commands, linting rules, and project guidelines match the package.json scripts and Biome/ESLint configs.
namereview-docs
descriptionドキュメントとコードの乖離を監査。APIエンドポイント、スキーマ、設定ファイルとドキュメントを比較し、不整合をレポート。定期的なドキュメントヘルスチェックに使用。

ドキュメント監査スキル

このスキルは、ドキュメントとコードの乖離を検出し、レポートを生成します。

監査対象

ドキュメント 検証対象
docs/API.md 実際のAPIエンドポイント
docs/TESTING.md テスト設定、テスト戦略
docs/DEPLOYMENT.md デプロイ設定、環境変数
docs/SECURITY.md セキュリティ設定、認証方式
docs/TROUBLESHOOTING.md 解決策の有効性
ARCHITECTURE.md ディレクトリ構造、技術スタック
CLAUDE.md コマンド、パターン、ガイドライン
CONTRIBUTING.md 開発フロー、コード規約
README.md セットアップ手順、概要

監査項目

1. API.md の監査

チェック項目

  • 記載されているエンドポイントが実際に存在するか
  • 実際のエンドポイントがすべて記載されているか
  • HTTPメソッドが正しいか
  • リクエスト/レスポンスの仕様が最新か
  • 認証方式の記述が正確か
  • レート制限の値が正しいか

検証方法

# 実際のAPIエンドポイントを列挙
find apps/main/src/app/api -name "route.ts" | sort

エンドポイントファイルを読み込み、以下を抽出:

  • エクスポートされているHTTPメソッド(GET, POST, PUT, DELETE等)
  • Zodスキーマ(リクエストバリデーション)
  • レスポンス形式

2. ARCHITECTURE.md の監査

チェック項目

  • ディレクトリ構造が実際と一致するか
  • 技術スタックのバージョンが最新か
  • パッケージ依存関係が正確か
  • データベーススキーマが最新か
  • 図表が現状を反映しているか

検証方法

# 実際のディレクトリ構造
tree -L 3 -I "node_modules|.next|.git"

# パッケージバージョン
cat package.json | jq '.dependencies, .devDependencies'

# スキーマファイル
ls packages/database/src/schema/

3. CLAUDE.md の監査

チェック項目

  • 必須コマンドが実行可能か
  • スクリプト名が package.json と一致するか
  • ヘルパー関数のリストが最新か
  • コンポーネント構成が実際と一致するか
  • テスト戦略が現状を反映しているか
  • TailwindCSSトークンが最新か

検証方法

# package.json scripts
cat package.json | jq '.scripts'

# ヘルパー関数
ls packages/helpers/src/

# コンポーネント
ls apps/main/src/app/_components/

4. DEPLOYMENT.md の監査

チェック項目

  • 環境変数リストが最新か
  • Cronジョブ設定が vercel.json と一致するか
  • Docker設定が compose.yml と一致するか
  • デプロイフローが現状を反映しているか

検証方法

# 環境変数
cat apps/main/.env.example

# Cronジョブ
cat apps/main/vercel.json | jq '.crons'

# Docker設定
cat compose.yml

5. CONTRIBUTING.md の監査

チェック項目

  • 開発環境セットアップ手順が最新か
  • コード規約がBiome設定と一致するか
  • ブランチ戦略が現状を反映しているか
  • PR/Issue テンプレートが存在するか

6. README.md の監査

チェック項目

  • プロジェクト説明が現状を反映しているか
  • インストール手順が動作するか
  • バッジ/ステータスが最新か
  • リンクが有効か

7. TESTING.md の監査

チェック項目

  • テスト実行コマンドが動作するか
  • テスト戦略が現状を反映しているか
  • カバレッジ目標が最新か
  • モック戦略が実装と一致するか

8. SECURITY.md の監査

チェック項目

  • セキュリティ対策が実装されているか
  • 認証方式の記述が正確か
  • 依存関係の脆弱性がないか
  • セキュリティヘッダーが設定されているか

9. TROUBLESHOOTING.md の監査

チェック項目

  • 解決策が有効か
  • コマンドが動作するか
  • 参照先が存在するか
  • 新しい問題が追加されるべきか

レポート形式

監査結果は以下の形式でレポート:

# ドキュメント監査レポート

**監査日時:** YYYY-MM-DD HH:MM
**対象ドキュメント:** [リスト]

## サマリー

| ドキュメント | ステータス | 問題数 |
|-------------|-----------|-------|
| docs/API.md | ⚠️ 要更新 | 3 |
| ARCHITECTURE.md | ✅ 最新 | 0 |
| CLAUDE.md | ⚠️ 要更新 | 2 |
| ... | ... | ... |

## 詳細

### docs/API.md

#### 問題1: 未記載のエンドポイント
- **対象:** `/api/new-endpoint`
- **発見日:** YYYY-MM-DD
- **推奨対応:** エンドポイントの仕様を追加

#### 問題2: 古い仕様
- **対象:** `/api/blog/views` のレスポンス形式
- **現状:** ドキュメントには `{ views: number }` と記載
- **実際:** `204 No Content` を返却
- **推奨対応:** レスポンス形式の記述を修正

### CLAUDE.md

#### 問題1: 存在しないコマンド
- **対象:** `pnpm run lint`
- **現状:** ドキュメントに記載あり
- **実際:** `pnpm run check` に変更済み
- **推奨対応:** コマンド名を修正

## 推奨アクション

1. [ ] docs/API.md: 新しいエンドポイントを追加
2. [ ] CLAUDE.md: コマンド名を修正
3. [ ] ...

使用例

例1: 全体監査

「ドキュメントの監査をして」
または
「/review-docs」

スキルの動作:

  1. すべての対象ドキュメントを読み込み
  2. 対応するコードファイルを読み込み
  3. 比較・検証
  4. レポートを生成

例2: 特定ドキュメントの監査

「API.mdが最新か確認して」

スキルの動作:

  1. docs/API.md を読み込み
  2. apps/main/src/app/api/ 配下のファイルを読み込み
  3. エンドポイント一覧を比較
  4. 不整合を報告

例3: PR前の確認

「PRを作る前にドキュメントの確認をして」

スキルの動作:

  1. git diff で変更ファイルを確認
  2. 変更に関連するドキュメントのみ監査
  3. 必要な更新を提案

自動検出パターン

以下は検出ロジックの実装イメージを示す疑似コードです。

API不整合の検出

// ドキュメントからエンドポイントを抽出
const docEndpoints = extractEndpointsFromMarkdown(apiMd);
// POST /api/blog/views
// GET /api/subscriptions/verify
// ...

// コードからエンドポイントを抽出
const codeEndpoints = extractEndpointsFromCode(apiRoutes);
// apps/main/src/app/api/blog/views/route.ts -> POST
// apps/main/src/app/api/subscriptions/verify/route.ts -> GET
// ...

// 差分を検出
const missing = codeEndpoints.filter(e => !docEndpoints.includes(e));
const outdated = docEndpoints.filter(e => !codeEndpoints.includes(e));

コマンド不整合の検出

// CLAUDE.mdからコマンドを抽出
const docCommands = extractCommandsFromMarkdown(claudeMd);
// pnpm run dev
// pnpm run build
// ...

// package.jsonからコマンドを抽出
const pkgCommands = Object.keys(packageJson.scripts);
// dev, build, test, ...

// 差分を検出
const invalidCommands = docCommands.filter(cmd =>
  !pkgCommands.includes(cmd.replace('pnpm run ', ''))
);

スキーマ不整合の検出

// ARCHITECTURE.mdからスキーマを抽出
const docSchemas = extractSchemasFromMarkdown(archMd);
// blogs, talks, quizzes, ...

// コードからスキーマを抽出
const codeSchemas = fs.readdirSync('packages/database/src/schema/')
  .filter(f => f.endsWith('.ts'))
  .map(f => f.replace('.ts', ''));

// 差分を検出
const missingSchemas = codeSchemas.filter(s => !docSchemas.includes(s));

重大度レベル

レベル 説明 例
🔴 Critical 機能に関わる誤情報 存在しないAPIエンドポイント
🟠 High 重要な情報の欠落 新機能が未記載
🟡 Medium 細かい不整合 バージョン番号のずれ
🟢 Low 軽微な改善点 表現の改善

注意事項

  • 監査結果は提案であり、すべてを機械的に適用しない
  • コンテキストを考慮して判断する
  • 一時的な変更(実験的機能等)は除外することがある
  • ドキュメントの意図を尊重する
  • 大規模な変更は段階的に実施

定期実行の推奨

以下のタイミングで監査を実行することを推奨:

  1. PR作成前: 変更に関連するドキュメントのみ
  2. 週次: 全体監査
  3. リリース前: 重要ドキュメントの全体確認
  4. 大規模変更後: 影響範囲の確認