Claude Code in production: the real-work guide

The agent that impresses in a demo differs from the one that survives your project by the context infrastructure you build around it: five layers almost nobody builds, because no installation tutorial mentions them.

We know this because the two most serious studies ever run on coding agents reached opposite conclusions. A randomized controlled trial from METR measured experienced developers 19% slower with an AI assistant. A Microsoft study covering tens of thousands of engineers measured agentic CLI adopters with 24% more approved pull requests. Both are right. The year, the tool and above all what surrounded the agent are what changed between them.

This guide maps those five layers, with the official cost figures and the traps that show up once you leave the example and enter a real repository.

Because the demo has a context that is small, verifiable and days old. Your project has eight years of accumulated decisions, three conflicting conventions and a 4,000-line file nobody understands end to end.

The agent does not get worse. The context does.

Both studies deserve a careful look, because a lazy reading of them produces the two wrong narratives in circulation: that agents are a miracle, and that agents are an illusion.

What METR actually measured

In July 2025, METR published a randomized controlled trial with 16 experienced open-source developers, covering 246 real tasks of about two hours each. The result: when allowed to use AI, the developers took 19% longer to finish.

The more uncomfortable finding is the perception one. Participants expected a 24% speed gain. After the measurement showed them slower, they still believed they had gained 20% (METR, July 2025, accessed 19 August 2026).

Before using that number as an argument against agents, read the fine print: most participants used Cursor Pro with Claude 3.5 and 3.7 Sonnet. No Claude Code, no 2026, and no skills, MCP or subagents in the configuration under test. The authors themselves classify the finding as "a snapshot of AI capabilities in early 2025, in one relevant setting".

If comparing the tools themselves is the point, Claude Code, Codex and Cursor side by side covers each one's permission model, which is where they diverge.

Citing METR as proof that coding agents fail today is a misreading. The study proves, and this still holds, that your sense of speed is no measuring instrument.

What Microsoft measured a year later

In July 2026, Microsoft researchers published a study of the internal rollout of Claude Code and GitHub Copilot CLI, following tens of thousands of engineers across a four-month window.

Adopters approved about 24% more pull requests than they would have without the tools, and the effect held across the whole window, so no novelty effect explains it. The study also found that first use spread through internal social networks above all, and that retention tracked an engineer's code activity more than their demographics (Murphy-Hill, Butler and Savelieva, arXiv:2607.01418, July 2026, accessed 19 August 2026).

The authors add the caveat that matters: "an approved PR is not the same as the value it delivers". They use approved PRs as a proxy for production, and they say so in the open.

The honest reading of the two

A year separates the two. A generation of tools separates the two. And the metric differs: time per individual task and volume of approved PRs measure different things.

Neither proves that your setup works. A controlled trial has high internal validity and a tiny sample; a large observational study has the opposite problem. The question left for you is the one this guide tries to answer: what has to exist around the agent for it to help instead of getting in the way.

Context, capability, connection, delegation and verification. In that order, because each depends on the one before.

The order matters more than it sounds. Installing ten MCP servers before writing a decent CLAUDE.md is the most common mistake I see, and it makes the result worse, because it fills the context without giving the agent the information that would make the tools get used at the right moment.

Claude Code loads CLAUDE.md into the context at the start of every session. Each of its lines therefore gets charged on every task you run, including the ones with nothing to do with what it says.

The official documentation is direct about the practical limit: keep CLAUDE.md under 200 lines, including the essentials alone, and move specialized instructions (PR review, database migration, commit convention) into skills, which load on demand when something invokes them (Claude Code Docs, Manage costs, accessed 19 August 2026).

That is layer 1's central trade-off. Everything in CLAUDE.md is guaranteed knowledge and guaranteed cost. Everything in a skill costs nothing until something needs it, at the risk of nothing invoking it at the right moment.

Two hygiene habits make more difference than any prompt engineering:

• /clear when you switch subjects. Old context wastes money on every following message. Use /rename before clearing so you can find the session later, and /resume to come back.
• /compact with an instruction. /compact Focus on the code examples and the API usage tells the agent what to preserve in the summary. Without one, it chooses on its own, and sometimes chooses wrong.

