health

Health: Agent-Assisted Engineering Health

将第一行以🥷内联方式前缀，不要作为独立段落。

更新检查（非阻塞）。 每次对话运行一次 bash <skill-base-dir>/scripts/check-update.sh，将 <skill-base-dir> 替换为此技能的基目录；中继任何打印的行，否则静默继续（当脚本已运行、缺失或出错时也是如此）。它每天最多检查一次，只读取一个公共版本文件，不发送任何数据。

根据以下框架审计当前项目的代理设置和AI编码可维护性：
agent config → instruction surfaces → tools/runtime → verifiers → maintainability

查找违规。识别错位的层。仅根据项目复杂度进行校准。

结果契约

• 结果：一份预算感知的健康报告，将代理配置风险与AI可维护性风险分开。
• 完成条件：每个发现都指明错位的层、具体证据以及可复制粘贴的操作或诊断命令。
• 证据：收集的健康脚本输出、跟踪的项目指令、运行时配置摘要、验证器日志、hooks/MCP表面以及必要时实时探测。
• 输出：按优先级排列的发现，包含状态、影响和下一步操作，或明确的无问题声明及剩余风险。

两个通道共享一份报告：

• 代理配置健康：Codex/Claude/Pi指令漂移、权限、hooks、MCP、技能和记忆供应链。
• AI可维护性健康：项目上下文表面、验证器包装器、生成工件检查、热点所有权以及过时或误导性的持久文档。

输出语言： 按顺序检查：(1) 项目代理指令（AGENTS.md 优先于运行时特定文件）；(2) 全局代理指令；(3) 用户最近使用的语言；(4) 英语。

预算姿态： 从摘要审计开始。当用户要求进行深度、完整、全面、彻底、"深入"、"完整"、"彻底"或"继续跑完"审计时，当用户明确提到AI编码代码腐化、Codex/Claude配置漂移、上下文不清晰、缺少验证、验证输出指向过时路径或"代码变烂"时，当当前项目指令或记忆的用户偏好默认运行深度健康检查时，当项目为复杂时，或当摘要通过暴露了无法本地解决的关键歧义时，自动升级。否则不要读取完整的对话摘录或启动检查器子代理。在升级前告知用户，因为深度健康审计可能消耗大量令牌配额。

持久上下文预检

参见 references/durable-context.md 了解何时读取持久上下文、读取顺序预算和记忆类型映射。

对于 /health：当前配置、命令输出和实时探测覆盖记忆。当影响行为时，也要标记持久记忆问题：过大的注入摘要、过时或矛盾的条目、缺少项目入口点引用、或复制到公共指令中的私有路径。将这些作为上下文发现，而不是代码审查发现。

步骤 0：评估项目层级

选择一个。仅应用该层级的要求。

层级	信号	预期内容
简单	<500 文件，1 个贡献者，无 CI	仅 CLAUDE.md；0-1 个技能；hooks 可选
标准	500-5K 文件，小团队或 CI	CLAUDE.md + 1-2 条规则；2-4 个技能；基本 hooks
复杂	>5K 文件，多贡献者，活跃 CI	需要完整的六层设置

步骤 1：收集数据

首先以摘要模式运行收集脚本。暂不解释。

# 从规范位置解析 collect-data.sh（不使用个人主目录路径）。
HEALTH_SCRIPT="${CLAUDE_SKILL_DIR:+$CLAUDE_SKILL_DIR/scripts/collect-data.sh}"
if [ ! -f "${HEALTH_SCRIPT:-}" ]; then
  for candidate in \
    "./skills/health/scripts/collect-data.sh" \
    "$(npx skills path tw93/Waza 2>/dev/null)/skills/health/scripts/collect-data.sh"; do
    [ -f "$candidate" ] && HEALTH_SCRIPT="$candidate" && break
  done
fi
if [ ! -f "${HEALTH_SCRIPT:-}" ]; then
  echo "health collect-data.sh not found; set CLAUDE_SKILL_DIR or reinstall: npx skills add tw93/Waza -a claude-code -g -y"
  exit 1
fi
bash "$HEALTH_SCRIPT"

当工具缺失时，部分可能显示 (unavailable)：

• jq 缺失 → 对话部分不可用
• python3 缺失 → MCP/hooks/allowedTools 部分不可用
• settings.local.json 不存在 → hooks/MCP 可能不可用（仅全局设置时正常）

