project-audit

project-audit

トリガー: /project-audit、プロジェクト監査、claude 設定のレビュー、sdd 診断、プロジェクトの健全性チェック

---

Claude/SDD 設定の読み取り専用診断です。フロー： /project-audit → audit-report.md → /project-fix → /project-audit (verify)。レポートは /project-fix が実装する仕様です。中核：検出 → 評価 → レポート（安定；ルールは進化します）。レポートを [project_root]/.claude/audit-report.md に保存します。

関連する参照ファイル — REPORT_TEMPLATE.md（出力形式）、SCORING.md （100 点の配分と解釈）、PHASE_A_SCRIPT.md（検出スクリプトとスキーマ）。

ディメンションの分類

クラス	ディメンション	スコアへの影響
スコア対象	D1, D2, D3, D4, D6, D8	95 点スコア
情報提供のみ	D9, D10, D11, D12, D13, D14	なし

D5 と D7 は削除されました。明記されていない限り、情報提供のみのディメンションがスコアに影響することはありません。

互換性ポリシー — グローバル設定の免除

IS_GLOBAL_CONFIG=1 → 方法論リポジトリは自身のデプロイ先ではありません。以下の表に従ってスキップします。

ディメンション	チェック	グローバル設定の場合のスキップ
D1	スタック / package.json	スキップ
D1	## Architecture セクション	スキップ（README 内）
D1	スキルレジストリ	常にスキップ（原則 2 — ハーネスが自動検出）
D1	ai-context/ パス参照	スキップ
D2	メモリ（ai-context/）	ディメンションをスキップ；スコアでは N/A
D4a	レジストリとディスクの照合	スキップ

理由：ai-context/ は /project-setup によって、このリポジトリから利用側のプロジェクトにデプロイされます。方法論リポジトリを対象にこれを監査するのは、カテゴリの誤りです。 スコアリング：D2 → N/A；分母は 70（95 点の基準値 − 25）になります。最終スコア = round(actual/70*100)。

---

プロセス

実際のファイルを読み取ります。決めつけないでください。各ディメンションを体系的に実行します。

フェーズ A — 検出

PHASE_A_SCRIPT.md を 1 回実行し、key=value の出力を取得します。スクリプト後の「Legacy commands/ detection」も実行します。監査 1 回あたりの Bash 呼び出しは最大 3 回です。

フェーズ B — ディメンションごとの評価

各ディメンションを適用します。調査結果には重大度（CRITICAL/HIGH/MEDIUM/LOW/INFO）と、任意の FIX_MANIFEST エントリが含まれます。

Dimension 1 — CLAUDE.md

プロジェクトタイプの検出: IS_GLOBAL_CONFIG=1 → global-config。ルートの CLAUDE.md は .claude/CLAUDE.md と同等として扱います。レポートに Project Type を記載してください。

チェック	重大度
.claude/CLAUDE.md が存在する（または global-config の場合はルート）	CRITICAL
空でない（50 行超）	CRITICAL
Stack セクションがある（## Tech Stack または ## Stack）	CRITICAL
Stack に明示的なバージョンを伴う技術が 3 つ以上ある	CRITICAL
Stack が package.json / pyproject.toml と一致する	HIGH
## Architecture セクションがある	HIGH
Skills レジストリがある	HIGH
Unbreakable Rules セクションがある	MEDIUM
Plan Mode セクションがある	LOW
SDD（/sdd-*）に言及している	HIGH
ai-context/ パスへの参照が正しい	MEDIUM

ADR-004 により、Stack の重大度は CRITICAL です（すべての技術参照スキルが Stack に基づいて処理されるため）。IS_GLOBAL_CONFIG=1 の場合の免除については、「Compatibility policy」を参照してください。

Stack の比較: package.json / 同等のファイルから依存関係の上位 5～10 件を抽出し、 CLAUDE.md と比較します。不一致は declared X.Y, actual A.B の形式で報告してください。

テンプレートパスの検証: ## Documentation Conventions セクションを見つけ、 docs/templates/*.md に一致するパスを抽出し、それぞれが存在することを確認します。見つからないパスごとに MEDIUM と required_actions.medium の type: create_file を設定します。一致するパターンが見つからない場合は、この検証を 完全にスキップしてください。

