papercuts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Papercuts

Capture small friction in the moment without derailing the current task. Aggregated entries show where the repository needs sanding down — so the bar is that a different contributor would hit the same thing, and the repository can do something about it.

记录当下遇到的小摩擦，同时不中断当前任务。汇总的条目可以显示仓库需要优化的地方——判断标准是：其他贡献者也会遇到同样的问题，且仓库能够对此采取措施。

The two-question test

双问题测试

Log it only if both are true:

Reproducible for anyone. A different person, on a fresh checkout, working in this repo would hit the same friction. It is not specific to your sandbox, shell config, machine, network, or a one-time hiccup.
Fixable in the repo. A change to the repo's code, config, scripts, or docs would prevent or reduce it.

If either answer is "no," push through it and move on — do not log it.

只有当以下两个条件同时满足时，才进行记录：

任何人都可复现：不同的人在全新检出的仓库中工作时，会遇到相同的摩擦。该问题并非特定于你的沙箱环境、Shell 配置、机器、网络，或是一次性故障。
可在仓库内修复：通过修改仓库的代码、配置、脚本或文档，能够避免或减轻该问题。

如果任一答案为“否”，则跳过该问题继续任务——不要记录它。

Do NOT log

请勿记录

Your environment's failures. Sandbox
```
EPERM
```
/
```
listen
```
/ IPC-socket errors, blocked network or
```
fetch failed
```
, permission denials, missing system tools. That is the runner, not the repo.
Your own shell mistakes. Reserved or special variable names (
```
status
```
,
```
path
```
), unquoted globs, a broken login-shell hook. Fix the command — there is nothing in the repo to sand down.
Transient flakiness. A command that succeeded on retry with no repo-side cause (a network blip, a hung push, a slow mirror).
Local state you corrupted. A partial
```
node_modules
```
after branch-switching, a stale dev-server port, a dirty cache. Re-run the install or cleanup.
Third-party or beta-tool limitations the repo can't change — unless the fix is a repo-side workaround worth writing down (then log that workaround).
Product or code correctness bugs (fix now or track as real work), and what you accomplished (that belongs in the task summary).
Secrets, credentials, personal data, raw customer payloads, or sensitive paths.

When something fails, first ask "is this the repo, or is this me/my environment?" Only the former is a papercut.

你的环境故障：沙箱的
```
EPERM
```
/
```
listen
```
/ IPC 套接字错误、网络受阻或
```
fetch failed
```
、权限拒绝、缺失系统工具。这些属于运行环境问题，而非仓库本身的问题。
你自身的 Shell 操作失误：使用保留或特殊变量名（
```
status
```
、
```
path
```
）、未加引号的通配符、损坏的登录 Shell 钩子。修正你的命令即可——仓库中没有需要优化的内容。
临时性不稳定问题：无需修改仓库，重试即可成功的命令（如网络波动、推送挂起、镜像缓慢）。
你损坏的本地状态：切换分支后不完整的
```
node_modules
```
、过时的开发服务器端口、脏缓存。重新运行安装或清理命令即可。
仓库无法改变的第三方或测试版工具限制——除非存在值得记录的仓库侧解决方案（此时需记录该解决方案）。
产品或代码正确性 bug（应立即修复或作为正式工作跟踪），以及你已完成的工作（应归入任务摘要）。
机密信息、凭证、个人数据、原始客户负载或敏感路径。

当出现问题时，首先问自己：“这是仓库的问题，还是我/我的环境的问题？”只有前者才属于 Papercut。

Log proactively

主动记录

Search
```
.agents/PAPERCUTS.md
```
for an equivalent entry and avoid duplicates.

Append one unchecked item under

## Open

using this format:

markdown

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

Keep it to one or two sentences: what got in the way, and the likely repo-side fix. Lead with the friction, not with what you were doing.
Continue the original task. Do not expand a papercut into unrelated work.

Use UTC timestamps and a short agent label (

codex

claude

human

). Add a PR or task identifier only when it helps future triage.

在
```
.agents/PAPERCUTS.md
```
中搜索是否存在等效条目，避免重复记录。

在

## Open

下添加一个未勾选的条目，格式如下：

markdown

- [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — <摩擦内容，以及最小可行的修复或解决方案>。

控制在一到两句话：说明遇到的障碍，以及可能的仓库侧修复方案。先描述摩擦，再说明你当时正在做的事情。
继续执行原任务。不要将 Papercut 扩展为无关工作。

使用 UTC 时间戳和简短的 Agent 标签（如

codex

、

claude

、

human

）。仅当有助于未来分类处理时，才添加 PR 或任务标识符。

Review or resolve

审核或解决问题

Only mine a whole session or do a broad review when the user explicitly asks.

When asked to review the file:

Re-run the two-question test on every open entry; delete any that fail it (environment/shell/flake noise that slipped in).
Deduplicate and group related entries.
Verify each surviving papercut still reproduces.
Fix the smallest safe, high-leverage entries first.
Move fixed items to
```
## Resolved
```
, check them, and append the resolving date or commit. Route real bugs to normal issue/fix work; route recurring review-policy gaps through
```
maintain-greptile-rules
```
.

Preserve useful history for genuinely-resolved papercuts; do not delete them merely to make the file shorter. (Noise that never belonged — see step 1 — is different: remove it.)

仅当用户明确要求时，才对整个会话进行梳理或进行全面审核。

当被要求审核该文件时：

对每个未解决的条目重新执行双问题测试；删除任何不符合条件的条目（即混入的环境/Shell/临时性故障噪音）。
对相关条目进行去重和分组。
验证每个留存的 Papercut 是否仍可复现。
优先修复最小、最安全且影响力最大的条目。
将已修复的条目移至
```
## Resolved
```
，勾选复选框，并添加修复日期或提交记录。将真实的 bug 转至常规的问题修复流程；将反复出现的审核政策漏洞通过
```
maintain-greptile-rules
```
处理。

保留已真正解决的 Papercut 的有用历史记录；不要仅仅为了缩短文件长度而删除它们。（而第一步中提到的不属于记录范围的噪音则不同：应予以删除。）