docs-quality-check

コードベースのドキュメント品質を分析・検証し、PRD、ADR、PRP、CLAUDE.md、.claude/rules/ が標準を満たし、最新の状態であることを確認します。

コンテキスト

• 対象パス：$1（指定されていない場合は現在のディレクトリ）
• ブループリントディレクトリの有無：!find .claude -maxdepth 1 -name 'blueprints' -type d
• CLAUDE.md の有無：!find . -maxdepth 1 -name 'CLAUDE.md' -type f
• ルールディレクトリ：!find .claude/rules -maxdepth 1 -name '*.md'
• ADR（docs/adr）：!find docs/adr -maxdepth 1 -name '*.md'
• ADR（docs/adrs）：!find docs/adrs -maxdepth 1 -name '*.md'
• PRD（docs/prds）：!find docs/prds -maxdepth 1 -name '*.md'
• PRD（ブループリント）：!find .claude/blueprints/prds -maxdepth 1 -name '*.md'
• PRP（docs/prps）：!find docs/prps -maxdepth 1 -name '*.md'
• PRP（ブループリント）：!find .claude/blueprints/prps -maxdepth 1 -name '*.md'

パラメーター

• $1：分析対象のパス（指定されていない場合は現在のディレクトリ）

タスク

次の方法に従って、ドキュメント品質を包括的に分析します。

フェーズ 1：ToDo リストの作成

分析の進捗を管理するため、構造化された ToDo リストを作成します。

- Analyze CLAUDE.md structure and quality
- Check .claude/rules/ directory and standards
- Validate ADRs (Architecture Decision Records)
- Validate PRDs (Product Requirements Documents)
- Validate PRPs (Product Requirement Prompts)
- Check documentation freshness and git history
- Generate quality report with recommendations

フェーズ 2：CLAUDE.md の分析

2.1 存在と構成の確認

• プロジェクトのルートに CLAUDE.md が存在することを確認します
• 必須の YAML フロントマターを確認します：

  ---
  created: YYYY-MM-DD
  modified: YYYY-MM-DD
  reviewed: YYYY-MM-DD
  ---
  

2.2 コンテンツ品質のチェック

• 完全性：プロジェクトのコンテキストが明確に示されていますか？

  • プロジェクト構成の概要
  • 開発規約
  • 主要なルールとガイドライン
  • 該当する場合は、プラグインやツールへの参照

• 明瞭さ：整理され、読みやすい内容ですか？

  • 明確な見出しを使ったセクション
  • 適切な Markdown 形式
  • 構造化データには表を使用
  • 役立つ箇所には例を記載

• 正確性：古くなった情報がないか確認します

  • 更新日を最近の Git コミットと比較
  • 非推奨のパターンへの言及を確認
  • ファイルパスや参照先が存在することを検証

2.3 ベストプラクティス

CLAUDE.md の基準に照らして確認します：

• AI アシスタントがコードベースを扱う際の指針となっていること
• プロジェクト構成の説明が含まれていること
• 主要なルールや規約が参照されていること
• 追加ドキュメント（ADR、ルール）への参照があること
• クイックリファレンスに表を使用していること
• 焦点が絞られ、簡潔であること

フェーズ 3：.claude/rules/ の分析

3.1 ディレクトリ構成

• .claude/rules/ ディレクトリの存在を確認します
• 存在するすべてのルールファイルを一覧表示します
• 推奨される基本ルールを確認します：
  • アーキテクチャ／設計パターン
  • コーディング規約
  • 開発ワークフロー
  • テスト要件

3.2 個々のルールの検証

.claude/rules/ 内の各ルールファイルについて、次の項目を確認します。

必須のフロントマター：

---
created: YYYY-MM-DD
modified: YYYY-MM-DD
reviewed: YYYY-MM-DD
name: docs-quality-check
---

コンテンツ基準：

• 明確なタイトルと目的
• 明確に定義された適用範囲
• 具体的で実行可能なガイダンス
• 適切な箇所に例を記載
• 関連ルールへの相互参照

3.3 ルールの整理

• ルールは適切に分類されていますか？
• ルールの数が多すぎたり少なすぎたりしませんか？
• ルール間に重複や矛盾はありませんか？
• ルール名は具体的で一貫していますか？

フェーズ 4：ADR の検証

4.1 ADR ディレクトリの確認

• docs/adrs/ または docs/adr/ が存在することを確認します
• ADR のインデックス／README を確認します
• すべての ADR ファイルを一覧表示します（番号付きの形式であること：0001-title.md）

4.2 ADR の構造検証

各 ADR について、次の項目を確認します。

命名規則：

• 形式：NNNN-kebab-case-title.md（例：0001-plugin-architecture.md）
• 連番になっていること
• タイトルが内容を具体的に表していること

