papercuts について
リポジトリ内で修正でき、誰でも再現する小さな不便を記録するスキルです。環境の問題や一時的な失敗、個人の操作ミスと、対処可能な課題を区別できます。
主な機能
- 012段階の記録判定
- 02記録前の重複確認
- 03時刻付きの項目形式
- 04レビューと整理のガイド
- 05分類と優先順位付けの基準
活用シーン
- 01繰り返し起きるセットアップの不便を記録
- 02環境固有の失敗を除外
- 03既存の記録をレビュー
- 04小さなリポジトリ修正の優先順位付け
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/papercutsを入力して読み込まれたか確認します。
詳細
Papercuts
現在のタスクを中断せずに、小さな不便をその場で記録します。 記録を集約すると、リポジトリで改善すべき箇所が見えてきます。つまり、基準となるのは、_別の_コントリビューターも同じ問題に遭遇し、_リポジトリ_側で対処できることです。
2つの質問による判定
両方に当てはまる場合にのみ記録してください。
- 誰でも再現できる。 新しいチェックアウトを使い、このリポジトリで作業する別の人も同じ不便に遭遇します。自分のサンドボックス、シェル設定、マシン、ネットワーク、または一時的な不具合に固有の問題ではありません。
- リポジトリ側で修正できる。 リポジトリのコード、設定、スクリプト、またはドキュメントを変更すれば、その不便を防止または軽減できます。
どちらか一方でも「いいえ」なら、そのまま作業を進めてください。記録しないでください。
記録しないこと
- 自分の環境で発生した失敗。 サンドボックスの
EPERM／listen／ IPC ソケットのエラー、ネットワークのブロックやfetch failed、権限エラー、システムツールの不足。原因はランナーであり、リポジトリではありません。 - 自分のシェル操作のミス。 予約語や特殊な変数名（
status、path）、引用符で囲んでいないグロブ、壊れたログインシェルのフック。コマンドを修正してください。リポジトリ側で改善できることはありません。 - 一時的な不安定さ。 リポジトリ側に原因がなく、再試行で成功したコマンド（ネットワークの瞬断、プッシュのハング、ミラーの遅延など）。
- 自分で壊したローカルの状態。 ブランチ切り替え後の不完全な
node_modules、古い開発サーバーのポート、汚れたキャッシュ。インストールまたはクリーンアップを再実行してください。 - リポジトリ側で変更できない、サードパーティ製ツールまたはベータ版ツールの制限。ただし、記録する価値のある回避策をリポジトリ側で用意できる場合は、その回避策を記録してください。
- 製品やコードの正確性に関わるバグ（すぐに修正するか、実作業として追跡してください）、および達成したこと（タスクの概要に記載してください）。
- シークレット、認証情報、個人データ、生の顧客ペイロード、機密性の高いパス。
何かが失敗したら、まず「原因はリポジトリか、それとも自分／自分の環境か？」と考えてください。記録するのは前者だけです。
積極的に記録する
-
.agents/PAPERCUTS.mdを検索して同等の項目がないか確認し、重複を避けます。 -
次の形式で、
## Openの下に未チェックの項目を追加します。- [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — <friction, and the smallest useful fix or workaround>. -
1〜2文にまとめます。現在の事例（コマンド／エラーまたは影響を受けるパス）、作業を妨げる人や無駄になる時間、リポジトリ側でできる最小限の有効な修正を記載します。何をしていたかではなく、不便な点から書き始めてください。
-
元のタスクを続けます。無関係な作業にまでペーパーカットへの対応を広げないでください。
UTC のタイムスタンプと短いエージェントのラベル（codex、claude、human）を使用します。今後のトリアージに役立つ場合にのみ、PR またはタスクの識別子を追加してください。
レビューまたは解決
ユーザーから明示的に依頼された場合に限り、セッション全体を調査するか、広範なレビューを行います。
レビューまたは優先順位付けの依頼では、調査して提案してください。ユーザーが整理または実装も依頼していない限り、ログを編集したり、修正を実装したりしないでください。許可された整理を行う場合は、同じトリアージ手順に従ってください。
- 未解決の各項目について、2つの質問によるテストを再度行います。テストに合格しない項目（紛れ込んだ環境／シェル／フレークノイズ）は削除を提案してください。
- 重複を排除し、関連する項目をまとめます。
- 残った各ペーパーカットが現在も再現するか確認します。再現した不具合、ソースコードの調査で確認した内容、検証できなかった過去の報告を区別してください。
- 現在の影響度とレビューおよび保守のコストを照らし合わせて優先順位を付けます。新しいヘルパー、依存関係、セットアップフックよりも、既存のコマンドや短いドキュメントの修正を優先してください。仮定に基づく改善は、具体的な必要性が生じるまで見送ってください。
- 整理が許可された場合は、ノイズを削除し、重複を統合して、合意した修正を実装します。修正済みの項目は
## Resolvedに移動してチェックし、解決日またはコミットを追記してください。見送った報告は、再検討する理由と具体的な条件を添えて、対応可能な未解決作業とは分けてください。実際のバグは通常の課題／修正作業に回し、繰り返し発生するレビューポリシーの不備はdocs/maintainers/review-guidelines.mdに記録してください。
実際に解決したペーパーカットの有用な履歴は残してください。ファイルを短くするためだけに削除してはいけません。（初めから記録すべきでなかったノイズは別です。手順1を参照してください。削除してください。）