CLAUDE.mdを置いても出力が安定しない理由

公式は「強制される設定ではない」と書いている

CLAUDE.mdに「必ずこうして」と書いても、その通りに動くとは限りません。
Claude Code公式の記憶についての解説を、次の2文に要約します（2026年9月7日確認）。

公式は、CLAUDE.mdをコンテキスト（判断材料）として扱い、操作を強制する設定とは区別しています。
Claudeの判断によらず操作を止めたい場合は、PreToolUseフックを使うよう説明しています。
（出典：Claude Codeがプロジェクトを記憶する仕組み（公式ドキュメント））

ここでいうコンテキストとは、Claudeが返事を組み立てるときに目を通す材料一式のことです。
書き方を整えるだけで、すべての操作を強制できるわけではありません。

止めたいことはフックに、伝えたいことはCLAUDE.mdに

フックは、会話の開始時や、Claudeがファイルの読み書き・コマンド実行などの操作をする直前に、決めた処理を動かす設定です。
この記事では、パソコンに実行させる操作を文字で指定するコマンドを使います。
ファイルの読み書きやコマンド実行など、Claudeが行う操作をツールと呼びます。

入れる順番は4段階だけ

私が経営管理用のリポジトリ（プロジェクトのファイル一式を管理する場所）で動かしているのは、CLAUDE.mdと、この記事で扱う3種類のフックです。

1. CLAUDE.mdで基本ルールを伝え、操作を強制せずに判断材料を渡します。
2. SessionStartで会話の最初に前提を自動で差し込み、繰り返しの説明を減らします。
3. PreToolUseでツールの実行前に確認し、条件に合わない操作を止めます。
4. Stopで通常の応答終了時に変更を記録するなど、応答後の後始末を自動化します。

前の段が無いまま後ろの段を入れると、切り分けができなくなります。
たとえばPreToolUseで止まったとき、それがフックが正当な操作まで止めてしまったのか、CLAUDE.mdの記述が曖昧だからなのかが判別できません。
最初にCLAUDE.mdだけで一定期間運用しておけば、「CLAUDE.mdでは守られなかったから、この項目をフックに移す」という判断が根拠つきでできます。

順番①：CLAUDE.mdは200行未満を目安に、置き場所を決める

公式の記憶についての解説は、1ファイル200行未満を目安として挙げています。

4つの置き場所は上書きではなく連結される

Gitは、ファイルの変更履歴を残す仕組みです。
GitHubは、その履歴ごとファイル一式をインターネット上で共有できるサービスです。
CLAUDE.mdは1か所ではありません。
公式の記憶についての解説が置き場所として挙げているのは、次の4つです。
あわせて、作業フォルダより上の階層にあるCLAUDE.mdとCLAUDE.local.mdも起動時に読み込まれます。
表の ./ はそのプロジェクトのフォルダの直下、~/ は自分のホームフォルダを表します。

個人用の CLAUDE.local.md は、Gitの記録対象から外すファイルを指定する .gitignore に追加します。

大事なのは、これらが上書き関係ではないことです。
公式は「All discovered files are concatenated into context rather than overriding each other」と書いています。
訳：見つかったファイルはすべて、互いを上書きするのではなく連結されてコンテキストに入る。
4つは足し算で読み込まれます。

トークンは、AIが文章を読み書きするときの分量の単位です。
長い指示は、会話や作業に使える判断材料の枠を多く使います。
公式も、ファイルが長くなると指示が守られにくくなると説明しています。
個人設定に長い指示を書いていると、それが全プロジェクトのトークンを毎回食い続けることになります。

別ファイルに切り出しても読み込み量は減らない

@path は、CLAUDE.mdの中に別のファイルの中身を読み込ませるための書き方です。
ファイルを分割しても、読み込む量を減らせるとは限りません。
別ファイルを読み込む方法の公式説明では、読み込む対象のファイルも起動時にコンテキストへ入るとされています。
見た目のファイルが短くなるだけで、読み込み量は変わりません。

私が200行に収めるためにやっているのは、領域ごとに内容を1ファイルに集約し、そこを唯一の正しい版とする書き方です。
この1ファイルを、私は正本と呼んでいます。
CLAUDE.mdからは、その正本の場所だけを指します。
経理の運用は経理の正本、記事の作り方は記事の正本、というように対応表だけをCLAUDE.mdに置きます。
中身は必要になったときに読ませます。
これで、必要な内容への参照を保ちながら行数を減らせました。

順番②：SessionStartで「毎回言い直していること」を消す

SessionStartで何を共有するか

私のリポジトリでは、SessionStartで2つの情報をClaudeに渡しています。

