How to Code with AI Without Burning Tokens: A Spec-Driven Workflow (2026)
AI writes worse code when you give it more context, not better — a bloated context confuses the model, burns tokens on every request, and sends it editing the wrong files. The fix is spec-driven, context-efficient coding: write a short spec (exact stack versions, architecture, the reusable code to use, and how to verify), load only the documents a task needs, and work in small sprints with a fresh context each time. AI-driven development is really context management.
The engineers getting clean code out of AI in 2026 aren't using a secret model — they're managing context. This is the practical playbook: why more context makes AI worse and pricier, what a spec actually contains, how to split a large project's docs so each task loads only what it needs, and a symptom-to-fix table for when the agent goes rogue. It maps straight onto Claude Code's CLAUDE.md and the AGENTS.md standard, which are where this spec lives.
Why does more context make AI code worse (and burn tokens)?
It's counterintuitive, but dumping your whole project into the model backfires. The agent sees a pile of things irrelevant to the task, gets confused, and invents more; and because every request re-sends the entire context, each one costs more tokens and makes the model think longer. Noise raises the odds it wanders — touching other files, making ten edits instead of one, or paying down technical debt you never asked it to.
Without a spec it's worse: the agent burns tokens scanning your files to reconstruct the architecture, versions, and conventions you never told it — or it invents its own from generic internet "best practices." The cost is double: the tokens (which every provider now caps), plus the rework time when it builds the wrong thing. A missing spec that "saves 15 minutes" up front costs far more later. The upside of the opposite: with a tight, sufficient context you can often run a cheaper model, because the agent has nothing to figure out. This is the same context-budget problem we cover for CLAUDE.md — less, but exactly right, beats more.
What is spec-driven AI coding?
Spec-driven AI coding means you write a spec, not a prompt, before you ask for code — and the spec is machine-facing rules, not human documentation. It states the stack and exact versions, the architecture and real folder names, the existing code to reuse, the hard constraints, and how to verify the result. In AI development the specification becomes a prompt: part of the context and the rule set the agent executes against.
The reason it matters is blunt: the model can't read your mind, and it won't ask. It only sees the context you give it, so anything you leave unspecified it will invent — the architecture, the library versions, the UI components, and "improvements" you didn't request. A spec removes the guessing, which is exactly what removes the wasted tokens.
What goes in the spec?
Six things. Keep each short and concrete — the goal is the minimum that stops the agent from guessing:
| Put this in the spec | So the agent doesn't… | Example |
|---|---|---|
| Stack + exact versions | use removed or outdated methods, or pick versions itself | "Python 3.13, FastAPI 2.1" — not "Python + FastAPI" |
| Architecture + real folders | invent its own structure so code doesn't fit the system | "Clean architecture; services in src/services, routes in src/routes" |
| Reusable code to point at | rebuild auth, users, UUIDs, or your UI kit from scratch | "Auth: src/services/auth.ts. UI: use packages/ui — never rebuild a component." |
| Hard constraints | cross a boundary it shouldn't | "No direct DB access — only through the repository layer." |
| Acceptance + edge cases | test only the happy path and leave errors unhandled | "Run the tests. Cover empty, invalid, auth-error, and network-failure states." |
| Technical-debt handling | silently "improve" unrelated code | "Log any shortcut in TECH-DEBT.md; don't refactor code the task didn't touch." |
A spec you can copy (AGENT.md)
Here's a minimal, machine-facing spec for one service — the kind of file you keep at the repo root as AGENT.md (or CLAUDE.md for Claude Code) so the agent reads it every session. Copy it and swap in your own stack, paths, and rules.
# AGENT.md — spec for the payments service
## Stack (pin exact versions)
- Node.js 22, TypeScript 5.6, Fastify 5.1, Drizzle ORM, Postgres 16.
## Architecture
- Clean architecture. Routes in src/routes, business logic in src/services,
DB access in src/repositories. Routes never touch the database directly.
## Reuse — do NOT reinvent these
- Auth + sessions: src/services/auth.ts
- User repository: src/repositories/user.ts
- IDs: src/lib/id.ts (do not add a new uuid package)
- UI: the components in packages/ui — never rebuild one from scratch.
## Constraints
- No raw SQL in routes or services — only through src/repositories.
- No new dependencies without asking first.
## Acceptance
- Run `pnpm test` and make it pass. Cover the empty, invalid-input,
auth-error, and network-failure cases — not just the happy path.
## Technical debt
- Log any shortcut you take in TECH-DEBT.md. Do not refactor code this
task did not ask you to touch.The spec-driven workflow, step by step
The whole loop, in order — small enough that the context never balloons:
- 01Define the task — decide what's being built and why before you prompt anything.
- 02Write the spec for that specific task (the six things above).
- 03Collect only the relevant docs — the ones this task needs, never the whole project.
- 04Work in short sprints — one sprint = one agent (with subagents) = one fresh context. Don't drag old dialogue into a new task.
- 05Verify — automate the checks (run the tests), but keep the final judgment human.
- 06Record the changes and the technical debt, so you always know what moved.
How do you manage context on a large project?
Small project (a hobby repo, ~30 files, no dependencies)? Two documents are enough: a README that says what it does and how it's built, and an AGENT.md that points at the README and holds the task plan. Beyond that, one big doc becomes the problem — so you split it, and load only the pieces each task needs.
The split-by-concern doc set that keeps every task's context small:
| Doc | Holds | Loaded when |
|---|---|---|
| tech-stack.md | Languages, exact versions, allowed and forbidden libraries | Almost every task |
| architecture.md | Layers, folder rules, module boundaries, hard constraints | Any structural change |
| db-schema.md | Tables, fields, types, relations, indexes, read/write rules | DB and migration work |
| edge-cases.md | Errors, empty states, validation, auth/network failures | Feature + test work |
| ui-kit.md | Where the component kit lives and what not to rebuild | Frontend work |
| links.md | Links to official docs, guidelines, migration rules | When it would otherwise guess an API |
| current-sprint.md | This iteration's tasks, priorities, and statuses | Every run |
AI coding problems, diagnosed
When an agent misbehaves, the cause is almost always a missing artifact — not a bad model. The symptom tells you which one:
| Symptom | What's missing |
|---|---|
| Burns tokens and writes the wrong thing | No spec |
| Re-reads the whole project every time | Docs not split by concern |
| Invents its own architecture or patterns | Architecture not documented |
| Uses the wrong libraries or installs new ones | You never said where the existing code lives |
| "Doesn't understand the task" | You described the task badly |
| Loses track of what it changed | Sprint file missing, or the context is too big |
How do you make a legacy project AI-ready?
An old repo that was never written for agents needs a one-time setup. Do an up-front context dump — a single expensive pass where the agent studies the whole project and generates the split doc set (architecture, constraints, libraries, where the business logic lives, a module/dependency map). You pay the big token cost once so you don't pay it on every task afterward; a tool like Context.dev is built for exactly this.
Then two habits keep it clean. For each change, write a change request — you decide what to change (from the dump or an existing ticket) so the agent doesn't re-scan the project to figure it out. And keep a legacy-warnings file listing what's outdated or fragile: don't let the agent refactor blindly — either fix a thing on purpose, or knowingly reuse the crutch. A good practice run: fork a repo, delete the stale README (it misleads), run the context dump, then have the AI propose and apply improvements — fixed debt goes in the report, unfixed debt into the warnings file.
Where do CLAUDE.md and AGENTS.md fit?
This spec is not a separate ceremony — it's the file your agent already reads. For Claude Code that's CLAUDE.md; the cross-tool open standard is AGENTS.md; both hold the always-loaded rules plus a pointer to the task plan. See our guide to writing a CLAUDE.md (and AGENTS.md) that works for the file itself, the best Claude Code prompts for driving each sprint, and what an AI agent harness is for the machinery underneath. The through-line across all of them is the same as context engineering: give the agent the minimum context that's still sufficient, and it stops guessing.
Frequently asked questions
- What is spec-driven AI coding?
- Writing a short, machine-facing spec — stack and exact versions, architecture and real folders, the existing code to reuse, hard constraints, and how to verify — before you ask an AI agent for code. The spec becomes part of the context, so the agent executes against rules instead of guessing (and burning tokens reconstructing what you didn't tell it).
- Why does AI burn tokens when coding?
- Mostly because of context. Every request re-sends the whole context, so a bloated one costs more each time; and without a spec the agent burns extra tokens scanning your files to reconstruct architecture and versions you never stated. Give it a tight, sufficient spec and it stops figuring things out — which cuts both the tokens and the rework.
- What is context engineering?
- Deliberately choosing what goes into an AI agent's context — the minimum that's still sufficient for the task. In practice: a spec, only the documents the task needs (split by concern on a big project), and a fresh context per sprint. AI-driven development is largely context management.
- How long should a spec or CLAUDE.md be?
- Short. Include only what the agent couldn't figure out on its own and would otherwise get wrong — stack versions, architecture, reusable code, constraints, acceptance. On a large project, split the detail into per-concern docs and load only what each task needs, rather than one giant file.
- Do I still need to review AI-generated code?
- Yes. Automate the checks — run the tests, verify the acceptance criteria — but the final judgment stays human. As output gets more trustworthy, review shifts from reading every line toward verifying the result against the spec, which is why you still need to understand the architecture you asked for.