gap-trap

gap-trap

为主要由 Agent 编写代码的代码仓库搭建质量框架。Agent 遵循的每条规则都必须有一道关卡：违反规则时，关卡会阻止提交、推送或 CI 运行。某条规则如果可以由脚本检查，却没有指定关卡，就是一个缺陷。该框架详见 reference/framework.md；开始任一模式前，请先阅读。

两种模式：setup 会在尚未建立框架的代码仓库中搭建框架。 refine 会审查已建立框架的代码仓库，并根据已发生的问题提出下一批规则和关卡。 如果没有指定关键词，直接运行 gap-trap 时，若代码仓库中没有 AGENTS.project.md，则使用 setup；否则使用 refine。单独存在的手写 AGENTS.md 或 CLAUDE.md 是 setup 的输入，不代表框架已经建立。

模型关卡

此技能需使用你所处环境中的顶级编码模型运行：在 Claude Code 中，使用 Opus 或更强的模型（Opus 4.8 或更新版本、Opus 5、Fable、Mythos）；在 Codex 中，使用前沿编码模型，并采用 high 或 xhigh 推理强度。 代码库分析将决定哪些部分需要契约，而错误的契约会影响之后的每次会话。你的系统提示词会注明你使用的模型。

如果你使用的是更便宜或更快的模型档位（Sonnet、Haiku、mini 模型或低推理强度），请停止。不要读取任何内容，也不要写入任何内容。请原样说出以下内容，然后结束本轮：

gap-trap runs on the top coding model of this harness. You are on . Switch with /model, then run gap-trap again.

不要让较弱的协调模型派遣更强的子 Agent，不要只做“简单部分”，也不要提供简化版本。

setup

