0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@ei_1263_

CLAUDE.md、"ほとんど"何も書かなくてよくない？

0
Posted at

Claude Codeを使っていると、一度は「CLAUDE.mdに何を書けばいいんだろう？」って考えると思います。

検索すると、

  • コードを書く前に必ずテストする
  • 既存コードを確認してから変更する
  • 勝手にファイルを作らない
  • 命名規則を守る
  • コミット前にlintを実行する
  • このディレクトリ構成を守る

など、AIに守ってほしいルールをに書いている例をよく見かけます。

もちろん、こうした情報を書くこと自体が悪いわけではありません。

ただ、Claude Codeを実際に使っていると、個人的には少し違う考えになりました。

CLAUDE.mdは、ほとんど何も書かなくていいのではないか。

むしろ重要なのは、

「AIに守らせたいルール」を書くのではなく、「AIが自力では知り得ないプロジェクト固有の情報」を書くこと

なのではないかと思っています。

あくまで個人的な考えですが、この記事では、私が現在考えているCLAUDE.mdの使い方について整理します。

そもそもCLAUDE.mdにはどんなスコープがあるのか

まず、CLAUDE.mdは置く場所によって適用される範囲が変わります。

大きく分けると、私は次の3つとして考えています。

1. グローバルなCLAUDE.md

パソコン全体、あるいは複数のプロジェクトに共通して適用するものです。

2. プロジェクト直下のCLAUDE.md

特定のプロジェクトにだけ適用したい情報です。

ここが一般的にイメージされるCLAUDE.mdだと思います。

3. サブディレクトリのCLAUDE.md

さらに限定された範囲で適用したい情報です。

例えば、

frontend/
  CLAUDE.md

backend/
  CLAUDE.md

のような構成です。

frontendにしか存在しないルールや、backendにしか存在しない特殊な事情などを記述できます。

つまりCLAUDE.mdは、

「この情報はどの範囲で必要なのか」

というスコープを意識して配置するものだと考えています。

結論：CLAUDE.mdはほとんど何も書かなくていい

ここまで説明しておいてですが、私の結論はかなりシンプルです。

CLAUDE.mdは、できるだけ小さくした方がいいと思っています。

特に、

AIにこうしてほしい
AIはこれをしてはいけない
AIは必ずこれを実行する

というルールを大量に書くことには、そこまで価値がないと感じています。

理由は単純で、

CLAUDE.mdに書いたからといって、AIが必ずそのルールを守るわけではないからです。

「〜するな」を大量に書いても、結局破られる

Claude Codeを使っていると、たぶん多くの人が経験すると思います。

例えばCLAUDE.mdに、

- テストを必ず実行してください
- lintを必ず実行してください
- 勝手に既存ファイルを削除しないでください
- anyを使用しないでください

と書いておいたとします。

それでも、状況によっては普通に破られます。

「テストを実行してください」と書いたのにテストを実行しない。

「このファイルは変更しないでください」と書いたのに変更する。

「この方法は禁止」と書いたのに、別の文脈では普通にその方法を使う。

これはClaudeが悪いというより、そもそもCLAUDE.mdが強制力を持つ仕組みではないからだと思っています。

AIはコンテキストをもとに判断してコードを生成しています。

したがって、CLAUDE.mdを「絶対に守らせるルールブック」のように扱うことには限界があります。

だったら、ルールは仕組みで守ればいい

ここが一番重要だと思っています。

例えば、

「テストを必ず実行してください」

とCLAUDE.mdに書くより、

CI/CDでテストを実行して、失敗したらマージできないようにする。

こちらの方が確実です。

同じように、

守りたいこと CLAUDE.mdより向いているもの
コードフォーマット Formatter
命名規則の一部 Linter
型安全性 TypeScript
テスト Test runner + CI
Build CI
Deploy CI/CD
ブランチ保護 GitHub
禁止された依存関係 Linter / dependency checks

というように、機械的に検証できるものは機械に任せるべきだと思います。

例えば、

Claude Code
    ↓
コードを書く
    ↓
CI
 ├─ lint
 ├─ type check
 ├─ test
 └─ build
    ↓
問題があれば失敗

という仕組みがあれば、

テストを必ず実行してください
lintを必ず実行してください
buildを必ず確認してください

とCLAUDE.mdに書く必要性はかなり下がります。

