Blog

Prompt Caching Lessons from Claude Code

August 2026 · 8 min read · Technical

Abstract layered storage and retrieval visualisation
← Back to all posts

Prompt caching is one of the few cost optimisations that is close to free to adopt and routinely produces a large saving, and it is also one of the most commonly misconfigured. Cached input tokens read at a small fraction of the base rate, but the cache only helps if the cacheable part of your prompt is stable and sits where the cache can find it. Running Claude Code at volume surfaces the practical rules quickly.

The structural rule everything depends on

Caching works on prefixes. Everything from the start of your prompt up to the first thing that changes can be cached; everything after the first variable element cannot. That single fact determines your entire prompt architecture, and it is why two prompts containing identical content can differ enormously in cost depending purely on ordering.

  • Put system instructions, tool definitions, business rules and reference material at the very front, in that order of stability.

  • Put the variable content, the user request, the current file, the specific task, at the end.

  • Never interleave a small variable element, such as a timestamp or a session identifier, into the stable prefix. One variable token near the front invalidates everything behind it.

That last point is the most common mistake we find when auditing an existing implementation. A team injects the current date into their system prompt for context, which seems harmless, and unknowingly destroys caching for the entire prefix on every request.

Cache write costs are real

Writing to the cache costs more than a normal input read, with longer cache durations costing more to write than shorter ones. This means caching is a volume play: a prefix read hundreds of times a day pays back its write cost many times over, while a prefix read twice costs more cached than uncached. Before caching a given prefix, check how often it is actually reused, because caching everything indiscriminately can increase your bill.

What this looks like at Australian production volume

For a workflow sending a large stable prefix, system instructions plus tool definitions plus a reference document, several hundred times a day, correctly structured caching typically cuts input token costs substantially. On a workload spending around $6,000 AUD a month with input dominating, we have seen this bring the input portion down by most of its value, with the write costs amounting to a small fraction of the saving.

The catch is that this benefit degrades silently. A developer adds a small dynamic element to the system prompt six months later, caching quietly stops working, and nobody notices because nothing breaks. The bill simply goes back up, and by then it is attributed to increased usage rather than a regression.

Monitoring the thing that degrades quietly

Because a caching regression produces no error, it needs an explicit monitor. Track the ratio of cache reads to total input tokens as a first-class metric and alert when it drops materially. That single metric catches the entire class of failure, and teams that have it in place find regressions within a day rather than at the end of a billing cycle.

It is also worth reviewing the stable prefix during code review with the same seriousness as a database migration. Adding a variable to a system prompt is a change with a cost consequence, and treating it as a trivial edit is how the regression gets introduced in the first place.

Ordering your prefix by stability, not by logic

A second-order refinement worth applying once the basics are in place: within the stable prefix, order content from most stable to least. System instructions that change once a year go first, tool definitions that change with each release go next, and reference material that gets updated monthly goes last. That way an update to the most volatile stable content invalidates only the tail of the cached prefix rather than all of it.

This runs against the instinct to order a prompt in the sequence that reads most logically to a human, and the cost difference is worth the slight awkwardness. Teams that structure by stability rather than readability keep more of their cache intact through routine updates, which matters most for workflows where the reference material changes regularly.

Where caching does not help

Workflows where every request is genuinely different, with no substantial shared prefix, get little from caching and should not be contorted to create one. Some teams add artificial shared preamble purely to have something cacheable, which adds tokens to every request in exchange for a discount on tokens that did not need to be there. If your prompts are genuinely varied, the cost lever you want is context scoping or model tiering rather than caching.

The general principle for Australian teams running Claude at any real volume is that caching is an architectural decision made once and then protected, not a setting toggled on. Get the ordering right, verify the reuse volume justifies the write cost, monitor the read ratio, and treat changes to the stable prefix as changes worth reviewing.

Ready to move from AI pilot to production?

We help mid-market Australian businesses deploy AI automations that actually reach production and deliver measurable ROI.