One cost detail almost nobody knows: a session open for hours sends the whole conversation on every request. With prompt caching, that history gets reread at the cache rate, though the cache lives for one hour on a subscription and drops to five minutes once you move to usage credits or an API key. A one-line question in a session left open all day still bills against the full history.

That explains a phenomenon that looks like a bug: the first message after a gap longer than the cache lifetime misses the cache and reprocesses your entire context. You came back from lunch, typed "and now?", and paid for the whole conversation again. Worth knowing too: /compact is itself a large request, because it has to read the conversation it will summarize. /clear costs nothing when you want a fresh start instead of continuity.

The criterion I use to decide whether something goes into CLAUDE.md or becomes a skill is one question: does this hold true in every task in this project? A naming convention, yes. A database migration procedure, no, and that one belongs in a skill.

To go deep on this layer, I wrote the anatomy of a CLAUDE.md that works, with the four scopes, the 200-line limit and what to do with the overflow.

Skills give domain knowledge. Hooks take work off the agent before it spends context on it.

The distinction is useful. An "architecture overview" skill describes directories, conventions and project decisions, and once invoked the agent gets that ready-made instead of spending dozens of file reads inferring the same thing.

Hooks solve another problem. Instead of the agent reading a 10,000-line log to find the errors, a hook does the grep and returns the lines that matter, cutting the context from tens of thousands of tokens to hundreds.

The example from the official documentation is worth copying whole, a PreToolUse that filters test output down to failures:

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

# If running tests, filter down to failures only
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"updatedInput\":{\"command\":\"$filtered_cmd\"}}}"
else
  echo "{}"
fi

The complete Claude Code command reference covers the 294 that exist today, with what each delivers. To check whether the hook is active, /hooks shows whether it appears under PreToolUse. Running with claude --debug, the log shows modified tool input keys: [command] when the hook rewrites the command.

For anyone working in a typed language, an easy gain sits unclaimed by many: code intelligence plugins. They give precise symbol navigation in place of text search, so one "go to definition" replaces a grep followed by reading several candidate files. And an installed language server reports type errors after edits, so the agent catches the problem without running a compiler.

The difference between this layer's three tools, in short:

Anyone using CLAUDE.md alone pays context on every task. Anyone using skills alone risks nothing invoking them. Anyone using a hook solves the problem before it becomes context, and it is the most underused of the three, and the one that cuts the bill most.

The walkthrough sits in how to write your first Agent Skill, including why the body has to be short. The catalog of 44 reviewed skills and 294 documented commands shows which passed the filter and which failed, with the reason for each.

MCP connects the agent to systems outside the repository. And the most important decision about MCP is when to skip it.

The official guidance is clear and runs against the instinct of anyone who discovered the protocol last week: prefer CLIs where they exist. Tools such as gh, aws, gcloud and sentry-cli are more context-efficient than MCP servers, because they add no per-tool listing. The agent runs the command.

This improved a lot: MCP tool definitions now load on demand by default, so the names alone enter the context until the agent uses a specific tool. Even so, /context shows what is taking up room, and /mcp lists the configured servers so you can switch off what you are not using.

The practical rule I use: MCP for what has no decent CLI (Figma, Notion, internal databases, proprietary APIs). CLI for everything that already has one.

The reason is mechanical, not ideological. An MCP server has to announce itself to the agent, and even with on-demand loading a discovery cost exists. A CLI announces nothing: the agent already knows how to run a terminal command, so gh pr list costs what the command's output costs, and nothing beyond that.

One side effect seldom gets discussed: an MCP server is attack surface. It runs with the permissions you gave the agent and talks to systems holding your data. Installing a third-party server without reading what it does is the equivalent of npm install on an unknown package, with the difference that this one reaches your repository and your credentials. /mcp lists what you configured, and that list deserves the same periodic look you would give package.json.

Worth knowing that /usage shows consumption attribution per individual MCP server, counting the requests that used a tool result from that server. It is how you find which server is expensive without guessing.