将 (unavailable) 视为数据不足，而不是发现。不要标记这些区域。

收集器包括运行时特定和代理无关的表面：

• AGENT CONFIG SUMMARY / AGENT CONFIG DETAIL 用于 Codex、Claude、Pi 和项目指令文件。
• AI MAINTAINABILITY SUMMARY / AI MAINTAINABILITY DETAIL 用于项目形态、验证表面、热点所有权、包装器和文档链接。

步骤 1b：MCP 实时检查

测试每个 MCP 服务器：每个服务器调用一个无害工具。记录 live=yes/no 及错误详情。尊重 enabled: false（跳过而不标记）。对于 API 密钥，仅检查环境变量是否设置（echo $VAR | head -c 5），绝不打印完整密钥。

步骤 1c：安全与安全检查

这些在收集之后、步骤 2 分析之前运行。前两项适用于每次审计；第三项仅适用于具有长时间运行或自主代理的项目。

安全基线检查

每次审计都运行这些，无论层级如何。它们是底线，不是上限。

拒绝列表底线。 仅当运行时实际强制执行所推荐的规则形态时应用：代理权限设置、hook 设置、MCP 设置、允许/禁止工具，或文档化的自主代理启动器。在这种情况下，设置应至少拒绝：凭据和密钥目录（SSH、云提供商、GPG、gh CLI）、秘密文件（.env、credentials*、secrets*）以及管道到 shell 的安装程序。将其报告为一个简洁的 WARN，包含缺失的类别；让审查者填写确切的本地路径。三种校准：前缀/全局权限规则无法可靠匹配管道，因此建议使用主机的预执行 hook 来阻止管道到 shell，而不是发明全局变体，并命名 hook 自身的权衡（字符串匹配 hook 也会触发包含该模式的引用文本和 heredoc）；在预测出站 shell 拒绝的影响范围之前，检查它匹配的层：对 ssh 的命令前缀拒绝仅阻止代理直接调用 ssh，而让 git 的内部 SSH 传输不受影响，而进程级或沙箱级阻止确实会破坏 git-over-SSH 推送；当运行时没有命令级拒绝表面时（Codex：杠杆是 sandbox_mode 和 approval_policy），将该杠杆作为用户权衡命名一次，而不是推荐运行时无法表达的拒绝键。如果根本不存在代理设置表面，则将拒绝列表报告为不适用，而不是失败。

权限层与指令层门控。 git 写操作（git push）的允许列表条目旁边有指令层规则（"仅当用户说时才推送"）并不自动矛盾：指令决定何时执行操作，权限决定是否重新提示，而每次会话都明确授权推送的用户可能故意保留推送在允许列表中以避免双重确认。根据可逆性和用户自己的规则进行校准：指令明确禁止的操作（git reset --hard、git stash、强制推送）应属于拒绝或询问；常规明确授权的操作保留在用户放置的位置，最多作为注释报告。仅当自动模式加上跳过提示加上广泛允许使得写操作在会话中零用户输入运行时才升级，并且即使如此，也要呈现摩擦权衡供用户选择，而不是静默移动条目。

环境覆盖表面。 将以下内容视为攻击面，当在跟踪文件或已发布设置中设置而没有理由注释时报告：API 基础 URL 覆盖（将所有流量重定向到第三方）、项目本地 MCP 服务器的自动信任标志、通配符工具允许列表（allowedTools: ["*"]）和权限跳过标志（--dangerously-skip-permissions 或等效项）。仅打印文件:行和键名；绝不打印秘密。

记忆与技能供应链

将代理记忆和第三方技能视为供应链工件。它们以用户权限运行。

记忆卫生。 审计项目的长期代理记忆存储，查找秘密、令牌或凭据（严重），以及由不可信运行（在攻击者控制的输入上调用的子代理、对外部内容的 /loop 迭代）写入的条目；建议在此类运行后轮换。对于高风险的一次性运行（不可信 PDF、不受控制的抓取、第三方脚本），建议完全禁用该会话的记忆持久性。

技能供应链。 第三方技能、插件和 MCP 服务器以用户权限运行。对于每个非本仓库编写的，检查：源固定到发布标签或修订版（不是 main、分支或跟踪最新头的远程 git 市场），hook 处理程序不写入凭据目录，MCP 服务器有明确的用户同意（不是通过通配符自动信任）。将未固定的源或未审查的 hook 处理程序报告为结构性，而不是严重，除非存在活跃的利用信号。

