Claude Code scratchpadはどこ? スクラッチパッドの場所と片付け方

Claude Codeのスクラッチパッド(scratchpad)は、セッションごとに用意される一時作業用のディレクトリで、リポジトリの外にあります。macOSなら/private/tmp/claude-<uid>/<project>/<session-id>/scratchpad/です。

LinuxとWindowsのパスは、下の「一時ファイルが残る場所は2つある」で示します。リポジトリ内に残った検証ファイルはプロンプトかCLAUDE.mdで、スクラッチパッドはSessionEnd hookで片付けます。

Claude Codeがコーディング中に一時ファイルを作る理由

Claudeはコードを書くタスクで、検証用のPythonスクリプトやテスト用ファイルを作業の途中に新規に作ることがあります。公式のプロンプトエンジニアリングガイドは、この振る舞いを「最終出力を保存する前の一時的なスクラッチパッド」として使っていると説明しています。

これはバグではなく、意図された挙動です。同ガイドは一時ファイルの活用が「特にエージェント的なコーディングのユースケースで結果を改善する」ことがあるとも述べています。試行と検証を挟むほど、最終的な出力の質が上がりやすいという理屈です。

一方で、リポジトリに検証用ファイルが残り続けるのは避けたい状況です。差分に無関係なファイルが混ざると、レビューやコミットの際に見分ける手間が増えます。新規ファイル作成を抑えたい場合の対処として、公式ガイドはプロンプトに一文を加える方法を示しています。

一時ファイルが残る場所は2つある

「一時ファイル」と言っても、Claude Codeでは置かれる場所が2つに分かれ、片付けの手段も変わります。

スクラッチパッドの場所は、OSごとに次の形です。<project>は作業ディレクトリのパスの英数字以外を-に置き換えたもので、CLAUDE_CODE_TMPDIRを設定すると全体がそのディレクトリの下へ移ります。この変数の設定先と制限はCLAUDE_CODE_TMPDIRの解説にあります。

macOS    /private/tmp/claude-<uid>/<project>/<session-id>/scratchpad/
Linux    /tmp/claude-<uid>/<project>/<session-id>/scratchpad/（$TMPDIR が設定されていれば、同じ形がその下に作られる）
Windows  %TEMP%\claude\<project>\<session-id>\scratchpad\

スクラッチパッドが使えるのは、claude.aiアカウントでサインインし、Anthropic APIを使うセッションに限られます。APIキー認証の場合や、Amazon Bedrock・Google Cloud・Microsoft Foundry経由の場合は作られません。設定enableArtifactをfalseにしたときも作られません。

中のファイルは、セッションのトランスクリプトと同じ期間だけ残ります。保持期間のクリーンアップ(cleanupPeriodDaysの既定は30日)がトランスクリプトと一緒にディレクトリを消し、OSの再起動で消えることもあります。claude purgeはこのディレクトリには触れません。残したいファイルはClaudeに頼んでプロジェクトへ移します。

プロンプトに一文加えて片付けさせる

やり方はシンプルです。作業を依頼するプロンプトの末尾に、後片付けを指示する一文を足します。公式ガイドが示すサンプルは次の一文です。

If you create any temporary new files, scripts, or helper files for iteration, clean up
these files by removing them at the end of the task.

日本語で書くなら「検証やイテレーションのために一時ファイル・スクリプト・ヘルパーファイルを作った場合は、タスクの最後にそれらを削除してください」という指示になります。ポイントは2つです。

1つ目は、削除対象を「一時ファイル・スクリプト・ヘルパーファイル」と具体的に書くことです。「ファイルを片付けて」だけでは、テスト用に作ったファイルなのか意図して残した成果物なのかをClaudeが判断しにくくなります。2つ目は「タスクの最後に」という実行タイミングの指定です。作業の途中で消してしまうと、後続のステップで同じファイルを再利用できなくなります。

この一文は、単発のタスクを頼むときのプロンプトにそのまま貼り付けて使えます。

置き場所を限定する一文を重ねる方法もあります。「検証用のファイルは専用のスクラッチディレクトリにだけ作成し、タスクの最後にそのディレクトリを削除する」と書けば、確認する箇所が1つのフォルダに絞られ、リポジトリ内の他のファイルと混ざる心配も減ります。

この一文はClaude Code固有の機能ではありません。Claudeモデル全般に向けた公式ガイドに載っている指示なので、Anthropic APIを直接呼ぶ場合や、別のエージェント基盤でClaudeを動かす場合でも使えます。永続化の手段であるCLAUDE.mdだけが、Claude Code固有です。

CLAUDE.mdに書けば毎回言わなくて済む

毎回繰り返す指示は、プロジェクトの永続的な指示を書いておくCLAUDE.mdに移せます。一時ファイルの後片付けは、その典型です。

プロジェクトのCLAUDE.md(または./.claude/CLAUDE.md)に、次のような一文を追記します。

## 作業規約
- 調査・検証のために一時ファイルやスクリプトを作った場合は、タスクの最後に削除する

