Diagnosing a Bloated CLAUDE.md

1. Useful vs. filler:

Almost the entire addition is filler. "Microservices architecture," the list of three services and their directory names, "each has its own package.json and Dockerfile," "communicate over HTTP using REST APIs," "Express.js for routing," "Jest for testing" — all of this is directly visible by listing the services/ directory and opening any one service's package.json. A competent engineer (or Claude) would reconstruct all of it in under a minute of reading the code. None of it is a rule, a convention that deviates from what Express/Jest would lead you to expect, or a trap.

"Please write clean, well-tested code and follow best practices" is the other common filler pattern: it's unverifiable. There's no concrete action anyone could point to and say "this violates the instruction" or "this satisfies it." It gives the agent nothing to act on differently than it would by default.

Nothing in the paragraph is load-bearing. If it were deleted entirely, an agent working in this repo would lose no actionable information.

2. A version that earns its place (inventing plausible specifics, since the real repo's actual quirks aren't given):

## Services (services/user-service, order-service, notification-service)

- Inter-service calls MUST go through `shared/http-client.ts`, not raw
  `fetch`/`axios` — it injects the internal auth header and retry logic.
  A service calling another service without it will 403 in staging.
- `notification-service` is the only service allowed to write to the
  `sent_notifications` table directly; other services publish an event
  instead (see `shared/events/`). Writing to that table from elsewhere
  breaks the dedup logic.
- Each service's tests run against a shared Postgres test container
  (`make test-services`), not per-service — running `jest` directly in
  one service's directory will fail on missing tables.
- `order-service`'s Dockerfile pins Node 18 specifically (not the repo
  default of Node 20) because of a native dependency; don't "fix" this
  during a routine bump.

Every line here is either a command with a non-obvious flag/behavior, a convention that a default Express/Jest setup would not lead you to assume, or a trap that would cost real debugging time to discover independently. This is the bar: each entry should be something that, if omitted, would plausibly cause a real mistake — not just "would be nice to mention."

3. Why filler degrades the rest of the file:

This isn't just about token cost, though that's real too (every session, every engineer, pays to load it). The more important mechanism is about signal-to-noise inside the instruction-following process itself. CLAUDE.md is delivered as context the agent reads and weighs, not as a hard constraint it mechanically checks off. When a file is mostly restating things the agent would already infer, the genuinely load-bearing rules — "never write to sent_notifications directly," "don't bump order-service off Node 18" — are surrounded by sentences that look equally authoritative but carry zero new information. The agent has no structural signal distinguishing "this is critical, deviates from defaults, and will break something" from "this is scene-setting." Documented behavior from Claude Code's own guidance is that longer, less-focused CLAUDE.md files measurably reduce instruction adherence — the practical effect of filler isn't neutral, it's actively worse than not writing the filler section at all, because it dilutes the entries that were doing real work.