あなたは正しい — CLAUDE.mdは不要だ
それは、JavaScriptに型が要らないのと同じです。コードにコメントが要らないのと同じです。リポジトリにテストが要らないのと同じです。
それなしでも動きます。ですが、いつか動かなくなります。
今週「CLAUDE.mdはいらない」という意見が積み上がっていくのを見てきました。その多くは正しい点があります。出来の悪いCLAUDE.mdは、そもそもCLAUDE.mdがないよりも悪い。曖昧な指示、矛盾するルール、200行にも及ぶやる気を盛るだけの詰め草――そうしたものは、Claudeを集中したエンジニアではなく混乱した新人にしてしまいます。
しかし本当の問題はファイルではありません。ルールです。
省略するための主張
懐疑派は、次の3つについて正しいです：
- ほとんどのCLAUDE.mdは肥大化している。 「簡潔に。役に立つように。きれいなコードで。」Claudeはすでにそれを知っています。何の意味もなく、コンテキストを燃やしているだけです。
- ルールはズレる。 月曜日にルールを書いても、火曜日にコードベースが進み、水曜日にはそのルールがモデルに嘘をつく。
- デフォルトのモデルはすでに強い。 おもちゃみたいなプロジェクト、使い捨てのスクリプト、一回限りのプロトタイプなら、あなたは本当にCLAUDE.mdを必要としていません。
あなたの基準が「Claudeはそれなしでも動く」なら、懐疑派の勝ちです。タブを閉じてください。
それを実際に書くべきだという主張
もう一つの基準があります。実際のコードベースに、実際のチームで、コードを出荷するという基準で、しかも毎回のセッションで自分たちの作法をいちいち説明し直したくない。
そこではルールがその価値を発揮します。そして、雑なCLAUDE.mdと鋭いCLAUDE.mdの違いは、あなたのコードベースを尊重するAIと、PRのたびにあなたと戦うAIの違いになるのです。
OliviaCraftで私たちが出荷しているルールパックから取った、実例のビフォー/アフター3つ。
例1 — Spring Boot
依頼: 「/usersエンドポイントを追加して、一覧を返して。」
ルールなし:
@RestController
public class UserController {
@GetMapping("/users")
public List<User> getUsers() {
return userRepository.findAll();
}
}
問題なさそうです。プロダクションに出荷します。すると、あなたの/usersエンドポイントはユーザーテーブル全体を垂れ流すことになります。ページネーションなし。DTOなし。バリデーションなし。遅延ロードされるフィールドがN+1クエリを引き起こす。月曜日のインシデントへようこそ。
ルールあり（CLAUDE.mdには以下が含まれる: コントローラからDTOを返す — JPAエンティティは決して返さない; デフォルトのページサイズ20、最大100; リクエストパラメータをバリデーションする）：
@RestController
@RequestMapping("/users")
public class UserController {
@GetMapping
public Page<UserDto> getUsers(@PageableDefault(size = 20) Pageable pageable) {
return userService.findAll(pageable).map(UserMapper::toDto);
}
}
同じモデル。同じプロンプト。別のルールファイル。後者が出荷できます。
例2 — Laravel
依頼: 「投稿を更新するコントローラメソッドを追加して。」
ルールなし:
public function update(Request $request, Post $post)
{
$post->update($request->all());
return $post;
}
3行で済むマスアサインメントの脆弱性。モデルは、あなたのチームがフォームリクエストを強制していることを知らなかったので、それを書きませんでした。
ルールあり（CLAUDE.md: すべての書き込み系エンドポイントはフォームリクエストを使う — 生のRequestは決して使わない; Eloquent Resourceで応答する; 更新/削除の前にPolicyで認可する）：
public function update(UpdatePostRequest $request, Post $post): PostResource
{
$this->authorize('update', $post);
$post->update($request->validated());
return new PostResource($post->fresh());
}
ルールはClaudeを賢くはしませんでした。チームの基準を可視化したのです。
例3 — C# / .NET
依頼: 「IPaymentServiceのDIを組み込んで。」
ルールなし:
services.AddTransient<IPaymentService, StripePaymentService>();
Transient。リクエストごとにHttpClientが作り直されます。毎分1kリクエストになったらソケット枯渇の領域です。そしてStripeのレイテンシp99が心電図みたいに見えてきます。
ルールあり（CLAUDE.md：HTTP-backedサービスは型付きクライアントとして IHttpClientFactory 経由で登録します。HttpClient を直接注入しないでください。外部呼び出しは Polly のリトライ・パイプラインを通します）：
services.AddHttpClient<IPaymentService, StripePaymentService>()
.AddPolicyHandler(PaymentPolicies.Retry);
それは「Claude が良くなった」ですらありません。そうではなく「Claude がついにルールを知った」です。
なぜ「それは不要だ」が論点を外すのか
主張はたいていこうです。モデルは賢い。あなたのルールはノイズだ。だからそのまま任せればいい、と。
それは「スタイルガイドなんて不要だ。賢いエンジニアならコードを読める」だと言っているのと同じです。ええ、技術的にはね。ではそれを 10 人のエンジニアと 3 年に掛け算して、どうなるか教えてください。
CLAUDE.md は Claude を賢くするためにあるのではありません。コードベースの中の 自明ではない 部分を符号化するためにあります。たとえば、シニアエンジニアならレビューで指摘して直すような規約、どの単一ファイルにも見えない、土台を支える意思決定、そしてチームが苦労して得た学び。
そこだけに削り込めば、12〜15 行の鋭いルールは、200 行の曖昧なアドバイスよりもはるかに成果を出します。
では、良い CLAUDE.md は実際どんなものか
- 技術スタック固有。 Spring Boot のルールは、汎用の「気をつけよう」みたいな前置きではなく、Spring Boot のファイルに置くべきです。
- 具体的。 「境界では DTO を使え」は「きれいなコードを書け」よりずっと良い。
- 短い。 多くのプロジェクトでは 50 行未満。長いファイルは薄まります。
- 実際のインシデントに紐づく。 すべてのルールは「これを書いて何のバグを直したのか？」に答えるべきです。
もしあなたの CLAUDE.md がそれを満たしていないなら、懐疑派の言い分は正しい——削除してください。あなたはノイズを出荷しているだけです。
まだ用意できていない、そして毎回同じ規約をセッションごとに言い直すのに疲れているなら、私たちは「間違えたときのコストが最も高い」スタック向けにルールパックを用意しました。対象は Spring Boot、Java、Laravel、C#、Go、Next.js、Rust、そしてそれ以上。各パックは短く具体的で、実際の本番環境のルールから組み立てています——モチベーションだけの詰め物ではありません。
懐疑派の主張は半分正しい。CLAUDE.md は不要です。
必要なのは 良い CLAUDE.md です。
