SuperAPI AI 工具集

papercuts

编程与开发

查看项目

更新于 10-16 22:15

技能介绍

Papercuts

在当下捕捉小摩擦,而不打断当前任务。聚合后的条目能显示仓库哪里需要打磨——因此门槛是:另一位贡献者会撞上同样的问题,并且仓库能对此做点什么。

两问测试

只有以下两点同时成立时才记录:

  1. 对任何人都可复现。 换一个人,在全新检出、于本仓库中工作时,会撞上同样的摩擦。它不是你的沙箱、shell 配置、机器、网络特有的,也不是一次性小故障。
  2. 可在仓库内修复。 对仓库代码、配置、脚本或文档的改动能够防止或减少它。

如果任一答案为“否”,就硬扛过去、继续前进——不要记录。

不要记录

  • 你的环境故障。 沙箱 EPERM / listen / IPC-socket 错误、被阻断的网络或 fetch failed、权限拒绝、缺少系统工具。那是运行器的问题,不是仓库的问题。
  • 你自己的 shell 失误。 保留字或特殊变量名(status、path)、未加引号的 glob、损坏的登录 shell 钩子。修好命令即可——仓库里没有什么可打磨的。
  • 偶发不稳定。 重试后成功、且没有仓库侧原因的命令(网络抖动、推送卡住、镜像缓慢)。
  • 你自己弄坏的本地状态。 切换分支后残缺的 node_modules、过期的开发服务器端口、脏缓存。重新运行安装或清理即可。
  • 仓库无法改变的第三方或测试版工具限制——除非修复方案是值得写下来的仓库侧变通办法(那就记录_那个变通办法_)。
  • 产品或代码正确性缺陷(立即修复或作为真实工作跟踪),以及你完成了什么(那属于任务总结)。
  • 机密、凭据、个人数据、原始客户载荷或敏感路径。

当某件事失败时,先问“这是仓库的问题,还是我/我的环境的问题?”只有前者才是 papercut。

主动记录

  1. 在 .agents/PAPERCUTS.md 中搜索等价条目,避免重复。

  2. 在 ## Open 下追加一条未勾选项,使用以下格式:

    - [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — <摩擦,以及最小可用的修复或变通办法>。
    
  3. 保持在一两句话:一个当前示例(命令/错误或受影响的路径)、它阻塞了谁或浪费了什么时间,以及最小可用的仓库侧修复。以摩擦开头,而不是以你当时在做什么开头。

  4. 继续原任务。不要把一条 papercut 扩展成无关的工作。

使用 UTC 时间戳和简短的 agent 标签(codex、claude、human)。仅当有助于未来分诊时才添加 PR 或任务标识符。

审查或解决

仅在用户明确要求时,才挖掘整个会话或做广泛审查。

对于审查或优先级排序请求,只检查并给出建议;除非用户同时要求清理或实现,否则不要编辑日志或实施修复。使用同样的分诊执行获授权的清理:

  1. 对每条未关闭条目重新运行两问测试;建议移除未通过测试的条目(混入的环境/shell/偶发噪声)。
  2. 去重并归并相关条目。
  3. 检查每条存活的 papercut 是否仍可复现。区分已复现的失败、源码检查和无法验证的历史报告。
  4. 根据审查与维护成本,对当前影响排优先级。优先使用现有命令或简短的文档修复,而非新增辅助工具、依赖或安装钩子。把假设性的改进推迟到出现具体需求时。
  5. 对于获授权的清理,移除噪声、合并重复项,并实施商定的修复。把已修复项移到 ## Resolved,勾选它们,并追加解决日期或提交。把推迟的报告与可执行的未关闭工作分开,附上原因和重新审视的具体触发条件。把真实缺陷转给常规 issue/修复工作;把反复出现的审查策略缺口转给 docs/maintainers/review-guidelines.md。

为真正已解决的 papercut 保留有用的历史;不要仅仅为了让文件更短就删除它们。(从来就不该存在的噪声——见第 1 步——则不同:移除它。)