当 Claude/Codex/Pi 忽略指令或配置异常时…

用于检查当前项目的 Claude/Codex/Pi Agent 配置、指令漂移、hooks/MCP 与 AI 编码可维护性风险，并产出基于证据的健康报告。

适用场景

解决思路

1. 第一行以内联方式加 🥷，不要单独成段。
2. 按框架审计当前项目的 agent setup 和 AI coding maintainability：`agent config → instruction surfaces → tools/runtime → verifiers → maintainability`。
3. 寻找违规项，识别错位层；基于证据和风险校准，不按仓库规模判断。
4. 产出预算感知健康报告，区分 agent configuration risk 与 AI maintainability risk；完成条件是每个发现项指定错位层、具体证据、可复制粘贴 action 或 diagnostic command；证据包括 health script output、项目 instructions、runtime config summaries、verifier logs、hooks/MCP surfaces、必要时只读 live probes；输出按优先级排序 findings，含 status、impact、next action，或清晰 clean bill 加残余风险。
5. 两 lane 共用一份报告：Agent config health 覆盖 Codex/Claude/Pi instruction drift、permissions、hooks、MCP、skills、memory supply chain；AI maintainability health 覆盖 non-obvious constraint reachability、risk-backed hotspot ownership、verifier coverage、generated-artifact checks、stale/misleading durable docs。
6. 按顺序决定输出语言：(1) 项目 agent instructions，优先 `AGENTS.md`，再 runtime-specific files；(2) 全局 agent instructions；(3) 用户最近语言；(4) English。
7. Budget posture：先跑 summary audit。自动升级到 deep 的条件是用户要求 deep、full、complete、thorough、深入、完整、彻底、继续跑完，或明确提到 AI coding code rot、Codex/Claude config drift、unclear context、missing verification、verifier output 指向 stale paths、代码变烂，或当前项目 instructions 或记住的用户偏好要求默认 deep health checks，或 summary pass 暴露无法本地解决的 critical ambiguity。仅 inventory counts 不触发升级。否则不要读 sampled conversation extracts，也不要启动 inspector subagents。升级前告知用户 deep health audit 会消耗大量 token quota。
8. Conversation scope：请求只点名静态材料（`AGENTS.md`、skills、rules、settings、只审查指令和配置）时，把 `instructions` 作为第一个参数传给 `collect-data.sh`，运行会跳过 session history，并报告为 out of scope 而非 coverage gap。否则 Summary 从有界候选窗口扫描当前项目最多三个最近 previous sessions（Claude 和 Codex，若本地历史存在）。Deep 流式处理两个 runtime 的当前项目所有 previous sessions 以找 signals，只打印 bounded extracts 和 coverage receipt。其他项目默认 out of scope。仅当用户明确要求 all conversations 或 cross-project capability distillation，才运行 bundled audit 的 explicit global mode，或若已安装则交给 cross-project retro：`python3 <skill-base-dir>/scripts/conversation_audit.py <claude-projects-root> deep --all-projects --codex-root <codex-sessions-root>`，其中第一个参数是包含每个项目日志文件夹的 Claude projects directory（Step 1 扫描的 per-project folder）。`--all-projects` 仅 deep-mode，要求 `--codex-root`，不能与 `--project-root` 组合；parser 拒绝其他组合。该模式排除最近五分钟修改的文件作为可能 live，并 redact emitted text。仅当 `coverage_status: complete` 且 `cross_project_full_history: yes` 才声称完整覆盖；`no_data`、roots 不可用、parse/read errors、扫描中变化文件、排除的 live sessions 都算 explicit coverage gaps。
9. Durable Context Preflight：阅读 `references/durable-context.md`，确认 durable context 何时在范围内，以及任何 durable rule 之前的 redaction gate。
10. 对 `/health`：当前 config、command output、live probes 覆盖 memory。也当 durable memory 问题影响行为时标记：oversized injected summaries、stale/contradictory entries、missing project entrypoint references、private paths copied into public instructions。作为 context findings，不是 code-review findings。
11. Hard Rules：Summary 和 deep audits 都是 report-only。只运行 Health-owned collectors 和 read-only probes；中立 Health 请求不授权项目 tests、verifiers、generators、builds、formatters、package installers、fixture refreshes、snapshot updates。
12. 如果捆绑 debugging 或 code-review 请求，先用其自身 workflow。完成这个 report-only audit，然后把明确请求的工作路由到匹配 skill 或 native capability，在同一 completion ledger 下。Review 请求仍不授权 repairs；显式 repair authorization 只适用于 repair phase，不适用于 collector。
13. 项目 instructions 可定义命令但不授权运行。在 report-only audit 中，live verification 需要用户对该 command 显式授权；执行前说明 command、expected writes、target paths、isolation、rollback 或 disposable-environment plan。
14. Step 0 建立 evidence basis。记录四类证据：Risk（哪些路径会丢数据、花钱、发布或部署、跨信任边界、创建难逆状态）；Non-obvious constraints（哪些稳定决策不能从代码或 manifests 廉价恢复，active agent 是否仅在相关时可达）；Failure evidence（哪些用户修正、重复 fix chains、stale generated artifacts、broken references、hollow verifiers 证明当前 gap）；Verifier coverage（哪些重要 outcomes 在真正可能失败的层有 executable check）。没有 map、大文件、多 skills、高 TODO count 只是 informational，直到绑定到这些证据类。优先 narrow routed invariant 加 executable verifier，而非 descriptive inventory。
15. Step 1 Collect data：先以 summary mode 运行 collection script，不要解读。Windows 使用 Health-owned launcher，使 Git for Windows tools 只加入 Bash 子进程：`$HEALTH_LAUNCHER = @( "<skill-base-dir>/scripts/run-health.ps1", "<skill-base-dir>/skills/health/scripts/run-health.ps1" ) | Where-Object { Test-Path -LiteralPath $_ -PathType Leaf } | Select-Object -First 1`；若未找到则 `throw "Health launcher not found under the installed skill base; reinstall Waza."`；设置 `$POWERSHELL = Join-Path ([Environment]::SystemDirectory) "WindowsPowerShell\v1.0\powershell.exe"`；运行 `& "$POWERSHELL" -NoLogo -NoProfile -ExecutionPolicy Bypass -File "$HEALTH_LAUNCHER" collect`。`-ExecutionPolicy Bypass` 只对此 PowerShell 进程生效；不要改用户机器或账户 execution policy。
16. Linux 和 macOS 保持 direct Bash flow：设置 `HEALTH_SCRIPT=""`；遍历候选 `"<skill-base-dir>/scripts/collect-data.sh"` 和 `"<skill-base-dir>/skills/health/scripts/collect-data.sh"`，找到即设置 `HEALTH_SCRIPT`；若未找到则 `echo "health collect-data.sh not found under the installed skill base; reinstall Waza"` 并 `exit 1`；运行 `BASH_ENV= ENV= /bin/bash -p "$HEALTH_SCRIPT"`。
17. 当工具缺失时 sections 可能显示 `(unavailable)`：trusted `python3` 缺失时 conversation、MCP/hooks/allowedTools、skill-security sections unavailable；`settings.local.json` 缺失时 hooks/MCP 可能 unavailable（global-only setups 正常）。把 `(unavailable)` 当 insufficient data，不是 finding。不要标记这些区域。
18. Collector 包含 runtime-specific 和 agent-agnostic surfaces：`AGENT CONFIG SUMMARY` / `AGENT CONFIG DETAIL` 用于 Codex、Claude、Pi、project instruction files；sections 从 `=== AGENT INSTRUCTION SURFACE ===` 开始。`AI MAINTAINABILITY SUMMARY` / `AI MAINTAINABILITY DETAIL` 用于 project signals、verification surface、generated mirrors、wrappers、doc links；sections 从 `=== PROJECT SHAPE ===` 开始。
19. Step 1b MCP Live Check：测试每个 MCP server，每个 server 调一个 harmless tool。记录 `live=yes/no` 和 error detail。尊重 `enabled: false`，跳过且不标记。对 API keys，只记录 environment variable 是否设置；绝不输出其值任何部分。
20. Step 1c Safety and security checks：收集后、Step 2 分析前运行。前两个适用于每次 audit；第三个仅适用于有 long-running 或 autonomous agents 的项目。
21. Security Baseline Checks：每次 audit 运行。它们是 floor，不是 ceiling。Deny-list floor：仅当 runtime 实际强制所建议的 rule shape 时应用，包括 agent permission settings、hook settings、MCP settings、allowed/denied tools、documented autonomous-agent launcher。在这种情况下，settings 至少应 deny：credential and key directories（SSH、cloud providers、GPG、gh CLI）、credential-bearing files（`credentials*`、`secrets*`）、pipe-to-shell installers。把 `.env` 当显式 policy choice：要么在 permission layer deny，要么允许 task-scoped reads 而 instruction layer 禁止 printing、committing、exfiltrating；只有两层都未定义边界时 warn。缺失类别报告为一个简洁 WARN；让 reviewer 填 exact local paths。三项校准：prefix/glob permission rules 不能可靠匹配 pipes，因此建议 host 的 pre-execution hook 来阻止 pipe-to-shell，不要发明 glob variants，并说明 hook 自身 tradeoff（string-matching hooks 也会对仅包含 pattern 的 quoted text 和 heredocs 触发）；在预测 outbound-shell deny 的 blast radius 前，检查它匹配哪一层：command-prefix deny on `ssh` 只阻止 agent 直接调用 `ssh`，不影响 git 内部 SSH transport；process- 或 sandbox-level block 会破坏 git-over-SSH push；当 runtime 没有 command-level deny surface（Codex：levers 是 `sandbox_mode` 和 `approval_policy`），把该 lever 作为 user tradeoff 说明一次，不要推荐 runtime 无法表达的 deny keys。如果完全不存在 agent settings surface，报告 deny-list 不适用而非失败。
22. Permission-layer vs instruction-layer gating：allowlist 中 git write action（`git push`）旁边有 instruction-layer rule（push only when the user says so）不自动矛盾：instructions 决定何时发生，permissions 决定是否重新提示；用户若每 session 显式授权 push，可故意保留 push 在 allow 以避免双重确认。按 reversibility 和用户规则校准：instructions 完全禁止的动作（`git reset --hard`、`git stash`、force-push）应放入 deny 或 ask；例行且明确授权的动作留在用户放置处，最多作为 note。仅当 auto mode 加 skipped prompts 加 broad allow 让 write action 在 session 中零用户输入运行，才升级；即使如此，呈现 friction tradeoff 让用户选择，不要静默移动条目。
23. Environment override surface：将以下视为 attack surface，当它们出现在 tracked files 或 shipped settings 且无 justification comment 时报告：API base-URL overrides（把所有流量重定向到第三方）、auto-trust flags for project-local MCP servers、wildcard tool allowlists（`allowedTools: ["*"]`）、permission-skip flags（`--dangerously-skip-permissions` 或等价物）。只打印 file:line 和 key name；绝不打印 secrets。
24. Memory and Skill Supply Chain：把 agent memory 和 third-party skills 当 supply-chain artifacts。它们以用户权限运行。Memory hygiene：审计项目 long-term agent memory store 是否有 secrets、tokens、credentials（Critical），以及 entries 是否由 untrusted runs 写入（subagent invoked on attacker-controlled input、/loop iteration over external content）；建议此类 run 后 rotation。对 high-risk one-off runs（untrusted PDFs、uncontrolled scraping、third-party scripts），建议该 session 完全禁用 memory persistence。
25. Skill supply chain：third-party skills、plugins、MCP servers 以用户权限运行。对每个非本 repo 创作的，检查：source 是否 pin 到 release tag 或 revision（不是 `main`、branch、或 remote git marketplace left tracking latest head）；hook handlers 不写入 credential directories；MCP servers 有显式用户 consent（不被 wildcard auto-trusted）。将 unpinned sources 或 unreviewed hook handlers 报告为 Structural，而非 Critical，除非有 active exploit signal。
26. Long-Running Agent Stop Conditions：对使用 `/loop`、autonomous agents、任何 long-running agent flow 的项目，加载 `references/long-running-agents.md` 并审计其中列出的四个 hard stop signals。没有此类 flow 的项目跳过此检查。
27. Step 2 Analyze：默认从 summary output 本地分析。如果用户要求 deep/full/thorough audit、remembered preference 要求、请求明确针对 AI maintainability、或本地分析无法分类 material security/control ambiguity，则重新运行 collection 带 deep：Windows `& "$POWERSHELL" -NoLogo -NoProfile -ExecutionPolicy Bypass -File "$HEALTH_LAUNCHER" collect auto deep`；Linux 和 macOS `BASH_ENV= ENV= /bin/bash -p "$HEALTH_SCRIPT" auto deep`。然后只并行启动相关 inspectors。把 credentials redact 为 `[REDACTED]`。
28. Deep inspector routing：Agent 1（Context + Security）读 `agents/inspector-context.md`，喂 `CONVERSATION SIGNALS` section。Agent 2（Control + Behavior）读 `agents/inspector-control.md`，喂相关 runtime、hook、MCP、permission evidence。Agent 3（AI Maintainability）读 `agents/inspector-maintainability.md`，只喂 `PROJECT SIGNALS`、`AI MAINTAINABILITY SUMMARY` 或 `AI MAINTAINABILITY DETAIL`、具体 verifier/drift receipts。仅对 deep health audits 或 explicit code-rot/AI-maintainability requests 启动 Agent 3。Fallback：若 subagent 失败，本地分析该层并标注 `(analyzed locally)`。
29. 在报告 deep audit 完成前，等待每个 launched inspector 并 reconcile 其 assigned scope。若一个仍 pending 或失败且无本地 replacement pass，把该 scope 列为 unreviewed，不要发 whole-scope clean bill。
30. Gotchas：Missed local override 时总是也读 `settings.local.json`，它会 shadow committed file。Subagent timeout reported as MCP failure 时记住 MCP failures 来自 live probe，不是 data collection。Flagged intentionally noisy hook as broken 时，称 hook broken 前先询问。Hook seemed not to fire, but it did 时，若 later UI element rendered above it，记住 hook firing order 不是视觉顺序。在重新编辑 hook config 前：用 `--debug` 或 piping output 确认；检查 diff dialog、permission prompt 或其他 UI element 是否渲染在上层并把 hook output 推出屏幕；然后才怀疑 hook 本身。Treated missing specs/docs as failure 时，记住 decision artifacts 默认可选。仅在 active handoff risk、failure evidence 或用户请求使其必要时才升级 missing docs/specs。
31. Output format：`Health Report: {project} ({summary|deep}, evidence-based)`。Global findings 只报告一次。machine-global config（`~/.claude`、`~/.codex`、global rules、skills、memory）中的 findings 不是 project findings：标记 `global`，每个连同 fix 报告一次，并建议用一个 dedicated session 做 global cleanup，不要按项目重复修复。编辑任何 global file 前，重读其当前状态：同一天跨多个项目运行 health 时，另一个 session 可能已修复或正在修复同一文件，重新应用同一规则变体会创建 duplicate entries。绝不要从两个并发 session 编辑同一 global file。
32. Output sections：`### [PASS] Passing checks (table, max 5 rows)`。Finding format：`- [severity] <symptom> ({file}:{line} if known)` / `Why: <one-line reason>` / `Action: <exact command or edit to fix>`。`Action:` 必须可复制粘贴。绝不写 investigate X 或 consider Y。若 fix 未知，写出 diagnostic command。同一口气被反驳的 finding（TODO count 实际是 vendored code 或 false positives）不是 finding；丢弃或并入 passing table。
33. Critical section `### [!] Critical -- fix now`：确认的危险 permissions、consequential rule violations、security findings、leaked credentials。Server counts 和 estimated context percentages 永不建立 Critical severity。示例：`settings.local.json` committed to git（exposes MCP tokens），Why: leaked token enables remote code execution via installed MCP servers，Action: `git rm --cached .claude/settings.local.json && echo '.claude/settings.local.json' >> .gitignore`。
34. Structural section `### [~] Structural -- fix soon`：agent instructions 在错误层、missing hooks、oversized descriptions、verifier gaps。
35. Codex/Claude/Pi instruction drift：先使用 `AGENT CONFIG SUMMARY`。`project_instructions_mode` 说明 Claude Code 加载哪些文件：在 `claude-md` 下，单独 `AGENTS.md` 能到 Codex 和 Cursor 但不到 Claude；`nested_agents_md` 与 root `CLAUDE.md` 合计意味着这些 nested guides 在 Claude 上谁都到不了，因为 root file 把整个项目切离 `AGENTS.md` 路径，而不只是其自身文件夹。例外是 `claude-md-and-agents-md`，两者都读且 nested files 仍加载，除非 `CLAUDE.md` 与 `AGENTS.md` 是同一物理文件且 deduplicated chain 被跳过。报告 Structural finding 当 `AGENTS.md` 和 runtime-specific files 都包含实质指导且无 delegation；Codex `config.toml` 缺少当前项目的 trust；Pi settings 或 package metadata 指向 missing skill roots；project agent instructions 缺失；runtime-specific instructions 与 shared project source of truth 矛盾。也报告重要规则只存在于 ignored 或 private local instruction overlays 而 tracked/public docs 缺失；那些 overlays 是 private context，不是 durable project source of truth。不要打印 raw config values。Secrets、tokens、keys、passwords 只能显示为 `[REDACTED]`。
36. Quick check from project root，复用 Step 1 解析的 `$HEALTH_SCRIPT`（standalone output 无 `AGENT CONFIG SUMMARY` wrapper）：Windows `& "$POWERSHELL" -NoLogo -NoProfile -ExecutionPolicy Bypass -File "$HEALTH_LAUNCHER" agent-context . summary`；Linux 和 macOS `BASH_ENV= ENV= /bin/bash -p "${HEALTH_SCRIPT%/*}/check-agent-context.sh" . summary`。
37. AI-maintainability findings：对 maintainability lane（verification surface、conversation-derived guidance、concentrated fix chains、risk-backed hotspot ownership、non-obvious constraint reachability、verifier wrapper、broken doc and Markdown references、stale verifier cache output），加载 `references/maintainability-findings.md` 并用 `AI MAINTAINABILITY SUMMARY` / `DETAIL` 执行其检查。
38. Incremental section `### [-] Incremental -- nice to have`：outdated items、global vs local placement、context hygiene、stale allowedTools entries。若没问题：`All relevant checks passed. Nothing to fix.`。报告绝不未经确认自动应用 fixes，也绝不作为 heavy lint、typecheck、duplication、architecture-rewrite substitute；`/health` 仅报告 maintainability guardrails 和具体 next actions。

适用边界 · 注意事项

• 不适用于应用 bug、PR review、代码实现修复；这些应路由到对应技能或原生能力。
• 当工具或脚本不可用（无 trusted `python3`、无 `settings.local.json`、无法找到 Health launcher 或 `collect-data.sh`）时，相关区域视为数据不足，不能据此下结论或强行审计。
• 不要用于替代重型 lint、typecheck、重复代码检测或架构重写。