The curated list of AI tools gathers what earns an MCP connection and what already has a better CLI.

The walkthrough sits in MCP in practice, including the three scopes and the precedence that does not merge fields.

The two differ in architecture, and confusing them costs money.

Subagents are specialized instances running inside your session. Each has an isolated context window, its own system prompt defined in the agent file's body, a scoped tool list through tools or disallowedTools, and independent permissions through permissionMode. You can pin the model per subagent, and model: haiku for a simple task is the easiest saving in Claude Code.

Their best use is isolation. The documentation is explicit: one of the most effective uses of a subagent is isolating operations that produce a lot of output. Running tests, fetching documentation or processing log files consumes significant context, and by delegating that, the verbose output stays in the subagent's context and only the relevant summary returns to the main conversation.

Agent teams have a different architecture. One session acts as team lead: it coordinates the work, assigns tasks and synthesizes results. The teammates work on their own, each in their own context window, and that is the difference that matters: they talk to each other, without going through the lead.

The structure has four pieces: a team lead, the teammates, a shared task list they claim from, and a mailbox for messages between agents.

When each one wins

The rule: use a subagent when you need a fast, focused worker that reports back. Use an agent team when the workers have to share findings, challenge each other and coordinate on their own.

The number that decides

Agent teams consume about 7x more tokens than a standard session when the teammates run in plan mode, because each teammate holds its own context window and runs as a separate instance (Claude Code Docs, accessed 19 August 2026).

That is why they are experimental and ship disabled, behind CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

One side effect catches many people by surprise: with agent teams on, a subagent Claude names on its own launches as a teammate. Teams can form without you asking, and if your flow waits on a subagent's result, it hangs, because a teammate notifies that it went idle without returning the output.

