anti-slop-engineering

反糟粕工程

使命： 交付最小的、自洽、正确、易维护的变更，并以独立证据作为支撑。绝不为了拿到绿色 CI 徽章而牺牲契约完整性、安全性或可审查性。贯彻 Google 网站可靠性工程（SRE）原则：简洁（KISS）、单一事实来源（DRY）、反臆测（YAGNI）和规模化修复问题（消除琐务）。纳入干净环境下的 Stop-That-Shit 边界拦截、高级开发人员晋升阶梯，以及高性能 Rust/Go 微服务。此技能同样适用于人工和 AI 编写的变更。

运作优先级

1. 明确的用户要求、仓库架构、安全策略和现有公开契约，优先于审美偏好。
2. 保留已获授权的现有行为，优先于让新实现通过自己的测试。
3. 先证明行为，再润色风格；先修复正确性和安全方面的阻塞问题，再处理外观问题。
4. 尽量减少不必要的复杂性，而不是删减必需的测试、安全检查或清晰度。简短但错误的解决方案不合格。
5. 没有文件和行号证据及影响说明，不得报告问题。绝不编造工具结果或测试运行记录。
6. 绝不为了让当前请求通过而更改或批准无关的代码、测试、策略、依赖项、CI 或基础设施。
7. 优先使用官方样板和安装程序，而非手动搭建： 对于任何全新项目、服务、框架、库或 SDK 集成，Agent 必须依赖官方 CLI 安装程序、入门样板或生成器（例如 uv init、cargo init、bun create、官方 SDK 快速入门）。绝不手动随意搭建脚手架、任意目录结构或零散配置文件。
8. 严格使用最新稳定版本： 安装、初始化或引入任何新依赖项、库或 SDK 时，必须严格查询注册表并锁定最新稳定版本。绝不凭训练记忆猜测过时版本，也不依赖过时模板。
9. 品味、视觉克制与简洁的 UI 文案： 绝不让大段文字、重复说明或过度拥挤的导航栏使用户界面杂乱。遵循视觉层次、合理留白和精炼 polished 的微文案。去除多余的小部件、统计徽章或图标堆砌。
10. 用户界面中不得泄漏开发备注： 绝不在用户可见的 DOM/JSX 中呈现内部开发指令、Agent 提醒、模拟免责声明或架构道歉语（"Note: In production..."、"Mock data displayed"、"TODO: Add auth"）。严格将内部技术背景保留在代码注释或项目设计文档中。
11. 克制文档编写，杜绝臆测性文档： 绝不在未经要求时生成文档文件、提交材料包、审阅者资料包或平台指南（例如“发布到 OpenAI ChatGPT Plugins”、虚构的市场提交资料包、臆测的部署方案）。绝不引用失效、已弃用或杜撰的第三方提交门户（例如 platform.openai.com/plugins）。文档必须严格以事实为依据，精简且基于仓库中真实、受请求的功能。杜绝文档文件泛滥和形式化的备注提示。
12. 杜绝显而易见的内容，直接呈现有效载荷： 严格消除对琐碎语法的讲解、同义反复的文档字符串、居高临下的 UI 微文案、形式化的文档常识以及对操作方式的赘述。所有文档、代码和界面都必须遵循直接呈现有效载荷原则：从领域标题直接进入技术内容（代码、表格、媒体、架构），不添加任何对话式前言（“下表概述了……”）、操作方式描述（“点击播放/展开/复制/滚动”“无需离开页面即可观看”）、机械式引导（“打开终端”“保存文件”）、双语标题堆叠或夸张的营销话术。标准 UI 操作方式和技术内容本身足以说明问题；保持简洁胜过制造噪音。
13. 遵循 Google 站点可靠性工程（SRE）规范： 在所有更改中贯彻 Google SRE 的四项基本原则：
    • KISS（简单是可靠性的前提）： 循环嵌套不超过 4 层。超过 80 行的函数必须拆分为职责单一的单元。拒绝没有实际价值的透传包装链。
    • DRY（单一事实来源）： 重复的不变量、重复的验证模式或并行的错误结构都是可靠性隐患。将其整合到规范模块中。
    • YAGNI（反对臆测性工程）： 不得包含臆测性参数（_unused_param、future_kwargs）、死分支（if False:）或占位桩。只针对当前需求构建。
    • 大规模修复问题（消除琐碎操作与分布式韧性）： 自动化重复的人工操作。所有网络重试都必须采用带完整抖动的指数退避，以避免重试风暴。绝不使用 sleep() 来临时规避异步竞争。对并发设限，并确保会改变状态的端点具备幂等性。
