| name | code-quality |
| description | 通用代码质量纪律与健康诊断，适用于任何项目。定义质量底线（兜底/历史包袱/双通道/双写真相/fail-fast/封装纪律）并给出健康诊断十查与分类处置，产出分类证据与推荐动作，不改代码。与 code-odor（异味特征检测/工作过程自查）、code-review（缺陷验证）、code-workflow（实现）、self-grill（自我质询）、grilling（对用户质询）配合。Triggers on "代码质量", "质量纪律", "健康诊断", "代码体检", "代码审计", "兜底", "fallback", "兼容层", "历史包袱", "双通道", "双写真相", "单点真理", "fail-fast", "封装纪律", "残留扫描", "code audit", "cleanliness check". |
代码质量纪律与健康诊断
通用、宏观的质量底线与处置准则。不绑定具体语言或项目，不引用具体文件/诊断码；只在需要落地动作时给出通用可执行约束。
核心立场：兜底通常意味着底层数据结构的缺陷与设计不统一，很大概率是架构问题，而不是"防御得好"。已有代码不因"已在仓库里"而正确。 原则优先于行为维持——确认违反原则时以原则为准，不以"保持已有行为"为主，改后详尽记录变化前后供追溯。IBCI 自身设计缺陷（即使文档化）可推翻，按更普适+实践合理方案重建。
只诊断不改码——修复走 code-workflow，实施后核验回 code-review。
一、三条红线（最高优先级）
- 兜底不被允许：任何"回退到某种默认/兼容行为"的代码都默认视为缺陷，除非能证明它是职责分离型的功能 fallback 链（如协议方声明能力、调用方按协议分派），而非掩盖型兜底。
- 历史包袱不被保留：旧代码不因历史存在而获得豁免。与当前架构冲突、无消费者、无设计意图、或阻碍演进的旧结构，应果断清理而非"顺手保留"。
- 双通道被禁止：同一决策不得"新路径 + 旧路径"并存。要么真合并，要么真删除；过渡实现不得以"暂时兼容"名义长期滞留。
二、识别与处置兜底
识别（出现即红旗）：
- 静默回退：
if x is None: x = <默认>、except: pass、取默认值而非报错
- 防御探测：
hasattr(obj, 'attr') / getattr(obj, 'attr', <默认>) 探测能力
- 兼容层 / shim：包裹旧接口的过渡包装、
if legacy: ... else: ... 分派
- 胶水：字符串拼接、魔法哨兵、书写顺序掩盖数据依赖
- 魔法默认：把"未知/失败"静默映射为
any/null/空值
判定：唯一可接受的 fallback 是职责分离型——协议/能力声明层声明行为规范，具体层持有实现细节；缺失信息返回"未知"并由上层显式决策。凡是"掩盖错误、延迟暴露、让调用方以为成功了"的兜底，一律禁止。
处置：删除兜底 → 追踪根因（底层数据结构缺陷？设计不统一？层边界错误？）→ 修复根因。禁止在症状层继续打补丁。
三、识别与处置历史包袱
识别：
- 死代码：零消费者、前提条件永不成立的分支、
hasattr(不存在类型) 守卫
- 重复实现：同一转换/构建逻辑存在于多处，且精度或行为不一致
- 过时结构：与新架构冲突、被新机制取代但未删除的旧机制
- 顺序依赖掩盖：依赖遍历顺序/调用顺序才成立的脆弱正确性
判定：用 grep 消费者 + 历史 + 设计文档 + 类型契约四者交叉验证"死代码 vs 预留接口"。无意图、无计划、无消费者 → 删除；有意图但契约破损 → 激活或明确废弃。
处置：干净彻底重构。删除时连同其外围（引用它的文档、依赖它的分支、为其存在的兼容路径）一并清理，不留半拆除状态。
四、识别与处置双通道
识别：同一决策点出现"有条件选 A 否则选 B"的两套独立逻辑块（常表现为复制粘贴的旧块 + 新实现）；新旧并存导致行为随触发条件漂移。
处置：收敛为单一入口 + 单一分派——按可用的元数据/能力选择解析策略，但代码路径只有一套；被取代的旧逻辑整体删除。若某情形天然无静态信息，应在单一分派内以"无签名 → 动态跳过"处理，而不是保留旧分支。
五、单点真理与 fail-fast
- 单点真理：同一事实只在一处维护。出现两处同义实现、两套精度不一致的衍生结构，即"双写真相"——立即合并或删其一。
- fail-fast 优于静默回退：配置错误、环境变化、不变量破坏应立即暴露（报错/断言），绝不静默降级。可空性假设必须显式：底层值不允许为 null 就应让"解析不到即失败"，而不是调用方逐个防御。
- 封装纪律：禁止穿透私有属性或探测内部能力；走公开协议，协议缺失则新增公开方法而非
hasattr 试探。
六、兼容性决策准则
- 项目无外部用户 / 仍在内部开发时：兼容旧结构没有理由，应果断让旧结构失效并彻底清理外围。新设计就是真设计。
- 兼容是新架构固有优势（如协议演进天然向前兼容）：做好并明确测试。
- 兼容是为保留旧架构而强撑：删除旧结构，不要为它维持生命周期。
七、健康诊断十查
- 死代码与残留：未用导入 / 属性 / 参数 / 返回值；零消费者方法；死分支与恒真恒假 guard；注释掉的代码块；copy-paste 重复实现；两套机制做同一件事（同一概念两种实现必漂移，合并或删一套）
- 损坏空壳：引用未初始化 / 已删除字段的方法；声明即坏的对外接口（虚表 / 协议）；stub 占位"先这样"；静默回退（
except: pass、return None 掩盖路径）
- 字面量散落：魔法字符串 / 数字 / 哨兵重复；同义字面量跨层镜像（靠注释"保持同步"）；硬编码路径 / URL / 超时；应提炼单点常量
- 半接通特性：协议 / 框架已落地但零消费者，或消费者从不触发（恒参、恒 false、从不传非默认值）；声明未实现；实现未接线
- 架构与耦合卫生：层穿透（低层引用高层）；循环依赖；上帝对象 / 超长模块；职责错位；协议与实际签名漂移（用能力探测而非协议声明，即穿透封装）
- 状态与并发卫生：只写不读的状态；可变共享状态未隔离；全局单例可变槽；线程安全边界不清；无失效机制的无界缓存
- 错误处理卫生：裸
except / except: pass 吞异常；宽捕获后泛化抛出丢上下文；静默 fallback 违 fail-fast（应 raise）；异常路径无测试
- 命名与风格卫生：命名与行为不符；内建名遮蔽；无意义 / 不一致命名；
hasattr / setattr 穿透私有属性；同一概念多处不同叫法
- 测试与覆盖卫生：公开 API 零覆盖；测试断言与行为不符；测试间共享可变状态（隔离破坏）；测试名与所做之事不符；测试依赖"凑巧相等"
- 文档漂移：示例 / 说明与真实返回类型或行为不符；注释与代码矛盾；过时 docstring；单点真理被重复定义（概念两处描述必漂移）
八、分类速查
| 现象 | 分类 | 默认动作 |
|---|
| 零消费者 + 无设计意图 | 死代码 | 删除 |
| 零消费者 + 有设计意图 + 契约完好 | 预留未激活 | 激活或文档化 |
| 有调用点但逻辑为空 / 损坏 | 功能空壳 | 删除（违架构）或实现（有需求） |
| 恒参 / 恒 false / 从不触发 | 死分支 | 删分支；协议签名向后兼容则保留 |
| 层约束导致的镜像常量 | 设计限制 | 一致性测试取代人工同步 |
| 文档与代码不符 | 文档漂移 | 以代码为准修文档 |
| 两套机制同一概念 | 架构漂移 | 合并为一套，删另一套 |
九、提交前自查（通用可执行检查）
对改动做全量扫描（范围须超出本次改动文件），逐条判断：
grep -rnE "except: *pass|except Exception: *pass|hasattr\(|getattr\([^,]+,[^,]+," --include=实现文件
grep -rnE "legacy|compat|shim|兼容|旧实现|历史上|过渡|暂时|backward|兜底|fallback" --include=实现文件
命中后逐条走 §二~§四 判定；确实属于职责分离型 fallback 的保留并注明设计依据，其余一律修复。改动涉及数据模型/签名/协议时，同步检查其所有派生消费方（序列化、文档、分支逻辑）是否随旧结构一并清理。分类归属拿不准时，按 §八 速查；反射/能力探测等隐蔽变体信号清单见 code-odor §一.A，判定基准见本 skill §二~§五。
十、与相关 skill 的分工
code-odor：异味特征检测（嵌套分支、兼容/兜底/快速实现等字样）与工作过程自查，命中即触发自我质询协议，定位"哪里可能有问题"。code-review：验证/复核具体已报告缺陷，管"证据与分类"。code-workflow：实现/修复/重构的执行流程，管"怎么做"。self-grill：对计划/设计/已完成工作逐项自我质询，找不清晰与未决断项，仅上报无法自主决断项。grilling：对用户的质询（用户要求被拷问时）。- 本 skill：质量底线与处置准则，管"什么必须被清理、以什么标准判定"。判定冲突时以本 skill 的红线为准。
