Project Health

プロジェクトの Claude Code 設定に関するあらゆることを1つのスキルで対応します。プロジェクトの開始、途中、終了時に実行できます。— 必要なことを自動判断します。

目標: パーミッションプロンプトがゼロ、整理されたコンテキストファイル、無駄なクラッタなし。

いつ使う

あなたの指示	実行内容
"project health" / "check project"	完全監査: パーミッション + コンテキスト + ドキュメント
"setup project" / "kickoff" / "bootstrap"	新規プロジェクトセットアップ
"tidy permissions" / "clean settings"	パーミッションファイルのみ修正
"capture learnings" / "update CLAUDE.md"	セッション内での発見を保存
"add python" / "add docker permissions"	既存設定にプリセットを追加
"audit context" / "audit memory"	コンテキスト監査のみ

アーキテクチャ: サブエージェント

重い分析はサブエージェントで実行し、メイン会話をクリーンに保ちます。メインエージェントが調整し、サブエージェントがスキャンして概要を返します。

エージェント1: パーミッション監査者

Task(subagent_type: "general-purpose") で起動します。プロンプト:

.claude/settings.local.json を読む。

**接続されている MCP サーバーを検出**: ToolSearch を使用 (「mcp」で検索) し、
ツール名から一意のサーバープリフィックスを抽出 (例: mcp__vault__secret_list → vault)。

**インストール済みスキルを検出**: Skill ツールまたは ToolSearch を使用して
利用可能なスキルをリスト。各スキルについて scripts/ がディレクトリ内にあれば、
必要な Bash パターンをメモ (python3, GEMINI_API_KEY=* のような環境変数プリフィックス等)。
SKILL.md でスキルが参照している MCP ツール (例: mcp__vault__secret_get) をチェック。

レポート:
1. 接続されているが設定に含まれていない MCP サーバー (不足)
2. 設定には含まれているが接続されていない MCP サーバー (古い)
3. スキルパーミッション: インストール済みスキルが必要だが承認されていない Bash パターンと MCP ツール
4. ファイルアクセス: プロジェクト設定の .claude/** と //tmp/** に対する Read/Edit/Write パターン、
   グローバル設定の ~/Documents/**/~/.claude/** をチェック
5. 漏洩した機密情報: API キー、トークン、bearer 文字列、20文字以上の16進数、20文字以上の base64 を含むエントリ
6. レガシーコロン構文: Bash(git:*) のような Bash(git *) ではなくコロン構文のエントリ
7. ジャンク エントリ: シェルフラグメント (Bash(do), Bash(fi), Bash(then), Bash(else), Bash(done)),
   __NEW_LINE_* アーティファクト、ループボディフラグメント (Bash(break), Bash(continue), Bash(echo *))
8. 重複: より広いパターンでカバーされているエントリ (例: Bash(git *) が存在する場合 Bash(git add *) は冗長)
9. 不足しているプリセット: 存在するファイルに基づき、[permission-presets.md] のプリセットを提案

Bash よりも Read/Glob/Grep ツールを優先。1つの分析に複数ファイルをスキャンまたは
3つ以上のコマンドを実行する必要がある場合は、Python スクリプトを .jez/scripts/
に書いて1度実行 (先に mkdir -p .jez/scripts)。

構造化された概要を返す (生データではなく)。

エージェント2: コンテキスト監査者

Task(subagent_type: "general-purpose") で起動します。プロンプト:

[repo-path] でプロジェクトコンテキスト環境を監査:

1. すべての CLAUDE.md ファイルを検出。各ファイルについて:
   - 行数カウント (目標: ルート 50-150, サブディレクトリ 15-50)
   - 6つの基準で品質スコア (quality-criteria.md を参照)
   - 古いファイル/パス参照をチェック
   - サイズが大きすぎるファイルをフラグ

2. .claude/rules/ トピックファイルを検出。サイズをチェック (目標: 20-80行)。

3. 存在するファイルからプロジェクトタイプを検出 (project-types.md を参照)。
   予想されるドキュメントが存在するかチェック (ARCHITECTURE.md, DATABASE_SCHEMA.md 等)。

4. パブリック markdown を検出 (README.md, LICENSE, CONTRIBUTING.md)。
   CLAUDE.md コンテンツとのオーバーラップをチェック。

5. ~/.claude/projects/*/memory/MEMORY.md でオート メモリをチェック。

