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") で起動します。プロンプト：

Read .claude/settings.local.json.

**Discover connected MCP servers**: Use ToolSearch (search "mcp") and extract unique
server prefixes from tool names (e.g. mcp__vault__secret_list → vault).

**Discover installed skills**: Use the Skill tool or ToolSearch to list available skills.
For each skill that has scripts/ in its directory, note what Bash patterns it needs
(python3, env var prefixes like GEMINI_API_KEY=*, etc.). Check the SKILL.md for any
MCP tools the skill references (e.g. mcp__vault__secret_get).

Report:
1. MCP servers connected but NOT in settings (missing)
2. MCP servers in settings but NOT connected (stale)
3. Skill permissions: Bash patterns and MCP tools that installed skills need but aren't approved
4. File access: check for Read/Edit/Write patterns for .claude/** and //tmp/**
   in project settings, and ~/Documents/**/~/.claude/** in global settings
5. Leaked secrets: entries containing API keys, tokens, bearer strings, hex >20 chars, base64 >20 chars
6. Legacy colon syntax: entries like Bash(git:*) instead of Bash(git *)
7. Junk entries: shell fragments (Bash(do), Bash(fi), Bash(then), Bash(else), Bash(done)),
   __NEW_LINE_* artefacts, loop body fragments (Bash(break), Bash(continue), Bash(echo *))
8. Duplicates: entries covered by a broader pattern (e.g. Bash(git add *) redundant if Bash(git *) exists)
9. Missing presets: based on files present, suggest presets from [permission-presets.md]

Prefer Read/Glob/Grep tools over Bash. If you need to scan multiple files or
run 3+ commands for one analysis, write a Python script to .jez/scripts/
and run it once (mkdir -p .jez/scripts first).

Return a structured summary, not raw data.

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

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

Audit the project context landscape at [repo-path]:

1. Find all CLAUDE.md files. For each:
   - Count lines (target: root 50-150, subdirs 15-50)
   - Score quality on 6 criteria (see quality-criteria.md)
   - Check for stale file/path references
   - Flag oversized files

2. Find .claude/rules/ topic files. Check sizes (target: 20-80 lines).

3. Detect project type from files present (see project-types.md).
   Check expected docs exist (ARCHITECTURE.md, DATABASE_SCHEMA.md, etc.)

4. Find public markdown (README.md, LICENSE, CONTRIBUTING.md).
   Check for overlap with CLAUDE.md content.

5. Check auto-memory at ~/.claude/projects/*/memory/MEMORY.md

6. If Cloudflare project: find all wrangler.jsonc/wrangler.toml files.
   Check each has "observability": { "enabled": true }. Flag any missing it.

Prefer Read/Glob/Grep tools over Bash. If you need to scan many files or
aggregate data across the repo, write a Python script to .jez/scripts/
and run it once rather than running many individual bash commands
(mkdir -p .jez/scripts first).

Return: project type, quality scores, missing docs, stale refs, overlaps,
size violations, observability gaps, and total markdown footprint.

並列実行

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

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

両方のエージェントが要約を返します。メインエージェントはそれらを1つのレポートにまとめ、修正案を提示します。

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

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

手順

1. 権限監査エージェントとコンテキスト監査エージェントを並列で起動します

2. 調査結果を1つのレポートにまとめます。

   ## Project Health Report
   
   **Project type**: [detected type]
   **CLAUDE.md quality**: [score]/100 ([grade])
   
   ### Permissions
   - Missing MCP servers: [list]
   - Leaked secrets: [count] found
   - Legacy syntax: [count] entries
   - Missing presets: [list]
   
   ### Context
   - Oversized files: [list]
   - Stale references: [list]
   - Missing docs: [list]
   - Overlaps: [list]
   
   ### Recommended Fixes
   1. [fix 1]
   2. [fix 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 + 静的サイト
   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	モバイル
   Dockerfile または docker-compose.yml	docker	Docker
   fly.toml、railway.json、または netlify.toml	hosted-app	ホスティングプラットフォーム
   supabase/config.toml	supabase	ホスティング + データベース
   .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/ を Git の追跡対象外にしないでください。生成したスクリプトは残しておく価値があります

5. 任意（事前に確認）：git init + gh repo create

6. 警告：「プロジェクトの settings.local.json はグローバル設定をシャドウします（マージしません）。セッションの再起動が必要です。」

モード 3：権限を整理する

実行条件：ユーザーが「権限を整理して」と言った場合、またはヘルスチェックで権限の問題が見つかった場合。

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

モード 4：学びを記録する

実行条件：セッション終了時、「学びを記録して」「学んだことを保存して」と言われた場合。

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

1. 保存する価値のある発見がないか、会話を確認します
2. 保存先を決めます：

   Applies to all projects?
   ├── YES → ~/.claude/rules/<topic>.md
   └── NO  → Specific to a subdirectory?
       ├── YES → <dir>/CLAUDE.md
       └── NO  → Reference or operational?
           ├── Reference → docs/ or ARCHITECTURE.md
           └── Operational → ./CLAUDE.md (root)
   

3. すべての変更を単一のバッチで差分として作成します
4. 1 回の yes/no 確認後に適用します

簡潔にまとめます：概念ごとに 1 行にします。

モード 5：プリセットを追加する

実行条件：「Python の権限を追加して」「Docker を追加して」「MCP サーバーを追加して」と言われた場合。

1. references/permission-presets.md からプリセットを読みます
2. 既存の .claude/settings.local.json を読みます
3. 重複しないようにマージします
4. セッションの再起動が必要であることを伝えます

モード 6：コンテキストを再構成する

実行条件：ルートの CLAUDE.md が 200 行を超えた場合、または「メモリを再構成して」と言われた場合。

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 フェッチ
WebSearch	すべての Web 検索
mcp__servername__*	1 つの MCP サーバー上のすべてのツール

機能しないもの

パターン	理由
mcp__*	ワイルドカードは __ の境界を越えません
mcp__*__*	これも機能しません
Bash(git:*)	非推奨のコロン構文（機能しますが、スペースの使用を推奨します）

重要な動作

• ホットリロードされません：settings.local.json の編集を反映するには、セッションの再起動が必要です
• **「次回から確認しない」**はコロン形式を使って実行時に適用されます（再起動不要）。これは正常な動作です
• マージではなく上書き：プロジェクト設定はグローバル設定を完全に置き換えます
• gh の不具合：Bash(gh *) ではサブコマンドが認識されない場合があります。Bash(gh issue *) などを明示的に含めてください

自律性

• そのまま実行：プロジェクトの種類を検出し、監査エージェントを起動し、MCP サーバーを検出します
• 簡潔に確認：ファイルの作成・更新（まとめて一括で yes/no を確認）
• 事前に確認：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