Communitygithub.com

lMysticl/bug-receipt

便携式智能体技能:提供有证据支持的Bug修复、根因分析及可验证的AI编码结果。

bug-receipt 是什么?

Bug Receipt 是一个专为 AI 编码智能体设计的便携式技能,旨在强制在每次缺陷或事件关闭时输出结构化的、可验证的“收据”。它通过一个固定的文本格式收据,要求智能体明确记录问题、基线、根因、更改、证据和差距,从而根本性地解决 AI 代理工作流中常见的“幻觉”和证据不透明问题。该技能支持 Cursor、Claude Code 等主流 AI 编码平台,通过强制一个严格的证据边界和验证闭环来工作。它要求智能体在编辑代码前记录观察到的行为和预期行为,通过实时执行或提供的证据来追溯根因,最后根据其证据的完整性程度将状态标记为 VERIFIED、PARTIAL 或 BLOCKED,从而为用户提供完全可审计且不可否认的修复过程。这对于调试、代码审查以及建立对 AI 生成补丁的信心至关重要。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add lMysticl/bug-receipt

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Bug 收据

强制结束输出

对于每个 Bug 或事件结束决策,必须返回以下完整的收据作为面向用户的全部结果,即使当用户要求简洁回复或未指名此格式时也是如此。简洁只会缩短字段值;绝不会移除或重命名某行。不要用散文替换收据。

BUG RECEIPT · VERIFIED | PARTIAL | BLOCKED

Problem    <观察到的缺陷和预期行为>
Baseline   <失败的交互或命令及决定性的结果;或 not run>
Root cause <已证实的机制;或未证实的假设>
Change     <负责的变更;或 none>
Proof      <提供或执行的检查:结果;包括每一个决定性的层面>
Gaps       <none;或确切的缺失证据及下一个实验/包>
Source     executed now | supplied | mixed

明确使用 not run、unproven 或 none。绝不要为了看起来完整而省略某行。

建立证据边界

在编辑之前,记录观察到的缺陷、预期行为、最强直接检查以及证据来源:executed now、supplied 或 mixed。切勿暗示提供的证据是在当前运行中执行的。

保持证据的隐私最小化。编辑凭据、令牌、Cookie、个人数据、私人 URL 和敏感负载;仅保留重现或关联失败所需的标识符和摘录。

尽可能通过最窄的安全检查重现失败。如果无法重现,则保留已获得的证据并将结果限制为 PARTIAL 或 BLOCKED。

追踪与修复

  1. 沿着实时所有者路径从输入追踪到症状。
  2. 分离观察到的事实、有限推断和差距。
  3. 在命名根因之前,需要具体的位置或运行时转换。
  4. 做出最小影响的变更;避免不相关的清理、重试、静默回退和特定于测试夹具的异常。

不要将合理的补丁、过时的日志、源代码阅读或通过的构建转换为用户可见行为的证明。

关闭验证循环

仅执行受影响合约所需的检查:

  • 原始重现或直接验收检查;
  • 最近的负向或回归检查;
  • 受影响的构建或集成门控;
  • 当主张跨越该边界时,真实的 UI、API、持久性、并发或运行时路径。

使用这些决定性的边界:

表面所需直接证据
逻辑或失败的测试原始失败输入或聚焦测试现在通过
UI 行为真实的交互以及相关的控制台和网络观察
API 或集成请求、响应和负责服务的行为
持久性通过真实所有者路径的写入/读取或重新加载往返
竞态或生命周期重复的并发触发;成功次数为零或一;受影响行和事务证据;最终不变量
跨系统阻塞一个经过筛选的失败请求/响应(带有时间戳或请求 ID)、边缘和服务应用程序日志,以及当追踪到达该所有者时的身份提供商日志

分配状态

  • VERIFIED:观察到的基线、具体原因、负责的变更、所有声明的检查已通过、无实质性差距。
  • PARTIAL:存在有用的证据,但所需的验证层面缺失或不具决定性。
  • BLOCKED:特定的外部条件阻止了重现、修复或验证。

对于 PARTIAL 或 BLOCKED,要指明能够弥合决定性差距的单一最小实验或相关证据包。切勿编造命令、观察、计数、位置或结果。

有关机器可读的收据或 CI 集成,请阅读 references/receipt-contract.md 并遵循其 JSON 字段、证据来源标记、兼容性规则和状态不变量。

当请求 JSON 工件时,从 assets/receipt.template.json 开始,将其写入任务拥有的路径,并使用本技能目录中的 node scripts/validate-receipt.mjs <receipt.json> 进行验证。除非用户请求,否则不要提交生成的收据。

相关技能