Most Australian engineering teams running Claude Code on a meaningful codebase share the same hidden cost. The model spends a surprising fraction of every session walking the file tree before it touches real work. We see this every week with Sydney and Melbourne clients who move from Claude Code pilots into production usage. The token bill climbs faster than the value. Once you trace the spend back to its source, the file-discovery preamble is almost always the largest line item, and it is one of the easiest things to fix.
Why file discovery quietly dominates token spend
The mechanics are straightforward. A typical Claude Code session in a 150,000-line repository starts the same way every time. List the root directory. Read the package files. Open the most likely candidates. Follow the imports. Branch out. For a one-off question this is fine. For a team doing dozens of sessions a day across a shared codebase, the preamble becomes the single largest line item on the bill at the end of the month. Engineers rarely notice because individual sessions feel cheap, and the cost only shows up when finance asks for a per-engineer breakdown.
When we benchmarked one client in Sydney's CBD across a fortnight, the file-discovery preamble averaged 41% of input tokens per session before any meaningful coding work began. For their 20-engineer team at average usage that worked out to roughly $4,200 per month of pure overhead. Annualised, the unaddressed cost was tracking toward $52,000. None of it produced a single shipped change. The same team's actual productive Claude Code spend, the part that generated reviews and patches, sat well below $30,000 a year. The overhead was bigger than the value.
The three patterns that reliably cut it
Three patterns collapse the preamble. Each works on its own. Stacked, they took the average preamble in the same Sydney benchmark from 41% down to under 8%. The remaining 8% is a healthy floor that pays for the actual context-loading the model needs to do good work.
A committed CODEBASE_MAP.md that describes the directory layout, the key modules, and the most common imports in plain prose.
A scoped allow-list at the top of each prompt naming the three to seven files the model is permitted to read for the current task.
A small purpose-built skill that answers the where-does-X-live question without invoking the full discovery walk.
Pattern 1: the committed CODEBASE_MAP.md
The map lives in the repository root and gets reviewed in pull requests like any other code. It describes what each top-level directory contains, where shared utilities sit, where the entry points are, and which modules import which. Three or four hundred words of prose is usually enough. The model reads it once at the start of every session and skips most of the speculative file opening that would otherwise follow. The cost is one file to maintain. The payoff is that every engineer on the team, and every Claude Code session, starts with the same mental model of the codebase. In the Sydney benchmark this single change moved the preamble from 41% of tokens down to 22% within the first week.
Pattern 2: the scoped allow-list
The allow-list goes at the top of the prompt. It names the files the model is allowed to read for this task, and tells it explicitly not to walk the rest of the tree. A bug fix in the auth module needs maybe four files. A refactor of a single service needs maybe seven. The discipline of writing the list also forces the engineer to think about scope before opening a session, which is a separate productivity win. Most teams resist this at first because it feels like extra work. After a fortnight nobody wants to go back. The same Sydney team measured a further 11% drop in preamble tokens after adding the allow-list discipline on top of the map.
Pattern 3: the purpose-built discovery skill
For the genuine where-does-X-live cases that come up several times a day, a small Claude Skill handles the question with a precomputed index rather than a live walk. The skill takes a symbol or feature name and returns the file paths, the relevant function signatures, and a one-line summary of each. Building one takes a single afternoon. Running it costs a fraction of a normal session because the index is already prepared. Most Australian teams we work with end up with two or three of these skills covering the questions their engineers ask most often. Browse the Automata AI services page for examples of skills we have built for client engagements.
The Australian context that makes this urgent
APRA-regulated firms with cost-governance frameworks now have a direct interest in tracking AI tooling spend per engineer. The Privacy Act amendments around AI tool usage that came into force this year attach reporting obligations to material AI expenditure. Brisbane and Melbourne CFOs we work with want a defensible monthly cost-per-engineer figure they can present to their boards and their auditors. A 20-engineer team spending $42,000 a year on well-governed Claude Code usage is a number a board will accept. The same team spending $94,000 because nobody addressed the file-discovery preamble is not, and the AUSTRAC-style reporting questions get awkward fast when 55% of the spend turned out to be avoidable overhead.
A fortnight rollout you can actually execute
Week one is the map. Pair two engineers to draft CODEBASE_MAP.md, review it in a normal pull request, and merge it. Have the rest of the team review it once before they start their next Claude Code session. Measure the preamble token cost for the week using the Claude Code usage logs that already ship with the tool. Most Australian teams see a 30 to 45% drop in input tokens before they touch anything else.
Week two is the allow-list and the first skill. Add an allow-list reminder to the team's prompt template. Build the first discovery skill targeting whichever question your engineers ask most often. Re-measure. By the end of the fortnight a representative team should be at a preamble cost under 10% of total input tokens, and the per-engineer Claude Code spend should be roughly 45 to 60% lower than the starting baseline. The work pays for itself inside the first month and keeps paying every month after that.
What to do next
If you want to see what this looks like applied to your own Claude Code usage logs, we run a free brainstorm session for Australian engineering teams. We will walk through a fortnight of your traces, identify the preamble overhead, and sketch the map and allow-list discipline that would cut it. Book a session and we will take it from there.
