fable-anti-slop-engineering

Fable 反劣质工程

**使命：**交付有独立证据支持的、尽可能小且 连贯、正确、可维护 的改动。绝不为了 CI 绿灯而牺牲契约完整性、安全性或可审查性。本技能同样适用于人工编写和 AI 编写的改动。

目的

在每轮编码和整个生命周期的各个阶段，贯彻专业软件工程标准、契约保护、测试完整性和安全边界。检测并阻止 AI 编码劣质代码、薄弱或同义反复的断言、跳过测试、吞掉异常、类型抑制、安全绕过以及不受约束的差异膨胀，避免这些问题在代码提交或合并前溜过审查。

适用场景

• 规划或实现必须保持现有契约不变的功能和 Bug 修复。
• 修改测试断言、测试固件、快照或基准数据集。
• 审查拉取请求和差异，查找隐藏回归、作弊模式或代码膨胀。
• 在所有编码会话中执行提交前、推送前和生命周期完成门禁。
• 审计 Agent 生成的代码，查找静默吞掉错误、过度使用模拟、UI 开发备注泄露或安全边界逃逸等问题。
• **NOTED_SLOP：**将新发现的 AI 劣质代码问题整理为诊断目录模式、Agent 指令和自动化差异防护启发式规则。

不适用场景

• 不适用于没有经过验证的基线契约时进行推测性、未经验证的重写或大规模重新架构。
• 不适用于与行为契约毫无关系的风格吹毛求疵或格式争论。
• 不能替代可执行测试套件、真实动态测试或渗透扫描。

输入

• task_specification：用户需求、问题说明或验收标准。
• current_diff：相对于基准引用的统一 git 差异（或用于纯净代码检查的文件树）。
• repository_context：现有测试套件、架构契约、错误处理惯例和安全策略。

预期输出

• slop_audit_report：结构化审计报告，将发现分为阻断、审查和警告级别，并提供准确的文件和行号引用。
• diff_integrity_evidence：最新的通过验证证据，证明当前差异中不存在劣质代码阻断项。
• sarif_report：用于 CI/CD 集成和自动化代码扫描的标准 SARIF 2.1.0 输出。

流程

每轮编码都执行 7 道反劣质代码协议门禁：

1. **门禁 0（发现）：**检查仓库架构、包清单、锁文件、现有测试和惯例。绝不自行臆造惯例。
2. **门禁 1（脚手架与依赖检查）：**对于新项目或模块，使用官方生成器（uv init、cargo init、bun create）。对于新依赖，解析并固定最新稳定版本。
3. **门禁 2（锁定测试基线）：**编辑前检查现有测试。保护断言；绝不削弱测试来迁就错误行为。
4. **门禁 3（精确实施）：**修改现有抽象。只引入最低限度且有充分理由的复杂性；不创建平行重复的抽象；UI 组件中不得出现开发备注或元对话。
5. **门禁 4（超越绿灯进行验证）：**运行真实的单元、集成和契约测试套件。将覆盖率和 lint 视为参考信号，而非证明。
6. **门禁 5（使用原生引擎扫描差异）：**运行 get-fable anti-slop --base HEAD --fail-on-blocker 或 fable-anti-slop scan。
7. **门禁 6（证据与决策）：**给出明确的合并判定（PASS / REVIEW / REWORK / BLOCK），并以机器检查过的证据为依据。

决策规则

• 阻止（失败关闭）： 未经批准禁用或跳过任何测试、削弱断言、在生产路径中吞掉异常、UI 组件中泄露开发备注／模拟道歉（DEV_NOTE_IN_UI）、禁用身份验证或安全检查、硬编码凭据，或构建失败。退出代码为 2。
• 返工： 不必要的代码重复、缺乏合理依据的新依赖、测试实现细节而非契约的测试、未经审查的生成产物变更。
• 审查： 新增行数超过 400 行的差异、类型抑制（any 或 @ts-ignore），或有合理依据的契约更新。
• 通过： 满足所有验收标准、没有阻止项、全新测试通过，且差异范围聚焦、整洁。

工具政策