长时间运行代理停止条件

对于使用 /loop、自主代理或任何长时间运行代理流的项目，项目必须定义明确的停止条件。永不停止的代理是预算和安全事故的隐患。

审计以下四个硬停止信号；将每个缺失标记为结构性发现：

1. 连续两个检查点无进展。 相同的文件被触及，相同的错误被记录，没有新的提交/测试/输出。建议终止循环并呈现状态，而不是重试。
2. 重复相同的失败。 相同的堆栈跟踪、相同的错误消息、相同的失败断言连续三次意味着假设是错误的；更多尝试无济于事。
3. 超出成本或令牌预算。 项目应声明每次运行的预算（令牌、API 花费、挂钟分钟）。当达到预算时循环退出，而不是工作完成时。
4. 外部阻塞。 目标分支上的合并冲突、代理无法解决的依赖锁定、缺失凭据、网络不可达。任何这些都会停止循环并询问用户，而不是永远重试。

停止条件应存在于跟踪的项目文档中（AGENTS.md、循环的启动脚本或专用配置），而不仅仅在代理的提示中。提示是可遗忘的；跟踪的配置是可执行的。当项目支持时，建议使用 hooks（相关工具上的 PostToolUse）而不是提示指令：hook 物理上不能被跳过，提示指令可以。在推荐之前确认主机的 hook 覆盖范围：某些代理仅为工具子集触发 PostToolUse（例如，运行时可能仅匹配 shell/Bash），因此必须在文件编辑后运行的修复应放在那里的 Stop 或会话结束 hook 上。

步骤 2：分析

确认层级。然后路由：

• 简单： 本地分析。无子代理。
• 标准： 从摘要输出本地分析。默认不启动子代理。如果用户要求深度/完整/彻底审计，或者本地分析无法分类安全/控制问题，则升级到深度模式并解释可能的令牌成本。
• 复杂、记忆的深度偏好、明确的深度审计或明确的 AI 可维护性审计： 使用 bash "$HEALTH_SCRIPT" auto deep 重新运行收集，然后并行启动相关子代理。将凭据编辑为 [REDACTED]。
  • 代理 1（上下文 + 安全）：读取 agents/inspector-context.md。提供 CONVERSATION SIGNALS 部分。
  • 代理 2（控制 + 行为）：读取 agents/inspector-control.md。提供检测到的层级。
  • 代理 3（AI 可维护性）：读取 agents/inspector-maintainability.md。仅提供 TIER METRICS、AI MAINTAINABILITY SUMMARY 或 AI MAINTAINABILITY DETAIL 以及脚本热点列表。仅对深度健康审计、复杂项目或明确的代码腐化/AI 可维护性请求启动此代理。
• 回退： 如果子代理失败，本地分析该层并注明 "(analyzed locally)"。

步骤 3：报告

健康报告：{project}（{tier} 层级，{file_count} 文件）

全局发现仅报告一次。 机器全局配置（~/.claude、~/.codex、全局规则、技能、记忆）中的发现不是项目发现：将其标记为 global，每个报告一次并附带修复，建议一个专用会话进行全局清理，而不是每个项目重新修复。在编辑任何全局文件之前，重新读取其当前状态：当健康在同一天跨多个项目运行时，另一个会话可能已经修复或正在修复同一文件，重新应用规则的变体会创建重复条目。绝不要从两个并发会话编辑同一全局文件。

[PASS] 通过检查（表格，最多 5 行）

发现格式

- [severity] <symptom> ({file}:{line} if known)
  Why: <one-line reason>
  Action: <exact command or edit to fix>

Action: 必须可复制粘贴。绝不要写 "investigate X" 或 "consider Y"。如果修复未知，命名诊断命令。

在同一句话中被反驳的发现（TODO 计数结果证明是供应商代码或误报）不是发现；删除它或将其折叠到通过表中。

[!] 严重 -- 立即修复

违反规则、危险的 allowedTools、MCP 开销 >12.5%、安全发现、泄露的凭据。

示例：

• [!] settings.local.json 已提交到 git（暴露 MCP 令牌）
  Why: 泄露的令牌允许通过已安装的 MCP 服务器远程执行代码
  Action: git rm --cached .claude/settings.local.json && echo '.claude/settings.local.json' >> .gitignore

[~] 结构性 -- 尽快修复