If you do use them: Sonnet on the teammates, start with 3 to 5, a spawn prompt carrying the task context (they load CLAUDE.md, MCP and skills on their own, though they do not inherit the lead's history), one owner per file to avoid overwrites, and switch them off when you finish.

When composing several agents pays off, and when it does not, sits in multi-agent orchestration.

The full criterion sits in subagents: when to delegate and when not to.

By giving the agent a verification target before it starts, and not after.

This is the layer separating people who use an agent from people the agent uses. Four habits, in order of impact:

Plan mode before a complex task. Shift+Tab cycles to the mode where the agent explores the code and proposes an approach for your approval, before writing anything. That avoids the expensive rework of a wrong initial direction.

Correct early. Esc interrupts on the spot. /rewind, or Esc twice, restores conversation and code to an earlier checkpoint. Letting the agent finish an approach you already saw was wrong is the most common waste there is.

Give a verification target. Test cases, a pasted screenshot, the expected output stated in the prompt. An agent that can check its own work catches the error before you have to ask for the fix.

Test in increments. One file, test, continue. Catching a problem early means catching a cheap problem.

Verification that runs on its own

The four habits above depend on your presence. Hooks solve the part that should not.

If you use agent teams, three hooks work as automatic quality gates. TeammateIdle runs when a teammate is about to go idle, and exiting with code 2 sends the return back and keeps it working. TaskCreated and TaskCompleted do the same on task creation and completion: code 2 blocks the operation and returns the reason.

That changes the nature of review. Instead of you looking at the result afterward, the rule gets encoded and the agent hits it before declaring itself finished. It is the difference between "I reviewed it and it was wrong" and "it did not pass".

What to keep off the delegation list

One line worth keeping clear: an architecture decision you cannot evaluate does not belong on the delegation list. Not because the agent errs more than you, but because you will not detect the error. Delegating what you cannot review transfers the risk without transferring the responsibility, and the responsibility stays yours at code review, in the incident and in the meeting.

The same holds for permissions. Running with automatic approval in a repository you know well is a reasonable decision. Running that way in code you saw for the first time today is a bet that the agent understands the system better than you, which may even be true, and remains a bet.

What to clear and what to lock sits in permissions and auto mode. The list of what should never enter an agent's tool set deserves an explicit decision, and not the tool's default.

In enterprise deployments, the mean runs at about US$13 per developer per active day and US$150 to 250 per developer per month, with the cost staying under US$30 per active day for 90% of users (Claude Code Docs, accessed 19 August 2026).

Those numbers come from enterprise deployments billed per token. On a Pro or Max subscription the plan includes the usage, and the dollar figure /usage shows serves no billing purpose, since Claude Code computes it on your machine from the token count at list rates.

Two sources of unexpected cost dominate the invoice surprises: long sessions never cleared and Opus left as the default model. The two habits that cut the bill most are the most tedious to keep: clearing between unrelated tasks and choosing the model that fits the work.

Worth knowing too that the agent consumes a small quantity of tokens in the background even while idle, on conversation summarization for --resume and processing a few commands. Under US$0.04 per session, in the usual case.

One extended thinking detail weighs more than it looks: it ships enabled, the reasoning tokens get billed as output tokens, and the default budget can reach tens of thousands of tokens per request. For a simple task, /effort at a lower level is a direct saving with no perceptible loss.

If you plan to budget for a team, the most useful advice is this: budget more for a coding seat than for a chat seat. Each Claude Code turn carries file content, tool calls and multi-step reasoning, and one debugging session can consume more than an entire day of chat.

The measurement of cost by usage pattern sits in what each usage pattern costs.

By not asking yourself. That is the METR finding surviving any change of tool: the measurement put the participants 19% slower and they went on believing they were 20% faster. The sense of speed and the speed are independent variables.

That leaves you with a practical problem. You cannot set up a randomized controlled trial at work, and your perception is useless. Three instruments remain, in order of effort.

The cheap one: /insights. Unlike /usage, which shows how many tokens you spent, /insights produces a report on how you work. It analyzes your recent sessions and writes an HTML file covering what you work on, friction points (misread requests, faulty code) and usage suggestions. One run analyzes up to 200 sessions it has yet to see. The report lands at ~/.claude/usage-data/report.html, and each run keeps a dated copy.

Its value lives in the friction section. A request type that keeps showing up as misread points at no model failure: a gap in your CLAUDE.md explains it. The report becomes a task list for layer 1.

The honest one: an output metric you already collect. The Microsoft study used approved PRs as a proxy, with the explicit caveat that an approved PR is not the value it delivers. It is a poor proxy, and it still beats a feeling. If you already count PRs, closed issues or releases, compare comparable time windows. It does not have to be rigorous; it has to be a number existing outside your head.

What does not work: counting generated lines of code. It is the easiest metric to collect and the easiest to game, since the agent excels at producing volume, and volume is no delivery.

One methodological warning holds for any measurement you run: watch out for the novelty effect. The Microsoft study raised that concern head-on and verified that the gain persisted across four months. Two weeks of enthusiasm are no data. If you measure, measure for at least a quarter.

And accept the possibility that the result is "nothing changed". In that case the answer is neither abandoning the tool nor persisting on faith: it is looking at which of the five layers you skipped. In most cases I have seen, the answer is the first.

In the order they appear, from my experience building this on client projects.

CLAUDE.md swells and nobody notices. It starts at 40 useful lines, reaches 400 in three months, and from then on every task carries database migration instructions even while you work on CSS. The symptom: the agent starts to "forget" the request midway through long tasks.

MCP servers accumulate. Each one seemed like a good idea on the day. The symptom: /context shows half the room went before the first message.

The eternal session. You open it in the morning and use it until night. The symptom: the bill triples with no change in work volume.

Opus as the default for everything. The symptom: a cost per task that makes no sense against the task's complexity.

Agent teams on without need. The symptom: consumption that spikes with no explanation, around 7x when the teammates run in plan mode.

One pattern runs through all of them: they degrade by degrees. None breaks at once. The setup decays over weeks until you conclude that "Claude Code got worse". It did not get worse. Your context got fat.

The diagnosis is the same command every time. /usage shows the recent usage attribution per skill, subagent, plugin and MCP server, each as a percentage of the total, and flags behaviors accounting for 10% or more of consumption. It is the setup's blood test. Twenty minutes a month for running it alongside /context, and switching off what you do not use, earns its place on the calendar.

I catalogued the 18 Claude Code traps in a real project, each with the symptom that reveals it.

Five steps, in the order of the layers. Each takes under an hour.

1. Cut your CLAUDE.md to under 200 lines. What is left over becomes a skill.
2. Run /context and switch off the MCP servers you do not use. Swap for a CLI wherever one exists.
3. Write a hook for the command whose output you filter by hand most often.
4. Adopt /clear between unrelated tasks. It is the highest-return habit on the list.
5. Run /usage at the end of the week and look at the attribution per skill and per MCP server.

Only after that is it worth touching subagents or agent teams. Delegation on top of bad context multiplies the bad context.

If your use case is content production instead of code, the same layered reasoning shows up in skill stacks for blog articles, built on the same logic of context before capability.

Does Claude Code work well on a large legacy project?

It does, though it rests on layer 1 and nothing else. In a large codebase, the bottleneck is how much relevant context it can gather before acting. Code intelligence plugins help a lot in a typed language, because they replace text search with precise symbol navigation.

Do I need agent teams to work seriously?

No. They ship disabled and consume about 7x more tokens in plan mode. A subagent solves most context isolation cases (running tests, fetching documentation, processing logs) at a fraction of the cost. Turn agent teams on when you have work that is parallel and independent in fact, and not to speed up a sequential task.

How do I know whether I am overspending?

/usage shows the attribution per skill, subagent, plugin and MCP server, and flags behaviors accounting for 10% or more of consumption. If the number does not match the sense of work done, the usual suspects are a session never cleared and Opus as the default.

Skill or CLAUDE.md: where does the instruction go?

The question that settles it: does this hold true in every task in this project? If yes, it goes into CLAUDE.md: naming conventions, the stack, architecture decisions that always apply. If it is a specific procedure that comes up now and then, it becomes a skill. PR review, database migration, release publishing. Claude Code loads CLAUDE.md in every session and charges for it; a skill loads on demand. The official recommendation caps it at 200 lines.

Is running everything on Opus worth it?

Seldom. Sonnet handles most coding tasks and costs less. The official recommendation reserves Opus for complex architecture decisions or multi-step reasoning, switching with /model mid-session. Opus left as the default is one of the two most common causes of an unexpected invoice, the other being a long session never cleared. For a subagent on a simple task, model: haiku in the configuration cuts more still.

Does that study saying AI makes devs slower invalidate all this?

No, though it deserves a serious look. The METR trial measured 19% slower in early 2025, with Cursor Pro and Sonnet 3.5/3.7, across 16 developers. The Microsoft study measured +24% approved PRs in early 2026, with Claude Code and Copilot CLI, across tens of thousands of engineers. Different tools, eras, scales and metrics. The METR finding that survives all of it is the perception one: you are no reliable instrument for measuring your own speed.

• METR — Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity. Published 10 July 2025. Accessed 19 August 2026.
• Murphy-Hill, E.; Butler, J.; Savelieva, A. — Adoption and Impact of Command-Line AI Coding Agents: A Study of Microsoft's Early 2026 Rollout of Claude Code and GitHub Copilot CLI. arXiv:2607.01418, July 2026. Accessed 19 August 2026.
• Anthropic — Claude Code Docs: Manage costs effectively. Accessed 19 August 2026.
• Anthropic — Claude Code Docs: Agent teams. Accessed 19 August 2026.
• Anthropic — Claude Code Docs: Sub-agents. Accessed 19 August 2026.
• Anthropic — Claude Code Docs: Hooks reference. Accessed 20 August 2026.

Verified on 19 August 2026.

Review trigger: this post needs revisiting when (a) METR publishes the study redesign it announced in 2026, (b) agent teams stop being experimental or the 7x multiplier changes, (c) the official documentation updates its cost-per-developer figures, or (d) the recommended 200-line CLAUDE.md limit changes.