CLAUDE.md を憲法として書く。禁止事項、振る舞いルール、既定の判断。5 日 92 commits、迷走なし。
5 日間で 92 コミットを積み、プロダクトを本番投入した（github.com/defi-io/smarts）。途中で破綻も巻き戻しも大規模リファクタリングもなかった。これができたのは Claude が天才だからではない。プロジェクトルートに置いた 565 行の CLAUDE.md のおかげだ。
この記事は、「憲法」として機能する CLAUDE.md をどう書くか、書いた後に何が起きるかについての話だ。
多くの人は CLAUDE.md を README のように書く——プロジェクトの概要、起動方法。これは無駄だ。
README は人間のためのもの。CLAUDE.md は Claude のためのもの。Claude は session 開始時に自動でロードする。つまりそこに書いた一行一行が、その後のすべての判断の前提条件になる。
README 風に書くと、こうなる：Claude はプロジェクトの大枠とテストの走らせ方を知っているが、技術判断は毎回ゼロから下す。
憲法風に書くと、こうなる：Claude はどの道が閉ざされているか、どの規約が必須か、分岐でどちらにデフォルトすべきか、どこで立ち止まって尋ねるべきかを知っている。
違いはこうだ：前者は「ついでに」新しい依存を入れ、抽象を一段足し、Gemfile をいじる。後者はそれをやらない。
最近作っているプロジェクトは smarts.md ——スマートコントラクトの live docs と MCP server を生成するプラットフォームだ。CLAUDE.md は 565 行、こう分かれている：
1. プロジェクトの身元（5 行）
2. プロダクトの核（一文の定義 + 競合との構造的な違い）
3. 技術スタック（硬い制約、YAML 形式）
4. 禁忌リスト（明示的な ❌ 項目）
5. 対応範囲（MVP の硬い境界）
6. アーキテクチャ（ASCII 図入り）
7. ディレクトリ構成（ファイルごとの責務付き）
8. Ruby コーディング規約（良い例・悪い例のスニペット付き）
9. キャッシュ戦略（表）
10. テスト要件
11. デプロイ詳細
12. Git ワークフロー
13. Claude Code 使用規約（振る舞い指令）
14. 90 日マイルストーン
15. 中核原則
どれも装飾ではない。以下、いくつかをピックアップして「なぜこう書くか」を説明する。
私の禁忌リストはこう：
❌ TypeScript / Node.js サービスを入れない
❌ ethers.js / web3.js を入れない
❌ Sidekiq を入れない（Solid Queue を使う）
❌ React / Vue / Svelte を入れない（Hotwire を使う）
❌ Redis を入れない（Solid Cache / Solid Queue / Solid Cable で全部カバー）
❌ 未検証のコントラクトは扱わない（Etherscan 検証済みのみ）
❌ Solana / Bitcoin / Move 系は扱わない（EVM のみ）
これは Web3 プロジェクトだ。Web3 の界隈では TypeScript + ethers.js + Redis + React がデフォルト。私はそれに逆らっている。理由はこちらにあるが、Claude は知らない。禁忌リストがなければ、Claude は学習データの「業界の常識」に基づいて提案してくる——ほぼ確実に TypeScript 路線だ。
禁忌リストがあると、Claude は「web3.js を動かす Node サービスを足しますか？」と訊かなくなる。その道はデフォルトで閉ざされている。
ポイント：各項目は 明確 で 絶対 であること。「TypeScript はなるべく避ける」ではなく「TypeScript を入れない」と書く。曖昧さは Claude にとって「交渉可」と読まれる。
CLAUDE.md の最後の大きなブロックは「Claude Code 使用規約」、こう書かれている：
### 私が「X を始めて」と言ったら
1. CLAUDE.md の制約がそのアプローチを許すか先に確認
2. 既存コードに関連実装がないか確認（車輪を再発明しない）
3. コードを書く前に新しいブランチを切る
4. 実装後にテストを走らせる
5. 自動 commit しない——コードが書け、テストが緑になったら止まって
報告する。私が明示的に "commit" と言うまで commit しない
### 私が「アイデアがある」と言ったら
すぐにコードを書かない。先に：
1. 理解が正しいか確認（言い直す）
2. CLAUDE.md の制約と照らす
3. 潜在的な問題やより良い代案を指摘
4. 私の確認を待ってから動く
### 技術的な分岐に出会ったら
CLAUDE.md に明示がないとき：
1. デフォルトで「より Rails ネイティブ」を選ぶ
2. デフォルトで「依存が少ない」を選ぶ
3. デフォルトで「一人開発者がより速く回せる」を選ぶ
4. 迷ったら止まって尋ねる
これは「snake_case で命名」よりも 10 倍重要だ。
コードスタイルはコードを読めば学べる。だが「いつ立ち止まって尋ねるか」「『アイデアがある』と聞いたらまず言い直して確認する、すぐに書かない」——こういう振る舞いパターンはコードからは学べない。
いちばん効くのは：分岐でどちらにデフォルトするか。この一行で、あなたが部屋にいないとき（例えば「X を始めて」とだけ言って離席するとき）に Claude が何をするかが決まる。これを明文化すれば、放っておいて働かせられる。
CLAUDE.md の冒頭にはこう書いてある：
このドキュメントはプロジェクトの「第一源」である。Claude Code の各 session 開始時に自動ロードされる。技術判断を変えるときは、まずここを変え、コードを後から追従させる。
これはワークフロー上の取り決めだ。技術選択を切り替えると決めたとき——例えばメインの AI モデルを gpt-5-mini から gpt-5 に上げる——一歩目は initializer をいじることではない。一歩目は CLAUDE.md のこの段落を直すことだ：
ai:
fast: gpt-5-mini # 以前
fast: gpt-5 # 変更後
その後で Claude に CLAUDE.md を読み直させ、コードを揃えさせる。
なぜか？コード側の値を直して CLAUDE.md が追いつかないと、次に Claude が CLAUDE.md を読んだとき古い値を見て、「親切心で」あなたのコードを巻き戻す。衝突の根は単一障害点——CLAUDE.md の遅れだ。憲法が現実より遅れると内乱が起きる。
CLAUDE.md を憲法として扱うことの意味は：常にコードよりも先を走る。
smarts.md、5 日、92 commits：
PR の平均寿命は 30 分。大規模リファクタなし、「さっきの方向が違った、巻き戻し」もなし。
Claude が魔法だからではない。session ごとに 565 行のレールの上を走っていたからだ。TypeScript を入れないこと、Solid Queue がデフォルトキューであること、view 関数のキャッシュが 60 秒であること、各 service が call クラスメソッドを実装すること、commit の前に私の確認を待つこと——全部知っている。
これらの制約を半分剥がせば、こうなる：毎日 30 分「なぜ X を使わないか」を説明し、5 分「ついでに」入った依存をレビューし、Gemfile が静かに崩れていく。
白紙から始めるな。直近で痛かった判断から始めろ。
最近 Claude にやられたのが「すぐ新しい依存を入れる」なら、禁忌リストを書け。
「すぐにアーキテクチャを変える」なら、アーキテクチャ図 +「マイクロサービス追加・DB 入れ替えは要確認」。
「テストを書かない」なら、「単体テスト必須の範囲」。
「コミットが攻撃的すぎる」なら、「自動 git commit 禁止、明示指示まで待つ」。
痛むたびに 1 行追加する。それ以外は当面書かない。
3 ヶ月後には 500 行の CLAUDE.md ができている。そのすべての行が、具体的な「もう二度とこれをやらせたくない」の裏返しだ。このドキュメントはどんなテンプレートよりも効く。あなたのプロジェクト、あなたのワークフロー、あなたのチーム（一人でも）の現実的な制約に厳密に合わせ込まれているからだ。
憲法は一発で書き上がるものではない。具体的な衝突が一つひとつ結晶化していく。