show-me-your-work

作業内容を記録する

人が後から確認する作業では、判断の経緯を残しておくと、作業をやり直したり、やり取り全体を読んだりせずに、何を、なぜ、どの証拠に基づいて決めたのかを再構成できます。記録を一元化し、経緯に一貫性を持たせ、後のエージェントが見つけられるようにしてください。

形式

判断ごとに1行を記録する単一のTSVファイルです。GitHubで並べ替え可能な表として表示され、column -s$'\t' -tやスプレッドシートで読み取れ、1つのコマンドで行を追加できるため、TSVを使います。各セルは1行に収めます。証拠欄には説明文ではなく参照先を記載します。

references/decision-log-template.tsv（ヘッダー行）をコピーして、空のログを作成してください。列は次のとおりです。

• ts. ISO8601形式のタイムスタンプ。時間軸です。
• phase. フェーズまたは作業ストリームです。
• decision. 選択したこと、または実行したことを1行で記載します。
• why. 平易な言葉で理由を記載します。原則が判断の根拠なら、専門用語のタグではなく、分かりやすく記載してください（選択肢を先に検討した。これは後戻りできない決定だった）。
• evidence. それを裏付けるリンクまたはパスです。コミットSHA、PR番号、file:line、成果物、トレース、スクリーンショットのパスなどを指定します。段落は記載しないでください。
• result. 結果または条件の状態です。例：テスト成功、差し戻し、pixel-diff 0、INCONCLUSIVE、open。

レビュアーがひと目で読めるよう、平易な言葉で書いた例です。これはあくまで説明用です。実際のログにこの行をコピーしないでください。

ts	phase	decision	why	evidence	result
2026-05-24T09:02:00Z	frame	counted the work first, about 100 components and roughly 75 hours	wanted to know the size before starting a long run	commit 3a9f1c2	found 5 things to sort out before starting
2026-05-24T09:40:00Z	harness	took screenshots of the old version before changing anything	so we can compare old against new and catch any visual change	scripts/snapshot.sh, baseline/	saved 120 reference screenshots
2026-05-24T11:15:00Z	widget	moved the widget styles over without changing how it looks	keep the change small and the result identical	commit 7c21e0a, pixel-diff 0	looks identical, tests pass
2026-05-24T12:30:00Z	widget	threw out a helper's work because its screenshots were blank	checked the real files instead of trusting its summary	worktree reset	reverted, tightened the instructions for next time

行の記録

各項目は、同僚に作業内容を伝えるように書いてください。平易な言葉で具体的な行動を記し、AI特有の言い回しや抽象的な専門用語は避けます（ログの文章にも unslop スキルを適用してください）。レビュアーが解読せずに各行を理解できるようにします。

行の形式を適切に保つため、ヘルパーを使用してください：scripts/log.sh <logfile> <phase> <decision> <why> <evidence> <result>。このスクリプトはtsを付与し、初回の使用時にヘッダーを書き込み、余分なタブや改行を取り除きます。また、セルが=、+、-、@のいずれかで始まる場合は、先頭にシングルクォートを1つ付けます。これにより、レビュアーがスプレッドシートでログを開いたときに、数式が実行されるのを防ぎます。printfで行を直接追加してもかまいませんが、セルに生成テキストやユーザー提供テキストを使う場合は、同じ文字への対処を忘れないでください。

すべての行動ではなく、判断の節目やチェックポイントを記録します。選択した分岐、検証結果を伴う単位作業の完了、きっかけとともに記した方針転換や差し戻し、明らかになったブロッカー、修正したゲートなどです。ループ実行は、反復ごとに1行記録します。些細なことや自明なことは省きます。

保存場所

デフォルトでは、ログは作業用の成果物であり、コミットしません。作業ディレクトリのdecisions.tsv、または複数の作業を同時に進める場合は.audit/<task-slug>.tsvに保存し、Gitの対象から除外します。ほとんどの作業では、経緯をコミットする必要はありません。ローカルログでも作業の妥当性を保てますし、作業後に破棄できます。

レビュアーが結果を信頼するために経緯の確認が必要となるほど大規模な作業の場合に限り、ログをコミットします。たとえば、大規模な複数言語間の移植や数週間にわたる移行など、確信を前提とせず、示す必要がある作業です。コミット済みのログはPRで表として表示されます。

ルール

• 1行につき、判断またはチェックポイントを1つ記録します。1行に収まらない場合は、判断がまだ明確ではありません。
• 追記のみとします。誤った判断は、新しい行で置き換えます。履歴を編集または削除してはいけません。
• レビュアーが再実行できるよう、手作業で作った一時的なものより、コミット済みのスクリプトが生成した証拠を優先します（encode-lessons-in-structure 原則スキル）。

トランスクリプトと照合してログを監査する

実行の最後に、結果を返す前に、ログが事実を伝えているか確認してください。アクティブなワークスペースの agent-transcripts/ ディレクトリにある今回の実行のトランスクリプトを読みます（システムプロンプトにパスが記載されています）。~/.cursor/projects/*/ 全体を glob してはいけません。無関係なプライベートチャットまで読み込むことになります。ログを実際の出来事と照合してください。

• 各行が実際のアクションに対応していること。作り上げた項目や、実行するつもりだっただけの項目は削除します。
• 各行の証拠が参照先で確認でき、その行の主張を裏付けていること。
• 作業に影響した分岐、方針転換、または断念したアプローチが記録されていなければ、そこは漏れです。追加します。
• 内容を水増ししないでください。誰も監査しないような行は記録する必要がありません。

修正するのはログであり、ストーリーではありません。作業が行の主張と食い違っているなら、その行が誤りです。

作業経緯のクロスモデルレビュー

結果を返す前に、作業を行ったモデルとは異なるモデルファミリーのサブエージェントを必ず起動してください。セルフレビューでは代用できません。自分では得られない新鮮な視点を得ることが目的です。サブエージェントは監査証跡と今回の実行のトランスクリプトを読み、ユーザーが注意すべき点を指摘します。作業をやり直すのではなく、最適でない点やリスクを確認します。

• 証拠が弱い、または存在しない状態で記録された判断。
• 省略された検証手順や、トランスクリプトで証拠が示されていないのに実施済みとされた検証。
• 後から見るとリスクがある選択（時期尚早、スコープの拡大、症状の取り繕い）。
• ざっと目を通しただけではユーザーが見落としそうな抜け。

監査証跡を作成した実行では、返信の末尾に必ず「Attention」セクションを設けます。最初にレビュアーのモデル名を単独の行に記載します（reviewed by <model>）。続けて、各指摘を該当する行または箇所とともに列挙します。「指摘なし」も有効な値ですが、モデル名は必ず記載してください。セルフ監査ではログが事実を伝えているかを確認します。こちらでは、事実を伝えているログであっても、ユーザーが引き続き精査すべき点を確認します。

監査証跡を確認する

上から順に読み、証拠への参照先をたどって抜き取り確認します。コミット済みの TSV は GitHub では表として表示され、ターミナルでは column -s$'\t' -t decisions.tsv で整形表示できます。証拠を参照先で確認できない行や、結果が検証されていない行があれば、監査で漏れを検出できています。

このスキルの作成

他のスキルでは、監査証跡を独自に作らず、ここにまとめます。名前で参照して形式を任せ、列を再掲しないでください。