14. 洁净环境下的资深开发阶梯与 SHIT 拦截（Ponytail、STS、朴素工程）：
    • 拦截四类 SHIT 风险：范围蔓延（S）、假设性加固/未读取的伴随哈希（H）、意图违背（I）和任务反复折腾（T）。
    • 编写代码前，先按资深开发阶梯逐步判断：(1) 这有必要存在吗？(2) 代码库中已有实现吗？(3) 标准库/平台能完成吗？(4) 原生运行时是否已涵盖？(5) 现有依赖项能解决吗？(6) 能否直接表达？(7) 只编写最少、必要且经过测试的代码。
    • 指出内置功能： 在编写自定义解析、验证或 UUID/克隆工具之前，先指出平台内置功能（crypto.randomUUID()、URLSearchParams、structuredClone()）。手工实现标准原语属于缺陷。
    • 务实 DRY 三点门槛： 仅当共享工具或抽象满足以下条件时才允许使用：至少出现在 2 个实际现有调用点；变更时所有调用点都需要相同修改；且抽象名称无需使用并列连词（and、or）。
15. 做出重大承诺前先通过决策守卫： 如果任务涉及派生指标、架构技术栈、基础设施、持久化或难以撤销的工程决策，请先阅读 Decision Guard。在认定提议的方法必不可少之前，先检查直接证据和独立替代方案。绝不能用决策记录的结构性检查取代对源代码的核验。

激活／模式

选择相关模式，并遵循相同的关卡：

• BUILD： 新功能或行为变更。基线 -> 契约 -> RED -> GREEN -> REFACTOR -> 独立审查 -> 证据。
• FIX： 先复现观察到的 Bug，再修复最小范围的根因，并证明回归测试通过。
• REVIEW： 只读审查差异和仓库上下文；报告发现的问题，并注明严重程度、证据和反事实。
• CLEANUP： 建立可观察的行为基线，将纯重构与功能变更隔离，并证明行为未发生偏移。
• NOTED_SLOP： 将新观察到的 AI 代码异味归纳为诊断目录模式、Agent 指令和自动化差异防护启发式规则（参见 CONTRIBUTING.md）。
• DECIDE： 当前提、直接答案或长期架构选择存在重大不确定性时，先遵循 Decision Guard，再进入 BUILD。做出决定后返回常规模式；日常修复无需采用额外流程。

对于全面审计，请加载 反模式目录。对于 Google SRE 规范和分布式弹性模式，请加载 google-sre-discipline。对于任何测试变更，请加载 测试完整性策略。对于 PR 或合并请求，请加载 PR 审查协议。对于提升的权限、敏感代码、网络访问或部署，请加载 安全与执行边界。对于项目特定的例外情况，请加载 工程判断与例外。对于社区贡献，请遵循贡献者指南。

七道关卡

关卡 0：先了解仓库；不要凭空臆断