1. 发现。 按照 reference/discovery.md 执行。它会在你的临时目录中生成计划文件，内容包括：技术栈、命令、CI 提供方、包含真实符号名称的契约候选项、从历史记录中发现的首批领域事实（无论提交数量多少都会运行回滚探测），以及现有指令文件中每条规则的去向和门禁说明。
2. 确认一次。 用简短列表展示计划：你将编写的契约（最多六条）、将添加的门禁、找到的测试和 lint 命令、迁移规则表，以及 slop-mop 的安装位置。如果构建、类型检查或 lint 当前已报错，应首先列出：设置阶段只修复其自身门禁文件所需的问题（例如缺少类型包、锁文件），其余问题记录为棘轮计数或范围外条目。记录每项错误前，先指出其原因：复现问题、阅读失败信息，并说明具体哪里出了问题。错误信息中提到环境变量，也可能是代码缺陷。在一次试验中，有七项测试因 Environment variable not found: DATABASE_URL 失败，原因是 Prisma 模拟对象在被测模块加载后才加载，并非缺少 .env；若将其记录为环境缺失，就会掩盖这个缺陷以及防止该问题的契约。只针对发现阶段无法确定的事项提一轮问题，然后继续。
3. 安装 slop-mop。 将 slop-mop/slop-mop 通过 git clone https://github.com/pliablepixels/slop-mop.git 克隆到你的临时目录，并将其复制到当前运行环境的技能目录（Claude Code：~/.claude/skills/；Codex：~/.agents/skills/）；如果已存在则跳过。不要将其作为 vendored 内容放进仓库；AGENTS.project.md 中的项目规则要求安装它。运行环境会在会话启动时加载技能列表，因此本次安装的技能无法用于安装它的这次运行：将本次运行的文字按 P10 的要求写入 AGENTS.md，并在报告中告知用户 slop-mop 从下次会话开始生效。
4. 根据 templates/ 编写指令文件。 AGENTS.md 和 agents/generic/agent-workflows.md 应原样复制，只有一项例外：如果某条规则的门禁在此仓库中无法存在（例如没有 UI 的仓库中，I3 的无障碍 lint 和 C3 的本地化内容），则将其 Gate: 子句替换为 Gate: n/a, no <thing> in this repo。不得对 AGENTS.md 做其他改动。根据计划填写 AGENTS.project.md、CLAUDE.md 和 agents/project/；如果仓库没有 UI，则删除 UI 和端到端相关行以及 {{E2E_CMD}}，并删除所有无法用已验证值填写的占位符。契约只能使用真实符号名称。根据计划中的迁移规则表，逐条迁移现有指令文件（AGENTS.md、CLAUDE.md、.cursorrules、.github/copilot-instructions.md、CONTRIBUTING.md）：契约行改为契约块；规则行改为带有门禁名称或 Gate: review 的项目规则；操作指南行逐字放入指定的 agents/project/ 文件；命令行用于填写验证区块；重复或丢弃的行则不保留。不得悄然丢弃任何规则；确认步骤已展示该表。模板拥有的文件名（AGENTS.md、CLAUDE.md）应由对应模板替换。其他任何指令文件（.cursorrules、.github/copilot-instructions.md）都应改为一行指向 AGENTS.md 的内容，让读取该文件的 Agent 找到规则，而不是过时的副本。CONTRIBUTING.md 保持原位。用户会看到差异。
5. 根据 reference/gates.md 编写门禁，使用仓库自己的测试运行器和 CI 提供方： 指令门禁、已验证的失败门禁、PR 正文检查、棘轮（始终添加，并用仓库支持的计数器初始化：超过 C2 长度的文件数、运行 lint 时每条规则的 lint 问题数、当前存在违规的每条契约 Never 子句）；如果发现阶段指出了高风险模块（身份验证、解析器、API 客户端），还要添加变异测试冒烟检查；否则在首次修复链后由 refine 添加。该文件中的技术栈表用于选择参考实现：Node 和 Python 使用原生移植版本，其他所有语言使用只需 git、grep 和 awk 的 shell 参考实现。将指令门禁的字数预算设置为当前字数加一半，并向上取整到下一个 500。
6. 通过临时违规证明每个门禁会失败， 移除违规，运行仓库的完整测试命令，并按以下顺序每次提交一个逻辑变更：先提交带有对应检查门禁的指令文件；之后每个门禁各提交一次（棘轮、已验证的失败门禁、变异测试冒烟检查、PR 正文检查）；再提交组合门禁命令和 pre-commit 钩子；最后提交 CI。把整个框架放在一个提交中，会掩盖每个门禁是针对什么情况验证失败的，也无法单独回滚。除非有人要求，否则不要推送。
7. 报告已编写的内容、指令字数及其预算、哪些契约标记为 Gate: review 以及原因、本次运行是否安装了 slop-mop（如果安装，则说明从下次会话开始生效），以及仓库外任何始终加载且文风与仓库冲突的文件（~/.codex/AGENTS.md、~/.claude/CLAUDE.md，或简短、压缩的内部风格）：写明文件名，并说明仓库规则适用于仓库内的文字。最后只给出一个下一步：在首次发生问题后或一个月后运行 gap-trap refine。
8. 提供检查选项。 报告末尾只问一个问题：现在要根据新框架检查仓库吗？如果回答否，则停止。如果回答是，不要更改任何文件，并按契约或规则 ID 分组列出：
   • 每个棘轮计数器、其计数，以及该计数器每个计数单位所对应的文件和行号；
   • 每个 Gate: review 契约：阅读其 Path: 和 Never: 行所涵盖的代码，并列出疑似违规项及其文件和行号，同时标记为未经验证，因为没有门禁检查它们；
   • 第 2 步记录的构建、类型检查或 lint 报错项。 此轮不要修复任何问题。用户选定的修复应单独提交；降低计数的修复应使用 --update 重新运行棘轮。 指令文件由 Agent 阅读。请将其写成带 ID 和门禁名称的简洁陈述。 面向人的说明性文字应放在仓库的文档中， 而不是放在 AGENTS*.md 或 agents/ 中。

refine

遵循 reference/refine.md。它会审查没有门禁的规则、不再存在的 契约名称，以及上次 refine 以来的提交历史，并通过自我改进协议 将编辑提议合并为一个 PR。对于没有事故作为依据的规则，它会像 添加门禁一样，毫不犹豫地将其删除。

常见错误

错误	修正方法
契约使用了猜测的符号名称	Path: 行中的每个名称都能在代码树中通过 grep 找到；否则指令门禁会失败
第一天就写十个契约	从有唯一认可路径且当前存在违规的地方开始；其余内容通过 refine 添加
门禁首次运行就通过	先用临时违规证明它会失败；从未失败过的门禁毫无证明力
将 slop-mop 复制进仓库	它会从自己的仓库按 Agent 安装；项目规则要求使用它
为人润色指令说明文字	Agent 会阅读这些内容。写成陈述、用一个分句说明原因，并注明门禁名称
因为仓库很小而跳过模型门禁	交付成果是发现质量；门禁排在第一位是有原因的