代理指令在错误层、缺少 hooks、过大的描述、验证器缺口。

Codex/Claude/Pi 指令漂移。 首先使用 AGENT CONFIG SUMMARY。当 AGENTS.md 和运行时特定文件都包含大量指导而没有委托时，当 Codex config.toml 缺少对当前项目的信任时，当 Pi 设置或包元数据指向缺失的技能根时，当项目代理指令缺失时，或者当运行时特定指令与共享项目真相源矛盾时，报告结构性发现。当重要规则仅存在于被忽略或私有的本地指令覆盖中，但跟踪/公共文档缺少它们时，也要报告；这些覆盖是私有上下文，不是持久的项目真相源。不要打印原始配置值。秘密、令牌、密钥和密码必须仅显示为 [REDACTED]。

从项目根目录快速检查，重用步骤 1 中解析的 $HEALTH_SCRIPT：

bash "$(dirname "$HEALTH_SCRIPT")/check-agent-context.sh" . summary

AI 可维护性缺口。 在摘要模式下使用 AI MAINTAINABILITY SUMMARY，在深度模式下使用 AI MAINTAINABILITY DETAIL。当项目没有可执行的验证命令、非平凡仓库没有代理指令表面或文档引用损坏时，报告 FAIL。当指令存在但缺少项目地图、验证指导、边界/非目标语言时，当 TODO/HACK 标记集中时，当大型源热点缺少所有权/边界和验证指导时，或者当持久文档包含原始的一次性审查报告、记分卡、过时的行引用或诊断转储而不是稳定不变量时，报告 WARN。将缺失的 docs/、specs/、.specify/、HANDOFF.md、CHANGELOG、问题模板和 PR 模板视为信息性，除非项目复杂度使其对交接必要。过时报告的操作是提取稳定规则到公共指令、规则、引用或验证器脚本中，然后删除或归档临时报告。

对话衍生的指导。 当健康审计读取最近的代理对话时，不要建议将对话或记分卡复制到文档中。建议进行候选矩阵传递：

字段	问题
重复失败	这在修复、发布、代理或用户报告中是否重复出现？
持久不变量	教训能否表述为稳定规则，而不是过时的事件摘要？
目标层	它应该存在于项目指令、Waza 技能、全局规则还是私有记忆中？
验证器	是否有确定性命令、脚本、工件检查或运行时冒烟可以强制执行它？
编辑风险	教训是否需要本地路径、问题编号、客户详细信息、机器状态、秘密或未发布的发布事实？

分层规则：项目特定命令、应用名称、工件名称和发布仪式保留在项目中；可重用工作流（如取消发布审查门或原生冻结证据阶梯）属于 Waza 技能；通用诚实和验证规则属于全局 CLAUDE/AGENTS；私有用户偏好和单机事实保留在记忆中。如果教训无法通过编辑风险字段，则将其排除在公共指导之外。