必須セクション（MADR 形式）：

# ADR-NNNN: Title

**Date**: YYYY-MM
**Status**: Accepted | Superseded | Deprecated
**Deciders**: [who made the decision]

## Context
[The issue motivating this decision]

## Decision
[The change being proposed or made]

## Consequences
[What becomes easier or harder]

4.3 ADR の品質チェック

• ステータスの正確性：非推奨の ADR にその旨が記されていますか？
• 完全性：ADR に必須セクションがすべて含まれていますか？
• 関連性：ADR は現在のコードベースにも適用できますか？
• インデックスの保守状況：ADR のインデックスは最新ですか？

4.4 対象範囲の分析

• ADR で主要なアーキテクチャ上の決定が扱われていますか？
• 最近の重要な変更が文書化されていますか？
• 文書化されていないことが明らかな決定事項はありますか？

フェーズ 5：PRD の検証

5.1 PRD ディレクトリの確認

• docs/prds/ または .claude/blueprints/prds/ が存在することを確認します
• すべての PRD ファイルを一覧表示します

5.2 PRD 構成の検証

各 PRD について、以下を確認します。

フロントマター（Blueprint の方法論を使用している場合）：

---
created: YYYY-MM-DD
modified: YYYY-MM-DD
reviewed: YYYY-MM-DD
status: Draft | Active | Implemented | Archived
name: docs-quality-check
---

必須セクション：

• エグゼクティブサマリー／問題提起
• ステークホルダーとユーザーペルソナ
• 機能要件
• 非機能要件
• 成功指標
• スコープ（対象／対象外）
• 技術的な考慮事項

5.3 PRD の品質チェック

• 明確さ：要件は具体的で測定可能ですか？
• 完全性：重要なセクションがすべて含まれていますか？
• ステータス：ステータスフィールドは正確ですか？
• 追跡可能性：要件を実装まで追跡できますか？
• ユーザー重視：ユーザーのニーズが明確に記述されていますか？

フェーズ 6：PRP の検証

6.1 PRP ディレクトリの確認

• docs/prps/ が存在することを確認します（Blueprint の方法論）
• すべての PRP ファイルを一覧表示します

6.2 PRP 構成の検証

各 PRP について、以下を確認します。

必須セクション：

• 目標とその理由
• 成功基準（テスト可能）
• コンテキスト（ドキュメントの参照、コードベースの情報、既知の注意点）
• 実装ブループリント（アーキテクチャ、タスクの内訳）
• TDD 要件（テスト戦略、重要なテストケース）
• 検証ゲート（実行可能なコマンド）
• 信頼度スコア（各評価軸で 0～10）

6.3 PRP の品質チェック

• 具体性：ファイルパスとコード参照が明示されていますか？
• テスト可能性：成功基準は測定可能ですか？
• 完全性：信頼度スコアは内容の品質と一致していますか？
• 実行可能性：この PRP はすぐに実行できますか？
• コンテキスト：実装に十分な、厳選されたコンテキストがありますか？

フェーズ 7：鮮度の分析

7.1 最終更新日の確認

すべてのドキュメントについて：

• modified フロントマターの日付を Git の履歴と比較します
• 古いドキュメント（6 か月以上レビューされていないもの）を特定します
• 関連コードの変更に基づき、レビューが必要なドキュメントにフラグを付けます

Git を使用して変更状況を確認します：

# Check recent commits affecting docs
git log --since="6 months ago" --oneline -- docs/ .claude/ CLAUDE.md 2>/dev/null || echo "Not a git repo or no history"

# Check when documentation was last touched
git log -1 --format="%ai %s" -- CLAUDE.md 2>/dev/null || echo "No git history"

7.2 コード変更との相互参照

• ドキュメントが更新されないまま、大規模なコード変更が行われていませんか？
• ADR は実際のアーキテクチャを反映していますか？
• PRD は実装済みの機能を正確に反映していますか？

フェーズ 8：品質レポートの生成

8.1 ドキュメント一覧

概要表を生成します。

## Documentation Inventory

| Document Type | Status | Count | Issues |
|---------------|--------|-------|--------|
| CLAUDE.md | ✅/❌ | 1 | [list issues] |
| .claude/rules/ | ✅/❌ | N files | [list issues] |
| ADRs | ✅/❌ | N files | [list issues] |
| PRDs | ✅/❌ | N files | [list issues] |
| PRPs | ✅/❌ | N files | [list issues] |

8.2 品質スコア

総合品質スコアを算出します。

カテゴリ	スコア（0～10）	備考
構成	X	ファイルの整理、命名
完全性	X	必須セクションの有無
鮮度	X	最近の更新、Git との同期
標準への準拠	X	フロントマター、形式
コンテンツの品質	X	明確さ、具体性
総合	X	平均スコア

