Writing Lean Context: Token-Efficient Documents for Claude

The problem this solves: Every file Claude reads consumes context. Context is finite. A bloated CLAUDE.md leaves less room for your actual work. A sprawling _history.md read at session start costs tokens Claude could spend on the task. This document covers how to write project files so Claude processes them efficiently — and follows them more reliably.

Why token efficiency is not just about size

The context window is Claude's working memory for a session. When it fills, Claude does not crash — it deprioritizes. Earlier content is weighted more heavily; later content drifts toward background. An overlong auto-loaded file does not just cost tokens: it actively degrades the instructions at the bottom of the file.

Token efficiency matters differently for different files:

File When read Priority
CLAUDE.md Every session, automatically Ruthless — every token competes with your task
notes/progress.md Most session starts, explicitly Tight — current state only, not full history
_history.md On demand, when context matters Can be longer, but needs a cheap entry point
_index.md On search Fine as-is — read selectively, not in full
@imported files Only when Claude accesses matching content Costs nothing until invoked

The rule of thumb: trim auto-loaded files aggressively; structure on-demand files for fast scanning.

Principle 1: Active instructions, not background

CLAUDE.md is loaded into every session whether you need it or not. Every sentence that does not change Claude's daily behaviour is a token tax you pay permanently.

Background — things that help you understand the project — belongs in _history.md or notes/, read when needed. Instructions — things that should change what Claude does — belong in CLAUDE.md.

Belongs in CLAUDE.md Belongs elsewhere
"Write all output to /output/ — never to /sources/" "This project studies heretical networks in Languedoc 1245–1320" (unless it changes how Claude responds)
"Person IDs are primary keys — never modify them" "We chose CSV over XLSX because Claude can read it directly" (→ _history.md)
"Current phase: data extraction from registers 25–40" "Phase 1 ran from March to May 2025 and produced X results" (→ _history.md)
"Default output language: English" The reasoning behind the language choice

If a sentence would be equally true six months from now, it is an instruction. If it describes how you got here, it is history.

Principle 2: Structure over prose

Structured text conveys the same information in 30–50% fewer tokens than equivalent prose. It is also parsed more reliably — Claude adheres to bullet-list instructions more consistently than to instructions embedded in paragraphs.

Prose (expensive, less reliable):

When working with the source files, please be careful not to modify them
because they are the original archival scans and any modification would
compromise the integrity of our primary sources. All output should be saved
to the output folder, not to the sources folder.

Structured (lean, more reliable):

## File rules

- `/sources/` — read only, never modify (original archival scans)

- `/output/` — write all derived files here

The structured version is one-third the length and produces more consistent behaviour.

Prefer:

Principle 3: Positive instructions over negative

Positive instructions — what to do — are processed more efficiently and followed more reliably than negative ones. Every "do not X" requires Claude to first parse what X is, then invert it.

Less efficient More efficient
"Do not write files anywhere except /output/" "Write all files to /output/"
"Never use XLSX; don't use JSON either" "Output format: CSV"
"Don't skip the confidence field or leave it blank" "Confidence field required on every row: high / medium / low"

Negative instructions are sometimes necessary — especially for constraints where the prohibited action is likely. But where a positive form is equivalent, use it.

Principle 4: Front-load

When context fills, Claude weights earlier content more heavily. The instructions most important for daily work belong in the first quarter of CLAUDE.md — not buried after three paragraphs of project background.

Typical ordering:

# Project name

## Working rules          ← most important; first

- Output conventions

- File rules

- Domain conventions

## Project structure      ← second

- Folder map

- Key files

## About this project     ← last (or remove if not actionable)

- Background, if Claude needs it to calibrate responses

The project background that helps Claude understand your domain (who you are, what you study) does affect response quality — but it is the most stable content and can go last, or be @imported.

Principle 5: Match structure to read frequency

Different files serve different reading patterns. Write each one for how it will actually be read.

notes/progress.md — read almost every session

Keep it current-state only. No cumulative history. A single rolling block of the present moment:

## Current state (updated 2025-04-10)

Done: registers 1–24 → 480 deposition entries in extractions.csv
In progress: name-variant resolution for "Guilhem" cluster
Next: registers 25–35
Open: Duvernoy edition discrepancy (three entries differ — cause unknown)
Blocked on: nothing

When this gets updated, the previous block goes to _history.md, not stays here. Progress.md should always be readable in under 30 seconds.

_history.md — read on demand

This file can be long — its value is in completeness. But give it a cheap entry point: a TL;DR block at the top, updated at project milestones, that gives Claude (and you) the essential narrative without reading everything.

# Project history

## TL;DR (as of 2025-04-10)
Corpus: 40 inquisition registers, Languedoc 1245–1330.
Current phase: data extraction (Phase 2 of 3).
Key decisions: CSV over XLSX (Claude-readable); post-1350 records excluded
  (scribal quality); deponent = unit of analysis (not deposition).
Known dead ends: direct JPEG processing (worse extraction than PDF conversion).
Open: Duvernoy edition discrepancy in three entries.

## Entries
[detailed entries follow]

When Claude needs a quick orientation, it reads the TL;DR. When you need the reasoning behind a specific decision, it reads the entries. Two reads for two purposes — neither wastes context on the other.

_history.md archiving

Once the detailed entries section exceeds ~200 lines, move old entries to _history.archive.md. The main file stays scannable. If you ever need the full record, the archive is there — but it is not loaded unless you explicitly ask for it.

Principle 6: @imports for depth

CLAUDE.md can reference other files rather than embedding their content:

## Name variant conventions
@conventions/name-variants.md

## Column definitions
@data/schema.md

Claude reads those files as part of reading CLAUDE.md — but only when it processes CLAUDE.md. The import does not cost tokens unless the file is actually accessed.

Use this to separate:

A researcher extracting persons from a new source needs @conventions/name-variants.md. A researcher writing a summary paragraph does not. Keeping it in a separate imported file means it costs nothing on irrelevant sessions.

Principle 7: Remove dead information

The most expensive content is content that no longer applies. It still costs tokens; it no longer contributes.

Regular pruning targets:

A quarterly prune takes ten minutes. Every line removed from CLAUDE.md is permanently cheaper.

The test: if a sentence were missing, would it change what Claude does today? If no, remove it.

Putting it together: the lean meta-document stack

CLAUDE.md                ← < 200 lines; active instructions only; structured bullets
                           front-loaded with working rules; @imports for reference

notes/progress.md        ← current state only; fits in 10–15 lines; one rolling block

_history.md              ← TL;DR block at top; detailed entries below;
                           archive entries to _history.archive.md when > ~200 lines

@conventions/            ← reference material; @imported from CLAUDE.md;
                           costs nothing until accessed

This stack gives Claude everything it needs, at the moment it needs it, without paying for what it does not.

Quick checklist before saving a project file

Related