---

name: review-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. 大規模変更後: 影響範囲の確認