DEV Community

Olivia Craft
Olivia Craft

Posted on

You Are Right — You Don't Need CLAUDE.md

#ai #programming #productivity #claudeai

You Are Right — You Don't Need CLAUDE.md

You don't need it the same way you don't need types in your JavaScript, comments in your code, or tests in your repo.

It will work without them. Until it doesn't.

I've been watching the "you don't need CLAUDE.md" takes pile up this week, and most of them have a point. A bad CLAUDE.md is worse than no CLAUDE.md. Vague instructions, conflicting rules, 200 lines of motivational filler — all of that turns Claude into a confused intern instead of a focused engineer.

But the real problem isn't the file. It's the rules.

The case for skipping it

The skeptics are right about three things:

  1. Most CLAUDE.md files are bloated. "Be concise. Be helpful. Use clean code." Claude already knows. You're burning context for nothing.
  2. Rules drift. You write a rule on Monday, the codebase moves on Tuesday, the rule lies to the model on Wednesday.
  3. The default model is already strong. For toy projects, throwaway scripts, one-off prototypes — you genuinely do not need CLAUDE.md.

If your bar is "Claude works without it," the skeptics win. Close the tab.

The case for actually writing one

There's a second bar. The bar where you ship code on a real codebase with a real team and you don't want to re-explain your conventions every single session.

That's where rules earn their keep. And it's where the difference between a sloppy CLAUDE.md and a sharp one becomes the difference between an AI that respects your codebase and one that fights you on every PR.

Three real before/afters, pulled from the rule packs we ship at OliviaCraft.

Example 1 — Spring Boot

Ask: "Add a /users endpoint that returns a list."

Without rules:

@RestController
public class UserController {
    @GetMapping("/users")
    public List<User> getUsers() {
        return userRepository.findAll();
    }
}
Enter fullscreen mode Exit fullscreen mode

Looks fine. Ships to prod. Now your /users endpoint dumps your entire users table. No pagination. No DTO. No validation. Lazy-loaded fields trigger N+1 queries. Welcome to the Monday incident.

With rules (CLAUDE.md includes: return DTOs from controllers — never JPA entities; default page size 20, max 100; validate request params):

@RestController
@RequestMapping("/users")
public class UserController {
    @GetMapping
    public Page<UserDto> getUsers(@PageableDefault(size = 20) Pageable pageable) {
        return userService.findAll(pageable).map(UserMapper::toDto);
    }
}
Enter fullscreen mode Exit fullscreen mode

Same model. Same prompt. Different rule file. The second one ships.

Example 2 — Laravel

Ask: "Add a controller method to update a post."

Without rules:

public function update(Request $request, Post $post)
{
    $post->update($request->all());
    return $post;
}
Enter fullscreen mode Exit fullscreen mode

Mass-assignment vulnerability in three lines. The model didn't know your team enforces Form Requests, so it didn't write one.

With rules (CLAUDE.md: all write endpoints use a Form Request — never raw Request; respond with Eloquent Resources; authorize via Policy before update/destroy):

public function update(UpdatePostRequest $request, Post $post): PostResource
{
    $this->authorize('update', $post);
    $post->update($request->validated());
    return new PostResource($post->fresh());
}
Enter fullscreen mode Exit fullscreen mode

The rule didn't make Claude smarter. It made the team's standards visible.

Example 3 — C# / .NET

Ask: "Wire up DI for IPaymentService."

Without rules:

services.AddTransient<IPaymentService, StripePaymentService>();
Enter fullscreen mode Exit fullscreen mode

Transient. Every request rebuilds the HttpClient. After 1k req/min you're in socket-exhaustion territory and your Stripe latency p99 looks like a heart monitor.

With rules (CLAUDE.md: HTTP-backed services register through IHttpClientFactory as typed clients; never inject HttpClient directly; external calls go through a Polly retry pipeline):

services.AddHttpClient<IPaymentService, StripePaymentService>()
        .AddPolicyHandler(PaymentPolicies.Retry);
Enter fullscreen mode Exit fullscreen mode

That's not "Claude got better." That's "Claude finally knew the rule."

Why "you don't need it" misses the point

The argument is usually: the model is smart, your rules are noise, just let it work.

That's true the way "you don't need a style guide, smart engineers can read code" is true. Yes, technically. Now multiply by ten engineers and three years and tell me how that goes.

CLAUDE.md isn't there to make Claude smarter. It's there to encode the non-obvious parts of your codebase — the conventions a senior engineer would correct in review, the load-bearing decisions that aren't visible in any single file, the team's hard-won lessons.

Strip it down to that, and 12-15 sharp lines do more for your output than 200 lines of vague advice ever will.

What a good CLAUDE.md actually looks like

  • Stack-specific. Spring Boot rules belong in a Spring Boot file, not a generic "be careful" preamble.
  • Concrete. "Use DTOs at the boundary" beats "write clean code."
  • Short. Under 50 lines for most projects. Long files dilute themselves.
  • Tied to real incidents. Every rule should answer "what bug did we fix by writing this down?"

If your CLAUDE.md doesn't do that, the skeptics are right — delete it. You're shipping noise.

If you don't have one yet, and you're tired of re-explaining the same conventions every session, we put together rule packs for the stacks where the cost of getting it wrong is highest: Spring Boot, Java, Laravel, C#, Go, Next.js, Rust, and more. Each pack is short, concrete, and built from real production rules — not motivational filler.

→ Get the CLAUDE.md Rules Pack

The skeptics are half right. You don't need CLAUDE.md.

You need a good CLAUDE.md.

Top comments (0)