---

Dimension 2 — Memory（ai-context/）

IS_GLOBAL_CONFIG=1 の場合は完全にスキップします — INFO "D2 skipped — global-config repos do not use ai-context/" を出力します。D2 は N/A（25 点を分母から除外）です。「Compatibility policy」を参照してください。

標準的なプロジェクトの場合：

ファイル	最小行数	注記
ai-context/stack.md	> 30
ai-context/architecture.md	> 40
ai-context/conventions.md	> 30
ai-context/known-issues.md	> 10	新しいプロジェクトでは短くても可
ai-context/changelog-ai.md	> 5	エントリーが少なくとも 1 件必要

場所は ai-context/ または docs/ai-context/ のいずれかです。両方を確認してください。

内容チェック（既存ファイルごと）：

• stack.md：依存関係の上位 5 件のバージョンが package.json と一致すること。
• architecture.md：記載されたディレクトリがディスク上に存在すること。
• conventions.md：文書化された規約が、実際のファイル 2～3 件のサンプルに反映されていること。
• known-issues.md：[To confirm] / [Empty] のプレースホルダーではなく、実際の内容があること。
• changelog-ai.md：## YYYY-MM-DD のエントリーが少なくとも 1 件あること。

プレースホルダー句の検出 — 内容をスキャンして、次の語句を検索します（角括弧内は大文字と小文字を区別せず、TODO は大文字と小文字を区別します）：[To be filled]、[empty]、 [TBD]、[placeholder]、[To confirm]、[Empty]、大文字表記の TODO。一致するたびに HIGH "[filename] appears to contain unfilled placeholder content" とします。行数の条件を満たしていても、そのファイルは実質的に空として扱います。 required_actions.high に type: update_file を追加してください。

stack.md のバージョン数 — x.y、x.y.z、または vX に一致する行を数えます。 3 件未満の場合は MEDIUM "stack.md lists fewer than 3 technologies with concrete versions — minimum is 3" とします。stack.md が存在しない場合、またはすでにプレースホルダーと判定されている場合はスキップしてください。

ユーザー向けドキュメントの鮮度（ai-context/scenarios.md および ai-context/quick-reference.md が対象）：

• 存在しない場合 → LOW "[filename] missing — create via /project-onboard or manually"。
• 存在する場合 → 先頭 10 行を検索し、^> Last verified: (\d{4}-\d{2}-\d{2})$ に一致するか確認します。 見つからない、または形式が不正な場合 → LOW。90 日を超えて古い場合 → 経過日数を添えて LOW。すべての指摘は LOW とし、D2 のスコアは減点しません。

---

ディメンション 3 — SDD オーケストレーター

3a. グローバル SDD スキル — 8 つのフェーズスキルが ~/.claude/skills/ に存在する必要があります： sdd-explore、sdd-propose、sdd-spec、sdd-design、sdd-tasks、sdd-apply、 sdd-verify、sdd-archive。欠けているものがあれば CRITICAL です。

3b. Engram の利用可否 — mem_context を呼び出します。到達可能な場合は INFO ログに記録します。 到達不能な場合は HIGH "Engram に到達できません — SDD アーティファクトは永続化されません" とします。

3c. CLAUDE.md に SDD の記載がある — /sdd-* が含まれていない場合は HIGH とします。 SDD フローを説明するセクションがない場合は LOW とします。

3d. 孤立した変更 — mem_search(query: "sdd/", project: "{project}") を実行し、 last_updated > 14 days ago であり、archive-report がない状態アーティファクトを抽出します。 それらを一覧表示します。

3e. フックスクリプトの存在 — 存在する各設定ファイル （settings.json、.claude/settings.json、settings.local.json）について、hooks キーを特定し、 スクリプトのパスを抽出します。ディスク上に存在しないものは、それぞれ HIGH と required_actions.high type: create_file に追加します。hooks キーがない場合はスキップします。

3f. アクティブな変更の競合検出：

