CLAUDE.md は582行。6つの層と、それぞれの裏にあった失敗

新しい Claude Code のチャットは、毎回ゼロから始まります。プロジェクトのことは知らず、隣のウィンドウで1時間前に話した内容も覚えておらず、あるサーバーの1つのポートに触れてはいけないことも分かりません。この記事では、それに対処するために作った CLAUDE.md を取り上げます。6つの層があり、それぞれを生んだインシデント、ルールが効かないところでフックが効く理由、侵害された npm パッケージを私のマシンに入れなかった設定の1行、そして通常のプロジェクトでも残すべき部分について書きます。2026年4月12日にロシア語の原文を公開した時点で、設定は582行でした。

CLAUDE.md には、2つの問題を同時に解決することが期待されています。セッションをまたいで文脈を運ぶことと、エージェントが取り返しのつかないことをしないようにすることです。r/ClaudeAI には毎週新しい怖い話が投稿されます。エージェントが本番のデータベースを消した。エージェントが公開リポジトリに秘密情報を push した。エージェントが課金サービスを「最適化」した結果、すべての顧客に0円の請求書が届いた。典型的な5〜10行の CLAUDE.md では、どちらの問題も解決しません。私はこれを願望のリストではなく、アーキテクチャの課題として扱うことにしました。そして、そこに書かれたルールには、それぞれ具体的な話があります。

最初のルールを生んだ3つのインシデント

エージェントが動いているシステムを「直した」。 日曜日の夕方です。エージェントは、外部のストレージサービスの設定に 127.0.0.1 があるのを見て、前のセッションが間違えたのだと判断しました。実 IP を入れてしまったのです。アップロードが壊れました。30分ほどデバッグしてから、トラフィックはローカルのトンネル経由の SNI プロキシを通っていて、127.0.0.1 が正しい値だったと分かりました。文脈がなければ、明白な修正こそが損害でした。

ここから出てきたルール：現在の値がなぜそうなっているのかを理解するまで、設定を変更しない。値がおかしく見えたら、まず理解してから行動する。

fail2ban が、エージェントをブルートフォーサーだと判断した。 エージェントはサーバーの状態を確認していて、確認のたびに新しい SSH 接続を開いていました。1分間に十数回の接続は攻撃に見え、そのIPは30分間BANされました。そのときそのマシンでは学習が走っていて、私はもうアクセスできなくなりました。

ルール：すべてのために SSH ブリッジは1つ、セッションごとにクライアントは1つ。確認、修正、検証のために別々のスクリプトは作らない。まとめて1回の呼び出しにする。

「フィルタ」が「削除」の意味になった。 私はデータセットのフィルタリングを頼みました。不適切な画像を取り除いてほしい、という意味でした。エージェントは文字どおりに読み、ファイルを削除しました。移動でも印付けでもなく、削除です。

ルール：フィルタリングは移動か印付けを意味し、削除はしない。削除の前には、ユーザーがその言葉で削除を求めたかを確認する。

「気をつけて」と書いても効きません。仕組みが必要です。

6つの層。どれも計画したものではない

それぞれの層は、特定の失敗のあとに現れました。

ルール、9ファイル。 状況に応じて読み込まれます。エージェントが記事を書くとき、SSH のルールは要りません。コードをデバッグするとき、文章のルールは要りません。Claude Code は、作業に合ったルールファイルを読み込めます。

メモリ、78ファイル。 エージェントがサーバーの設定を3回目に忘れたときに現れました。セッションをまたいで、インフラの設定、プロジェクトの決定、私の好み、過去のミスを保存しています。ファイル同士は [[filename]] でリンクされていて、合計178本のクロスリンクがあります。そのため、普通の Markdown がナレッジグラフになります。一部は常に読み込まれ、残りはトピックに応じて読み込まれます。

ハンドオフ。 新しいチャットが、前のチャットの行き止まりにそのまま入り込んでしまうたびに現れました。セッションを閉じるとき、エージェントは要約を書きます。何を実施したか、何がうまくいかなかったか（これが価値のある部分です）、次の一手1つです。以下は、実際のハンドオフをロシア語から訳したものです。

## Session goal
Colour checker: CNN sweep + diffusion, first visual results.

