I kept running out of Claude before I ran out of work.
Not on the big days. On ordinary ones.
The fix was not a better prompt. It was everything around the prompt. This post is what I built, why each piece exists, and what twenty-nine days of measured usage says about which parts actually earn their place. If you are starting your own, the last two sections are the ones to read first.
What a Harness Actually Is #
Prompt engineering is a small component of a much larger object, and the object does not have a settled name yet. I call it the harness.
You do not write a prompt for a coding agent working on a real system. You build the room it works in, and then it works in that room for months. The room has parts, and every one of them is an engineering decision with a cost:
Two properties make this worth treating as engineering rather than configuration. The first is that everything in the fixed tier is paid for on every single turn, so a paragraph you write once is a paragraph the model reads ten thousand times. The second is that none of it is enforced by default. A rule is a suggestion until something reads it.
The payoff is not subtle. Across the window I measured, the harness reduced my effective token cost by a factor of 6.94, which in practical terms means the usage limit arrives 6.94 times later for the same work. That number comes from one mechanism, and I will get to which one.
Where Mine Came From #
The first file landed on 8 January 2026, a single skill describing frontend patterns. The multi-agent architecture followed on 25 January, rules and agent definitions in the same commit.
The heaviest month of construction was May, by a wide margin. Almost half of the harness's history was written in that one month, and everything since has been revision rather than invention. It changes whenever I read something worth acting on, and it changes after incidents. The fan-out budget rule exists because the machine livelocked at a load average of 138 on sixteen cores. The path-scoping discipline that keeps most rules out of the always-loaded tier arrived in one afternoon, when I demoted six rules at once.
It is still being built. 377 commits landed on the harness inside the twenty-nine days I was measuring it.
The part that reads strangest in the git log is that Claude wrote most of it. I describe a failure, it drafts the rule, and its own catalogue of traps grew from 13 named entries to 85 the same way. That recursion is not a gimmick. An agent is a very good technical writer for the exact class of mistakes it just made, and it will do that work while you do other things.
None of this is hobby tooling, which matters for whether the numbers transfer. It sits under a financial protocol: ten repositories, about twenty backend services, 34,597 commits, 1.68 million lines of code. At that size an unharnessed agent does not merely underperform. It generates work.
The Always-Loaded Tier #
Start here, because it is the only part you pay for unconditionally.
My fixed tier is roughly 200 kilobytes: a root instruction file plus ten rules that load in every session. Twenty-seven rules exist. Seventeen of them are scoped to file globs and cost nothing until a matching file is opened.
That split is the single most useful discipline in the whole harness, and it is worth stating as a rule: a rule belongs in the always-loaded tier only if violating it is dangerous everywhere. My database-safety rule is universal because a test helper once truncated a live database, and I would rather pay for it in every session than in one. My testing-pyramid rule is scoped to test files, because it is meaningless anywhere else.
Now the part that surprised me and will probably surprise you. I assumed my instruction tier was the prefix, and spent weeks trimming it. It is not.
A cold session on my setup writes 129,335 tokens to cache. My own always-loaded files account for at most 51.5 percent of that even under a pessimistic estimate, and closer to 39 percent under a realistic one. The rest is the client's own system prompt, tool schemas, the deferred tool list, the agent roster summary, skill descriptions.
So trim your tier, and calibrate the expectation before you do. Deleting all of it removes less than half of what a cold start costs you.
Prefix Stability #
This is the highest-leverage thing in the post and almost nobody talks about it.
Caching works on prefixes. Everything before the first changed byte is reusable, everything after it is not. One ordering rule follows: stable content first, volatile content last.
Think of the prefix as a printed form. Change a box near the top and the whole page reprints. Change the last line and you reprint one line.
Here is how I got that wrong. My session-start hook injects a digest from my knowledge base: current work, recent commits, an index summary. Useful, and mean size 5,892 bytes. It also carries a wall-clock timestamp at minute resolution, sitting at median byte 917, with a median of 4,961 bytes of otherwise identical text downstream of it.
Two sessions started twenty-nine seconds apart, both payloads exactly 5,193 bytes:
-## Peer state (fetched 2026-08-19 06:47)
+## Peer state (fetched 2026-08-19 06:52)
Two characters. And that injection lands before the first user message in twenty-one of twenty-three sessions, ahead of roughly 190 kilobytes of static instruction.
The bill lands on subagents, because a fleet of them is a fleet of cold starts.
| Subagent cold starts | Measured |
|---|---|
| Cold starts in the window | 2,872 |
| Mean cache write on first response | 79,210 tokens |
| Read nothing from cache at all | 37.8 percent |
| Share of every cache write I paid for | 31.0 percent |
| Began within 5 minutes of the previous one | 79.0 percent |
My instruction tier genuinely changed 100 times. It was rewritten to cache at least 2,269 times where a warm cache already existed, a gap of roughly 22.7 times. That is a layout cost, not a content cost, and the fix changes nothing about what the model reads: move volatile injections to the end of the turn, and round any timestamp to something two sessions in the same hour will agree on.
What I want you to take from this is not the bug. It is that I had a generator, a pre-push gate and a twenty kilobyte rule file all policing the size of that tier, and no instrument at all for its stability. I optimised the wrong axis for months, thoroughly.
Retrieval Instead of Dumping #
The second largest cost is reading things you did not need.
My knowledge base is a generated catalogue beside the corpus: 3,711 documents indexed by their frontmatter, plus a graph where every node carries a pointer back to the file and line that authored it. No embeddings, no vector store, no daemon. Plain files and small scripts, because that is what makes it inspectable.
The catalogue itself is 661,056 bytes, which is the point. Even the index is too big to read, so the rule in my retrieval skills is written as a prohibition: never read the index whole, query it with a script that prints only matches.
One real question, measured both ways. Which open items block module N, and where is each recorded? You cannot grep for that, because you do not know the identifiers in advance. Finding them is the question.
| Approach | Tokens | Ratio |
|---|---|---|
| Read the candidate files | 144,053 | 342.2x |
| Read the compiled registry | 68,004 | 161.5x |
| Query the graph | 421 | 1x |
The query returns eleven results, each with a file and a line number.
Now the honest part, because it changed how I advise people. I classified all 120,591 shell invocations in the window. My purpose-built retrieval scripts account for 190 of them, which is 0.16 percent. What actually carries the load is unglamorous: targeted reads with an explicit line range or a head and tail bound are 41.5 percent of all shell calls, and whole-file reads are 2.8 percent. Bounded reads beat whole-file dumps 14.9 to 1.
So build the fancy tier if your corpus needs it. But the discipline that saves you tokens every single day is smaller than that, and you can adopt it this afternoon: never read a whole file when you know the line range. The shell's default read is bounded and a file tool's default is not, which is most of why my tool histogram looks the way it does.
Isolation and Fan-Out #
Subagents are usually sold as a cost saving. On my data they are better understood as capacity, and the difference matters when you are deciding what to delegate.
| Group | Responses | Mean prompt | p90 |
|---|---|---|---|
| Main session | 25,277 | 576,405 | 907,609 |
| Subagents | 89,056 | 172,646 | 251,372 |
A subagent turn attends to 3.34 times less context than a main-session turn, and 77.8 percent of all my responses ran in that cheaper regime.
Whether that saves money depends on an assumption I cannot measure. Pricing those subagent responses at main-session context size suggests 2.20 times the tokens avoided, but inline work would not have needed as many turns, because a subagent re-derives context the main session already had. The honest range is somewhere between 1.34 and 2.20, and only the 3.34 ratio is directly measured.
The capacity argument is stronger and needs no assumption. My main session runs at 907,609 tokens at the ninetieth percentile against a one million token window. Its largest turn was 999,898. Most of that subagent work would not have fitted inline at any price, and delegation is what gave it somewhere to go.
One belief I had to drop: I assumed narrow tool permissions made agents cheap. Across my roster, permission width explains about 17 percent of the variance in prompt size. A three-tool reviewer runs a larger prompt than most six-tool implementers, because reviewing means reading a large diff. Narrow permissions are blast-radius control. Keep them for that reason, not for cost.
Routing by Model Tier #
The theory is easy. Cheap fast models for exploration, prompt generation and documentation. Mid tier for implementation. The expensive tier for architecture and security review, and never let it write.
The practice is where I have something useful to say, because mine failed.
Four of my twenty-one agents are pinned to the small fast model, and one rule marked CRITICAL routes prompt generation through it before every complex dispatch. Measured: the large model carried 89.7 percent of my tokens. The small one carried 0.19 percent. One message in 177.
The cause is structural, not laziness, and this is the transferable part. Named-agent dispatch carries the model field and accounted for 124 calls. The workflow route, which composes many agents from a script, inherits the session model by default and accounted for 306 runs and 2,757 agents. The tiering lever was bypassed by the dispatch route that won.
If you write a routing policy, find every path that spawns work and check which of them actually read it. Mine was correct on the path I had designed for and absent on the path I actually used.
Gates That Actually Run #
A rule is a suggestion until something reads it. This is the lesson that took me longest.
In July I wrote about verifying that your harness loads what you think it loads. That was right and it did not go far enough, because loaded is not obeyed, and I had no way to tell the difference. When I finally measured adherence rather than presence:
None of these was argued with or revoked. They quietly stopped being followed while the documents stayed immaculate.
The controls that did work share one property, and it is the whole lesson: something mechanical reads them. Path-scoped rules load because a glob matches. Pre-push gates run because a hook invokes them. Everything that depended on an agent choosing to comply drifted to somewhere between zero and four percent, silently.
If you want a policy honoured, put it where the machine reads it, not where the reader does. A gate that has never been seen to fail is not well-tested. It is unobserved.
What It Costs and Buys #
Twenty-nine days, 114,573 API responses, 30,055,552,810 tokens. The cache hit ratio across all of it was 97.549 percent, with every cached block read back an average of 39.80 times before being rewritten. That is where the 6.94x comes from, and it is worth more than every other optimisation in this post combined.
One number goes the wrong way and I want it in here rather than buried. My token cost per shipped line of code tripled across the window, up 3.35 times, while cache efficiency stayed flat at 97.4 percent. I tested three explanations. Context growth was refuted at 1.8 percent. Fan-out was refuted, because the subagent share of tokens actually fell. What survived was the work mix: feature commits fell 44 percent, documentation commits rose 27 percent, and 75.9 percent of my commits in that window touched no code at all.
The harness did not get worse. It got pointed at verification instead of construction, and verification is expensive per artifact it produces.
That distinction is the one I would leave you with. Waste is tokens that bought nothing: a timestamp forcing a rewrite of 190 kilobytes, a whole file read to answer a question about four lines. Spend is tokens that bought something you wanted: nine agents adversarially checking a claim, a fleet holding work that will not fit in one context. Harness engineering is cutting waste to zero so you can afford more spend. It is not using fewer tokens.
Concretely, what the headroom bought: 2,757 subagents across 306 workflow runs in twenty-nine days, doing work no single context could hold. A research fan-out I ran recently used 21 agents and finished in under six minutes what would have taken me a day by hand.
And I stopped hitting the limit on ordinary days.
Where to Start #
If you are building your own, this is the order I would do it in now, knowing what I know.
First, split your rules. Move everything into path-scoped files except the ones whose violation is dangerous everywhere. This is the cheapest large win and it takes an afternoon.
Second, look at what sits in the first two thousand bytes of your context. Anything with a clock, a git status, or a live counter in it is invalidating everything downstream of it on every session. Move it to the end.
Third, stop reading whole files. Adopt bounded reads as a default habit before you build any retrieval machinery. It is worth more than the machinery.
Fourth, delegate for capacity, not for cost. Push work to subagents when your main context is filling up, which is a much clearer signal than trying to predict savings.
Fifth, measure adherence, not presence. Pick your three most important rules and find hard evidence that they were followed. Not that they loaded. That they changed what happened.
What I Still Do Not Know #
I cannot price what my review gates prevented. The 3.35 times rise in cost per line is measurable and the defects that never shipped are not, so I will not claim that trade was worth it. I believe it was. I cannot show you.
I could not A/B any of this. The harness changed under me on 27 of the 29 days, and a thing being revised that fast cannot be tested against itself.
I do not know how much of the client-side portion of my prefix is reducible, because it is not on my disk and I cannot see its parts.
And I have no instrument for the thing I most want one for, which is whether any of this made the work better rather than merely cheaper. Every number here is about cost. Quality is still something I judge by reading, one file at a time.