• 阅读根目录和作用域内的指引（AGENTS.md、CLAUDE.md、贡献文档）、任务和验收标准、包清单、锁文件、CI，以及附近的实现和测试。
• 根据仓库实际内容确认语言和框架版本，而不是一味追新。找出已有的辅助工具、类型、错误处理模式、事务边界、可观测性、API 契约和测试命令。
• 如有相关未解决的 Issue 或 PR，请先阅读，避免重复工作或与正在进行的变更冲突。无法访问网络时，不要因此停止工作。
• 记录工作区状态；未经授权，不得覆盖用户变更、重置、暂存或修改无关文件。
• 如条件允许，运行适当的基线构建或测试；将已有故障标记为基线问题，而非本次变更所致。
• 对于派生答案类任务，在构建代理方案前，先检查现有的直接来源。对于架构承诺，请检查产品实际的渲染、工作负载、运维和持久化需求，而不是默认采用熟悉的服务商组合。只有在不确定性会造成重大影响时，才加载 skills/decision-guard/SKILL.md。
• 对于新项目、服务、组件或 SDK 集成，在编写代码前，先找出官方安装程序、CLI 生成器和规范的起始模板。不要凭记忆手动拼装配置或目录结构。绝不擅自生成文档文件、提交材料包或推测性的第三方平台指南。

关卡 1：建立变更契约

编辑前，记录：变更内容、不得变更的内容、业务不变量、外部 API、预期故障、数据影响、安全影响、回滚计划和验证要求。 对于没有正式规格的任务，应根据源码、现有测试和用户请求拟定临时契约，标明不确定之处，并选择保守的实现方案。

制定简短的范围计划：目标文件、可复用内容、测试点和风险区域。明确指出迁移、锁定／并发、认证和数据保留方面的影响。只有存在重大的外部可见歧义或破坏性操作时才请求批准；否则采取保守做法并说明假设。

Gate 2：锁定基线测试，同时不冻结合理演进

• 在实现前检查现有回归测试。优先采用独立指定的预期结果。
• 修复 Bug 时，应尽可能先编写失败的复现测试。新增行为时，应尽可能在实现前针对约定的契约编写测试。
• 现有断言／测试夹具／快照均受保护：如果更改后测试失败，应先调查实现／回归问题。绝不要仅为让测试通过而弱化断言、改写基准值、移除覆盖、标记为跳过／预期失败，或添加排除项。
• 如果获批行为确实发生变化、断言有误，或确有必要进行合理的测试重构，则可以更改现有测试。说明旧契约 -> 新契约，引用权威依据，展示更改前后的行为，并就语义获取独立审查。
• 不要盲目禁止修改测试，也不要坚持为每次 I/O 交互都编写单元测试。应根据风险选择单元／集成／契约／端到端测试。请参阅test integrity。

Gate 3：以最低限度的合理复杂度实现

• **优先使用官方工具，而非手动搭建脚手架：**初始化应用、模块或 SDK 集成时，应调用官方 CLI 安装程序／起始模板生成器，而不是手动编写构建配置（tsconfig.json、package.json、pyproject.toml、Dockerfiles 等）。
• **严格固定最新稳定版依赖：**添加新依赖或 SDK 时，始终查询软件包管理器或注册表以安装最新稳定版本（例如，bun add <pkg>@latest、uv add <pkg>）。在清单中严格固定版本并生成有效的锁文件；绝不要依赖知识截止日期之前的记忆。
• 前端品味与零开发备注泄漏：
  • 从面向用户的 DOM/JSX 中移除所有内部开发者／Agent 注释、提醒或模拟数据警告（"TODO: Wire backend"、"Note: Mock data"、"Agent notice:"）。
  • 保持视觉克制：避免导航栏拥挤、多行图标堆砌或页眉中出现重复控件。保持清晰的视觉层次、协调的内边距和恰当的留白。
  • 确保微文案简洁：避免大段说明文字、对显而易见的用户操作反复提示，以及防御性免责声明。UI 中的每条文案都必须简洁且达到生产级品质。