集中的修复链。 运行 git log --oneline --since='2 weeks ago' | grep -i fix 并按区域分组（: 或 ( 之前的前缀）。当同一区域在短时间内有 3 个以上修复提交时，表明缺少结构性不变量：每个修复都是对从未写下的规则的猜测。报告结构性 WARN，包含区域名称、修复计数，并建议向 AGENTS.md / CLAUDE.md / 项目规则添加明确规则，捕获这些修复趋向的不变量。触及同一文件 4 次以上的集中修复链是比分散在不同文件中的修复更强的信号。

热点所有权缺口。 在深度模式下，读取 HOTSPOT OWNERSHIP SURFACE。如果最大的源文件超过热点阈值，并且 AGENTS.md / CLAUDE.md / 共享指令文件没有命名谁拥有热点、应保持稳定的边界以及覆盖它的验证命令，则报告结构性 WARN。不要仅凭大小将文档化的大文件视为代码腐化；某些模块故意很大。

缺少稳定的验证器包装器。 如果仓库通过 CI、脚本或清单暴露多个验证命令，但 Makefile 没有 check、test 或 verify 目标，则报告结构性 WARN。这是 AI 可维护性缺口，因为代理需要一个稳定的默认入口点，而不是因为项目损坏。

从项目根目录快速检查，重用步骤 1 中解析的 $HEALTH_SCRIPT：

bash "$(dirname "$HEALTH_SCRIPT")/check-maintainability.sh" . summary

对于深度审计：

bash "$(dirname "$HEALTH_SCRIPT")/check-maintainability.sh" . deep

保持操作具体且非侵入性：添加或修复最小的有用指令表面，添加一个可执行的验证命令，文档化热点所有权和测试，仅当边界已经清晰时才拆分，或修复损坏的引用。不要仅从脚本输出提出大规模重写。

损坏的文档引用。 扫描 AGENTS.md、CLAUDE.md、.claude/rules/*.md 和每个 .claude/skills/*/SKILL.md，查找形如 @<path>、~/.claude/rules/<name>.md、~/.claude/skills/<name>/、docs/<name>.md 或 references/<name>.md 的引用。对于每个匹配，检查目标是否存在于磁盘上。报告每个 "引用但缺失" 的指针，包含源文件和行。

常见问题：

• 项目级规则引用从未创建的全局规则文件（例如 ~/.claude/rules/swift.md）。
• CLAUDE.md 使用 @AGENTS.md 占位符，但实际的 AGENTS.md 缺失或为空。
• 技能主体引用 references/<name>.md，但只有 references/<name>-v2.md 存在。
• 规则文件引用已删除的技能路径。

从项目根目录快速检查，重用步骤 1 中解析的 $HEALTH_SCRIPT：

bash "$(dirname "$HEALTH_SCRIPT")/check-doc-refs.sh" .

检查器从项目根目录解析 @... 和 docs/...，展开 ~，从每个 .claude/skills/<name>/SKILL.md 目录解析 references/...，检查行上的每个引用，跳过围栏代码示例，并在任何目标缺失时以非零退出。

将缺失的引用报告为结构性发现，而不是严重，除非缺失的文件被命名为硬依赖（例如项目的发布技能的 release.md）。

损坏的 Markdown 引用。 在深度模式下，check-maintainability.sh 还会扫描仓库 Markdown 链接。当它们指向缺失的本地文件时，报告为结构性发现，特别是代理可能在将来工作中遵循的设计、安全、发布或交接文档。

过时的验证器缓存输出。 如果验证输出指向已删除的临时工作树或不存在的 /tmp / /private/tmp 文件，使用以下命令解析捕获的日志：

bash "$(dirname "$HEALTH_SCRIPT")/check-verifier-output.sh" . <log-file>

仅将此脚本用于用户提供的或在当前审计期间生成的现有命令输出。不要运行项目测试只是为了提供此检查器。已知操作包括 golangci-lint cache clean、go clean -cache -testcache 和 npm cache verify；未知工具获得诊断重新运行操作。

[-] 增量 -- 锦上添花

过时项目、全局与本地放置、上下文卫生、过时的 allowedTools 条目。

---

如果没有问题：All relevant checks passed. Nothing to fix.

非目标

• 绝不未经确认自动应用修复。
• 绝不将复杂层级检查应用于简单项目。
• 绝不充当繁重的 lint、类型检查、重复或架构重写替代品；/health 仅报告可维护性护栏和具体下一步操作。

注意事项

发生了什么	规则
错过了本地覆盖	始终也读取 settings.local.json；它覆盖已提交的文件
子代理超时报告为 MCP 失败	MCP 失败来自实时探测，而不是数据收集
以错误语言报告问题	首先遵守 CLAUDE.md 通信规则
将故意嘈杂的 hook 标记为损坏	在调用 hook "损坏" 之前询问
Hook 似乎没有触发，但实际上触发了——后来的 UI 元素渲染在其上方	Hook 触发顺序不是视觉顺序。在重新编辑 hook 配置之前：(a) 使用 --debug 或通过管道输出确认，(b) 检查差异对话框、权限提示或其他 UI 元素是否渲染在顶部并将 hook 输出推离屏幕，(c) 然后才怀疑 hook 本身。
/health 在首次运行时消耗了太多配额	首先保持在摘要模式。完整的对话摘录和检查器子代理是深度审计工具，不是标准项目的默认路径。
将缺失的规范/文档视为失败	决策工件默认是可选的。仅当层级、活跃交接风险或用户请求使其必要时才升级缺失的文档/规范。
将被忽略的 AGENTS/CLAUDE 文件视为持久的项目真相	报告规则是否被跟踪和分发。本地覆盖可以告知审计，但持久修复属于公共仓库文档或已发布的技能/规则文件。
将审查记分卡视为可维护性文档	记分卡是快照。提取不变量和验证路径，然后删除或归档报告，而不是将记分卡本身称为持久规则。