How to Write a Technical Spec for Claude Code (The Format I Use on Every Build)

A technical spec for Claude Code is a short plain document that defines what you are building, what the agent is allowed to touch, and what done looks like - before you type the first prompt. It is not a project plan, a PRD, or a design doc for a human engineer. It is context for an AI agent that starts fresh every session with no memory of yesterday's decisions, no relationship with your client, and no way to ask a clarifying question without burning your time.

Most builds that go sideways with Claude Code share the same root cause: the agent started with a vague prompt and made a reasonable but wrong assumption about scope, stack, or priority. By session three you are untangling decisions the agent made in session one that nobody explicitly authorized. A spec eliminates that. When Claude Code reads a complete spec at the start of a session, it knows exactly where to go and - just as importantly - where to stop.

Strip a well-run build down and you will find the same five pieces of context the agent needed to make good decisions. Everything else is either a nice-to-have or noise. Here is the CCC spec skeleton I use on every project.

That is the whole spec. One A4 page at most. If you are typing more than that, you are probably documenting decisions the agent could derive from context, or describing the implementation rather than the outcome. The spec defines the target; Claude Code picks the path.

Every spec starts with a single sentence that names the product, the user, and the core job the product does. Not two sentences. Not a paragraph. One sentence, because if you cannot state the build in a sentence, the scope is not defined yet - and you are not ready to write a spec.

A weak goal: 'Build a task management app with productivity features.' A strong goal: 'A web app where a solo founder can add daily priority tasks, mark them done, and see the list persist across sessions using Supabase.' The difference is specificity. The weak version gives Claude Code permission to guess. The strong version gives it nothing to guess about.

Write the goal sentence before anything else. If you are building for a client, derive the sentence from the kickoff call, not from the proposal. The proposal is usually too vague - it is written to be accepted, not to be implemented. The [client kickoff call guide](/blog/client-kickoff-call-ai-build) has the questions that extract the goal sentence before you ever write the spec.

The stack section is where most builders underspecify and then wonder why Claude Code introduced a library they did not want. The agent will pick reasonable defaults when you leave it room - but 'reasonable' to Claude Code might mean a full authentication library when you wanted a simple cookie check, or a full ORM when you wanted a raw Supabase query. The spec names the tools that are in and explicitly bans the substitutes.

Format it as two short lists: 'Use' and 'Do not use.' Example: Use Next.js App Router, Tailwind CSS, Supabase for database and auth, React Query for server state. Do not use Prisma, NextAuth, any UI component library, or any paid third-party API. Two lists, no prose. The agent reads lists faster and violates prose instructions more often.

Constraints also include environment rules: what goes in .env.local versus what is hardcoded, whether the build is for Vercel or somewhere else, and what the agent is not allowed to do to the repository structure. If the client has a monorepo and the agent should only touch a specific folder, that is a constraint. Put it in the spec, not in a prompt three sessions in when the damage is already done.

The feature list is two sections, not one. 'In scope' without 'out of scope' is an invitation to build adjacent features the agent thinks are related. The out-of-scope list is where most specifications skip a step and most builds drift.

For in-scope: list each feature as a user action, not a technical task. 'User can add a task with a title' is a feature. 'Create a POST endpoint at /api/tasks' is an implementation detail. Write features; let Claude Code design the implementation. One feature per line, no sub-bullets at the spec stage.

For out-of-scope: name the obvious adjacent features you are deliberately not building this sprint. If the build is a task manager and you know a client might ask for team sharing later, put 'Team sharing, comments, and notifications are out of scope for this build' in the spec now. When Claude Code sees something is explicitly excluded, it stops adding it speculatively. When that exclusion is absent, the agent sometimes adds a feature because it seemed helpful - and you are reverting it in session five.

A success criterion is a testable statement. Not 'the app works well' - that is a feeling, not a criterion. A testable criterion is: 'A user can create a task, see it appear in the list immediately, mark it complete, and reload the page to find the state persisted.' Claude Code can run that test. It can also generate a test file for it, which is how I get a basic smoke test suite out of the spec with no extra work.

Write one criterion per major user flow, not per endpoint. Four or five criteria are usually enough for a lean build. Keep each one to a single sentence in plain English. If you need a second sentence to explain the criterion, split it into two criteria.

At the end of every session I paste the success criteria back into the prompt and ask Claude Code to run through them. 'Here are our success criteria. Walk through each one and tell me which pass, which fail, and what is left to do.' It is the most efficient review loop I have found - faster than reading code and more reliable than trusting the agent's last message.

The file tree section is short and often skipped - which is why you keep finding components in the root folder and API handlers inside the wrong directory. Give Claude Code a minimal starting tree and it builds into it rather than around it. Approximately ten to fifteen paths is enough: the main directories, the config files, and the one or two files that need to exist before the build starts.

You do not need to pre-create every file - just name where they go. Example: src/app/page.tsx, src/app/api/tasks/route.ts, src/components/TaskList.tsx, src/lib/supabase.ts, .env.local. Claude Code reads the tree, understands the intended structure, and places new files accordingly. Without the tree, it defaults to its own conventions, which may not match your project, your client's conventions, or the existing codebase you are extending.

If you are building on an existing codebase rather than starting fresh, the file tree section becomes a map of the relevant files - the ones Claude Code should read and the ones it should not touch. Pair it with the constraints section to mark the no-go zones. The [how to use Claude Code on a large existing codebase guide](/blog/claude-code-large-existing-codebase) goes deeper on keeping the agent oriented in a code base it did not build.

The spec lives in two places: the CLAUDE.md file and the first prompt of every new session. CLAUDE.md is where the durable context goes - stack, constraints, file tree, and the out-of-scope list. These do not change during the build, so they belong in the persistent file the agent reads first. Features and success criteria can go in CLAUDE.md too, but I usually paste them fresh in each session prompt so I can update them as the build evolves without editing the file.

The first message of each session follows a fixed shape: 'Here is the spec for this build. [paste spec]. Today's task is [single concrete next step]. Start by reading the files in [directory] and tell me what you see before writing any code.' That last sentence - read before you write - is the single most valuable habit I have built into my workflow. It stops the agent from diving into implementation based on assumptions and makes it tell me what it actually found in the codebase first.

A spec that is too long is almost as bad as no spec. When the context document runs to ten pages, the agent's attention dilutes - it starts weighing section four at less than section one, and the rules buried in the middle get violated first. Keep the spec under one page. If you have that much to say, you have too much scope in one build.

A spec written in the third person is harder for Claude Code to parse than one written as direct instructions. 'The application should allow users to' is weaker than 'Users can.' Direct language processes faster and is less likely to be misread as a description of an existing system rather than a target to build toward.

The worst spec mistake is writing the spec after the build starts. I have done it. You get three sessions in, the agent has taken a turn you did not want, and you try to retroactively document the right direction. It does not work. The agent has already made decisions you would have prevented. Write the spec first, treat it as the mandatory first deliverable on every project, and send it to the client for a quick sign-off before session one. A ten-minute spec review is worth two hours of rework.