1. アクティブな変更（archive-report がないもの）を engram で検索します。それぞれの design.md を取得します。
2. ## File Change Matrix テーブルを特定します。File 列を抽出し、小文字に変換して先頭の ./ を削除します。
3. design.md を持つアクティブな変更が 2 件未満の場合はスキップします。
4. パスの集合の積集合を取ります。重複があれば、それぞれ MEDIUM "同時ファイル変更の競合： [path] は [change-A] と [change-B] の両方の対象です" とします。violations[] に追加し、 rule: "D3-active-changes-conflict" を設定します。

正規化で処理するのは、小文字への変換と先頭の ./ の削除のみです。その他の形式の 不整合は検出されません。

---

ディメンション 4 — スキルの品質

4a. レジストリとディスクの照合（双方向）：CLAUDE.md に記載された各スキルがディスク上に存在すること、またディスク上の各スキルが CLAUDE.md に記載されていることを確認します。両方向の不一致を報告します。

IS_GLOBAL_CONFIG=1 の場合は 4a をスキップします（手動のレジストリはありません。原則 2 を参照）。 INFO "D4a skipped — harness auto-discovery, not a manual registry" を出力します。 4b と 4c は引き続き適用されます。

4b. 最低限の内容 — 各スキルファイルについて：

• 30 行未満 → スタブの可能性があります。
• 形式に応じた構造チェック（docs/format-types.md を参照）：
  1. YAML フロントマターを解析し、format: を抽出します。存在しない場合は procedural として扱います。
  2. 未知の値の場合は INFO を出力し、procedural として扱います。

解決された形式	必須セクション	欠落時の指摘（MEDIUM）
procedural	## Process	"procedural skill [name] missing ## Process section"
reference	## Patterns／## Critical Patterns のいずれか 1 つ以上、および ## Examples／## Code Examples のいずれか 1 つ以上	"reference skill [name] missing (## Patterns or ## Critical Patterns) or (## Examples or ## Code Examples)"
anti-pattern	## Anti-patterns または ## Critical Patterns	"anti-pattern skill [name] missing ## Anti-patterns or ## Critical Patterns section"

**Triggers** または ## Rules が欠落している場合は、すべての形式で MEDIUM とします。## Process の欠落は、reference／anti-pattern では指摘対象になりません。

各指摘は required_actions.medium に追加します。 type: skill_quality_action、 action_type: add_missing_section、 target: [skill path]、 missing_sections: ["[heading]"]。

4c. 関連する技術スキルの網羅性（0～10 点で評価）：

技術スタックからスキルへの対応：React 18+ → react-19、Next.js 14+ → nextjs-15、 TypeScript → typescript、Zustand → zustand-5、Tailwind → tailwind-4、 Zod → zod-4、Playwright → playwright、Prisma → prisma、 React Native / Expo → react-native、Go → go-testing。

網羅性のルール（技術スキルのローカル配置ポリシー）：スキルは、プロジェクトのローカル .claude/skills/<name>/ またはグローバル ~/.claude/skills/<name>/ のいずれかに存在すれば「網羅済み」とみなされます。技術スキルはローカルに配置することを想定しています。グローバルに配置するのは、メタスキル／オーケストレータースキルのみです。zod-4 がローカルにあるのに、グローバルにないことを理由にプロジェクトを減点するのは、カテゴリの誤りです。

該当するスキルの網羅率	点数
100% 網羅、または該当なし	10
≥ 75%	8
50–74%	5
25–49%	2
< 25%	0

「該当する」とは、プロジェクトがその技術を使用しており、対応するスキルがローカルまたはグローバルに存在することを意味します。D4 の最大点数：20 点（4a+4b = 10、4c = 10）。

---

ディメンション 6 — 相互参照の整合性

Claude の設定で参照されているものが、すべてディスク上に存在する必要があります。

参照元	対象
CLAUDE.md の ## Documentation	.claude/docs/
CLAUDE.md の Templates セクション	.claude/templates/
スキル内のパス	/lib/、/domain/、pages/api/ など
ai-context/architecture.md のディレクトリ	プロジェクトのファイルシステム
コマンド内で参照されているスキル	スキルファイル

参照先が見つからない場合は、それぞれ参照元ファイル、概算行番号、存在しないパスを報告します。

Dimension 8 — テストと検証

8a. テストランナーが設定済み、または検出可能であること → 未設定の場合は HIGH。ai-context/ にテスト戦略が記載されていること → 記載がない場合は MEDIUM。

