仓库中出现可复现且可由仓库修复的摩擦时，记录并维护…

在仓库开发中遇到其他贡献者也会遇到、且能通过修改仓库代码/配置/脚本/文档解决的摩擦时，用纸割日志记录、去重、审查和解决。

适用场景

解决思路

1. 在当下捕获小摩擦，但不要让它打断当前任务。
2. 记录门槛：不同贡献者在 fresh checkout 后也会遇到同一摩擦，且仓库能对此做点什么。
3. 用两问测试筛选，只有两个都为「是」才记录：不同人在 fresh checkout 后、在本仓库工作会撞到同一摩擦；它不是你 sandbox、shell 配置、机器、网络或一次性故障特有的。
4. 第二问：修改仓库的代码、配置、脚本或文档能防止或减少该摩擦。
5. 任一答案为「否」时，绕过它并继续，不记录。
6. 不记录你所在环境的失败：sandbox 的 `EPERM` / `listen` / IPC-socket 错误、被阻止的网络或 `fetch failed`、权限拒绝、缺失系统工具；那是 runner，不是仓库。
7. 不记录你自己的 shell 错误：保留字或特殊变量名（`status`、`path`）、未加引号的 glob、损坏的 login-shell hook；应修正命令，仓库里没有可打磨的东西。
8. 不记录瞬时 flakiness：命令重试后成功且没有仓库侧原因（网络抖动、push 挂起、镜像慢）。
9. 不记录你损坏的本地状态：切换分支后不完整的 `node_modules`、过期的 dev-server 端口、脏 cache；重新运行 install 或 cleanup。
10. 不记录仓库无法改变的第三方或 beta 工具限制——除非修复是值得写下来的仓库侧 workaround（那就记录那个 workaround）。
11. 不记录产品或代码正确性 bug（现在修复或作为真实工作跟踪），也不记录你完成了什么（那属于任务总结）。
12. 不记录 secrets、credentials、个人数据、原始客户 payloads 或敏感路径。
13. 失败时先问「这是仓库，还是我/我的环境？」只有前者算 papercut。
14. 主动记录时，先搜索 `.agents/PAPERCUTS.md` 中是否有等价条目，避免重复。
15. 在 `## Open` 下追加一个未勾选项，格式：`- [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — <friction, and the smallest useful fix or workaround>.`
16. 保持一到两句话：当前例子（命令/错误或受影响路径）、它阻塞谁或浪费什么时间、最小有用的仓库侧修复；以摩擦开头，不要以你当时在做什么开头。
17. 继续原始任务；不要把 papercut 扩展成无关工作。
18. 使用 UTC 时间戳和短 agent 标签（`codex`、`claude`、`human`）。只有当有助于未来 triage 时才添加 PR 或 task identifier。
19. 只在用户明确要求时，才挖掘整个 session 或做广泛 review。
20. 对于 review 或 prioritization 请求，检查并建议；除非用户也要求 cleanup 或 implementation，否则不要编辑日志或实现修复。
21. 执行授权 cleanup 时，使用同样的 triage。
22. 对每个 open entry 重新运行两问测试；建议移除未通过的条目（混入的环境/shell/flake 噪音）。
23. 去重并分组相关条目。
24. 检查每个保留下来的 papercut 是否仍能复现；区分已复现失败、源码检查、以及你无法验证的历史报告。
25. 按当前影响与 review/maintenance 成本排优先级；优先使用现有命令或简短文档修复，而不是新 helpers、dependencies 或 setup hooks；将假设性改进推迟到具体需求出现。
26. 对于授权 cleanup，移除噪音、合并重复项，并实现已同意的修复。
27. 将已修复项移到 `## Resolved`，勾选它们，并追加解决日期或 commit。
28. 将 deferred reports 与 actionable open work 分开，附上原因和具体重新审视触发条件。
29. 将真实 bug 转到正常 issue/fix 工作；将反复出现的 review-policy gaps 转到 `maintain-greptile-rules`。
30. 为真正已解决的 papercuts 保留有用历史；不要仅仅为了让文件更短而删除它们。从未属于该文件的噪音（见步骤 1）不同：应移除。

适用边界 · 注意事项

• 当摩擦只存在于你的环境（sandbox/权限/网络/系统工具）、自己的 shell 错误、瞬时 flakiness、损坏的本地状态，或第三方/beta 工具限制且仓库无法改变时，不适用。
• 当问题属于产品或代码正确性 bug，或你只是记录自己完成了什么时，不适用。
• 当内容涉及 secrets、credentials、个人数据、原始客户 payloads 或敏感路径时，不适用。