AIにお願いするのではなく、システムとして保証する。

この考え方です。

READMEに書いてあることも、全部コピーしなくていい

もう一つ、CLAUDE.mdが肥大化する原因として、

READMEと同じことを書く

というものがあります。

例えば、

# プロジェクト概要

このプロジェクトは○○のためのWebアプリケーションです。

## ディレクトリ構成

src/
├── components/
├── lib/
├── services/
└── utils/

のような情報です。

もちろん必要な場合もあります。

ただ、AIはリポジトリ自体を読むことができます。

そのため、

「AIがリポジトリを見れば分かること」

までCLAUDE.mdに大量に書く必要はないのではないかと思っています。

READMEに書いてあるならREADME。

コードを見れば分かるならコード。

CIで検証できるならCI。

それぞれの情報を、それぞれ適切な場所に置く方がシンプルです。

じゃあ、CLAUDE.mdには何を書くのか

ここまで「書かなくていい」と言ってきました。

では、

「じゃあ何を書くんだよ」

という話になります。

私が個人的に書く価値があると思っているのは、主に次のような情報です。

1. 自分自身の設定

グローバルなCLAUDE.mdには、本当に最低限だけ書きます。

例えば、

- 日本語で回答してください
- 絵文字はあまり使用しないでください

くらいです。

個人的には、多くても20行程度で十分だと思っています。

ここに、

- 常に丁寧なコードを書いてください
- SOLID原則を遵守してください
- 可読性の高いコードを書いてください
- 適切な設計パターンを使用してください

などと大量に書く必要はないと思っています。

こうした一般的なことは、Claude自身がある程度知っています。

自分が本当に毎回伝えたい設定だけを書く。

それくらいでいいと思います。

2. Linterなどでは防げないプロジェクト固有のルール

これはCLAUDE.mdに書く価値があると思っています。

例えば、

Booleanを表す変数名は `is` または `has` から始める。

というルールがプロジェクトにあったとします。

もちろん、命名規則の一部はLinterなどで検証できます。

しかし、

isActive
hasPermission

のような一般的な命名規則ではなく、

このプロジェクトでは、
「ユーザーが一度でも操作したことがあるか」を表すBooleanは
必ず `hasInteracted` と命名する

のような細かいルールになると、機械的に検証するのは難しくなります。

こうした、

Linterでは防げないけれど、このプロジェクトでは重要

というルールはCLAUDE.mdと相性がいいと思います。

3. プロジェクト特有の「よくあるミス」

個人的には、これがCLAUDE.mdで最も価値のある情報の一つだと思っています。

例えば、

ユーザー情報を取得するときは `users` を直接参照せず、
必ず `user_profiles` 経由で取得する。

過去に `users` を直接参照する実装が入り、
データの整合性に問題が発生した。

という情報です。

これは一般的なベストプラクティスではありません。

Claudeが一般的な知識から推測できるものでもありません。

このプロジェクトを知らないと分からない情報です。

だからこそCLAUDE.mdに書く価値があります。

4. 「ベストプラクティスではないが、このプロジェクトでは必要」なこと

これも重要です。

一般的には、

Aの方法が推奨される

としても、

このプロジェクトでは、

歴史的な理由からBを使用している

ということがあります。

例えば、

通常はRepository Aを使用するが、
このプロジェクトでは外部サービスとの互換性のため
Repository Bを使用する。

新しいコードでもAには変更しない。

といったものです。

こういう情報は、コードだけを見ても理由が分からないことがあります。

そしてAIは一般的なベストプラクティスを知っているからこそ、良かれと思ってAに変更してしまう可能性があります。

こういうときにCLAUDE.mdが役に立ちます。

5. ライブラリや言語のバージョン

これも書いておくと便利だと思います。

例えば、

- Node.js: 24
- TypeScript: 5.x
- Next.js: 16.x
- Prisma: 6.x

などです。

もちろんpackage.jsonなどを見れば分かる情報ではあります。

ただ、AIが参照する情報として、

「このプロジェクトでは現在このバージョンを前提としている」

と明示しておくことには意味があります。

特に、ライブラリのAPIや設定方法が大きく変わっている場合には有効です。

逆に、書かなくてもいいと思うもの

ここまでの話を逆にすると、書かない方がいいものも見えてきます。

一般的なベストプラクティス

