papercuts

小摩擦

及时记录那些小小的不便，不要因此打断当前任务。 汇总后的条目会显示仓库哪些地方需要打磨——因此，记录标准是：_其他_贡献者也会遇到同样的问题，并且_仓库_能够对此采取措施。

两个问题的检验标准

只有在以下两点都成立时才记录：

1. 任何人都能复现。 其他人在全新检出后，在此仓库中工作，也会遇到同样的不便。这不是特定于你的沙箱、shell 配置、机器、网络或一次性故障的问题。
2. 能在仓库中修复。 修改仓库的代码、配置、脚本或文档，就能避免或减轻这个问题。

只要有一个答案是“否”，就继续处理并往下做——不要记录。

请勿记录

• 你环境中的故障。 沙箱中的 EPERM / listen / IPC-socket 错误、网络受阻或 fetch failed、权限拒绝、缺少系统工具。这是运行环境的问题，不是仓库的问题。
• 你自己的 shell 操作失误。 保留或特殊变量名（status、path）、未加引号的 glob、损坏的登录 shell hook。修正命令即可——仓库没有需要打磨的地方。
• 暂时性的故障。 没有仓库方面原因、重试后就成功的命令（网络短暂中断、推送卡住、镜像响应慢）。
• 被你弄坏的本地状态。 切换分支后不完整的 node_modules、过期的开发服务器端口、脏缓存。重新运行安装或清理操作即可。
• 仓库无法更改的第三方工具或测试版工具限制——除非解决方法是值得记录的仓库侧变通方案（这种情况下，记录_该_变通方案）。
• 产品或代码正确性问题（立即修复或作为正式工作跟踪），以及你完成的工作（应放在任务摘要中）。
• 密钥、凭证、个人数据、原始客户负载或敏感路径。

遇到故障时，先问：“这是仓库的问题，还是我／我的环境的问题？”只有前者才算小摩擦。

主动记录

1. 搜索 .agents/PAPERCUTS.md，查看是否已有类似条目，避免重复。

2. 在 ## Open 下追加一条未勾选事项，使用以下格式：

   - [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — <friction, and the smallest useful fix or workaround>.
   

3. 控制在一到两句话：说明当前示例（命令／错误或受影响路径）、会阻碍谁或浪费多少时间，以及最小且有效的仓库侧修复方案。开头先写不便本身，而不是你当时在做什么。

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

使用 UTC 时间戳和简短的 Agent 标签（codex、claude、human）。只有在有助于后续分流时，才添加 PR 或任务标识符。

审查或解决

只有在用户明确要求时，才全面检查整个会话或进行广泛审查。

对于审查或优先级排序请求，应进行检查并给出建议；除非用户同时要求清理或实施，否则不要编辑日志或实施修复。 执行获准的清理时，使用相同的分流流程：

1. 对每条未解决条目重新进行两问测试；对于未通过测试的条目（混入其中的环境、Shell 或 flake 噪声），建议移除。
2. 去重并归类相关条目。
3. 检查每个保留的痛点是否仍能复现。区分已复现的故障、源码检查结果，以及无法验证的历史报告。
4. 根据当前影响与审查和维护成本确定优先级。优先考虑现有命令或简短的文档修复，而非新增辅助工具、依赖或设置钩子。将假设性的改进推迟到出现具体需求时再处理。
5. 对于获准的清理，移除噪声、合并重复项并实施已商定的修复。将已修复的项目移至 ## Resolved，标记完成，并附上解决日期或提交记录。将推迟处理的报告与可执行的未完成工作分开，并注明推迟原因及具体的重新评估触发条件。将实际缺陷转入常规的问题处理与修复流程；将反复出现的审查策略缺口转交给 docs/maintainers/review-guidelines.md。

对于确实已解决的痛点，应保留有用的历史记录；不要仅仅为了缩短文件而将其删除。（从未应该收录的噪声——见第 1 步——则应移除。）