ktaroabobon sanitize-artifacts
会話の中で作った成果物を、会話を見ていない読み手のために仕上げる。対象はドキュメント、コード、コメント、コミットメッセージ、PR 本文、UI 文言など、人に渡るものすべて。
原則
会話は制作の文脈であって、成果物の内容ではない。
ユーザーの指示・例示・制約・修正依頼は、成果物の構成・語調・既定値・省略を決める材料として使う。成果物に文として残すのは、読み手が本当に必要とする内容だけ。残滓が無ければ何も変えず、「変更なし」と報告して終わる。
引数
path ...: 対象ファイル。省略時は、この会話で作成・編集した成果物を対象にする
Step 1: 残滓を見つける
対象ファイルに同梱スクリプトを当て、表層パターンの当たりを付ける:
bash ${CLAUDE_SKILL_DIR}/scripts/find_residue.sh <path ...>
(Codex ではスキルディレクトリからの相対パスで bash scripts/find_residue.sh と実行する)
スクリプトは発見の補助で、判定はしない。当たりが 0 件でも本文を通読する。 文章の継ぎ目、唐突な免責、読み手に関係ない前置きは grep では見つからない。
| 種類 | 表層パターンの例 |
|---|---|
| 指示の引用 | 「ご要望どおり」「ご指示のとおり」「ユーザーの指示により」「As requested」「Based on your instruction」 |
| 採用しなかった案 | 「今回は〜しない」「〜は使わない」「〜を避けるため」「Unlike the previous version」「This avoids」 |
| 制約の免責 | 「制約があるため」「本書では〜を扱わない」「No Git/CLI is used」「Because of the constraint」 |
| 修正経緯 | 「〜に変更しました」「前のバージョンと違い」「この節は〜のため追加」「This was changed to」 |
| 会話への参照 | 「先ほどの」「上記の要求」「会話の中で」「The prompt says」 |
Step 2: 分類する
見つけた記述と、成果物の各部分を、次のどれかに分類する。分類してから手を入れる。 個別に「消す / 残す」を決めると基準がぶれる。
| 分類 | 扱い |
|---|---|
| 1. 読み手が本当に必要とする内容 | そのまま残す |
| 2. 成果物の設計には影響すべきだが、見えてはいけない文脈 | 構成・語調・既定値・例の選び方に反映し、文としては消す |
| 3. 会話の残滓 | 消す |
判断に迷う記述は「読み手が会話を知らなくても、この一文を読んで得をするか」で決める。得をしないなら 2 か 3。
Step 3: 制約を設計に溶かす
2 に分類したものは、免責文ではなく設計として成果物に反映する。
| ✗ 漏れている | ⭕ 溶けている |
|---|---|
| 「本ガイドでは Git や CLI ツールは使いません」 | 「プロジェクトフォルダは Google Drive で共有する」 |
| 「X については触れません」 | X が無い構成にする |
| 「初心者向けに平易に書きました」 | 用語を定義し、手順を細かく刻む |
| 「ご指摘を受けて並び順を変えました」 | 最初からその順だったように書く |
| 「高度な用語は避けます」 | 平易な語で書く |
会話中の例は意図を読み取るための材料であり、成果物に写す内容ではない。成果物自体がその例を必要とする場合だけ残す。
Step 4: 通して読み直す
手を入れた後、読み手になったつもりで最初から読む:
- 会話を見ていない人が、なぜこう書かれているのか疑問に思う箇所は無いか
- ツール・除外・回避した選択肢への言及は、読み手に必要なものだけか
- 複数回の修正の継ぎ目(語調の揺れ、重複、矛盾する前提)は無いか
- 見出しと注記は、作り手ではなく読み手に向いているか
- 免責・注意書きは、読み手が本当に必要とするものだけか
- 全体が 1 つの声で書かれているか
最後にもう一度 find_residue.sh を当て、残りが「残すと決めたもの」だけであることを確認する。
やらないこと
- 成果物の目的・技術的な正しさ・読み手向けの要件を変えない
- 新しい内容を足さない。削る・言い換える・並べ替えるまで
- 表層パターンに当たったものを機械的に消さない。読み手に必要なら残す
完了時に返すもの
修正後の成果物そのものを先に出す。 「〜を削除しました」「こちらが修正版です」のような前置きは付けない。
- ファイルを編集した場合: 編集したファイル名だけを 1 行で
- 成果物をそのまま返す場合: 成果物本体のみ。ラベルが要るなら 1 行まで
- 変更が不要だった場合: 「変更なし」と、通読した範囲
- 変更のサマリは求められたときだけ、成果物の後に付ける