Claude Codeの精度が変わる、私が削った CLAUDE.md 5項目

Claude Cowork を社内AXに使っている私の実践ログです。社内固有名・個人名は伏せています。

最初、私は CLAUDE.md に「コーディング規約」「テストの書き方」「ディレクトリ構成」「コミットメッセージのルール」…と、思いついた指示を全部書き連ねていた。

結果、精度が落ちた。

正確には、長く書けば書くほど Claude Code が 本当に守ってほしい指示を無視するようになっていった。3週間くらい「なんで効かないんだろう」と首を傾げて、最終的に半分以上を削ったら一気に動きが安定した。今日はその話。

私が3ヶ月の運用で残した CLAUDE.md 5項目と、削ったときの判断基準を共有する。読んだ人がそのまま自分のリポジトリで貼り替えられる粒度で書く。

なぜ「全部書く」と効かなくなるのか

理由は単純で、長いプロンプトの中盤は読み飛ばされる(LLM の特性として中央の情報の保持率が落ちる、いわゆる lost-in-the-middle)。これは Claude に限らずどの LLM でも起きる。

つまり CLAUDE.md は 「短く書いて、毎回必ず読ませる」場所 であって、社内Wiki の写しを置く場所ではない。私はこれを理解するのに 3週間使った。正直しんどかった。

私の判断:CLAUDE.md は 200行を超えたら負け

賛否あると思うけど、私は CLAUDE.md は 200行以内 を絶対ラインにしている。それを超えそうになったら別ファイルへ切り出し、必要な時だけ @docs/xxx.md で参照させる。

「全部書く」より「読まれる」を取る。これが私の運用方針。

私が残した5項目チートシート

そのままコピペで使える形で置く。<> の中だけ自分のリポジトリ用に差し替えれば動く。

# <プロジェクト名> 開発ルール

## 1. このリポジトリは何か(3行で)
- 何を解決するサービスか
- 誰が使うか
- 触ってはいけないドメイン境界(例: `billing/` は別チーム管轄)

## 2. 動かし方(写経で動くコマンド)
```bash
# セットアップ
<setup command>
# テスト
<test command>
# ローカル起動
<dev command>

3. 鉄則(絶対ルール、5つまで)

• DB マイグレーションは <手順> を通すまで commit しない
• 型は any 禁止、unknown で受けて narrow する
• console.log を本番コードに残さない
• 秘匿情報は .env.local のみ、.env には書かない
• PR の前に <lint command> を必ず通す

4. このリポジトリ特有の落とし穴

• <モジュール名> は historical reasons で命名が逆。xxx が新、yyy が旧
• <API名> は本番では rate limit 60/min、テストは mock を使う

5. 困ったら見る場所

• アーキ図: @docs/architecture.md
• 用語集: @docs/glossary.md
• 過去の意思決定: @docs/adr/

ポイントは3つ。

ひとつ、**動かし方を写経で通るコマンド**として書くこと。「README を読んでください」じゃダメ。Claude Code は外を読まない前提で書く。

ふたつ、**鉄則は5つまで**。それ以上書いたら効かない。私は最初12個書いて、半分以下に削った。

みっつ、**詳細は `@` で別ファイル参照**にする。`CLAUDE.md` に全部書かないで、必要なときだけ膨らませる。

## 私がハマったところ(5つ)

### 1. 「コーディングスタイル」を細かく書きすぎた
最初、私はインデント・命名・コメントの書き方まで `CLAUDE.md` に列挙していた。これ、ぜんぶ linter の仕事。Claude Code に守らせるんじゃなくて、linter に守らせて Claude Code には「`pnpm lint` を通せ」と1行書けばいい。気付くまで2週間かかった。自分でも何やってんだろうって思った。

### 2. 「悪い例」を載せたら逆に増えた
「`any` を使わないでください」の補強で `any` の悪い例を `CLAUDE.md` に書いたら、Claude が **悪い例の方を真似する** 現象に遭遇した。これは罠。書くなら良い例だけ、もしくは「禁止」とだけ書く。

### 3. 否定文を多用すると判断がブレる
「〜してはいけない」「〜は避ける」を並べると、何をすればいいのか曖昧になる。私は途中から **肯定形で書き直した**。「`unknown` で受けて narrow する」のように、やることを書く。

### 4. ディレクトリ構成図を毎回貼っていた
変更頻度が高い情報を `CLAUDE.md` に置くと、すぐ古くなる。古い情報があると Claude はそれを信じて動く。だから構成図は外出しして `@docs/structure.md` 参照に変更した。これ、地味に効く。

### 5. プロジェクト固有の罠を書き忘れた
逆に、これは書かなきゃダメだった項目。「`xxx` は historical reasons で命名が逆」みたいな **コードを読んでも分からない知識** は CLAUDE.md にしか書く場所がない。同じチームの先輩から口頭で聞いた話を、私はずっと脳内に置いていた——もったいなかった。

## 200行を超えそうになったらやること

私のルールでは、以下の順で外へ追い出す。

1. アーキ説明 → `@docs/architecture.md`
2. ドメイン用語 → `@docs/glossary.md`
3. 意思決定の経緯 → `@docs/adr/`(Architecture Decision Records)
4. テスト戦略の詳細 → `@docs/testing.md`

`CLAUDE.md` 本体には「迷ったらここを見て」のリンク集だけ残す。索引として機能させる。

## まとめ

- `CLAUDE.md` は短く書いて、毎回読ませる場所。社内Wikiの写しを置く場所ではない
- 200行を超えそうになったら別ファイルへ切り出す
- 残すべきは「リポジトリの性質・動かし方・鉄則5つ・落とし穴・参照リンク」の5項目
- 「悪い例」を載せると Claude が真似する。書くなら良い例か、禁止だけ
- 否定文より肯定形。「やること」を書く
- linter で守れることは linter に任せる。CLAUDE.md に書かない

みなさんの `CLAUDE.md` はどれくらいの行数ですか? 200行説、賛成 / 反対あればコメントで教えてください。「うちはこの項目も入れてる」というのが一番知りたい。

---

Claude Cowork を社内AXの相棒として毎日使っているエンジニアの実践ログです。
シリーズ: Claude Cowork で社内AXを回す