評価ガイド：

• 9～10：優秀 — 十分に保守され、包括的です
• 7～8：良好 — 軽微な改善が必要です
• 5～6：普通 — 対処すべき問題がいくつかあります
• 3～4：不十分 — 大きな不足や古い情報があります
• 0～2：重大 — 欠落しているか、著しく不十分です

8.3 問題と推奨事項

調査結果を分類します。

重大な問題（必ず修正）：

• 必須ドキュメントの欠落
• 深刻な構造上の問題
• 完全に古くなった情報

警告（修正を推奨）：

• 古いドキュメント（6 か月以上）
• フロントマターの欠落
• セクションの不足
• 軽微な構造上の問題

提案（あると望ましい）：

• 役立つ追加ドキュメント
• 整理方法の改善
• 相互参照の改善
• 例の拡充

8.4 具体的な推奨事項

各問題について、具体的な対応方法を示します。

## Recommendations

### Immediate Actions
1. [ ] Fix [specific issue] in [file]
   - **Why**: [reason]
   - **How**: [specific steps]
   - **Command**: [if applicable]

2. [ ] Update [document]
   - **Why**: [reason]
   - **How**: [specific steps]

### Maintenance Tasks
1. [ ] Review and update stale documents:
   - [file1] - last modified [date]
   - [file2] - last modified [date]

2. [ ] Improve documentation coverage:
   - [ ] Document [undocumented decision]
   - [ ] Create ADR for [architectural choice]

### Best Practices
- Run `/docs:quality-check` monthly
- Update `modified` dates when editing docs
- Review `reviewed` dates quarterly
- Use `/blueprint:adr` for new architecture decisions
- Use `/blueprint:prd` for new features

フェーズ 9：結果の提示

9.1 エグゼクティブサマリー

明確で簡潔な概要を示します。

📊 Documentation Quality Report
═══════════════════════════════

Overall Score: X/10 ([Excellent/Good/Fair/Poor/Critical])

✅ Strengths:
- [strength 1]
- [strength 2]

⚠️  Issues Found:
- [issue 1]
- [issue 2]

📋 Recommendations:
- [top recommendation 1]
- [top recommendation 2]

See full report below for details.

9.2 完全なレポート

以下を含む分析全体を提示します。

• ドキュメント一覧
• カテゴリ別の品質スコア
• 詳細な調査結果
• 具体的な推奨事項
• メンテナンスチェックリスト

9.3 改善に向けたガイダンス

ユーザーが次のステップを把握できるよう支援します。

• Blueprint が初期化されていない場合 → /blueprint:init を提案します
• ADR がない場合 → /blueprint:adr を提案します
• PRD がない場合 → /blueprint:prd を提案します
• ドキュメントが古い場合 → 更新チェックリストを提示します
• 標準に従っていない場合 → 例とテンプレートを示します

ベストプラクティス

分析について

• 徹底的かつ簡潔に行う
• 実行可能な課題に焦点を当てる
• 具体的なファイル名と行番号を示す
• 良いパターンと悪いパターンの例を含める
• 問題を指摘するだけでなく、具体的な修正方法を提案する

ドキュメントの基準について

• フロントマター：作成日、更新日、レビュー日を必ず記載する
• 構成：確立されたテンプレート（ADR、PRD、PRP）に従う
• 明確さ：将来のメンテナーと AI アシスタントに向けて書く
• メンテナンス：四半期ごとにレビューし、更新日を更新する
• 相互参照：関連ドキュメントへのリンクを記載する
• 例：コードスニペットと実例を含める
• 範囲：焦点を絞り、1 つのドキュメントにつき 1 つの懸案事項を扱う

エラー処理

• Git リポジトリでない場合 → Git ベースの鮮度チェックを省略する
• ディレクトリが存在しない場合 → レポートに欠落として記載する
• ファイルの形式が不正な場合 → 具体的な解析エラーを指摘する
• ファイルを読み取れない場合 → 権限やアクセスの問題を記載する
• Blueprint が初期化されていない場合 → ドキュメントを作成する前に初期化するよう提案する

出力形式

明確な Markdown 形式を使用します。

• 構造化データにはテーブルを使用する
• アクション項目にはチェックボックスを使用する
• 例にはコードブロックを使用する
• すばやく確認できるよう、絵文字のインジケーター（✅ ❌ ⚠️）を使用する
• （対応している場合）詳細な分析には折りたたみ可能なセクションを使用する

重要：人間の開発者と AI アシスタントの両方に役立つ、高品質で最新のドキュメントをユーザーが維持できるよう支援することが目標です。