- DRYを意識してください
- SOLID原則を守ってください
- 可読性を意識してください
- 適切な設計をしてください

こういったものです。

悪くはありません。

ただ、CLAUDE.mdに書く必要性は低いと思います。

Claudeは既に大量のソフトウェア開発に関する知識を持っているからです。

CIで検証できるもの

- 必ずテストを実行する
- lintを実行する
- buildを確認する

これも、可能ならCI/CDに任せたいところです。

Linterで検証できるもの

- セミコロンを付ける
- ダブルクォートを使う
- import順を守る

こういったものも、FormatterやLinterに任せる方が適切です。

リポジトリを見れば分かること

src/
├── components/
├── services/
└── utils/

のようなディレクトリ構造を、毎回CLAUDE.mdに書く必要もあまりないと思います。

構造そのものが変わったらCLAUDE.mdも修正する必要があり、二重管理になってしまいます。

CLAUDE.mdは「ルールブック」ではない

ここまでの話を一言でまとめるなら、

CLAUDE.mdをAIのルールブックとして使わない。

ということになります。

では何なのか。

私は、

CLAUDE.mdは「AIがリポジトリを見ただけでは分からない情報を補足するためのコンテキスト」

くらいに考えています。

例えば、

AIが既に知っていること
        ↓
書かない

コードを見れば分かること
        ↓
書かない

READMEに書くべきこと
        ↓
READMEに書く

機械的に検証できること
        ↓
Linter / Test / CI/CDに任せる

AIが知らないプロジェクト固有の事情
        ↓
CLAUDE.mdに書く

この切り分けです。

CLAUDE.mdに書くか迷ったら

個人的には、次の質問をすると判断しやすいと思っています。

Q1. これはAIが既に知っている一般的な知識か？

→ Yesなら、基本的に書かない。

Q2. コードやREADMEを見れば分かるか？

→ Yesなら、基本的に書かない。

Q3. LinterやCI/CDで機械的に検証できるか？

→ Yesなら、可能な限り仕組みに任せる。

Q4. このプロジェクトを知らない人には分からない情報か？

→ Yesなら、CLAUDE.mdの候補。

Q5. 過去にAIが何度も同じ間違いをしているか？

→ Yesなら、CLAUDE.mdに書く価値が高い。

この最後のポイントは特に重要だと思います。

最初から大量のルールを書くのではなく、

「実際にAIが間違えた」→「なぜ間違えたか考える」→「AIが知り得ない情報ならCLAUDE.mdに追加する」

という運用です。

最初から100行書くより、10行から始める

CLAUDE.mdを作るときに、

これも守ってほしい
これも書いておこう
これも重要だ

と追加していくと、どんどん巨大化していきます。

しかし、情報が増えるほど、当然コンテキストとして読み込ませる情報も増えます。

さらに、古くなった情報が残れば、それ自体がAIの判断を邪魔する可能性もあります。

そのため、

最初はほとんど何も書かない。

くらいでいいと思っています。

そして実際に開発していて、

また同じ間違いをした
↓
これはコードだけでは分からない
↓
じゃあCLAUDE.mdに書こう

という形で少しずつ増やしていく。

その方が、実際のプロジェクトに必要な情報だけが残ります。

まとめ

個人的なCLAUDE.mdに対する現在の考え方は、かなりシンプルです。

CLAUDE.mdは、たくさん書けば書くほど良いものではない。

むしろ、

  • AIが既に知っていることは書かない
  • READMEと重複することは書かない
  • コードを見れば分かることは書かない
  • Linterで検証できることはLinterに任せる
  • テストで検証できることはテストに任せる
  • CI/CDで保証できることはCI/CDに任せる
  • プロジェクト固有の事情を書く
  • AIが何度も間違えるプロジェクト固有の知識を書く
  • 一般的なベストプラクティスではないが、そのプロジェクトでは必要なことを書く
  • 必要な情報を必要なスコープにだけ置く

という考え方です。

つまり、

CLAUDE.mdに「AIをどう動かすか」を大量に書くのではなく、「AIが知らないこと」を書く。

これが、今のところ私がClaude Codeを使っていて一番しっくりきているCLAUDE.mdの使い方です。

もちろん、プロジェクトの規模やチームの事情によって最適解は変わります。

あくまで「Claude Codeを実際に使ってみて、個人的にはこう考えるようになった」という一つの意見として、参考になればと思います。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?