CLAUDE.mdに書くべきなのは「コードの説明」ではない｜実際に運用中のファイルを分解する
技術構成やコーディング規約を丁寧に書いても、作業はあまり速くなりませんでした。実際に運用している187行のCLAUDE.mdを見直したら、有効に効いていた部分は4種類だけでした。
結論：書くべきは「毎回同じことを説明している内容」
CLAUDE.mdの書き方を調べると、たいてい「プロジェクトの概要、技術構成、コーディング規約を書きましょう」と出てきます。
その通りに書いても、作業はあまり速くなりませんでした。
実際に運用している187行のCLAUDE.mdを見直したところ、効いていたのは次の4種類だけでした。
| 書くべきもの | なぜ効くか |
|---|---|
| 毎回同じ手順の作業 | 手順を思い出す時間がゼロになる |
| どのファイルを触るべきか | 探す時間と、間違った場所を触る事故が消える |
| 知らないと壊れる落とし穴 | 一度やった失敗を二度やらなくなる |
| 作業前に確認すること | 情報が足りないまま始めるのを防ぐ |
共通しているのは、「自分が毎回説明している内容」である点です。逆に言うと、説明しなくても伝わることを書いても効果がありません。
効いた書き方1：毎回同じ手順は、そのまま貼る
実際のファイルに、こう書いてあります。
#### デプロイ手順（毎回同じ）
```bash
git add persona/goods_config.yaml src/static/goods/
git commit -m "商品名を追加"
git push -u origin claude/homepage-payment-spreadsheet-DD1ly
# → GitHub MCP で PR作成 → マージ → Render が自動デプロイ
```
ポイントは「毎回同じ」と明記していることです。
手順を書くだけなら普通のメモですが、「毎回同じ」と書いてあると、判断が不要な作業だと分かります。 考える対象から外れるので、そのぶん速くなります。
ブランチ名まで書いているのも意図的です。思い出す必要のあるものを1つも残さないのが目的です。
効いた書き方2：「コードは触らない」と明記する
これが一番効いた1行でした。
**設定ファイル:** `persona/goods_config.yaml`
**画像置き場:** `src/static/goods/`
**コード変更は不要** — YAMLを編集してコミットするだけ。
商品を追加するとき、設定ファイルを書き換えるだけで済む設計になっています。しかしこれは、コードを読んだだけでは分かりません。
書いていない場合に何が起きるかというと、設定ファイルで済む作業なのに、コード側を読みに行きます。 読んだ結果、正しくても遠回りですし、悪くするとコードを書き換えてしまいます。
「触らなくていい場所」を明示するのは、「触る場所」を書くのと同じくらい重要です。
効いた書き方3：落とし穴を、結果とセットで書く
同じファイルから、そのまま引きます。
- **応募データの永続化には `DATABASE_URL` が必須**。Renderの無料プランは
ファイルが再デプロイ・スリープ復帰で消えるため、未設定だと応募が消える。
注目してほしいのは「未設定だと応募が消える」の部分です。
これがなく「DATABASE_URL を設定すること」とだけ書いてあったら、優先度が伝わりません。 設定項目はいくつもあるので、その1つとして流されます。
「やらないとどうなるか」を書くと、優先度が伝わります。 データが消えると書いてあれば、後回しにはなりません。
もう1つ、判断の材料も添えてあります。
- `/audition/admin` の下部に保存先のステータスが表示される。
「⚠️ データベース未設定」と出ていたらRenderの環境変数を確認する。
確認方法まで書いてあるので、疑わしいときに調べ方で迷いません。
効いた書き方4：作業前の確認事項をリストにする
#### 商品を追加するときに確認すること
1. 商品名
2. 本体価格（税込）
3. サイズ展開（S/M/L/XL/XXL など）& XXLだけ値段が違うか
4. カラー展開
5. デザイン展開（複数デザインがあるか）
6. 商品写真（添付してもらう → `src/static/goods/` に保存）
これがあると、作業を始める前に足りない情報が分かります。
書いていないと、半分作ってから「サイズ展開は何ですか」と聞くことになります。 手戻りが発生し、そこまでの作業がやり直しになります。
「XXLだけ値段が違うか」のような細かい条件が入っているのが実務的です。過去に一度つまずいた項目が、そのままリストになっています。
書かなくてよかったもの
逆に、書いても効果が薄かったものを挙げます。
① 技術構成の一般的な説明
「FlaskはPythonのWebフレームワークで……」といった説明は不要でした。一般的に知られている内容は、書かなくても通じます。
書く価値があるのは「このプロジェクト特有の事情」だけです。
② コーディング規約の詳細
インデント幅や命名規則を細かく書くより、既存のコードに合わせるという方針が1行あれば足りました。 実際のコードが最も正確な規約だからです。
③ ファイル一覧
ディレクトリ構成を書き写しても、すぐ古くなります。 更新を忘れた瞬間に、間違った情報として害になります。
変わりやすいものは書かない。 これは重要な線引きです。CLAUDE.mdは手で更新するファイルなので、更新されない前提で内容を選ぶべきです。
複数のツールを使うなら、中身は1か所に置く
別のプロジェクトでは、CLAUDE.mdの中身が1行だけです。
@AGENTS.md
@ に続けてファイル名を書くと、その内容が読み込まれます。
なぜこうしているかというと、AIツールごとに読むファイル名が違うからです。同じ内容を複数のファイルに書くと、片方だけ更新して食い違います。
中身は1つのファイルに置き、他はそこを指すだけにする。 これで食い違いが原理的に起きなくなります。
分量の目安
長さより、更新できるかどうかで決めてください。
私のファイルは187行ですが、そのほとんどが、後から追加した落とし穴と手順です。最初から187行書いたわけではありません。
実際の増やし方はこうです。
同じ説明を2回した → CLAUDE.mdに書く
同じ失敗を2回した → 落とし穴として書く
1回目では書きません。 1回きりのことを書き始めると、更新されない情報でファイルが埋まります。2回目が「繰り返す」の証拠です。
つまずきやすい点
書いた内容と実際がずれると、害になる
間違った情報は、書いていないより悪いです。
設定ファイルの名前を変えたのにCLAUDE.mdを直さないと、存在しないファイルを探しに行きます。 そのぶん時間がかかり、しかも原因が分かりにくくなります。
ファイル名やパスを書くときは、変更したら直す対象が増えることを意識してください。 頻繁に変わるものは、そもそも書かないほうが安全です。
「丁寧に書く」と逆効果になることがある
説明が長いと、重要な行が埋もれます。
前述の「未設定だと応募が消える」のような絶対に外せない1行は、周りに一般論が多いほど目立たなくなります。一般論を削るのは、重要な情報を目立たせるためです。
よくある質問
CLAUDE.mdは最初にどれくらい書けばいいですか？
技術構成やディレクトリ構成は書くべきですか？
落とし穴はどう書けばいいですか？
他のAIツールも使っている場合はどうしますか？
CLAUDE.mdとスキルはどう使い分けますか？
まとめ
- 書くべきは「毎回同じことを説明している内容」。一般論ではない
- 毎回同じ手順は、コマンドごとそのまま貼る
- 「コードは触らなくていい」の明記が最も効いた
- 落とし穴は「やらないとどうなるか」とセットで書く
- 変わりやすい情報（ディレクトリ構成・ファイル一覧）は書かない
- 増やすのは2回目から。 1回きりのことを書くとファイルが腐る
作業ごとの長い手順書は、CLAUDE.mdではなくスキルに移すとファイルが短く保てます。役割ごとの権限分けについてはサブエージェントの記事にまとめました。