1つは、進捗ログの先頭8行です。
進捗ログとは、その日の作業結果を1行ずつ書き足していく1枚のメモのことで、私は新しい記述を上に積んでいます。
「先週のあの件はどうなったか」を毎回打ち込む手間が消えました。

もう1つは、正本を置いているフォルダの未追跡ファイル一覧です。
未追跡とは、Gitの管理下に一度も入っていない状態のことです。
自分のMacではなくサービス側で動かす環境を、ここではクラウドセッションと呼びます。
クラウドセッションのようにGit経由でファイルを受け取る環境には、未追跡ファイルは届きません。
その一覧があれば、必要なファイルが欠けていることを作業の最初に確認できます。

圧縮の直後にも前提を入れ直す

会話が長くなると、Claude Codeは過去のやり取りを要約して詰め直します。
この処理を圧縮（compaction）と呼びます。
SessionStartでどの開始場面に処理を動かすかを選ぶ欄（matcher）では、起動時（startup）や再開時（resume）、圧縮直後（compact）などを指定できます。
matcherに書く値はフックの種類ごとに違い、SessionStartでは開始の種類、PreToolUseでは対象のツール名を指定します。
compact を指定しておくと、圧縮が走った直後に前提を入れ直せます。

順番③：PreToolUseは「記録のみ」から始めて昇格させる

いきなり止めない導入手順

私が動かしている、出力先を確認するPreToolUseフックは、2026年9月時点もツールの実行を止めず、あとから読み返す記録用のテキストファイル（ログ）に1行書くだけで動いています。
リポジトリ直下に新しいファイルを作ろうとしたら記録する。
それだけです。

実務では、記録だけの期間を挟んだほうが安全だというのが私の判断です。
自分の作業パターンにどれだけ引っかかるかは、動かしてみないと分かりません。

記録・内容確認・停止の3段階で確認する

これから試す場合、ログは後述の登録例と同じ .claude/hook-check.log というファイルにまとめれば、確認先を1つにできます。

止め方の設定例は公式ガイドで確認できます。
段階3まで進めたら、止め方の説明をCLAUDE.mdに書き足しておきます。
止められた本人が、代わりにどこへ書けばいいのかをその場でたどれるようにするためです。

順番④：Stopフックで後始末を自動化する（中断した回は動かない）

変更の自動記録（コミット）と会話ログの書き出し

Stopは、Claudeが応答を終えたときに走るフックです。
私はここに2つを載せています。

1つは、追跡済みファイルの変更だけを記録として確定させ（コミット）、GitHubへ送る（push）処理。
もう1つは、その回の会話ログを、メモアプリObsidianで読める形のフォルダへ書き出す処理です。

新規ファイルは自動記録の対象から外す

新規ファイルを対象外にしているのは、認証情報の入った設定ファイルや巨大な生成物を誤ってコミットしないためです。
変更も新規ファイルもまとめて追加する git add -A は使わず、残したい成果物はファイルの場所を1つずつ指定して自分が追加しています。

Stopフックは中断（Esc）では動かない

ここが最大の落とし穴でした。
公式のフックガイドは、次の趣旨を示しています。

公式の説明では、StopフックはClaudeが応答を終えるたびに動作し、ユーザーが中断した場合には動作しません。
APIのエラー時は、代わりにStopFailureというフックが動作します。

StopFailure は、Claude Codeが外部サービスとのやり取り（API）で失敗したときに走る別のフックです。

Escで止めた回には、Stopフックは走りません。
つまり、自動コミットをStopに任せていると、中断した作業だけが未コミットのまま残ります。
私はこれを、後からGitの変更内容を見て気づきました。
「全部自動で保存されているはずだ」と思い込んでいた期間があったわけです。

複数のMacとクラウドでつまずくところ

Claudeが自動で覚える記録は他のマシンに届かない

Claude Codeが作業の中で覚えた知識を保存する仕組みが、auto memoryです。
公式の記憶についての解説によると、そのファイルはほかのマシンやクラウド環境とは自動で共有されません。

私はここで一度混乱しました。
片方のMacで覚えたはずのことを、もう片方が知らない。
他の端末でも要る知識は、auto memoryではなくリポジトリ側のファイルに書く。
これが結論です。

git操作は1台に寄せる