CLAUDE.mdはセッション開始時に毎回読み込まれるため、この記載があればタスクごとにプロンプトへ書き足す必要がなくなります。公式ドキュメントは1ファイルあたり200行未満を目安にしています。長いほど文脈量が増え、指示への追従が弱まるためです。一時ファイルの後片付けのような短いルールは、既存のCLAUDE.mdに1〜2行足す程度で収まります。

追記しても効いていないように見えるときは、まずファイル自体が読み込まれているかを調べます。セッション内で/contextを実行し、Memory filesの一覧にCLAUDE.mdが出ているかが目安です。出てこなければ、Claudeはそのファイルを認識していません。/memoryコマンドでCLAUDE.mdを開き、中身を編集できます。

プロンプト・CLAUDE.md・hookの使い分け早見表

一時ファイルの後片付けには、指示の強さが異なる3つの手段があります。どれも「一時ファイルを消す」という結果は同じでも、効く範囲と保証の強さが違います。

プロンプトとCLAUDE.mdはどちらも「文脈として読み込ませる指示」であって、設定として強制する仕組みではありません。公式ドキュメントは、Claudeの判断に関係なく振る舞いをブロックしたい場合の手段としてPreToolUse hookを挙げています。

単発の検証タスクなら、プロンプトへの一文で足ります。同じプロジェクトを継続して触るなら、CLAUDE.mdに書くと以後のセッションでも効き続けます。Claudeの自己判断に頼らず確実に消したいときは、次のSessionEnd hookを併用する構成が選択肢になります。

scratchpad_dirをhookから消して確実に片付ける

プロンプトやCLAUDE.mdは、Claudeが「これは自分が作った一時ファイルだ」と判断することに頼ります。Claudeの判断に頼らず消したいなら、Claude Code側の仕組みと組み合わせます。

Claude Code v2.1.257以降は、hookに渡す入力JSONにscratchpad_dirを含めます。前節のスクラッチパッドの絶対パスで、スクラッチパッドが無いセッション(APIキー認証など)やtempディレクトリが使えない場合は届きません。

{
  "session_id": "abc123",
  "hook_event_name": "SessionEnd",
  "scratchpad_dir": "/tmp/claude-1000/-home-user-my-project/abc123/scratchpad"
}

ここで注意が必要なのは、scratchpad_dirがリポジトリの外を指す点です。この記事のhookが消すのはscratchpad_dirだけで、冒頭で問題にしたリポジトリ内の検証用ファイルは対象外です。scratchpad_dir単体では、プロンプトやCLAUDE.mdの片付け指示を置き換えられないわけです。

確実さを上げる構成は、次の3段階です。

{
  "hooks": {
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "timeout": 5,
            "command": "dir=$(jq -r '.scratchpad_dir // empty'); if [ -n \"$dir\" ]; then rm -rf \"$dir\"; fi"
          }
        ]
      }
    ]
  }
}

jq -r '.scratchpad_dir // empty'はフィールドが無いときに空文字を返すので、続くif [ -n "$dir" ]のガードでその場合だけ削除を飛ばします。matcherを指定していないため、終了理由(clear・resume・logout・prompt_input_exit・other)を問わず毎回発火します。理由ごとに処理を分けたい場合や、より複雑な後始末を書く場合はSessionEnd hookでセッション終了時に後始末を自動化するを参照してください。

このhookには、副作用が1つあります。/clearや対話的な/resumeでもSessionEndは発火するため、終了する側のセッションのscratchpad_dirが渡される構成なら、セッションを切り替えた時点で、元のセッションのスクラッチパッドが消えます。スクラッチパッドの中身は本来トランスクリプトと同じ期間残るので、あとで/resumeして続きから作業したい場合に、そのファイルは戻りません。保持期間のクリーンアップがいずれ同じ場所を消すため、hookは「その日のうちに確実に消したい」ときの手段です。

一時ファイルを消しすぎると起きること

後片付けの指示を書くときに気をつけたいのは、削除の範囲を広げすぎないことです。公式ガイドが述べているとおり、一時ファイルの活用自体はエージェント的なコーディングで結果を改善する側面があります。試行のたびにファイルを完全に消すと、Claudeが検証の過程を残せず、同じ調査を繰り返すコストがかかることもあります。

たとえば大きめのリファクタリングで、途中経過を確認する検証スクリプトを作ったとします。その一時ファイルを途中で消す指示になっていると、Claudeは検証のたびに同じスクリプトを作り直し、トークンと時間を余分に使います。指示を書くときの条件は、次の3つです。

Claude Codeが自動で作る一時ファイルの中には、後片付け指示の対象にならない別種の問題もあります。Windows環境でプロジェクトディレクトリに残るtmpclaude-*-cwdファイルはその一例で、原因と削除方法はtmpclaude-*-cwdファイルが消えない原因と削除方法で扱っています。セッション履歴やチェックポイントといった別種のデータ保持は、プロンプトではなくsettings.jsonのcleanupPeriodDaysが管轄しており、こちらはClaude Code cleanupPeriodDaysでデータの保持期間を変えるに載せています。

まとめ

リポジトリに残したくない検証用ファイルには、「タスクの最後に、テスト用に作ったファイルだけを削除する」という一文をプロンプトかCLAUDE.mdに置くのが出発点です。スクラッチパッドの掃除まで確実にしたい場合に限って、SessionEnd hookを足すという順番になります。