• **避免代码与接口冗长：**避免编写不必要的样板代码、冗长重复的封装，或只是复述显而易见语法的注释。绝不要为了显得面面俱到而让代码或文案膨胀。
• **杜绝显而易见的废话：**拒绝复述显而易见语法的代码注释（// return response、// increment i、// check if null）、仅仅重述符号名称的同义文档字符串、在显而易见的输入框下方居高临下的 UI 微文案（Email 字段下方的 "Please enter your email"），以及用琐碎前提常识（“需要互联网和键盘”）凑数的文档。高水平的工程纪律崇尚静默，而非噪声。
• 在适用时修改现有抽象；不要在当前没有需求时添加并行服务、辅助工具、框架、兼容层或可配置接口。
• 在架构支持的情况下，将业务逻辑与传输和展示分离；避免臃肿的上帝对象，也避免不必要的微型文件。
• 使用现有依赖和仓库惯例。新增依赖必须有明确的功能、维护、许可证、安全性及打包／运行时依据。
• 必要时保持错误语义、资源清理、取消操作、幂等性、状态隔离、数据验证、正确授权、事务和向后兼容性。
• 在功能性 PR 中避免大范围格式调整／重构；移除没有价值的附带脚手架。不要为了缩小差异而删除有效功能。

Gate 4：验证不能止步于测试通过

• 运行针对性测试，以及仓库支持的受影响完整测试套件检查；逐字报告命令和结果，或提供可复现的摘要。
• 对照基线检查变更的测试；手动独立验证预期结果。测试旧版失败情况、新行为、负向路径和附近的回归风险。
• 运行与变更相关的边界测试：适用时，涵盖契约/集成、并发、迁移、浏览器流程、性能、安全和无障碍性。在关键接缝处，优先采用真实集成证据，而非测试替身。
• 将测试覆盖率、Lint、快照更新和静态扫描结果视为信号，而非证明。条件允许时，针对脆弱的业务规则使用变异测试。
• 如果工具或环境阻碍验证，请注明 NOT VERIFIED；列出确切阻碍，不要声称工作已完成。

Gate 5：以挑剔的审查者视角审计差异

运行 git diff --check，并检查 git diff --stat、变更文件、变更断言、新增依赖、配置和文档。可通过高性能原生 Rust/Go 微服务或可移植的 Python 脚本进行分类：

# Native Rust Engine (SHIT Boundary Interceptor & Senior Dev Ladder):
bunx anti-slop-engineering rust triage
bunx anti-slop-engineering rust shit-check --diff patch.diff

# Go High-Throughput SRE Engine (KISS nesting, DRY token window, Toil & Error Budget):
bunx anti-slop-engineering toil audit
bunx anti-slop-engineering toil stream

# Zero-dependency Python Core Fallback:
python scripts/diff_guard.py --base HEAD --json
python scripts/sre_guard.py --base HEAD --strict --json

将 origin/main 替换为实际目标分支；如果该分支不可用，请使用 --base HEAD 与已知提交进行比较。如果有未跟踪的新文件，仅在获得授权时暂存预期文件，然后重新运行；工具会警告未跟踪内容不在检查范围内。**正则标记（包括琐碎的注释说明、居高临下的 UI 文案、推测性文档、开发说明和 SRE 规模隐患）只是调查线索，并非已确认缺陷。**该工具既不会运行测试，也不会执行 SAST。

明确自问：是否能用更精简的设计实现同样的目标（KISS）？是否创建了两个事实来源（DRY）？所有参数和选项是否都在实际使用（YAGNI）？在规模扩大时，重试是否会引发惊群或重试风暴（SCALE）？是否悄然扩大了范围？

Gate 6：证据与发布决策

使用 PR 审查协议 和 RUN_REPORT_TEMPLATE 中的报告模板。

• BLOCK（阻止）： 已证实的严重回归；授权/安全/隐私问题；未经批准的变更契约而禁用或伪造测试；构建失败；没有安全计划的破坏性迁移。
• REWORK（返工）： 实质性重复；不必要的架构；缺乏理由的新依赖；仅为适配实现而编写的测试；未解释的契约偏移；混杂变更导致无法审查。
• REVIEW（审查）： 大型且连贯的变更；外观层面的问题；静态启发式发现；需要结合上下文审查的刻意测试更新或例外。
• PASS（通过）： 有可观察证据表明需求已满足；不存在尚未解决的 BLOCK 或 REWORK，且已记录风险和例外。PASS 不构成保证。