6. Cloudflare プロジェクトの場合: すべての wrangler.jsonc/wrangler.toml ファイルを検出。
   各ファイルに「observability」: { 「enabled」: true } があるかチェック。
   不足しているものをフラグ。

Bash よりも Read/Glob/Grep ツールを優先。多数のファイルをスキャンまたは
リポジトリ全体でデータを集約する必要がある場合は、Python スクリプトを .jez/scripts/
に書いて1度実行 (多くの個別 bash コマンドを実行するのではなく、先に mkdir -p .jez/scripts)。

リターン: プロジェクトタイプ、品質スコア、不足しているドキュメント、古い参照、オーバーラップ、
サイズ違反、observability ギャップ、および合計 markdown フットプリント。

並列実行

完全なヘルスチェックでは、両方のエージェントを並列で起動:

Task(subagent_type: "general-purpose", name: "permission-audit", prompt: "...")
Task(subagent_type: "general-purpose", name: "context-audit", prompt: "...")

両方が概要を返します。メインエージェントがそれらを1つのレポートに統合して修正を提案します。

モード1: 完全ヘルスチェック

デフォルトです。いつでも実行できます。

ステップ

1. Permission Auditor と Context Auditor エージェントを並列で起動

2. 発見結果を1つのレポートに統合:

   ## Project Health Report
   
   **Project type**: [検出されたタイプ]
   **CLAUDE.md quality**: [スコア]/100 ([グレード])
   
   ### Permissions
   - Missing MCP servers: [リスト]
   - Leaked secrets: [カウント] 件検出
   - Legacy syntax: [カウント] エントリ
   - Missing presets: [リスト]
   
   ### Context
   - Oversized files: [リスト]
   - Stale references: [リスト]
   - Missing docs: [リスト]
   - Overlaps: [リスト]
   
   ### Recommended Fixes
   1. [修正 1]
   2. [修正 2]
   ...
   

3. はい/いいえの1つの確認後に修正を適用

モード2: 新規プロジェクトセットアップ

時: .claude/settings.local.json が存在しない場合、または「setup」/「kickoff」と言った場合。

ステップ

1. プロジェクトタイプを検出 (存在するファイルから):

   インジケーター	タイプ	プリセット
   wrangler.jsonc または wrangler.toml	cloudflare-worker	JS/TS + Cloudflare
   vercel.json または next.config.*	vercel-app	JS/TS + Vercel
   astro.config.*	astro	JS/TS + Static Sites
   package.json (デプロイターゲットなし)	javascript-typescript	JS/TS
   pyproject.toml または setup.py または requirements.txt	python	Python
   Cargo.toml	rust	Rust
   go.mod	go	Go
   Gemfile または Rakefile	ruby	Ruby
   composer.json または wp-config.php	php	PHP
   pom.xml または build.gradle*	java	Java/JVM
   *.sln または *.csproj	dotnet	.NET
   mix.exs	elixir	Elixir
   Package.swift	swift	Swift + macOS
   pubspec.yaml	flutter	Mobile
   Dockerfile または docker-compose.yml	docker	Docker
   fly.toml または railway.json または netlify.toml	hosted-app	Hosting Platforms
   supabase/config.toml	supabase	Hosting + Database
   .claude/agents/ またはオペレーション スクリプト	ops-admin	—
   空のディレクトリ	ユーザーに質問	—

   タイプは積み重なる (例: cloudflare-worker + javascript-typescript)。

