半年前の自分と今の自分を比べて、開発のリズムが一番変わったのは「同じ前提を、毎回ゼロから説明しなくて済むようになったこと」でした。
Claude Codeを使い始めた頃は、新しいセッションを開くたびに「このプロジェクトはNext.js 16です」「記事は必ず日英セットで作成します」「pushはワークスペースではなく/tmp配下で行います」と同じ文脈を繰り返していた記憶があります。一回あたりは30秒ほどです。けれど1日に何度もセッションを立ち上げるようになると、気づけば「前提の説明だけ」に毎日かなりの時間と集中力を使っていました。
変えたのはたった一つ、プロジェクトルートに CLAUDE.md を置いて、本気で育て始めたことでした。
「毎回ゼロから」が半年続くと、それだけで疲弊する
最初、私にとってCLAUDE.mdは形式的な存在でした。READMEと似たような短い説明を書いて、一度も見直さずに放置していたのを覚えています。
当時の私は、Claudeへの説明を「一回限りのコスト」としか考えていませんでした。文脈が足りなければ、その場で補えばいい。そう割り切っていたのです。
けれど半年近く毎日Claudeと作業を重ねるうちに、この考えが見落としていたことに気づきます。同じ前提を何度も伝え続けるのは、コストの積み重ねではなく摩耗です。毎回、自分の記憶の中から「このプロジェクトの決まりは何だったか」を取り出して言葉にする作業は、想像以上に集中力を削ります。
決定的だったのは、あるリリース作業で「プレミアム記事の highlights 設定を忘れた」という同じミスを3週連続で繰り返したときでした。Claude自身は悪くないのです。私がそのルールを毎回伝えていなかったから、Claudeは気づきようがなかっただけでした。
ここから、CLAUDE.mdをまじめに育てる生活が始まりました。
CLAUDE.mdに書くべきもの、書かないべきもの
半年運用してたどり着いた線引きはシンプルです。
書くべきもの
- 絶対に曲げられないルール（例: 「記事は必ず日英セットで作成する」）
- プロジェクト固有のワークフロー（ディレクトリ構成、git操作の手順、デプロイの癖）
- 過去の失敗から得た教訓のうち、再発しやすいもの
- プロジェクトの「意思決定の理由」 — 決定内容だけでなく「なぜそうしたか」まで
書かないべきもの
- コードを読めば分かること（クラスの責務、関数の引数）
- 頻繁に変わる数値（現在の記事数、進行中のユーザー数）
- 初見の読者向けの説明（CLAUDE.mdはプロジェクト内部の申し送りです）
基準は一つです。CLAUDE.mdは毎セッション自動で読み込まれます。書きすぎれば、全てのセッションで冗長な情報が処理されることになります。 必要十分の量に絞るほうが、結果的にClaudeの判断精度が上がります。
私のDolice Labsプロジェクトでは、CLAUDE.mdの本文は約500行に落ち着きました。最初は1,000行近くありましたが、「これはコードを読めば分かる」と思った項目を半分削ったところ、かえって重要なルールが目立つようになったのです。この感覚は、Claude Codeのメモリ管理入門 — CLAUDE.mdとMEMORY.mdの仕組みと使い方の考え方とも重なります。
「成功パターン」を書き残すと、判断の型が再現できる
半年運用して一番効いたのは、実は失敗の記録ではなく、成功パターンの言語化でした。
たとえばDolice Labsには「決済コンポーネントを変更するときは、bfcache対策・リンク整合性・button使用・plan_type区別の4点を必ず確認する」というチェックリストがあります。過去の小さな障害から導き出したものですが、書き残したおかげで次にやるときの判断が速く、確かになりました。
### 決済コンポーネント変更時の必須チェック
1. **bfcache 対策**: 外部リダイレクトするボタンには `pageshow` + `event.persisted` で loading をリセット
2. **リンク先の整合性**: `/support` や `/membership` へのリンクが決済フローと一致しているか確認
3. **button 使用**: 決済ボタンは `<button onClick={handleCheckout}>` で `/api/checkout` を直接呼ぶ（`<a>` リンク禁止）
4. **metadata.plan_type**: `tip` / `premium` / `pro` を必ず区別するこのような「判断の型」を書き残しておくと、次の自分もClaudeも同じ基準で判断できます。人間一人の記憶には頼れない意思決定が、プロジェクト側に蓄積されていく感覚があります。
もう一つ大事なのは、この書き方をすると「なぜそうするのか」まで残ることです。理由が残っているルールは、例外的な状況が来たときに柔軟に判断できます。ただ「こうしなさい」とだけ書かれたルールは、ちょっと状況が変わるとすぐ運用に詰まるのです。
コードだけでなく、こうした「申し送り」の書き方にも「読まれる前提の工夫」が効いてきます。この感覚を体系的に言語化している書籍として、リーダブルコード ― より良いコードを書くためのシンプルで実践的なテクニック（Dustin Boswell, Trevor Foucher）はCLAUDE.mdを書く手助けにもなりました。コードレビューだけでなく、プロジェクト文書の書き方として読み直すと新しい発見があります。
月1回の「CLAUDE.md棚卸し」で腐らせない
CLAUDE.mdは放置すると静かに腐ります。半年前には重要だった情報が、現在の設計ではすでに不要になっている、ということも珍しくありません。
私は月に1回、必ずCLAUDE.mdを見直す時間を取るようにしています。チェックしているのは次の3点です。
- すでに解決した問題の記述が残っていないか（例: もう発生しないバグの回避策）
- 現在の設計と一致しないルールがないか（例: カテゴリ追加時の手順が新しい仕組みに合っていない）
- 書いたが一度も参照されていないルールがないか（使われないルールは、ノイズ以上のものになりません）
このメンテナンスを怠ると、CLAUDE.mdは「読んでも参考にならないもの」へと静かに変質していきます。信頼できる情報源であり続けることが、Claudeの提案品質を支える地味で重要な土台です。
ちなみに、Dolice Labsの運用全体を通した話はCoworkのおかげで、4サイトの毎日の更新がこんなに楽になったでも触れていますので、併せて読んでいただけると嬉しいです。
明日から始める最初の一歩
半年運用した今、私にとってCLAUDE.mdは単なる設定ファイルではなく、**自分とClaudeが共有する「プロジェクトの記憶」**になりました。プロジェクトとルールブックが並行して育っていく感覚は、一人で開発しているはずなのに、どこかチームで働いているような手触りがあります。
もしまだCLAUDE.mdを書いていない方は、次のセッションで一番繰り返している説明を、たった1行だけ書いてみてください。それだけでも、翌日からの作業が少し軽くなるはずです。
育てるのは急がなくていいのです。プロジェクトが動き続けている限り、記憶は少しずつ、でも確実に積み上がっていきます。