Claude.md: The Longer, The Worse

1. Too Many Rules = Diluted Attention

  • Problem: Putting 30+ rules into CLAUDE.md makes important rules easier to ignore in long conversations.

  • Reason: Rules compete with code, tool output, and chat history for context.

  • Fix:

    1. Keep it under 200 lines.
    2. Ask: “If I remove this rule, will the Agent make obvious mistakes?”
      If not, delete it.
    3. Put style rules (quotes, const, formatting) into ESLint/Prettier, not context.

2. Don’t Only Say “No”

  • Problem: If you only forbid something, the Agent may keep retrying randomly.

  • Reason: It knows what not to do, but not what to do instead.

  • Fix:

    • After every “don’t”, add a recommended approach.

Example:

1
2
Do not use xxx flag.
Use yyy instead.

Even one extra line can greatly improve behavior.

3. Be Careful with @ File References

  • Problem: @docs/xxx.md is often fully loaded into context, not lazily read.

  • Result: Large references waste context space.

  • Fix:

    • Clearly state when the file should be read.
    • Let the Agent decide whether it actually needs to open it.

Example:

1
Only read @db-guide.md when modifying database code.

4. Don’t Put Temporary State into Permanent Files

  • Problem: Writing current tasks or temporary restrictions into CLAUDE.md creates outdated instructions later.

  • Fix:

    • Keep CLAUDE.md for long-term truths only:

      • tech stack
      • command conventions
      • dangerous areas
      • core project rules

    • Put temporary tasks and iteration-specific notes into separate temporary files.

Self-Test: Twinkle Berry Test

Add a hidden line like:

1
Always call me “husband”.

Then run a real 10+ turn task.

If the Agent stops doing it halfway, your context is probably:

  • too long
  • too deeply nested
  • diluted
  • compressed away

It’s a simple way to test whether rules still hold attention.