2. .claude/settings.local.json を生成:

   • references/permission-presets.md を読む
   • 常に Universal Base を含める (.claude/, //tmp/ のファイルアクセスを含む)
   • 検出された言語 + デプロイメントプリセットを追加
   • グローバル ~/.claude/settings.local.json にホーム相対ファイルアクセスパターンがあるか確認 (~/Documents/, ~/.claude/)。ない場合、そこに追加することを提案 (プロジェクトファイルではなく — ホームパスはグローバル設定のみに属する)
   • Permission Auditor エージェントを起動して MCP サーバーを検出し、サーバーごとのワイルドカード を追加
   • 常に WebSearch, WebFetch を含める
   • 常に明示的な gh サブコマンドを含める (Bash(gh *) バグの回避策)
   • // コメントグループで書く

3. CLAUDE.md を生成:

   • references/templates.md を読む
   • プロジェクトタイプに適したテンプレートを使用

4. .gitignore を生成:

   • references/templates.md を読む
   • 常に .claude/settings.local.json, .claude/plans/, .jez/screenshots/, .jez/artifacts/ を含める
   • .jez/scripts/ を gitignore しない — 生成されたスクリプトの価値あり

5. オプション (先に質問): git init + gh repo create

6. 警告: "Project settings.local.json SHADOWS global settings (does not merge). Session restart needed."

モード3: パーミッション整理

時: ユーザーが「tidy permissions」と言った場合、またはヘルスチェックがパーミッション問題を検出した場合。

Permission Auditor エージェントを起動し、その推奨修正を適用します。

モード4: 学習内容をキャプチャ

時: セッション終了、「capture learnings」、「save what we learned」。

メインコンテキストで実行 (サブエージェントではなく) 会話履歴へのアクセスが必要なため。

1. 保存する価値のある発見について会話をレビュー
2. 配置を決定:

   すべてのプロジェクトに適用?
   ├── はい → ~/.claude/rules/<topic>.md
   └── いいえ → 特定のサブディレクトリに固有?
       ├── はい → <dir>/CLAUDE.md
       └── いいえ → リファレンスまたはオペレーション?
           ├── リファレンス → docs/ または ARCHITECTURE.md
           └── オペレーション → ./CLAUDE.md (ルート)
   

3. すべての変更を1つのバッチで diff として下書き
4. はい/いいえの1つの確認後に適用

簡潔に保つ: 概念ごとに1行。

モード5: プリセットを追加

時: 「add python permissions」、「add docker」、「add MCP servers」。

1. references/permission-presets.md からプリセットを読む
2. 既存の .claude/settings.local.json を読む
3. 重複なしでマージ
4. 注意: セッション再起動が必要

モード6: コンテキストを再構成

時: ルート CLAUDE.md が 200行以上、「restructure memory」。

1. まず Context Auditor エージェントを起動
2. 発見に基づいて:
   • 大きすぎる CLAUDE.md を .claude/rules/<topic>.md に分割
   • ディレクトリ固有のコンテンツをサブディレクトリ CLAUDE.md に抽出
   • リファレンス資料を docs/ に移動
   • オーバーラップを解決
   • プロジェクトタイプの不足しているドキュメントを作成
3. プランを提示、承認後に適用

サイズ目標

ファイル	目標	最大
ルート CLAUDE.md	50-150行	200
サブディレクトリ CLAUDE.md	15-50行	80
ルールトピック ファイル	20-80行	120

パーミッション構文クイックリファレンス

パターン	意味
Bash(git *)	推奨 — * の前のスペース = ワード境界
Bash(nvidia-smi)	完全一致、引数なし
WebFetch	一括 web fetch
WebSearch	一括 web search
mcp__servername__*	1つの MCP サーバーのすべてのツール

機能しないもの

パターン	理由
mcp__*	ワイルドカードは __ 境界を越えない
mcp__*__*	やはり機能しない
Bash(git:*)	廃止されたコロン構文 (動作するが スペース推奨)

重要な動作

• ホットリロードなし: settings.local.json 編集にはセッション再起動が必要
• 「Don't ask again」 はコロン形式を使用してランタイムで注入 (再起動不要) — 通常
• シャドウ、マージなし: プロジェクト設定がグローバル設定を完全に置き換える
• gh バグ: Bash(gh *) は時々サブコマンドを見落とす — 明示的な Bash(gh issue *) 等を含める

自律性

• ただやる: プロジェクトタイプを検出、監査エージェントを起動、MCP サーバーを検出
• 簡潔な確認: ファイルの書き込み/更新 (単一バッチのはい/いいえ)
• 先に質問: git init、GitHub リポジトリ、既存コンテンツ削除、大規模な再構成

リファレンス ファイル

時	読む
パーミッション プリセット構築	references/permission-presets.md
CLAUDE.md、.gitignore 生成	references/templates.md
CLAUDE.md 品質スコア	references/quality-criteria.md
プロジェクトタイプ検出 + 予想ドキュメント	references/project-types.md
コミット キャプチャ フック設定	references/commit-hook.md