【免费下载链接】Waza Engineering habits you already know, turned into skills Claude can run.项目地址https://gitcode.com/gh_mirrors/cl/Waza点击查看免费下载本篇技术指南聚焦 Waza 项目中health技能所承载的AI MaintainabilityAI 可维护性检查通道即 maintainability-findings.md 所定义的结构性发现Structural Findings判定框架。文章将完整讲解其 FAIL / WARN 判定标准、对话衍生指导的候选矩阵、集中式修复链分析、热点归属与约束可达性、验证器包装检查、文档引用与过期验证器缓存的处理并结合仓库源码check_maintainability.py、check_doc_refs.py、check_verifier_output.py与测试用例给出可复制运行的命令与实现级原理。读完你将能在自己的项目中执行可维护性健康审计识别空壳验证器、漂移的生成镜像、断裂的文档引用等真实风险并输出可粘贴的修复动作。一、AI 可维护性通道定位、输入与输出在 Waza/health的报告中审计被划分为两条通道laneAgent 配置健康agent config healthCodex / Claude / Pi 的指令漂移、权限、hooks、MCP、技能与记忆供应链AI 可维护性健康AI maintainability health非显式约束的可达性、风险支撑的热点归属、验证器覆盖率、生成产物检查、过期或误导性的持久化文档。本文讨论的 maintainability-findings.md 专门服务于第二条通道由收集脚本Step 1产出的AI MAINTAINABILITY SUMMARY/AI MAINTAINABILITY DETAIL提供数据。其读取约定如下summary 模式读取AI MAINTAINABILITY SUMMARY深度审计或明确的代码腐化code-rot请求读取AI MAINTAINABILITY DETAIL而Agent 指令通道instruction drift的判定留在 SKILL.md 中不在本文档范围内。文档中提到的$HEALTH_SCRIPT与$HEALTH_LAUNCHER是 Step 1 已经解析出的两个变量前者指向 Bash 收集脚本collect-data.sh后者指向 PowerShell 启动器run-health.ps1启动器的动作集合为collect、agent-context、maintainability、doc-refs、verifier-output。收集器输出节与独立运行形态在 Windows 上通过 Health 启动器运行时输出被包装在AI MAINTAINABILITY SUMMARY/AI MAINTAINABILITY DETAIL之下而直接独立运行检查脚本时没有该包装输出以 PROJECT SHAPE 开头。从源码看check_maintainability.py输出节依次为输出节内容 PROJECT SHAPE 总体状态maintainability_status、模式、跟踪文件数、生成镜像折叠/漂移/比较缺口、扩展名分布、最大源码文件与目录 AI CONTEXT SURFACE context_statusPASS / UNKNOWN / NOT_APPLICABLE、指令文件清单、验证指导与边界指导是否存在 VERIFICATION SURFACE verification_status、检测到的清单Makefile、package.json、Cargo.toml 等、命令清单、verifier_evidence、hollow_verifiers、缺失引用的命令 VERIFICATION WRAPPER SURFACE wrapper_status、是否含 Makefile、稳定 make 目标check/test/verify DECISION ARTIFACTS docs / specs / handoff / changelog / issue 模板 / PR 模板是否存在 DRIFT MARKERS TODO 标记统计、broken_doc_references、漂移发现 MARKDOWN LINK SURFACE markdown_link_status仅 deep 模式扫描二、判定规则什么时候报 FAIL、WARN该文档给出了严格的严重度判定标准核心原则是收集器状态是证据不是结论捷径collector status is evidence, not a verdict shortcut这一原则在 inspector-maintainability.md 中被进一步细化。报 FAIL 的条件当实现、CI、生成、发布、部署或其他实质性风险表明应当存在可执行的验证但verifier_evidence为空时报 FAIL或者当必需文档引用指向已失效文件时报 FAIL。关键界定commands只是发现清单discovery inventory不是证明。hollow_verifiers下列出的目标或脚本如果只打印输出、执行 shell 环境搭建或直接退出不满足覆盖率要求。从源码看check_maintainability.pyHOLLOW_COMMAND_RE会把echo、printf、true、false、exit、set、cd、export、mkdir/touch/chmod以及纯变量赋值等识别为空壳命令SETUP_ONLY_COMMAND_RE会把apt-get install、pip install、npm install、curl/wget、--version等识别为仅环境搭建命令。一条命令如果只有这些片段就不能算作真正的验证证据。对应到 Python 实现command_has_verifier_evidencemake target只有在目标名含test|check|lint|type|build|package|verify|smoke命名VERIFIER_NAME_RE或作为可信入口被递归解析时才有效且会递归检查其依赖与配方是否实质非空壳npm run script同理只有脚本名匹配验证器命名模式或pack --dry-run这类内建验证才被认可形如./scripts/check.sh的脚本调用要求脚本文件名含验证器命名且脚本正文经shell_script_has_verifier_evidence判定存在有意义的非空壳行为。也就是说一个只打印 success 的命名目标不提供验证。报 WARN 的条件以下情形报 WARN从文档原文归纳已验证的生成镜像漂移generated-mirror drift镜像与源文件内容不一致被引用的命令不存在指令文档里引用的 make 目标 / npm 脚本在清单中不存在稳定但非显式的约束相关任务无法触达关键约束存在但 agent 在相关任务中读不到反复失败却缺少持久不变量与验证器同一类失败反复发生却没有沉淀成规则和可执行检查空壳包装器漏掉了真正的失败层包装器只打印成功不覆盖实际会出问题的层面持久化规则只存在于被忽略/私有的 overlay 中重要规则只在.gitignore之外或私有的本地指令覆盖层里而跟踪/公开文档缺失持久化文档保留了原始一次性报告如 scorecard、带日期的行号引用、诊断转储而非稳定的不变量路径作用域加载运行时支持路径级加载但无关会话反复为大量领域性指导付费而这些指导其实可以安全地路由到路径级规则、嵌套指令文件或技能中——此时应将其迁移到路径作用域而不是删除其行为价值。关于 context_status 的解读纪律context_status: UNKNOWN存在实现或 CI 风险但缺少被跟踪的上下文证据应先核查实际风险再决定是否需要路由化不变量。既不能借此开出清白证明clean bill也不能因为缺少项目地图就强行要求补图。context_status: NOT_APPLICABLE收集器没有观察到实现/CI 上下文需求。同样不能据此虚构清白证明或地图要求。从源码看check_maintainability.pycontext_status在有实质指令证据时为 PASS否则若context_expected存在实现文件、workflow 或非 Makefile 清单则为 UNKNOWN反之为 NOT_APPLICABLE总状态在任一 FAIL 或 doc-ref 失败时取 FAIL有 UNKNOWN 或任一 WARN 时取 WARN否则 PASS。过期报告的处理动作对于过期报告stale reports文档给出的动作是把稳定规则抽取进公开指令、规则、引用或验证器脚本中然后删除或归档这份临时报告。这一点与测试 test_maintainability.sh 中仓库形状文件大小、目录结构绝不能成为可维护性发现的约束一脉相承。三、对话衍生指导候选矩阵Candidate Matrix当健康审计读取近期 Agent 会话时不要建议把会话原文或 scorecard 复制进文档而应执行一轮候选矩阵筛选。文档给出了完整的六字段矩阵字段要回答的问题Independent recurrence独立复现克隆的提示词、重试、自动化扇出会话、粘贴的助手输出、平台续接消息是否折叠为同一个底层事件Repeated failure重复失败该问题是否跨越修复、发布、Agent 或用户报告反复出现Durable invariant持久不变量教训能否表述为稳定规则而不是带日期的 incident 摘要Target layer目标层它应该进入项目指令、Waza 技能、全局规则还是私有记忆Verifier验证器是否存在确定性的命令、脚本、产物检查或运行时冒烟测试可以强制执行它Redaction risk脱敏风险教训是否包含本地路径、issue 编号、客户信息、机器状态、密钥或未发布的发布事实分层规则Layering Rule项目专属内容项目专属命令、应用名、产物名、发布仪式留在项目内可复用工作流如取消发布审查门禁、原生冻结证据阶梯属于 Waza 技能普适的诚实与验证规则属于全局 CLAUDE / AGENTS 文件私有用户偏好与单机事实留在记忆memory中。如果教训无法通过脱敏风险字段就不得进入公开指导。按加载面Load Surface划定作用域仅仅分层还不够还要考虑每条规则在每次会话中都要付出上下文代价除非它被绑定到其生效的位置语言与框架规则携带文件类型的paths作用域项目领域规则绑定到源目录pathsfrontmatter 或嵌套目录的CLAUDE.md只有真正横切的约束才无条件加载进 always-loaded 根文件。一条只在某个路径下才有意义的规则不应该放在 always-loaded 文件中。这正是 durable-context.md 中红色action 门禁思想的延续任何教训在变成持久规则前都要先过脱敏门。四、集中式修复链分析Concentrated Fix Chains文档给出可直接运行的诊断命令用于发现反复修复同一处的集中式修复链git -c core.fsmonitorfalse log --oneline --since2 weeks ago | grep -i fix然后按区域分组冒号:或左括号(之前的前缀。这里必须注意文档反复强调的判定纪律重复只是线索lead不是发现finding。必须读取足够证据确认多个修复收敛于同一个不变量或失败层而不是一群共享前缀的无关工作。只有完成这一验证后才报结构性 WARN且要指名反复出现的失败并推荐最窄的路由规则 可执行的验证器——也就是能防止该问题的那条规则与那个检查。core.fsmonitorfalse的写法同样出现在 iter_files 的git ls-files调用中用于规避文件系统监视器干扰快照。五、非显式约束可达性与风险支撑的热点归属这是最容易误用的部分文档明确给出了边界文件大小和模块形状不构成文档要求File size and module shape do not create documentation requirements。当真实失败或高后果路径集中在某区域并且暴露了一个无法低成本从代码中恢复的稳定边界时才需要验证相关任务能否触达一条简洁的归属规则以及锁定它的可执行检查。此时报告不可达的约束或缺失的验证器而不是报告一个笼统的 hotspot map 缺失。源码实现与测试双重印证了这一点context_findings只在context_expected且无实质指令证据时生成check_maintainability.py不会因文件大而报警测试 test_maintainability.sh 的 Case 4/5/6 明确验证1300 行或 900 行的大文件只要存在验证器make test即使完全没有 hotspot 归属文档deep 模式仍输出maintainability_status: PASS并断言输出中不得出现hotspot_ownership字样——大文件必须保持为库存信息inventory不能成为发现测试还验证node_modules、dist、build等排除目录中的超大文件绝不进入 summary/deep 输出Case 3这对应源码中的EXCLUDED_DIRS与MINIFIED_REcheck_maintainability.py。六、缺失稳定验证器入口Missing Stable Verifier Entrypointwrapper_findings只是发现线索。文档要求检查文档化的默认入口及其可执行覆盖覆盖范围包括 package scripts、原生构建工具、任务运行器、脚本与 CI——Makefile 不是必需的。只有当检查碎片化导致必需验证被遗漏、且没有可用默认入口覆盖它时才报结构性 WARN。一个只打印成功信息的命名目标不构成验证。从源码看wrapper_warnings的触发条件非常克制check_maintainability.py命令数 ≥ 2、存在 Makefile、但既没有稳定的 makecheck/test/verify目标也没有稳定的npm run check|test|verify且被证实有验证证据。测试 Case 7test_maintainability.sh展示了典型场景验证命令是./scripts/check.sh --no-format有实质验证证据verification_status: PASS但 Makefile 只有build目标且无check/test/verify默认入口于是wrapper_status: WARN提示检查文档化或原生的入口点后再推荐包装器。同时源码会检测各语言的原生验证表面verification_surface存在Cargo.toml则加cargo test/cargo check存在go.mod则加go test ./...存在Package.swift则加swift test配置了 pytest 且存在测试文件则加pytestpom.xml对应mvn testdeno.json/deno.jsonc对应deno test。测试 test_health_maintainability_regressions.py 验证了Package.swiftTests/目录下swift test会同时进入 commands 与 evidence。七、快速检查命令summary / deep 的跨平台用法文档提供了一系列可直接复制运行的命令均复用 Step 1 已解析的$HEALTH_SCRIPT与$HEALTH_LAUNCHER。单独运行脚本时输出不带AI MAINTAINABILITY SUMMARY包装首行即 PROJECT SHAPE 。可维护性检查summary 模式WindowsPowerShell $POWERSHELL -NoLogo -NoProfile -ExecutionPolicy Bypass -File $HEALTH_LAUNCHER maintainability . summaryLinux / macOSBashBASH_ENV ENV /bin/bash -p ${HEALTH_SCRIPT%/*}/check-maintainability.sh . summary深度审计deep 模式Windows $POWERSHELL -NoLogo -NoProfile -ExecutionPolicy Bypass -File $HEALTH_LAUNCHER maintainability . deepLinux / macOSBASH_ENV ENV /bin/bash -p ${HEALTH_SCRIPT%/*}/check-maintainability.sh . deep两处命令都体现了健康审计的只读铁律Hard Rules收集与检查不得运行项目测试、验证器、生成器或构建deep 模式与 summary 模式的差异只在于输出细节与 Markdown 链接扫描而不授权任何写入操作。BASH_ENV ENV与-p旗标用于屏蔽外部环境注入check-maintainability.sh 还会在启动时unset WAZA_PYTHON DOC_REF_CHECKER GIT_INSTALL_ROOT BASH_ENV ENV并对PATH做净化剔除目标仓库目录内的条目再挑选一个不在目标仓库内的 Python 3.9 解释器执行 Python 主体。动作纪律文档要求动作具体且非侵入concrete and non-invasive添加或修复最小的有用路由指令面、在真实失败层加一条可执行验证命令、修复生成镜像检查或修复损坏的引用。只有当边界已经清晰时才拆分。不要仅凭脚本输出就提出大规模重写。八、损坏的文档引用Broken Doc References扫描目标与引用形态文档规定扫描以下文件中的引用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.mdCLAUDE.md使用AGENTS.md占位符但实际AGENTS.md缺失或为空技能正文引用references/name.md但磁盘上只有references/name-v2.md规则文件引用了已删除的技能路径。检查命令Windows $POWERSHELL -NoLogo -NoProfile -ExecutionPolicy Bypass -File $HEALTH_LAUNCHER doc-refs .Linux / macOSBASH_ENV ENV /bin/bash -p ${HEALTH_SCRIPT%/*}/check-doc-refs.sh .检查器行为源码级check_doc_refs.py 实现了文档描述的全部行为值得逐条对照解析规则REF_REL21-L27匹配...、~/\.claude/...、docs/...、references/...四种形态解析基准resolve_refL99-L122...与docs/...从项目根解析~展开references/...若源文件位于.claude/skills/name/SKILL.md则从该技能目录解析否则从项目根解析——这解释了为何技能正文里的references/foo.md不能当作项目根的路径跳过围栏代码逐行维护 与 ~~~ 围栏状态围栏内的引用不检查退出码任何目标缺失时非零退出check_maintainability.py据此把broken_doc_references置为failL1046-L1047。严重度缺失引用一律报结构性Structural发现而非 Critical除非缺失文件被点名作为硬依赖例如发布技能所依赖的release.md。九、损坏的 Markdown 引用Broken Markdown References在deep 模式下check-maintainability.sh还会扫描仓库内 Markdown 链接。指向缺失本地文件的链接报结构性发现尤其是设计、安全、发布或交接文档——因为 agent 在未来工作中很可能跟随这些链接。从实现看scan_markdown_links有三类豁免非常值得注意围栏内的链接跳过代码块中的Template不算测试 test_health_maintainability_regressions.py 直接验证行内代码中的链接跳过Overview在反引号内不检查站点根路由/开头跳过以/开头的是站点路由而非本地文件引用把它当作审计主机上的路径会产生误报测试 Case 10 验证中文博客为 PASSRustdoc 生成链接跳过struct.Terminal.html这类 Rustdoc 在生成的 crate 文档中才解析的链接若源文件位于含Cargo.toml的目录树下则豁免测试 L97-L110 验证guide.html会报缺失而terminal/struct.Terminal.html不会。十、过期的验证器缓存输出Stale Verifier Cache Output当验证输出指向已删除的临时工作树或已不存在的/tmp//private/tmp文件时用以下命令解析捕获的日志Windows $POWERSHELL -NoLogo -NoProfile -ExecutionPolicy Bypass -File $HEALTH_LAUNCHER verifier-output . log-fileLinux / macOSBASH_ENV ENV /bin/bash -p ${HEALTH_SCRIPT%/*}/check-verifier-output.sh . log-file使用边界只用于用户提供的既有命令输出、或本次审计期间生成的输出不要为了喂给该脚本而专门去运行项目测试。从实现看check_verifier_output.py通过TOKEN_RE提取日志中的路径 token过滤掉含/.git/的条目再用TMP_RE(^|/)(private/)?tmp/筛出临时目录路径对不存在的路径stale_paths报verifier_output_status: WARN根据日志内容给出已知的缓存清理动作含golangci-lint/errcheck→golangci-lint cache clean匹配go test|vet|build或go-build→go clean -cache -testcache含npm/node_modules→npm cache verify未知工具 → 在移除过期临时工作树后重新运行验证器的诊断性重跑动作。这些动作正是过期验证器缓存问题的典型解法验证器golangci-lint 缓存、go 构建缓存、npm 缓存等指向了已被删除的临时工作树。十一、把发现写进报告Inspector 的产出约定当审计升级到 deep 模式时会启动第三个检查代理Agent 3AI Maintainability它只接收PROJECT SIGNALS、AI MAINTAINABILITY SUMMARY/AI MAINTAINABILITY DETAIL与具体的验证器/漂移回执产出格式如下inspector-maintainability.mdAI Maintainability: PASS|WARN|FAIL Findings: - [FAIL|WARN|INFO] short title: evidence from script output. Action: one concrete next step. Residual risk: - one short caveat, or None visible from collected data.其严重度映射与本文档完全一致FAIL应有验证但verifier_evidence为空 / 必需引用指向死文件、WARN漂移、缺失命令、过期/冲突的持久指导、仅私有 overlay 的重要规则、无可达不变量的反复失败、不覆盖真实失败层的包装器、INFO文件数、贡献者数、技能数、TODO 数、最大文件等库存信息除非关联到已证明的风险或失败证据、PASS表面存在且无可操作的维护性缺口。同时它明确要求不要仅凭UNKNOWN就报警——UNKNOWN 只意味着存在风险但未观察到指令表面需要先核查是否有非显式约束确实需要规则仅凭命令名也不满足验证覆盖率必须看verifier_evidence与hollow_verifiers。十二、报告呈现要求文档规定缺失引用按结构性问题上报且健康报告要求每个发现都包含可复制粘贴的Action:绝不写请调查 X或考虑 Y若修复未知则给出诊断命令。这一要求贯穿 SKILL.md 的 Finding 格式[severity] symptom ({file}:{line})Why:一行理由 Action:确切命令或编辑。被同一口气反驳掉的发现例如 TODO 计数其实是 vendored 代码不算发现应删除或并入通过表。测试 test_health_maintainability_regressions.py 还验证了报告输出的脱敏纪律redact_command_label会把PROVIDER_API_KEY、DATABASE_PASSWORD、CLOUD_SECRET_ACCESS_KEY、SSH_PRIVATE_KEY、--token等替换为[REDACTED]同时保留token_count42 api_key_statusmissing这类状态字段并保护notsecret、secretary等非密钥词——健康报告可以安全地在会话中呈现 CI 命令清单而不泄露密钥与主机路径。十三、落地建议把这份检查用起来从 summary 开始在任意项目根执行第七节的 summary 命令先看maintainability_status与各分节状态不要急于下结论对 UNKNOWN 先核查context_status: UNKNOWN不是报警理由先确认实现/CI 风险是否真的需要一条路由化不变量对 FAIL 补验证verification_status: FAIL意味着有实现风险但无实质验证证据——在真实失败层不是 Makefile 包装层补一条可执行验证命令对 WARN 逐个处置镜像漂移则修复镜像生成检查引用缺失则修doc-refswrapper_status: WARN则确认文档化默认入口deep 前先告知用户deep 审计会消耗较多 tokenSKILL.md仅在用户要求或存在明确代码腐化信号时升级只读边界整个审计是报告式的任何修复都发生在明确的 repair 阶段收集阶段绝不运行项目测试或修改文件。本仓库自身就是这套框架的活样例plugins/waza/下的技能与规则目录正是skills/、rules/的生成镜像collapse_generated_mirrors 会把plugins/name/skills|rules下字节级相同的文件折叠进源文件计数并单独列出漂移项——你可以对 Waza 仓库本身运行maintainability检查观察镜像折叠与漂移报告如何工作。小结AI 可维护性检查不是文件多大、TODO 多少、地图有没有的库存盘点而是四条证据轴风险、非显式约束、失败证据、验证器覆盖上的结构性审计。它的每一次 FAIL 与 WARN 都必须锚定在可执行的证据上verifier_evidence是否为空、命令是否真实可执行而非空壳、引用是否指向存在的文件、约束是否在正确的加载面可达。配合 check_maintainability.py、check_doc_refs.py 与 check_verifier_output.py 的实现这套方法论可以在任何语言、任何规模的项目上复制最小的路由规则面 真实失败层上的可执行验证器 干净的持久化文档正是防止 AI 编码腐化的三道防线。赞分享【免费下载链接】Waza Engineering habits you already know, turned into skills Claude can run.项目地址https://gitcode.com/gh_mirrors/cl/Waza点击查看免费下载相关推荐Waza /health AI 可维护性审计指南结构性发现的判定、分层归属与可执行验证Waza /health AI 可维护性审计指南结构性发现的判定、分层归属与可执行验证 本指南聚焦 Waza health 技能中的 AI 可维护性AI mApollo Client 开发模式错误消息机制全解析dev 子路径 API 深入指南Apollo Client 开发模式错误消息机制全解析dev 子路径 API 深入指南 本篇技术指南聚焦 Apollo Client 为开发调试场景专门提供的learn-harness-engineeringElectron 架构规则的 Harness 落地——从约束文档到可执行的端到端验证learn harness engineeringElectron 架构规则的 Harness 落地——从约束文档到可执行的端到端验证 本教程对应 第 10上一篇终极UMD指南如何在Angular项目中实现跨环境模块兼容下一篇5分钟搞定Intel RealSense深度相机在MATLAB中的极速部署创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/9 1:50:08 · 阅读 1.2k Waza `/health` AI 可维护性检查完全指南：从结构发现到可执行验证的落地实践
【免费下载链接】Waza Engineering habits you already know, turned into skills Claude can run.项目地址https://gitcode.com/gh_mirrors/cl/Waza点击查看免费下载本篇技术指南聚焦 Waza 项目中health技能所承载的AI MaintainabilityAI 可维护性检查通道即 maintainability-findings.md 所定义的结构性发现Structural Findings判定框架。文章将完整讲解其 FAIL / WARN 判定标准、对话衍生指导的候选矩阵、集中式修复链分析、热点归属与约束可达性、验证器包装检查、文档引用与过期验证器缓存的处理并结合仓库源码check_maintainability.py、check_doc_refs.py、check_verifier_output.py与测试用例给出可复制运行的命令与实现级原理。读完你将能在自己的项目中执行可维护性健康审计识别空壳验证器、漂移的生成镜像、断裂的文档引用等真实风险并输出可粘贴的修复动作。一、AI 可维护性通道定位、输入与输出在 Waza/health的报告中审计被划分为两条通道laneAgent 配置健康agent config healthCodex / Claude / Pi 的指令漂移、权限、hooks、MCP、技能与记忆供应链AI 可维护性健康AI maintainability health非显式约束的可达性、风险支撑的热点归属、验证器覆盖率、生成产物检查、过期或误导性的持久化文档。本文讨论的 maintainability-findings.md 专门服务于第二条通道由收集脚本Step 1产出的AI MAINTAINABILITY SUMMARY/AI MAINTAINABILITY DETAIL提供数据。其读取约定如下summary 模式读取AI MAINTAINABILITY SUMMARY深度审计或明确的代码腐化code-rot请求读取AI MAINTAINABILITY DETAIL而Agent 指令通道instruction drift的判定留在 SKILL.md 中不在本文档范围内。文档中提到的$HEALTH_SCRIPT与$HEALTH_LAUNCHER是 Step 1 已经解析出的两个变量前者指向 Bash 收集脚本collect-data.sh后者指向 PowerShell 启动器run-health.ps1启动器的动作集合为collect、agent-context、maintainability、doc-refs、verifier-output。收集器输出节与独立运行形态在 Windows 上通过 Health 启动器运行时输出被包装在AI MAINTAINABILITY SUMMARY/AI MAINTAINABILITY DETAIL之下而直接独立运行检查脚本时没有该包装输出以 PROJECT SHAPE 开头。从源码看check_maintainability.py输出节依次为输出节内容 PROJECT SHAPE 总体状态maintainability_status、模式、跟踪文件数、生成镜像折叠/漂移/比较缺口、扩展名分布、最大源码文件与目录 AI CONTEXT SURFACE context_statusPASS / UNKNOWN / NOT_APPLICABLE、指令文件清单、验证指导与边界指导是否存在 VERIFICATION SURFACE verification_status、检测到的清单Makefile、package.json、Cargo.toml 等、命令清单、verifier_evidence、hollow_verifiers、缺失引用的命令 VERIFICATION WRAPPER SURFACE wrapper_status、是否含 Makefile、稳定 make 目标check/test/verify DECISION ARTIFACTS docs / specs / handoff / changelog / issue 模板 / PR 模板是否存在 DRIFT MARKERS TODO 标记统计、broken_doc_references、漂移发现 MARKDOWN LINK SURFACE markdown_link_status仅 deep 模式扫描二、判定规则什么时候报 FAIL、WARN该文档给出了严格的严重度判定标准核心原则是收集器状态是证据不是结论捷径collector status is evidence, not a verdict shortcut这一原则在 inspector-maintainability.md 中被进一步细化。报 FAIL 的条件当实现、CI、生成、发布、部署或其他实质性风险表明应当存在可执行的验证但verifier_evidence为空时报 FAIL或者当必需文档引用指向已失效文件时报 FAIL。关键界定commands只是发现清单discovery inventory不是证明。hollow_verifiers下列出的目标或脚本如果只打印输出、执行 shell 环境搭建或直接退出不满足覆盖率要求。从源码看check_maintainability.pyHOLLOW_COMMAND_RE会把echo、printf、true、false、exit、set、cd、export、mkdir/touch/chmod以及纯变量赋值等识别为空壳命令SETUP_ONLY_COMMAND_RE会把apt-get install、pip install、npm install、curl/wget、--version等识别为仅环境搭建命令。一条命令如果只有这些片段就不能算作真正的验证证据。对应到 Python 实现command_has_verifier_evidencemake target只有在目标名含test|check|lint|type|build|package|verify|smoke命名VERIFIER_NAME_RE或作为可信入口被递归解析时才有效且会递归检查其依赖与配方是否实质非空壳npm run script同理只有脚本名匹配验证器命名模式或pack --dry-run这类内建验证才被认可形如./scripts/check.sh的脚本调用要求脚本文件名含验证器命名且脚本正文经shell_script_has_verifier_evidence判定存在有意义的非空壳行为。也就是说一个只打印 success 的命名目标不提供验证。报 WARN 的条件以下情形报 WARN从文档原文归纳已验证的生成镜像漂移generated-mirror drift镜像与源文件内容不一致被引用的命令不存在指令文档里引用的 make 目标 / npm 脚本在清单中不存在稳定但非显式的约束相关任务无法触达关键约束存在但 agent 在相关任务中读不到反复失败却缺少持久不变量与验证器同一类失败反复发生却没有沉淀成规则和可执行检查空壳包装器漏掉了真正的失败层包装器只打印成功不覆盖实际会出问题的层面持久化规则只存在于被忽略/私有的 overlay 中重要规则只在.gitignore之外或私有的本地指令覆盖层里而跟踪/公开文档缺失持久化文档保留了原始一次性报告如 scorecard、带日期的行号引用、诊断转储而非稳定的不变量路径作用域加载运行时支持路径级加载但无关会话反复为大量领域性指导付费而这些指导其实可以安全地路由到路径级规则、嵌套指令文件或技能中——此时应将其迁移到路径作用域而不是删除其行为价值。关于 context_status 的解读纪律context_status: UNKNOWN存在实现或 CI 风险但缺少被跟踪的上下文证据应先核查实际风险再决定是否需要路由化不变量。既不能借此开出清白证明clean bill也不能因为缺少项目地图就强行要求补图。context_status: NOT_APPLICABLE收集器没有观察到实现/CI 上下文需求。同样不能据此虚构清白证明或地图要求。从源码看check_maintainability.pycontext_status在有实质指令证据时为 PASS否则若context_expected存在实现文件、workflow 或非 Makefile 清单则为 UNKNOWN反之为 NOT_APPLICABLE总状态在任一 FAIL 或 doc-ref 失败时取 FAIL有 UNKNOWN 或任一 WARN 时取 WARN否则 PASS。过期报告的处理动作对于过期报告stale reports文档给出的动作是把稳定规则抽取进公开指令、规则、引用或验证器脚本中然后删除或归档这份临时报告。这一点与测试 test_maintainability.sh 中仓库形状文件大小、目录结构绝不能成为可维护性发现的约束一脉相承。三、对话衍生指导候选矩阵Candidate Matrix当健康审计读取近期 Agent 会话时不要建议把会话原文或 scorecard 复制进文档而应执行一轮候选矩阵筛选。文档给出了完整的六字段矩阵字段要回答的问题Independent recurrence独立复现克隆的提示词、重试、自动化扇出会话、粘贴的助手输出、平台续接消息是否折叠为同一个底层事件Repeated failure重复失败该问题是否跨越修复、发布、Agent 或用户报告反复出现Durable invariant持久不变量教训能否表述为稳定规则而不是带日期的 incident 摘要Target layer目标层它应该进入项目指令、Waza 技能、全局规则还是私有记忆Verifier验证器是否存在确定性的命令、脚本、产物检查或运行时冒烟测试可以强制执行它Redaction risk脱敏风险教训是否包含本地路径、issue 编号、客户信息、机器状态、密钥或未发布的发布事实分层规则Layering Rule项目专属内容项目专属命令、应用名、产物名、发布仪式留在项目内可复用工作流如取消发布审查门禁、原生冻结证据阶梯属于 Waza 技能普适的诚实与验证规则属于全局 CLAUDE / AGENTS 文件私有用户偏好与单机事实留在记忆memory中。如果教训无法通过脱敏风险字段就不得进入公开指导。按加载面Load Surface划定作用域仅仅分层还不够还要考虑每条规则在每次会话中都要付出上下文代价除非它被绑定到其生效的位置语言与框架规则携带文件类型的paths作用域项目领域规则绑定到源目录pathsfrontmatter 或嵌套目录的CLAUDE.md只有真正横切的约束才无条件加载进 always-loaded 根文件。一条只在某个路径下才有意义的规则不应该放在 always-loaded 文件中。这正是 durable-context.md 中红色action 门禁思想的延续任何教训在变成持久规则前都要先过脱敏门。四、集中式修复链分析Concentrated Fix Chains文档给出可直接运行的诊断命令用于发现反复修复同一处的集中式修复链git -c core.fsmonitorfalse log --oneline --since2 weeks ago | grep -i fix然后按区域分组冒号:或左括号(之前的前缀。这里必须注意文档反复强调的判定纪律重复只是线索lead不是发现finding。必须读取足够证据确认多个修复收敛于同一个不变量或失败层而不是一群共享前缀的无关工作。只有完成这一验证后才报结构性 WARN且要指名反复出现的失败并推荐最窄的路由规则 可执行的验证器——也就是能防止该问题的那条规则与那个检查。core.fsmonitorfalse的写法同样出现在 iter_files 的git ls-files调用中用于规避文件系统监视器干扰快照。五、非显式约束可达性与风险支撑的热点归属这是最容易误用的部分文档明确给出了边界文件大小和模块形状不构成文档要求File size and module shape do not create documentation requirements。当真实失败或高后果路径集中在某区域并且暴露了一个无法低成本从代码中恢复的稳定边界时才需要验证相关任务能否触达一条简洁的归属规则以及锁定它的可执行检查。此时报告不可达的约束或缺失的验证器而不是报告一个笼统的 hotspot map 缺失。源码实现与测试双重印证了这一点context_findings只在context_expected且无实质指令证据时生成check_maintainability.py不会因文件大而报警测试 test_maintainability.sh 的 Case 4/5/6 明确验证1300 行或 900 行的大文件只要存在验证器make test即使完全没有 hotspot 归属文档deep 模式仍输出maintainability_status: PASS并断言输出中不得出现hotspot_ownership字样——大文件必须保持为库存信息inventory不能成为发现测试还验证node_modules、dist、build等排除目录中的超大文件绝不进入 summary/deep 输出Case 3这对应源码中的EXCLUDED_DIRS与MINIFIED_REcheck_maintainability.py。六、缺失稳定验证器入口Missing Stable Verifier Entrypointwrapper_findings只是发现线索。文档要求检查文档化的默认入口及其可执行覆盖覆盖范围包括 package scripts、原生构建工具、任务运行器、脚本与 CI——Makefile 不是必需的。只有当检查碎片化导致必需验证被遗漏、且没有可用默认入口覆盖它时才报结构性 WARN。一个只打印成功信息的命名目标不构成验证。从源码看wrapper_warnings的触发条件非常克制check_maintainability.py命令数 ≥ 2、存在 Makefile、但既没有稳定的 makecheck/test/verify目标也没有稳定的npm run check|test|verify且被证实有验证证据。测试 Case 7test_maintainability.sh展示了典型场景验证命令是./scripts/check.sh --no-format有实质验证证据verification_status: PASS但 Makefile 只有build目标且无check/test/verify默认入口于是wrapper_status: WARN提示检查文档化或原生的入口点后再推荐包装器。同时源码会检测各语言的原生验证表面verification_surface存在Cargo.toml则加cargo test/cargo check存在go.mod则加go test ./...存在Package.swift则加swift test配置了 pytest 且存在测试文件则加pytestpom.xml对应mvn testdeno.json/deno.jsonc对应deno test。测试 test_health_maintainability_regressions.py 验证了Package.swiftTests/目录下swift test会同时进入 commands 与 evidence。七、快速检查命令summary / deep 的跨平台用法文档提供了一系列可直接复制运行的命令均复用 Step 1 已解析的$HEALTH_SCRIPT与$HEALTH_LAUNCHER。单独运行脚本时输出不带AI MAINTAINABILITY SUMMARY包装首行即 PROJECT SHAPE 。可维护性检查summary 模式WindowsPowerShell $POWERSHELL -NoLogo -NoProfile -ExecutionPolicy Bypass -File $HEALTH_LAUNCHER maintainability . summaryLinux / macOSBashBASH_ENV ENV /bin/bash -p ${HEALTH_SCRIPT%/*}/check-maintainability.sh . summary深度审计deep 模式Windows $POWERSHELL -NoLogo -NoProfile -ExecutionPolicy Bypass -File $HEALTH_LAUNCHER maintainability . deepLinux / macOSBASH_ENV ENV /bin/bash -p ${HEALTH_SCRIPT%/*}/check-maintainability.sh . deep两处命令都体现了健康审计的只读铁律Hard Rules收集与检查不得运行项目测试、验证器、生成器或构建deep 模式与 summary 模式的差异只在于输出细节与 Markdown 链接扫描而不授权任何写入操作。BASH_ENV ENV与-p旗标用于屏蔽外部环境注入check-maintainability.sh 还会在启动时unset WAZA_PYTHON DOC_REF_CHECKER GIT_INSTALL_ROOT BASH_ENV ENV并对PATH做净化剔除目标仓库目录内的条目再挑选一个不在目标仓库内的 Python 3.9 解释器执行 Python 主体。动作纪律文档要求动作具体且非侵入concrete and non-invasive添加或修复最小的有用路由指令面、在真实失败层加一条可执行验证命令、修复生成镜像检查或修复损坏的引用。只有当边界已经清晰时才拆分。不要仅凭脚本输出就提出大规模重写。八、损坏的文档引用Broken Doc References扫描目标与引用形态文档规定扫描以下文件中的引用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.mdCLAUDE.md使用AGENTS.md占位符但实际AGENTS.md缺失或为空技能正文引用references/name.md但磁盘上只有references/name-v2.md规则文件引用了已删除的技能路径。检查命令Windows $POWERSHELL -NoLogo -NoProfile -ExecutionPolicy Bypass -File $HEALTH_LAUNCHER doc-refs .Linux / macOSBASH_ENV ENV /bin/bash -p ${HEALTH_SCRIPT%/*}/check-doc-refs.sh .检查器行为源码级check_doc_refs.py 实现了文档描述的全部行为值得逐条对照解析规则REF_REL21-L27匹配...、~/\.claude/...、docs/...、references/...四种形态解析基准resolve_refL99-L122...与docs/...从项目根解析~展开references/...若源文件位于.claude/skills/name/SKILL.md则从该技能目录解析否则从项目根解析——这解释了为何技能正文里的references/foo.md不能当作项目根的路径跳过围栏代码逐行维护 与 ~~~ 围栏状态围栏内的引用不检查退出码任何目标缺失时非零退出check_maintainability.py据此把broken_doc_references置为failL1046-L1047。严重度缺失引用一律报结构性Structural发现而非 Critical除非缺失文件被点名作为硬依赖例如发布技能所依赖的release.md。九、损坏的 Markdown 引用Broken Markdown References在deep 模式下check-maintainability.sh还会扫描仓库内 Markdown 链接。指向缺失本地文件的链接报结构性发现尤其是设计、安全、发布或交接文档——因为 agent 在未来工作中很可能跟随这些链接。从实现看scan_markdown_links有三类豁免非常值得注意围栏内的链接跳过代码块中的Template不算测试 test_health_maintainability_regressions.py 直接验证行内代码中的链接跳过Overview在反引号内不检查站点根路由/开头跳过以/开头的是站点路由而非本地文件引用把它当作审计主机上的路径会产生误报测试 Case 10 验证中文博客为 PASSRustdoc 生成链接跳过struct.Terminal.html这类 Rustdoc 在生成的 crate 文档中才解析的链接若源文件位于含Cargo.toml的目录树下则豁免测试 L97-L110 验证guide.html会报缺失而terminal/struct.Terminal.html不会。十、过期的验证器缓存输出Stale Verifier Cache Output当验证输出指向已删除的临时工作树或已不存在的/tmp//private/tmp文件时用以下命令解析捕获的日志Windows $POWERSHELL -NoLogo -NoProfile -ExecutionPolicy Bypass -File $HEALTH_LAUNCHER verifier-output . log-fileLinux / macOSBASH_ENV ENV /bin/bash -p ${HEALTH_SCRIPT%/*}/check-verifier-output.sh . log-file使用边界只用于用户提供的既有命令输出、或本次审计期间生成的输出不要为了喂给该脚本而专门去运行项目测试。从实现看check_verifier_output.py通过TOKEN_RE提取日志中的路径 token过滤掉含/.git/的条目再用TMP_RE(^|/)(private/)?tmp/筛出临时目录路径对不存在的路径stale_paths报verifier_output_status: WARN根据日志内容给出已知的缓存清理动作含golangci-lint/errcheck→golangci-lint cache clean匹配go test|vet|build或go-build→go clean -cache -testcache含npm/node_modules→npm cache verify未知工具 → 在移除过期临时工作树后重新运行验证器的诊断性重跑动作。这些动作正是过期验证器缓存问题的典型解法验证器golangci-lint 缓存、go 构建缓存、npm 缓存等指向了已被删除的临时工作树。十一、把发现写进报告Inspector 的产出约定当审计升级到 deep 模式时会启动第三个检查代理Agent 3AI Maintainability它只接收PROJECT SIGNALS、AI MAINTAINABILITY SUMMARY/AI MAINTAINABILITY DETAIL与具体的验证器/漂移回执产出格式如下inspector-maintainability.mdAI Maintainability: PASS|WARN|FAIL Findings: - [FAIL|WARN|INFO] short title: evidence from script output. Action: one concrete next step. Residual risk: - one short caveat, or None visible from collected data.其严重度映射与本文档完全一致FAIL应有验证但verifier_evidence为空 / 必需引用指向死文件、WARN漂移、缺失命令、过期/冲突的持久指导、仅私有 overlay 的重要规则、无可达不变量的反复失败、不覆盖真实失败层的包装器、INFO文件数、贡献者数、技能数、TODO 数、最大文件等库存信息除非关联到已证明的风险或失败证据、PASS表面存在且无可操作的维护性缺口。同时它明确要求不要仅凭UNKNOWN就报警——UNKNOWN 只意味着存在风险但未观察到指令表面需要先核查是否有非显式约束确实需要规则仅凭命令名也不满足验证覆盖率必须看verifier_evidence与hollow_verifiers。十二、报告呈现要求文档规定缺失引用按结构性问题上报且健康报告要求每个发现都包含可复制粘贴的Action:绝不写请调查 X或考虑 Y若修复未知则给出诊断命令。这一要求贯穿 SKILL.md 的 Finding 格式[severity] symptom ({file}:{line})Why:一行理由 Action:确切命令或编辑。被同一口气反驳掉的发现例如 TODO 计数其实是 vendored 代码不算发现应删除或并入通过表。测试 test_health_maintainability_regressions.py 还验证了报告输出的脱敏纪律redact_command_label会把PROVIDER_API_KEY、DATABASE_PASSWORD、CLOUD_SECRET_ACCESS_KEY、SSH_PRIVATE_KEY、--token等替换为[REDACTED]同时保留token_count42 api_key_statusmissing这类状态字段并保护notsecret、secretary等非密钥词——健康报告可以安全地在会话中呈现 CI 命令清单而不泄露密钥与主机路径。十三、落地建议把这份检查用起来从 summary 开始在任意项目根执行第七节的 summary 命令先看maintainability_status与各分节状态不要急于下结论对 UNKNOWN 先核查context_status: UNKNOWN不是报警理由先确认实现/CI 风险是否真的需要一条路由化不变量对 FAIL 补验证verification_status: FAIL意味着有实现风险但无实质验证证据——在真实失败层不是 Makefile 包装层补一条可执行验证命令对 WARN 逐个处置镜像漂移则修复镜像生成检查引用缺失则修doc-refswrapper_status: WARN则确认文档化默认入口deep 前先告知用户deep 审计会消耗较多 tokenSKILL.md仅在用户要求或存在明确代码腐化信号时升级只读边界整个审计是报告式的任何修复都发生在明确的 repair 阶段收集阶段绝不运行项目测试或修改文件。本仓库自身就是这套框架的活样例plugins/waza/下的技能与规则目录正是skills/、rules/的生成镜像collapse_generated_mirrors 会把plugins/name/skills|rules下字节级相同的文件折叠进源文件计数并单独列出漂移项——你可以对 Waza 仓库本身运行maintainability检查观察镜像折叠与漂移报告如何工作。小结AI 可维护性检查不是文件多大、TODO 多少、地图有没有的库存盘点而是四条证据轴风险、非显式约束、失败证据、验证器覆盖上的结构性审计。它的每一次 FAIL 与 WARN 都必须锚定在可执行的证据上verifier_evidence是否为空、命令是否真实可执行而非空壳、引用是否指向存在的文件、约束是否在正确的加载面可达。配合 check_maintainability.py、check_doc_refs.py 与 check_verifier_output.py 的实现这套方法论可以在任何语言、任何规模的项目上复制最小的路由规则面 真实失败层上的可执行验证器 干净的持久化文档正是防止 AI 编码腐化的三道防线。赞分享【免费下载链接】Waza Engineering habits you already know, turned into skills Claude can run.项目地址https://gitcode.com/gh_mirrors/cl/Waza点击查看免费下载相关推荐Waza /health AI 可维护性审计指南结构性发现的判定、分层归属与可执行验证Waza /health AI 可维护性审计指南结构性发现的判定、分层归属与可执行验证 本指南聚焦 Waza health 技能中的 AI 可维护性AI mApollo Client 开发模式错误消息机制全解析dev 子路径 API 深入指南Apollo Client 开发模式错误消息机制全解析dev 子路径 API 深入指南 本篇技术指南聚焦 Apollo Client 为开发调试场景专门提供的learn-harness-engineeringElectron 架构规则的 Harness 落地——从约束文档到可执行的端到端验证learn harness engineeringElectron 架构规则的 Harness 落地——从约束文档到可执行的端到端验证 本教程对应 第 10上一篇终极UMD指南如何在Angular项目中实现跨环境模块兼容下一篇5分钟搞定Intel RealSense深度相机在MATLAB中的极速部署创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考