SKILL.md
只读
名称
papercuts
描述
将真实、反复出现的仓库摩擦记录到 .agents/PAPERCUTS.md — 令人困惑的设置、不稳定的仓库命令或脚本、仓库内误导性错误、过时的生成文件，或会浪费下一位贡献者时间的非显而易见的陷阱。也用于审查、去重和解决现有条目。记录前严格把关：只有仓库本身能修复的摩擦才算数。绝不记录代理自身的沙箱/权限错误、shell 脚本错误、瞬时波动或仓库无法改变的第三方工具怪癖。
小摩擦
在不偏离当前任务的情况下，及时捕捉小的摩擦。汇总的条目显示仓库需要打磨的地方——因此标准是：_另一个_贡献者会遇到同样的问题，并且_仓库_可以对此采取措施。
两个问题测试
仅当两个都为真时才记录：
- 对任何人都可复现。 一个不同的人，在新检出中，在此仓库工作时会遇到同样的摩擦。它不是特定于你的沙箱、shell 配置、机器、网络或一次性故障。
- 可在仓库中修复。 对仓库的代码、配置、脚本或文档的更改可以防止或减少它。
如果任一答案为“否”，就继续推进，不要记录。
不要记录
- 你的环境的失败。 沙箱
EPERM/listen/ IPC 套接字错误、网络阻塞或fetch failed、权限拒绝、缺少系统工具。那是运行器的问题，不是仓库的问题。 - 你自己的 shell 错误。 保留或特殊变量名（
status、path）、未加引号的通配符、损坏的登录 shell 钩子。修复命令——仓库中没有什么需要打磨的。 - 瞬时波动。 重试后成功且没有仓库侧原因的命令（网络故障、挂起的推送、慢速镜像）。
- 你损坏的本地状态。 分支切换后部分
node_modules、过时的开发服务器端口、脏缓存。重新运行安装或清理。 - 仓库无法改变的第三方或测试工具限制——除非修复是值得写下的仓库侧变通方法（然后记录_那个_变通方法）。
- 产品或代码正确性错误（立即修复或作为实际工作跟踪），以及你完成了什么（那属于任务摘要）。
- 机密、凭据、个人数据、原始客户负载或敏感路径。
当某件事失败时，首先问“这是仓库的问题，还是我/我的环境的问题？”只有前者才是小摩擦。
主动记录
-
搜索
.agents/PAPERCUTS.md以查找等效条目并避免重复。 -
在
## Open下追加一个未勾选的条目，使用以下格式：- [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — <摩擦，以及最小的有用修复或变通方法>。 -
保持在一两句话：什么阻碍了，以及可能的仓库侧修复。以摩擦开头，而不是你正在做什么。
-
继续原始任务。不要将小摩擦扩展为无关的工作。
使用 UTC 时间戳和简短的代理标签（codex、claude、human）。仅在有助于未来分类时添加 PR 或任务标识符。
审查或解决
仅在用户明确要求时，才挖掘整个会话或进行广泛审查。
当被要求审查文件时：
- 对每个未解决条目重新运行两个问题测试；删除任何未通过的条目（混入的环境/shell/波动噪音）。
- 去重并分组相关条目。
- 验证每个幸存的摩擦是否仍然可复现。
- 首先修复最小、安全、高杠杆的条目。
- 将已修复的项目移至
## Resolved，勾选它们，并附加解决日期或提交。将真正的错误路由到正常的 issue/修复工作；将反复出现的审查策略差距通过maintain-greptile-rules路由。
保留真正解决的摩擦的有用历史；不要仅仅为了缩短文件而删除它们。（从未属于的噪音——参见步骤 1——不同：删除它。）
