Claude Code for Platform Engineers: The Setup That Doesn't Burn Tokens¶
Claude Code out of the box is a brilliant engineer with no context and expensive habits.
You've probably seen both halves of that sentence play out. The brilliance: it writes a correct Crossplane Composition faster than you can look up the schema. The expense: a colleague's first month bill, driven by sessions where the model re-read the same repo structure forty times, carried three plugins' worth of context it never used, and explained every change in four paragraphs nobody read.
The gap between those two experiences isn't the model. It's setup. And the setup for platform work is specific enough — GitOps repos, YAML-heavy diffs, conventions that actually matter — that generic "10 Claude tips" listicles don't cover it.
Here's the starter stack I'd give a platform engineer today: two files, four repos, a short plugin list, and the token habits that keep the bill boring. Nothing here is exotic. All of it compounds.
The cheapest token is the one you never send
A well-structured CLAUDE.md saves thousands of input tokens per session by answering questions the model would otherwise explore the repo to resolve. Community benchmarks of the Superpowers skill framework measured about 14% fewer tokens with better output quality. Setup is a cost lever, not a convenience.
Start With Two Files, Not With Tools¶
The instinct is to start installing things. Resist it. The highest-leverage hour of your Claude Code setup is writing two markdown files.
CLAUDE.md is behavioural: what the agent must and mustn't do in this repo. Start from Karpathy's four rules — think before acting, minimum scope, surgical changes, verifiable goals — and extend with your platform specifics: which namespaces are off-limits, what "done" means for a manifest change, when to open a PR versus just answering. The two-files-in-one pattern covers the split between behavioural rules and repo context.
AGENTS.md is structural: what lives where, which docs cover what, how the repo's pieces relate. For a GitOps repo this is the difference between the agent grepping your entire clusters/ tree every session and reading one routing map. Here's what goes in it for platform repos specifically.
The token argument is blunt. Every question these files answer is a question the model doesn't burn input tokens exploring. Every convention they state is a wrong turn it doesn't take and you don't review.
Do this before anything else in this post
Thirty minutes: copy a CLAUDE.md template, delete what doesn't apply, add your three most-violated repo conventions. That file will save you more tokens this month than any plugin below.
The Four Repos Worth Your Clone¶
The ecosystem is enormous and mostly noise. Four repos have earned a place in my setup — the full tour is here if you want the deep dive.
andrej-karpathy-skills — the 65-line CLAUDE.md that started the discipline-layer conversation. Engineers applying its four rules measured AI coding error rates dropping from 41% to 11%. Use it as your CLAUDE.md base, not as gospel.
Superpowers — a skills framework with around 30 pre-built agents for security review, docs, and architecture checks. It's the rare add-on that's been benchmarked cheaper: skills load procedural knowledge on demand instead of holding it in context permanently.
everything-claude-code — the persistence layer: background tasks, checkpoints, parallel work. Most useful once you're running longer platform tasks (migrations, multi-repo rollouts) where losing session state is expensive.
ai-capabilities — our own templates repo: production CLAUDE.md extended for platform teams, AGENTS.md with approval tiers, and the agent-task issue template that forces scope and success criteria before any agent picks up work. Drop-in, then adapt.
Plugins: Install Less Than You Think¶
Here's the counterintuitive one. Every active plugin adds context overhead to every session, whether you invoke it or not. The plugin advice for platform engineers is mostly subtractive.
What earns its overhead: an engineering suite (code review, debugging, incident response workflows; you'll use these weekly), and a token auditor if you're on a team plan. Community favourites like Caveman (compresses output verbosity, with claims around 75% reduction) are worth testing for CI-driven agent runs where nobody reads prose anyway. Verify the claims on your own workload before believing the marketing numbers.
What rarely earns it: anything you installed to try once, MCP servers for services you touch monthly, and duplicate capabilities (two different docs plugins will cost you context twice and confuse routing).
The audit habit: monthly, list your active plugins and MCP servers, and disable anything that didn't fire in the last two weeks. This is the single most boring and most effective token optimisation there is.
The idle MCP server tax
Every connected MCP server ships its tool schemas into your context window at session start. Ten connected servers you're not using can cost more per session than the work itself. Connect what the current project needs; disconnect the rest. Your context window is a budget, and schemas spend it silently.
Skills: The Token-Efficient Alternative to Always-On Context¶
Skills are the piece of the Claude Code model that platform teams underuse, and they're the answer to a specific tension: you want the agent to know your procedures, but you don't want to pay for that knowledge in every session.
A skill is procedural knowledge that loads on demand. Your runbook for cluster upgrades, your incident triage flow, your release checklist — written once as a skill, they cost nothing until invoked. Contrast that with stuffing the same content into CLAUDE.md, where it rides along in every session forever, or an MCP server, where the schema overhead is permanent.
The starter move: take your three most-repeated procedures and turn them into skills with skill-creator. Good first candidates from platform work: "add a new service to the golden path" (encodes your conventions), "run the deploy checklist" (encodes your gates), and "draft the incident update" (encodes your comms format).
The experience-as-skill pattern is the deeper version of this argument: skills are how an agent accumulates your team's specific way of doing things without a per-session context tax.
Token Discipline: Five Habits That Keep the Bill Boring¶
Everything above is structural. These are behavioural, and they matter as much.
Scope requests like you'd scope a ticket. "Refactor the login function in auth.ts" beats "refactor the auth module": smaller scope, less context loaded, tighter diff to review. This is Karpathy's Rule 2 applied to your own prompts.
Use /recap, not scrollback replay. Resuming a session by summarised recap instead of replaying the conversation saves the full history re-read.
Turn on prompt caching for long sessions. ENABLE_PROMPT_CACHING_1H makes repeated context (your CLAUDE.md, the repo map) dramatically cheaper across a working session.
Match the model to the task. Routine YAML edits, log summaries, and PR descriptions don't need your biggest model. Save the heavyweight for architecture decisions and gnarly debugging; route the routine to a cheaper tier.
Measure before optimising. Run a token audit before installing optimisation plugins. Most teams find one or two session patterns causing most of the spend — usually repo re-exploration that a better AGENTS.md fixes for free.
FAQ¶
What's the minimum viable setup if I only have an hour?
CLAUDE.md from the Karpathy base (30 minutes), AGENTS.md routing map for your main repo (20 minutes), disconnect unused MCP servers (10 minutes). That's the highest-leverage hour. Plugins, skills, and repos can all come later; the two files can't, because everything else works better once they exist.
Do skills really save tokens versus just a good CLAUDE.md?
They solve different problems. CLAUDE.md is always-loaded behavioural rules; keep it short and universal. Skills are on-demand procedures, as detailed as you like, costing nothing until invoked. The failure mode is a 2,000-line CLAUDE.md full of procedures that should be skills, taxing every session for knowledge used in 5% of them.
Are the token-saver plugin claims (70-75% reductions) real?
Treat them as vendor benchmarks: directionally interesting, not transferable. Output-compression tools genuinely help in automated runs where nobody reads the prose. But the big, boring wins — tight CLAUDE.md, fewer idle plugins, scoped requests, caching — come first and cost nothing. Measure your own workload before and after; anything you can't measure, don't install.
How does this change for a whole team versus one engineer?
The two files become governance artifacts: versioned, reviewed, and rolled out across repos deliberately. Skills become shared team assets in a common repo. And token discipline becomes a platform concern — a monthly usage review per team, the same way you'd review cloud spend. Same principles, plus ownership.
The pattern across all of it: context is the product, and context is the cost. The engineers getting the most out of Claude Code aren't the ones with the most tools installed. They're the ones who decided, deliberately, what the agent should know by default, what it should load on demand, and what it should never have to figure out twice.
Two files, four repos, fewer plugins than you expected. Start there.
Walkthrough files¶
The first-hour checklist, context-budget table, and starter templates are in the ai-capabilities repo.
| File | What it is |
|---|---|
examples/claude-code-platform-setup.md |
The full setup checklist — context budget, four repos, token habits, first skills to create |
templates/CLAUDE.md |
Production CLAUDE.md extended for platform teams: blast-radius awareness, approval tiers, audit trails |
For the discipline layer that underpins all of this: The Four Rules That Make AI Agents Actually Trustworthy. For the repo deep-dive: The 6 GitHub Repos Redefining How AI Agents Work. For rolling this out beyond one engineer: Your AGENTS.md Is Great. Now How Do You Roll It Out to 40 Repos?.