## Done
- CNN baseline: median 1.99 deg (11M params, 21 MB)
- Sweep on 5 GPUs: crop128 (3.17), bs16 (2.04), lr3e-4 (NaN)
- Diffusion training started: epoch 5/50, loss 0.827

## Did NOT work
- EfficientNet-B0: hash mismatch in the Docker image
- lr=3e-4: NaN after epoch 10-13, no gradient clipping
- CNN, visually: three numbers give stray colour casts

## Next step
Inference script for diffusion + visual sheets with 24 patches

次のチャットは、プロジェクトをゼロから分析する代わりに、約1,500トークンを読みます。4日間で27件のハンドオフが溜まりましたが、同じ行き止まりは1つも繰り返されませんでした。アカウントをまたいでも機能します。私は3つのサブスクリプションを持っています。仕事用に2つ、個人用に1つです。ハンドオフがあれば、すべてを説明し直すことなく、別のアカウントで作業を続けられます。これが同時に作業する複数の人のためのツールへどう育ったかは、1つのリポジトリで複数の Claude を動かすにまとめています。

クロニクル。 20件のハンドオフを重ねたあと、プロジェクトが今の状態にどう至ったのかが分からなくなったときに現れました。ハンドオフは「次は何か」に答え、クロニクルは「どうやってここに来たか」に答えます。マイルストーンごとに、重要な決定、方向転換、行き止まりを3〜7行で書きます。

フック。 「作業前に CLAUDE.md のリンクを確認する」というルールが、セッションの20分後には守られなくなったときに現れました。次の節はフックについてです。

スキル、16個。 特定の作業のためにパッケージ化された知識です。説明文は、「use when: GPU がハングした、サーバーの状態確認が必要」のようなモデル向けのトリガーとして書いています。「サーバーの手助けをします」のような書き方はしていません。

ルールは願望、フックは保証

この月に学んだ中で、いちばん分かりにくかったことです。CLAUDE.md のルールは、プロンプトの中の指示です。モデルは忘れることも、解釈を変えることも、長いセッションの終わりに文脈が他のことでいっぱいになって落とすこともあります。私の「作業の前にリンクを確認する」というルールは、10分ほど守られたあと、エージェントがタスクに没頭して消えてしまいました。

フックは、Claude Code がイベント（SessionStart、Stop、PreToolUse）で実行する Python スクリプトです。忘れることも、解釈を変えることもありません。毎回実行されます。以下は、長いセッションを閉じる前にハンドオフを求めるフックです。

# remind_handoff.py  (Stop hook, simplified)
age = session_age_minutes()
if age < 15:
    return                      # short session, nothing to hand off

if fresh_handoff_exists():
    return                      # already written

print(json.dumps({              # block the close, ask for the handoff
    "decision": "block",
    "reason": f"Session ran {int(age)} min with no handoff. "
              f"Write one into .claude/handoffs/ before exiting."
}))

モデルは、タスクが終わったとき、文脈が埋まってきたときなど、いつが区切りかを自分で判断できることが多いです。フックは、モデルが忘れたときを受け持ちます。

毎回必ず起きてほしいことなら、それはルールではなくフックです。

1行の設定で、サプライチェーン攻撃を防ぐ

2026年3月31日、週に約1億回ダウンロードされる公式の npm パッケージ axios が、メンテナーのアカウント経由で侵害されました（Elastic Security Labs）。悪意のある 1.14.1 が UTC 00:21 に公開され、悪いバージョンは UTC 03:15 まで npm に残りました。約3時間です（axios の事後報告）。Microsoft は、この攻撃を北朝鮮の国家主体 Sapphire Sleet によるものとしています（Microsoft Security Blog）。

私の .npmrc には、次の1行がありました。

min-release-age=7

7日以内に公開されたパッケージはインストールされません。悪意のあるパッケージの大半は1〜3日で見つかるので、7日は十分な余裕です。私は影響を受けず、1行のコストで済みました。Python の場合は uv.toml に同じものを書きます。

exclude-newer = "7 days"

その裏にある研究：37本の論文

ルールの多くは、私自身のミスからではなく、学術研究から来ています。37本の arXiv 論文を原則に作り直したものがあります。そのうち私の作業を最も変えた4つは次のとおりです。

