CLAUDE.md Structure for Lossy Context Compression - Top and Bottom Wins
CLAUDE.md Structure for Lossy Compression
Context windows are not lossless. As they fill up, the model's attention to different parts of the input varies. Content at the beginning and end gets more reliable attention than content buried in the middle. This is not a bug - it is how transformer attention works in practice.
If your CLAUDE.md has critical instructions only in one place, they will eventually get lost during long sessions. The fix is structural redundancy.
Put Critical Instructions at Top and Bottom
Structure your CLAUDE.md with the most important rules at the very beginning and repeat them at the very end. The middle can contain detailed reference material, examples, and context that is useful but not critical.
# CRITICAL RULES (top)
- Never push to main without tests
- Always use accessibility APIs, never screenshots
- Run type checker before committing
# Detailed Context (middle)
... project architecture, API docs, conventions ...
# CRITICAL RULES (repeated at bottom)
- Never push to main without tests
- Always use accessibility APIs, never screenshots
- Run type checker before committing
Why Redundancy Beats Precision
Engineers instinctively avoid repetition. DRY is deeply ingrained. But CLAUDE.md is not code - it is a prompt. And prompts operate under different rules.
When the context window is full and the model is compressing its attention, having the same instruction in two high-attention positions means it is more likely to survive. A single mention in the middle might get compressed away entirely.
The Middle Is for Reference
Use the middle section for information the agent needs to look up but does not need to hold in active memory. Architecture diagrams, file path conventions, API endpoint lists - things the agent will reference when relevant but should not need to recall unprompted.
Test Your Structure
Run a long session - 30 minutes or more - and check whether the agent still follows your critical rules at the end. If it starts violating rules that appear only once in the middle of CLAUDE.md, you have a compression problem. Move those rules to the edges.
Fazm is an open source macOS AI agent. Open source on GitHub.