私の環境では、2台のMacがiCloudで同期された同じプロジェクトのフォルダを開いています。
一方のMacで変えたファイルが、もう一方にも反映される構成です。
この構成に自動コミットを入れた当初、2台が同時にgitを触り、gitが複数の操作を同じ時点で進めないために作るロックファイルがぶつかって、コミットが失敗しました。
2026年9月時点では、git操作を担当するMacを1台に固定しています。
そのMacのコンピュータ名（hostname -s というコマンドで確認できる名前）を .claude/git-primary-host というファイルに書いておき、担当のMac以外ではStopフックの自動コミットが何もせずに終了するようにしています。
.claude/git-primary-host はClaude Codeの標準設定ではなく、私が書いたフックの処理から読み込む自作のファイルです。
担当のMac以外で編集したファイルは、次に担当のMacが動いたときにまとめて拾われます。

私の運用では、クラウドセッションでの変更を元のリポジトリへ直接反映させません。
変更内容をまとめて提出する形（プルリクエスト）で返し、それを人が確認して取り込みます。

完成した設定の実例

最初に置くCLAUDE.mdの骨格

以下は、ファイルの置き場所と作業の進め方を伝えるための例です。
自分のフォルダ構成に合わせて書き換え、まずはこのファイルだけで試してください。
必要な処理を1本ずつ作り、公式の設定例で登録方法と動作を確認します。

<!-- CLAUDE.md（プロジェクト直下に置く。200行未満を目安にする） -->

# ◯◯プロジェクト

## 正本の対応表（中身はここに書かず、必要になったら読ませる）
| 領域 | 正本 |
|---|---|
| 事業戦略 | 01_strategy/README.md |
| 経理の運用 | 02_finance/CFO.md |
| 記事の作り方 | 03_projects/article-pipeline/article-agent-system.md |

## 出力先の規約
- 成果物は output/<内容別>/ か 03_projects/<案件>/ に置く
- リポジトリ直下に新規ファイルを作らない

## 禁止事項
- 認証情報をコードやファイルに直接書き込まない
- git add -A を使わない（残すものは明示パスで追加する）

3つのフックが動くか確認する登録例

Macで動作を確かめるための小さな設定例です。
プロジェクト内に .claude フォルダを作り、その中の settings.json に登録します。
すでに設定がある場合はファイル全体を置き換えず、既存の hooks と統合してください。
hooks は処理を動かすタイミング別の登録欄、matcher は対象を絞る欄で、Write|Edit はファイルの書き込み・編集を指定します。
type: "command" はコマンドを実行する方式、command は実行する内容です。
printf は文字を出力するコマンドで、>> はファイルへの追記を表します。
$CLAUDE_PROJECT_DIR は、Claude Codeが渡すプロジェクトのフォルダの場所です。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|compact",
        "hooks": [
          {
            "type": "command",
            "command": "printf '開始時の確認\\n' >> \"$CLAUDE_PROJECT_DIR/.claude/hook-check.log\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "printf '実行前の確認\\n' >> \"$CLAUDE_PROJECT_DIR/.claude/hook-check.log\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "printf '応答後の整理\\n' >> \"$CLAUDE_PROJECT_DIR/.claude/hook-check.log\""
          }
        ]
      }
    ]
  }
}

保存したらClaude Codeで新しい会話を始め、試験用のテキストファイルを書き込むよう依頼します。
たとえば「output/check/hook-test.txt がまだなければ、Writeツールで作って『動作確認』と書いてください」と入力します。
通常どおり応答が終わったあと、.claude/hook-check.log に「開始時の確認」「実行前の確認」「応答後の整理」が追記されているかを見ます。
追記されていないときは、Claude Codeで /hooks と入力し、SessionStart・PreToolUse・Stopの登録内容を確認します。
表示されない場合は、.claude/settings.json の保存場所と記述を見直してください。
これは登録の確認用で、ファイルの操作は止めず、GitHubにも送信しません。
確認用の .claude/hook-check.log も .gitignore に追加して、Gitの記録対象から外します。
開始時に渡す情報や応答後の処理を変えるときは、登録例の command の値を書き換えます。
いま入っている printf のコマンドを、自分で用意した処理を呼び出すコマンドに替え、1か所ずつ動作を確かめます。
（出典：公式のフック設定手順）

よくあるご質問

まとめ：順番を守れば、設定は4段階で整える

今日やること

CLAUDE.mdは伝えるための道具であって、止めるための道具ではありません。
止めたいことはPreToolUseへ移す。
この一点だけでも、出力の安定度はかなり変わるはずです。

今日やるのは1つで十分です。
CLAUDE.mdを200行未満を目安に整えてください。
公式の確認手順に沿って、Claude Codeの入力欄で /context と打ち、表示された Memory files（読み込んだ設定ファイル） の欄を見ます。
自分のCLAUDE.mdがそこに出ていれば、少なくとも届いてはいます。
フックは、翌週以降に1本ずつ足します。

この記事の仕様はすべて2026年9月時点のものです。
フックの仕様は公式のフックガイドで確認してから使ってください。