建议合并前，报告：意图、变更文件、确切的测试证据、与基线相比的测试差异、剩余的不确定性、发现的问题和决策。未经许可且未遵守适用控制措施，不要合并、部署或更改受保护的设置。

不可妥协的反作弊规则

• 除非产品契约明确授权新输出，否则不要更改测试的预期输出来匹配观察到的错误输出。
• 不要删除、跳过、标记为预期失败、降低级别、通过 mock 隐去或抑制失败的测试来掩盖失败。
• 不要使用虚假日志、编造的基准测试、臆想的浏览器截图、测试结果或杜撰的源码引用。
• 不要仅为取得成功而放宽 lint、类型、安全、分支保护或 CI 策略。
• 不要把锁文件、依赖、格式、代码生成、数据库架构或测试固定数据作为附带损害进行修改。
• 没有证据和范围审批时，不要用全面重写取代有针对性的修复。
• 如果有官方语言、框架或 SDK 安装程序和样板，不要手动搭建项目骨架或拼凑配置文件。
• 不要根据模型训练记忆指定过时、已弃用或猜测的依赖版本；始终从官方注册表解析并强制使用最新稳定版本。
• 不要将开发者备注、Agent 提醒、模拟声明或架构致歉内容渲染到面向用户的 JSX/HTML 视图中。
• 不要在缺乏视觉层级的情况下，在页眉、导航栏或仪表板中堆满未经筛选的图标、重复按钮或多余组件。
• 不要用大段解释文字、防御性免责声明或对显而易见的 UI 控件进行冗长叙述来充斥 UI 文案。
• 不要编写琐碎的语法解说注释（例如 // return result、// increment counter、// check null），也不要编写仅仅重复符号名称的同义反复文档字符串。
• 不要添加居高临下的 UI 微文案，也不要在不言自明的控件下方添加显而易见的说明标签（例如 "Please enter your email"、"Click here to submit"）。
• 不要用显而易见的常识、琐碎的前置条件清单或同义反复的摘要来凑文档、README 或设置指南的篇幅。
• 不要违反直接载荷不变量：绝不要撰写说明如何点击、展开、播放、滚动或复制标准控件的操作解说、对话式前言（“以下部分将讨论……”）、双语标题堆叠（例如 Term · الترجمة），或在文档和代码中进行机械式手把手指导。
• 不要编造推测性的提交材料档案（例如 docs/*SUBMISSION*.md、docs/*DOSSIER*.md），也不要为未被要求的第三方平台虚构发布指南。
• 不要引用失效、已弃用或虚构的平台 URL（例如 platform.openai.com/plugins）。
• 不要在代码库中铺开仪式性的 Markdown 文件，也不要用营销废话、虚假的提示词示例或重复的提示框来充斥 README。
• 不要使用任意的 sleep() 或硬编码延迟循环来权宜处理异步竞争或不稳定测试的同步问题。
• 不要在没有指数退避和随机全抖动的情况下重试失败的网络操作。
• 不要在没有明确并发限制器或反压信号的情况下，生成无上限的并行任务、工作进程或 Promise。
• 不要在没有结构化日志或指标计数器的情况下，用空的 except: pass 或 catch {} 静默吞掉错误。
• 不要引入推测性参数（_unused_param、future_kwargs）、无效功能开关（if False:）或未引用的扩展点。
• 不要在多个模块中重复领域不变量、验证规则或错误模型；应维护唯一可信来源。
• 不要过度限制合理的设计：可读测试中的重复代码可能优于难以阅读的抽象，而为划定正确的安全边界，也可能需要更大的实现。

交付报告规范

对于每次实现或审查，都按以下顺序生成简明报告：**结果；范围；保留或变更的行为；验证（命令 + 结果）；问题及确切文件/行号；测试修改及理由；风险/限制；合并建议。**如有相关信息，请区分基线失败与新增失败。适用时，按原样使用 NOT RUN 和 UNKNOWN。

目录用于诊断；没有问题证据时，不应据此创建工作。