8b. engram 内の各 archive-report について、verify-report が存在し、ツール実行結果を参照していることを確認します。不足している場合 → HIGH。

8c. tasks を含む各アクティブな変更について、タスク計画に検証基準が含まれていることを確認します。design を含む各変更について、設計でテストアプローチが定義されていることを確認します。

---

Dimension 9 — プロジェクトスキルの品質（参考情報）

$LOCAL_SKILLS_DIR が存在しない場合はスキップし、"No [value] directory found — Dimension 9 skipped" を出力します。減点はありません。

Global-config の循環検出：global-config リポジトリを監査する場合、skills/ の各サブディレクトリに対応するディレクトリが ~/.claude/skills/ に存在します（install.sh 経由で同じファイルを使用）。すべての処置は keep です（想定どおり）。

D9-2 重複 — $LOCAL_SKILLS_DIR の各サブディレクトリについて、~/.claude/skills/<name>/ が存在する場合、内容が異なれば処置は move-to-global、同一であれば delete です。グローバルカタログを読み取れない場合は INFO、処置は keep です。

D9-3 構造の完全性 — D4b の形式に応じたチェックを適用します。必須セクションまたは SKILL.md が不足している場合、処置は update、アクションは add_missing_section です。

D9-4 言語要件への準拠 — フェンス付きコードの外にある本文テキストに D4e のヒューリスティックを適用します。英語以外の文章がある場合、処置は update、アクションは flag_language_violation、重大度は INFO です（減点なし）。

D9-5 スタックとの関連性 — トリガー行とタイトル内のテクノロジーへの言及を確認します。ai-context/stack.md と package.json／pyproject.toml の両方に記載がない場合、処置は update、アクションは flag_irrelevant、重大度は INFO です。スタックの情報源がない場合は、"Stack relevance check skipped — no stack source found" を出力します。

---

Dimension 10 — 機能ドキュメントの網羅性（参考情報）

機能が検出されない場合はスキップします。

設定駆動 — プロジェクトの config.yaml に feature_docs: キーがある場合は、convention（skill｜markdown｜mixed）、paths、feature_detection を読み取ります。

ヒューリスティックによるフォールバック — 次の順に確認します。

1. $LOCAL_SKILLS_DIR 内の SDD 以外のスキル（名前が sdd-、project-、memory-、skill- で始まらないもの）。
2. docs/features/ または docs/modules/ 内の *.md ファイル。
3. README.md がある src/features/、src/modules/、app/ のサブディレクトリ。

常に除外する項目：shared、utils、common、lib、types、hooks、components。除外後に何も残らない場合は、"No feature directories detected — Dimension 10 skipped" を出力します。

機能ごとのチェック：

• D10-a 網羅性：規約に沿ったドキュメントがあれば PASS、なければ FAIL。
• D10-b 構造：SKILL.md は frontmatter、**Triggers**、## Process、## Rules があれば PASS。その他の .md は H1 と 1 つ以上の H2 があれば PASS。
• D10-c 最新性：/src/[^\s]+、/lib/[^\s]+、/app/[^\s]+ に一致するパスを抽出します。存在しないパスがある場合は、古くなっている可能性があるとしてフラグを立てます。
• D10-d レジストリとの整合性：.claude/skills/ 内の SKILL.md が CLAUDE.md のレジストリにない場合は INFO（警告ではありません）。

D10 の検出事項を required_actions または skill_quality_actions に含めてはなりません。

---

Dimension 11 — 内部整合性（参考情報）

Read／Glob／Grep のみを使用し、Bash は使用しません。$LOCAL_SKILLS_DIR とルートの CLAUDE.md がどちらも存在しない場合はスキップします。

D11-a 数の整合性 — 見出しと引用行から、次の形式で記述された主張を抽出します。 CLAIM_PATTERN = /(\d+)\s+(Dimensions?|Steps?|Rules?|Phases?|Checks?|Sub-checks?)/i 本文の該当セクション数と照合します。不一致の場合は INFO。コードブロック内は照合しないでください。

