← Terse Blog
Claude Code

System Prompt Bloat

By Luz Wang·Founder, Terse·Updated Jul 17, 2026

Your CLAUDE.md or system prompt is the most-read file in your project — the model loads it on every single turn. That makes every redundant sentence in it a tax you pay hundreds of times a day. Most instruction files are roughly three times longer than they need to be, and trimming them loses nothing: one rule, one line, stated once.

Why System Prompt Size Matters More Than Any Other File

An ordinary source file costs tokens when it is read. A system prompt costs tokens on every turn of every session, because it sits at the front of the context that gets re-sent with each request. A 40-turn day with an 8,400-token CLAUDE.md means the model processed those instructions 40 times. Trim it to 2,900 tokens and — even before caching enters the picture — you have removed roughly 220,000 tokens from a single day's traffic. Over a year that trim is worth on the order of $180 for one developer, more for a team.

The Three Bloat Patterns

1. Repetition

The same rule stated three different ways, usually because it was added three different times. "Always use tabs." Later: "Indentation: tabs, not spaces." Later still: "Note that this project uses tab indentation." The model needs one of these. Merge overlapping rules ruthlessly — if two bullets could be one, they should be.

2. Narration

Long explanations of why a rule exists, when the model only needs the what. The history lesson behind your branching strategy does not change how the model names a branch. Cut every "because" clause and every paragraph of rationale. A rule reads better as an imperative bullet than as a story:

Bloated:  "We decided back in 2024 that because our CI system
           has trouble with long file names, and since some
           developers are on Windows, it would be best if
           everyone tried to keep file names short."
Tight:    "- Keep file names under 40 chars"

3. Dead rules

Instructions referencing files, scripts, or workflows that no longer exist. Dead rules are worse than useless — the model may waste turns trying to follow them, and every stale path erodes its trust in the rest of the file. Audit quarterly: if a rule names a file, confirm the file exists.

How to Trim Without Losing Rules

Convert prose to bullets. Every rule should be one imperative line. "Always run tests before committing" — not a paragraph about why testing matters.
Delete the why. Keep rationale in your team wiki if you must keep it somewhere. The model follows tight instructions better, not worse.
Merge overlaps. One rule, one line, stated once.
Remove anything the model already does by default. Instructions like "be helpful" or "write clean code" consume tokens to request behavior you would get anyway.

Order the File for Caching

Trimming shrinks the tax; ordering makes what remains nearly free. Prompt caching works on stable prefixes: if the beginning of your context is byte-identical across requests, it is served at about a tenth of normal input price. That means volatile content — today's date, the current task list, session notes — must live at the bottom of your CLAUDE.md, never the top. One timestamp on line 3 busts the cache for everything after it, every turn. The full mechanics are covered in the prompt caching guide.

Terse can compress reference docs and CLAUDE.md blocks before you commit them, and its session monitor shows how much of each turn's cost is instruction overhead — the fastest way to find out whether your system prompt has quietly tripled in size. Once the instructions are lean, the next biggest lever is what your agent reads into context: see the context window diet.

See What Your Instructions Cost

Terse tracks per-turn token cost across your agent sessions, so a bloated system prompt shows up as a number instead of a hunch. On-device, free to start.

Download Terse

Frequently Asked Questions

How long should a CLAUDE.md file be?

As short as it can be while stating every rule once. Well-trimmed instruction files for a mid-size project typically land between 1,000 and 3,000 tokens. If yours exceeds 5,000, look for repetition, rationale paragraphs, and dead rules.

Does a shorter system prompt make the model follow rules worse?

No — usually the opposite. Models follow tight imperative bullets more reliably than long prose, because each rule is unambiguous and none are buried. Redundancy does not reinforce a rule; it dilutes the file.

Why should volatile content go at the bottom of CLAUDE.md?

Prompt caching matches the byte-identical prefix of your context. Stable rules at the top stay cached at ~10% of normal input cost; a date or task list near the top changes the prefix and forces a full-price re-read of everything below it, every turn.