Menu
在本仓库完成代码、脚本、测试或影响运行链路的配置改动后使用，用于自检可维护性漂移，重点发现超长文件和持续膨胀的文件。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | post-edit-maintainability-guard |
| description | 在本仓库完成代码、脚本、测试或影响运行链路的配置改动后使用，用于自检可维护性漂移，重点发现超长文件和持续膨胀的文件。 |
这个 skill 用来在“代码已改完、准备收尾”时执行一轮可维护性自检。它不替代 build、lint、tsc 或冒烟测试，补的是另一条线：
它的核心定位仍然是一个 diff-only maintainability gate，但文档上需要把“闸门型检查”和“趋势型指标”区分开。前者决定是否阻塞，后者负责持续观察。
当前这套可维护性检查可以按两类信号理解。
这些信号用于阻断“新增债务”：
eslint-disable 绕过既有约束的检查这些信号默认用于报告和趋势跟踪，不应轻易直接阻塞：
TypeScript / TSX 文件数与代码行数TS + TSX 的合并体积这里的“代码统计”属于可维护性的一部分，但它更适合作为趋势信号，而不是直接和“超长函数”“目录失控”混为同一阻塞级别。
以下场景默认适用：
service、controller、manager、runtime、loop、router、Page、App，以及大型表单/容器组件以下场景默认不适用：
不适用时，需要在结果中明确说明“本次不适用”及原因。
默认入口不变，仍然是：
node .agents/skills/post-edit-maintainability-guard/scripts/check-maintainability.mjs
如果这次属于纯 bugfix、纯重构、结构整理、命名调整或其它不新增用户能力的改动，必须改用：
node .agents/skills/post-edit-maintainability-guard/scripts/check-maintainability.mjs --non-feature
如果只检查特定文件：
node .agents/skills/post-edit-maintainability-guard/scripts/check-maintainability.mjs --paths path/to/file.ts path/to/file.tsx
如果既是非功能改动，又只想检查当前触达范围，可以组合：
node .agents/skills/post-edit-maintainability-guard/scripts/check-maintainability.mjs --non-feature --paths path/to/file.ts path/to/file.tsx
如果需要补充仓库级代码体积快照，可额外查看：
pnpm metrics:repo:local
或：
node scripts/metrics/code-volume-metrics.mjs --scope-profile repo-volume --no-write --print-summary
这里的代码统计默认仍属于“补充信号”，用于增强 maintainability report；但在 --non-feature 模式下，排除纯格式化噪音后的 非测试语义代码净增 <= 0 会升级为真实阻塞逻辑。
如果确实需要为非功能改动申请非测试代码净增长豁免，可以用 --no-fail 只生成报告和精确数字，但这不代表检查通过；它只能作为豁免申请材料。豁免必须由用户明确接受或在本次交付记录中显式记录。
--non-feature 模式下，排除纯格式化噪音后的非测试语义代码净增 <= 0 只是最低门槛，不是最终目标。真正目标是让生产代码维护成本下降。减债优先处理复杂度源、心智负担源和非必要链路，而不是机械寻找能减少行数的地方。这个 gate 只接受让系统变得更好的改动；不接受“都行”“能过检查”但没有质量收益的压缩。
完成标准是代码质量和可维护性提升。一次非功能改动只有在生产代码出现可观察的改善时才算通过：owner 更清晰、行为更简单、分支或状态更少、复用更自然、耦合更低、验证更容易、心智负担更低，或需要维护的代码更少。行数达标和正向减债动作只是证明这个结果的证据，不是结果本身。
正向减债不要求只发生在当前改动点、当前文件或当前几行；寻找范围必须按关系由近及远扩展：当前函数/类型 -> 当前文件 -> 当前 owner/class/service -> 同一责任链 -> 同一问题域 -> 本批次相关模块。只有较近范围没有正向收益时，才扩大范围；只要在这个顺序内真实删除、合并、收敛了旧实现，并且能证明系统整体更简单，就算有效。
当非功能改动被 line-change gate 阻塞时，默认按以下顺序解决：
删除和简化优先于新增抽象。新增抽象若只是多一层间接调用，不能算通过 line-change gate 的正向解法。
以下都不算正向解法：缩短命名、机械合并语句、去空白、把显式分支硬折成难读表达式、把复杂度转移到统计面外、删除类型安全或协议约束、增加临时 hack/特判只为压低数字，或其它不减少真实维护成本的“压行数”操作。
如果当前改动模块找不到有正向收益的删除或简化点，不能为了过 line-change gate 削弱当前实现；应按由近及远的范围顺序去同一责任链、同一问题域或同批次相关模块寻找真实冗余、旧路径、重复 contract 或无效分支来减债，并能说明为什么没有选择更近的范围。搜索半径由相关性、风险、检索成本和预期收益共同决定；低成本高相关时应主动扩大，跨到无关模块或需要高成本全仓库审计时可以停止。
收尾复核时必须能说清楚本次是哪一种正向减债动作让非功能改动通过，以及它如何带来代码质量或可维护性提升，而不是只报告行数达标。
若已经完成上述成本自适应搜索，仍确认剩余增长是清晰、安全、可验证实现所必需，则禁止为了满足数字继续做无收益压缩。不要通过缩短命名、折叠清晰分支、删除有价值的类型/协议保护、移除 implements / 显式返回类型 / 公共 contract 名称、把行为藏到更难读的位置，或把复杂度转移到统计口径外来“凑”非测试净增 <= 0。这类情况应停止压缩，提出 line-growth exemption：说明精确非测试净增、为何必须增长、已经查过哪些删除/简化/复用机会、搜索半径为什么到此为止、为什么继续压缩会损害清晰度或安全性，以及后续可偿还位置。未被明确接受或记录前，它仍是阻塞项；但继续做无争议收益不足的压缩同样是阻塞项。
默认检查模型分为六层。
HEAD 的行数变化12 个硬限制复用仓库 ESLint 结果，关注：
max-lines-per-functionmax-statementsmax-depthsonarjs/cognitive-complexity同时要注意与增量治理脚本的联动：pnpm lint:new-code:governance 当前除了 touched class / touched object 的箭头函数治理外，还会开始检查“普通函数是否偷偷修改入参”“React effect 是否把业务逻辑留在渲染后补丁里”“闭包多方法对象是否该升成 class/owner”“扁平混杂目录是否该长子树”“共享状态的顶层编排是否缺 owner”。其中 class 方法箭头函数这条虽然不由本 skill 直接计算阈值，但收尾时若命中该问题，默认修复策略应是：
methodName = () => {}constructor、get/set、static、abstract、override、带 decorator 的方法、async generator 方法仍按既有豁免处理若命中“普通函数修改入参”这条治理，默认修复策略应是：
input -> output 或 input -> patch 的纯返回形式若命中“React effect owner 边界”这条治理，默认修复策略应是：
query / view hookstoremanager / presenter按 diff-only 原则检查文件名是否与实现主职责明显冲突。当前优先覆盖高置信度场景，例如：
cache若本次触达仓库红区文件，则校验当前迭代 README.md 是否包含：
## 红区触达与减债记录### <repo-path>本次是否减债说明下一步拆分缝这部分当前应作为 report signal 来理解，重点看：
LOCTypeScript 文件数与代码行数TSX 文件数与代码行数TS + TSX 的合并规模文档上应把它明确纳入 maintainability 体系。默认模式下，它仍不与文件预算、复杂度、红区治理共享同一阻塞级别；但在 --non-feature 模式下，排除测试与纯格式化噪音后的非测试语义代码净增若大于 0，就必须直接阻断。
即使 --non-feature 模式下非测试净增已经 <= 0，后续 post-edit-maintainability-review 仍必须判断减债方式是否真实有效：能否对应到删除、简化、复用、职责收敛或必要解耦抽象；若只是让代码更密、更难读，或把复杂度移到统计口径之外，不能视为通过。
以下情况默认视为阻塞项：
<12 个直接手写代码文件增长到 >=12，且目录内没有明确记录的“目录预算豁免”说明12 个直接手写代码文件，但目录 README.md 中的“目录预算豁免”块缺失或不完整max-lines / max-lines-per-function / 复杂度规则的 eslint-disable 注释本次是否减债、说明 或 下一步拆分缝--non-feature 模式下，排除测试与纯格式化噪音后的非测试语义代码净增大于 0，且没有明确接受或记录的 line-growth exemption<= 0，但后续复核无法指出任何正向减债动作：删除、简化、复用、职责收敛或必要解耦抽象以下情况默认视为警告：
12 个直接手写代码文件，但已在目录 README.md 中留下完整的“目录预算豁免”说明12 个直接手写代码文件的历史目录，本次触达但未继续恶化，且仍未补豁免说明出现阻塞项时，默认应继续拆分后再结束任务；除非用户明确接受这笔债务。若保留债务，必须说明原因、指出下一步拆分缝，并在最终回复中写明风险。
line-growth exemption 只能用于“必要增长”，不能用于掩盖未完成的删除、可合并的重复实现、可复用而未复用的路径，或为了赶进度留下的补丁式实现。申请豁免前必须先证明没有更小且更清晰的实现方案。
12 个直接手写代码文件起默认禁止__tests__、tests、__fixtures__、fixtures、generated、migrationsservice / controller / manager / runtime / loop / router / provider：600 行types / schema / constants / 明确的纯配置文件：900 行若目录确实必须达到或超过 12 个直接手写代码文件，需在该目录的 README.md 中显式加入以下块：
## 目录预算豁免
- 原因：该目录受框架或生成约束，必须保留扁平文件集合。
预算只是启发式边界，不代表文件低于预算就一定设计良好。像裸名 config.ts 这类文件，若承载运行逻辑，不应自动按“纯配置文件”放宽预算。即使文件没超限，只要职责明显混杂，也应指出风险。
函数级规则不直接复刻在 skill 文档里，而是复用当前仓库 ESLint 基线，避免“ESLint 一套阈值、skill 又是一套阈值”的漂移。
这个 skill 的目标不是让每次任务都被历史债务卡死，而是优先阻断“新增债务”。
只要本次改动新增或恶化了文件级 / 函数级 / 命名职责 / 红区治理债务，就视为阻塞项。
运行这个 skill 后，输出里必须包含：
docs/logs/.../README.mdTypeScript、TSX、TS + TSX 的文件数 / 代码行数 / 增量推荐的输出顺序是：
后续给这个 skill 加能力时，优先沿着“信号类型”扩展，而不是继续堆一段段流程说明。
推荐扩展方向：
TS/TSX 体积趋势、测试资产密度、模块增长速度判断标准：
scripts/check-maintainability.mjs：Node 版入口脚本scripts/maintainability-guard-core.mjs：结果组装与 diff-only 判定scripts/maintainability-guard-directory-budget.mjs：目录文件预算与豁免说明检查scripts/maintainability-guard-hotspots.mjs：红区触达与迭代日志校验scripts/maintainability-guard-lint.mjs：ESLint 结果解析scripts/maintainability-guard-support.mjs：git / 文件 / 预算辅助函数../../../../scripts/governance/maintainability/maintainability-hotspots.mjs：仓库红区清单与日志格式约定../../../../scripts/metrics/code-volume-metrics.mjs：仓库代码体积快照与 LOC 趋势统计Use when implementing, refactoring, or designing source-level contracts in this repository, especially if a task touches frontend/backend i18n or user-facing copy, frontend base/display components, tool schemas, API/protocol parameters, shared contracts, compatibility paths, fallback-heavy logic, duplicate branches, weak abstractions, unclear file placement, ad-hoc helpers, or patch-style fixes that would turn into garbage code.
Create or update complete NextClaw lightweight apps, deciding whether the user needs a Panel App, a Service App, or a combined Panel + Service App. Use for NextClaw applets, small tools, dashboards, local file tools, AI-assisted UI tools, apps that may combine right-side UI with backend actions, or questions about what NextClaw/Panel apps can do and which app APIs/capabilities they can use.
当用户要求提交、收尾、统一 NPM 发布、GitHub release、changelog、release notes、版本更新说明、产品更新笔记、变更汇总，或担心并行会话导致发布内容靠记忆整理时使用。适用于需要进入用户可见发布说明的 NextClaw workspace 包变更、Changesets 聚合、AI 撰写版本更新笔记、可拉取结构化 release notes JSON，以及 update manifest releaseNotesUrl 闭环。
Use when building, verifying, or releasing NextClaw desktop installers, DMGs, update bundles, update manifests, or one-command desktop beta/stable release automation. Enforces the packaged update public key contract, the required verification commands, and the rule that raw electron-builder output is not enough.
当用户要求“发布 beta”“统一 beta 发版”“发一个新的 NPM beta 版本”“一键 beta release”或希望直接复用 NextClaw 的 beta 发布闭环时使用。适用于 nextclaw 及其相关 workspace 包的 beta 发布，也适用于需要同时闭合 npm registry 与 NPM runtime update channel 的场景。
Use when publishing NextClaw NPM packages or NPM runtime update channels, including beta/stable dist-tags, nextclaw@beta validation, runtime bundle manifests, packaged update public keys, and npm registry closure checks.