D11-b 番号の連続性 — パターン： /^#{2,3}\s+.*Step\s+(\d+)/im、Dimension\s+(\d+)、Phase\s+(\d+)、 /^#{2,4}\s+.*D(\d+)/m。番号をソートし、欠番と重複を検出します。2 個以上ある場合に適用します。重大度は INFO です。

D11-c frontmatter と本文の整合性 — description に数値を含む主張がある場合、D11-a のロジックで検証します。不一致の場合は INFO。

D11 の検出事項はすべて violations[] に含め、重大度を info、ルール名を D11-count-consistency、D11-numbering-continuity、D11-frontmatter-body とします。required_actions には決して含めません。

---

ディメンション 12 — ADR の網羅状況（参考情報）

有効化条件：CLAUDE.md に文字列 docs/adr/ が含まれていること。含まれていない場合 → INFO を出力してスキップします。

D12-1：ADR_README_EXISTS=0 → HIGH "CLAUDE.md references docs/adr/ but docs/adr/README.md is missing" ＋ required_actions.high type: create_file。

D12-2：docs/adr/NNN-*.md を Glob で検索します。一致なし → INFO "docs/adr/ contains no ADR files yet"。各 ADR について、## Status 見出しまたはフロントマターの status: フィールドを検索します。どちらもない場合 → MEDIUM "ADR file [filename] is missing a valid status field" ＋ required_actions.medium type: update_file。有効な値： accepted、deprecated、superseded。カスタム値も許可され、値の検証は行いません。

---

ディメンション 13 — 仕様の網羅状況（参考情報）

有効化条件：Engram に接続でき、かつ mem_search(query: "sdd/") が仕様アーティファクトを 返すこと。

D13-1：各 spec.md から、パス形式の参照（/ を含み、スペースを含まず、 URL またはフェンス付きコード内にないもの）を抽出します。 [project_root]/[path] に存在するか確認します。存在しない場合 → INFO "Spec artifact references a path that no longer exists: [path]"。violations[] に追加し、 rule: "D13-stale-path-reference"、severity: "info"、 file: "engram spec artifact" を設定します。INFO の検出結果は required_actions に含めません。

---

ディメンション 14 — 予算の遵守状況（参考情報）

すべての監査で実行します。

1. アクティブな CLAUDE.md を読み、文字数を数えます。D1 と同じ方法でパスを解決します。 .claude/CLAUDE.md が存在する場合はそのファイル、そうでない場合はルートの CLAUDE.md（ルートが 正式な場所となるのは IS_GLOBAL_CONFIG=1 の場合のみ）を使用します。どちらも存在しない場合 → INFO "No CLAUDE.md found — budget check skipped" を出力して終了します。
2. グローバル設定（install.sh と sync.sh が存在する場合）→ 20,000 文字の予算、 それ以外 → 5,000。
3. 予算超過の場合 → INFO "CLAUDE.md is [N] chars ([N-budget] over [budget] budget). Consider extracting content to skills (ADR-041)"。
4. 予算内の場合 → INFO "CLAUDE.md budget OK: [N]/[budget] chars"。

検出結果は ## Budget Compliance セクションに記載します。スコアには影響しません。

---

レポート

[project_root]/.claude/audit-report.md に、REPORT_TEMPLATE.md の正確な構造で保存します。 スコアの配分と解釈は SCORING.md に記載されています。

---

ルール

1. 必ず実際のファイルを読みます。内容を推測してはいけません。
2. 読み取りツールを備えたサブエージェントで実行します。メインコンテキストでは実行しません。
3. レポートを提示する前に、必ず .claude/audit-report.md に保存します。
4. FIX_MANIFEST は有効な YAML でなければなりません。ブロックが解析できることを確認します。
5. いかなる変更も行いません。完全な読み取り専用です。
6. ファイルを読み取れない場合は、正確なエラーとともに ❌ を報告します。存在しないと推測してはいけません。
7. 完了時は、"Report saved in .claude/audit-report.md. To implement: /project-fix" と表示します。
8. フェーズ A ですべてのシェルによる探索を行います。実行ごとの Bash 呼び出しは最大 3 回です。ディメンションごとの ls／grep／wc -l／find は使用しません。
9. 互換性に関する動作は明示的に記述し、ディメンション内で暗黙に扱いません。