• 在探索和审查阶段，优先使用只读工具。
• 对统一的 git 差异调用原生反劣化引擎（fable-anti-slop），并使用 --fail-on-blocker。
• 不要使用 shell 执行来绕过预提交钩子（严禁绕过验证标志）。

证据要求

• 提供来自 fable-anti-slop scan --base HEAD --fail-on-blocker --json-v1 或 get-fable anti-slop 的机器检查输出。
• 通过 get-fable evidence pass test ... 记录全新且通过的测试证据。
• 提供可验证的差异统计（git diff --stat），以证明变更范围受控。

失败处理

• 如果检测到阻止项级别的劣化问题：不得绕过检查或重新建立基线。找出根因，撤销劣化模式，恢复测试断言，然后重新运行扫描。
• 如果失败次数达到 2 次：立即转交给 fable-recover，诊断环境或执行路径故障。

完成标准

• fable-anti-slop 扫描以 passed 状态完成（0 个阻止项）。
• 所有修改和新增的测试均在真实运行时中通过。
• 在 .fable/state.json 中记录与当前 mutationGeneration 相匹配的全新证据。

操作优先级

1. 明确的用户要求、仓库架构、安全政策和现有公共契约优先于审美偏好。
2. 保留已授权的现有行为，优先于让新的实现通过其自身测试。
3. 先证明行为正确，再润色风格；先修复正确性和安全方面的阻止项，再处理外观问题。
4. 尽量减少不必要的复杂性，而不是删减必需的测试、安全检查或清晰度。简短但不正确的解决方案仍不合格。
5. 没有文件／行号证据和影响说明时，不得提出问题。绝不捏造工具结果或测试运行情况。
6. 绝不为了让当前请求通过，而修改或批准无关的代码、测试、政策、依赖、CI 或基础设施。

不可妥协的反作弊规则

• 除非产品契约明确授权新的输出，否则不得更改测试的预期输出以匹配观察到的错误输出。
• 不得删除、跳过、标记为预期失败、降级、通过模拟规避或抑制失败的测试来掩盖失败。
• 不得使用虚假的日志、捏造的基准测试、臆想的浏览器截图、测试结果或编造的源码引用。
• 不得仅为取得成功而放宽 lint／类型／安全／分支保护／CI 政策。
• 不得顺带修改锁文件、依赖项、格式、代码生成、数据库架构或测试固件。
• 未经证据支持且未获范围批准，不得用全面重写取代针对性修复。
• 不得过度限制合理的设计：在测试中，重复代码可能优于难以阅读的抽象；为确保正确的安全边界，较大的实现也可能是必要的。
• 不得在面向用户的组件或客户端 DOM 中呈现开发备注、内部 TODO、模拟数据免责声明或供其他 Agent 参考的备注。
• 不得让界面充斥大段微文案、过度说明、强迫性的装饰组件或拥挤的导航栏；应保持视觉克制、视觉平衡与留白。
• 官方 CLI 生成器可用时（uv init、cargo init、bun create、官方 SDK 快速入门），不得凭记忆手工编写样板代码或构建配置；应先调用官方脚手架工具。
• 引入新依赖时，不得凭模型记忆猜测过时或截止日期之前的库版本；应从官方注册表解析并锁定最新稳定版本。

交付约定

每次实现／审查都应按以下顺序生成简明报告：结果；范围；保留／变更的行为；验证（命令 + 结果）；发现（含准确的文件／行号）；测试修改及其理由；风险／局限；合并建议。 如有可用信息，应区分基线失败与新失败。适用时，须原样使用 NOT RUN 和 UNKNOWN。

渐进式资源

• 反模式目录 — AI 编码反模式的详尽目录，附有修改前后的示例。
• 测试完整性政策 — 关于断言保留、边界测试和测试重构的规则。
• PR 审查规程 — 严谨的审查清单和结构化问题模板。
• 安全与运维 — 信任边界、凭据卫生与运维安全。
• 工程判断 — 基于上下文的例外标准与设计权衡。
• 证据与来源 — 具体的证据层级与验证标准。
• 评估案例 — 真实世界的评估基准案例。
• PR 审查模板 — 可复用的 PR 审查 Markdown 模板。
• 运行报告模板 — 可复用的实现运行报告模板。