project-health

项目健康状况

一个涵盖项目 Claude Code 配置方方面面的技能。可在项目开始、中期或结束时运行，它会判断需要做什么。

目标：不出现权限提示、上下文文件井然有序、不留冗余内容。

适用场景

你说……	会发生什么
“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”	仅审计上下文

架构：子 Agent

繁重的分析由子 Agent 执行，以保持主对话简洁。主 Agent 负责协调；子 Agent 负责扫描并返回摘要。

Agent 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.

Agent 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.

并行执行

进行全面健康检查时，并行启动两个 Agent：

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

两者都会返回摘要。主 Agent 将其整合为一份报告，并提出修复建议。

模式 1：全面健康检查

默认模式。 可随时运行。

步骤

1. 并行启动权限审计员和上下文审计员 Agent

2. 将审查结果整合为一份报告：

   ## 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. 经一次是/否确认后应用修复

模式 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 Agent，发现 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. 警告：“项目的 settings.local.json 会覆盖全局设置（不会合并）。需要重启会话。”

模式 3：整理权限

适用时机：用户说“整理权限”，或健康检查发现权限问题。

启动 Permission Auditor Agent，然后应用其建议的修复。

模式 4：记录经验

适用时机：会话结束时，或用户说“记录经验”“保存已学到的内容”。

此操作在主上下文中运行（而非子 Agent），因为需要访问对话历史。

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. 一次性征得是/否确认后应用更改

保持简洁：每个概念一行。

模式 5：添加预设

适用时机：“添加 Python 权限”“添加 Docker”“添加 MCP 服务”。

1. 从 references/permission-presets.md 读取预设
2. 读取现有的 .claude/settings.local.json
3. 合并，不要重复
4. 提醒：需要重启会话

模式 6：重组上下文

适用时机：根目录 CLAUDE.md 超过 200 行，或用户说“重组记忆”。

1. 首先启动 Context Auditor Agent
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	不限范围的网页抓取
WebSearch	不限范围的网页搜索
mcp__servername__*	某个 MCP 服务上的所有工具

不起作用的模式

模式	原因
mcp__*	通配符不会跨越 __ 边界
mcp__*__*	仍然不起作用
Bash(git:*)	已弃用的冒号语法（可用，但建议使用空格）

重要行为

• 不会热重载：编辑 settings.local.json 后需要重启会话
• “Don't ask again” 会在运行时注入（无需重启），使用冒号格式——这是正常行为
• 覆盖，而非合并：项目设置会完全替换全局设置
• gh 错误：Bash(gh *) 有时会漏掉子命令——请明确添加 Bash(gh issue *) 等规则

自主性

• 直接执行：检测项目类型、启动审计 Agent、发现 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