• Proof loop。 エージェントが「テストは通る」と言う。確認すると通らない。Proof loop は、エージェントが自分の作業を自分で承認（完了判定）することを禁じます。必要なのは成果物です。テストの出力と、作業を見ていない新しいセッションの検証者による判定です。出典：arXiv 2603.10165。
• 構造化推論。 「たぶんこれ、たぶんあれ」という自由な文章の代わりに、コードとログから確実に分かっていること、段階的な追跡、そこから導かれること、検証して捨てた仮説を並べます。Ugare と Chandra の実験では、この種の準形式的な推論により、パッチの同等性判定の精度が、厳選された例で78%から88%に、実際のエージェントが生成したパッチで93%に上がりました（arXiv 2603.01896）。
• 決定論的なオーケストレーション。 テスト、リンター、フォーマットなど決定論的なものはすべてシェルスクリプトで実行します。モデルはループの中で数を見失い、分岐条件を取り違えます。スクリプトはそうしません。
• レッドライン。 通常のルールは、創造的に解釈されてしまいます。レッドラインは、例外のない絶対的な禁止事項で、それぞれが1つのインシデントに結びついています。確認なしに削除しない。本番の設定を理解せずに変更しない。この型は中国のエンジニアリングチームに由来します。红线、文字どおり「赤い線」です。

ジェネレーター・評価者の組み合わせから autoresearch、マルチエージェントへの分解、コンテキストの体系化、エージェントのセキュリティ、ドキュメントの整合性まで、残りはリポジトリに書いてあります。

数字と、うまくいかなかった箇所

メモリファイル78本。クロスリンク178本。4日間で27件のハンドオフ。1週間で83セッションにわたる KV キャッシュのヒット率96.9%。設定は自分自身を保守します。変更のたびにエージェントはリンクが古くなっていないかを確認し、SessionStart のフックが自動的に検証します。

完璧に動くかというと、そうではありません。監査で、インデックスから脱落していたメモリファイルが4本見つかりました。ドキュメントのずれです。ドキュメントのずれを防ぐために作ったシステムの中で起きました。システムがなければ、もっと悪かったはずです。

自信がないこと

全員にこのすべてが必要だとは思いません。ほとんどのプロジェクトでは、5つの原則で足りるでしょう。決定論的なオーケストレーション、構造化推論、サプライチェーンの防御、体系化されたコンテキスト、ハンドオフです。

6つの層が最低限かどうかも確信がありません。過剰に作ったのかもしれません。しかし、あの月には文脈が1つも失われず、行き止まりに戻ることもありませんでした。

原則の1つ、仮定のテストが、そのことをはっきり言っています。このセットアップのすべての部品は、モデルが単独ではできないことについての仮定を符号化しています。そしてモデルは改善されます。部品を外して、測定してください。ここにある層のどれかは、おそらくすでに不要になっています。

4月以降の変化

2026年9月の更新。リポジトリは claude-code-config から codex-claude-code-config に改名しました。同じ原則、フック、スキルが、Codex や Claude と Codex の混在セッションも動かすようになったため、古い名前が実態に合わなくなったからです。古い URL はリダイレクトされます。2026年9月23日時点で、リポジトリには30の原則、58のスキル、35のルールファイル、hooks/ に73のスクリプトがあり、GitHub で150スターと24フォークがありました。

上のセクションの数字（ルールファイル9本、メモリファイル78本、スキル16個、論文37本、582行）は、4月12日時点の私のセットアップを表しています。その日には正しく、そのまま残しています。

どこから始めるか

Claude Code のチャットに、次の文を貼り付けてください。

https://github.com/AnastasiyaW/codex-claude-code-config - study it, pick what fits my work and set up my Claude Code

小さく始めてください。サプライチェーンの防御（.npmrc の1行）、決定論的なオーケストレーション（テストをスクリプト経由で実行）、構造化推論（デバッグの形式）。残りは、失敗が必要としたときに足してください。すべては MIT ライセンスです。

このサイトのプロジェクトページは codex-claude-code-config です。その横に育った参照ライブラリは エージェントのための785本の記事 で説明しています。アプリ内蔵のセッション履歴より、なぜハンドオフを信頼するのかは、見ることのない Claude Code のセッション45 MB で書いています。