Understanding Claude Code and using it effectively

You can only drive well what you understand. Before talking method, let’s open the hood: what Claude Code really is, what it sees, what it remembers, and who holds the wheel. Two images will help us, and will stay with us to the end of the article: a new colleague, for the way it works, and a car, for the way it is built and driven.

A harness, not autocomplete

A new colleague, every morning

A direct consequence of the loop: Claude Code doesn’t “know” your project. It discovers it in every session, by reading. Imagine a new colleague, brilliant and very fast, who shows up every morning with no memory of the day before. To work well with it, you need to know what it has in its head, what it can do with its hands, what it puts on its desk, and what it writes in its notebook.

So before it starts, it knows only three things: what you wrote for it, what it noted down itself, and what it finds by searching. Everything else, it guesses. Let’s look at each trait more closely.

The built-in tools

A tool is an action the model can request. Claude Code provides about ten, and you can add more (we’ll get to that in Part 4). You’ll see their names scroll by in the terminal.

The context, its working memory

The article “Understanding AI and mastering its jargon” compared the context to a desk: everything the model needs in front of it to work is laid out there, and its size is limited. On recent models, Claude Code gets a huge desk, a million tokens, enough to lay out several thousand pages.

What’s already on it when you type your first message: the harness instructions, your CLAUDE.md files, the index of its auto memory, one line of description per skill, the tool definitions (for MCP servers, only the names are loaded at first; the details come on demand). After that, everything piles up: your messages, every file read, every command output, every answer.

Illustrative proportions. To see yours, type /context.

When the desk nears its limit, Claude Code compacts it: it replaces the history with a summary, then reloads your CLAUDE.md files, its memory and the current plan. It’s convenient, and it’s a loss.

Above all, a big desk is not a tidy desk. Anthropic acknowledges this itself in its writing on context engineering: the more loaded the context, the less precise the model’s attention. Specialists call it context rot, the context slowly going bad. An instruction given at the start of a long session carries less weight than the 300 lines of logs that followed. Hence the most profitable rule in this article:

What it remembers

Since the desk is cleared every evening, everything that must last goes through files. Claude Code knows four kinds, and mixing them up is a classic source of disappointment.

One engine, one car, several bodies

The colleague tells us how Claude Code works. To understand how it’s built, and who drives it, let’s switch images. The article “Understanding AI and mastering its jargon” distinguished the model and the product the way you distinguish the engine from the car. Claude Code is a car built around an Anthropic engine. Each part matches a setting you’ll come across.

The surfaces: terminal, editor, web…

The same harness comes in several forms. They share your settings and your configuration files; what changes is where the loop runs and how you watch it.

$ curl -fsSL https://claude.ai/install.sh | bash   # Windows: irm https://claude.ai/install.ps1 | iex
$ cd ~/my-project && claude                        # and claude doctor if something gets stuck

You need a paid Claude subscription (Pro, Max, Team or Enterprise) or an API account. Prices change often: the official page is the reference, and /usage tells you where you stand.

Who drives: the permission modes

It’s the most important setting, and the least looked at. It decides what Claude can do without asking you, in other words who holds the wheel. Shift+Tab cycles through the modes during a session, and the active mode is shown below the input box.

Permissions aren’t the only barrier. /sandbox turns on operating-system-level isolation for shell commands: writes limited to the project folder, network filtered by a list of domains. These are our car’s guardrails: the permission decides whether a command can go, the sandbox limits what it can damage.

Models, effort, thinking

/model chooses the engine (Option+P on Mac, Alt+P elsewhere). The aliases opus, sonnet, haiku and fable always point to the latest version of each family, and opusplan uses Opus to plan, then Sonnet to execute.

/effort sets the revs, that is, how hard it thinks, from low to max: more effort means a better answer on a hard problem, and more time and tokens on an easy one. The word ultrathink in a message pushes the thinking for that turn only. /fast turns on a fast mode for Opus, more expensive, in preview.

In the article “Will AI replace developers?”, I ranked AI tools for developers on an autonomy scale, from L0 (no AI) to L5 (from sentence to app). Claude Code sat at L4, among the agents. That was true, and incomplete: depending on how you use it, it covers almost the whole scale. Here are the seven uses I come across, ranked by who holds the wheel. None of them is the right one in absolute terms.

Each card follows the same format: the principle, an example request, the settings that go with it, and the trap. Skim the ones that don’t concern you yet, and try the switchman at the end.

> Explain how an order goes from “cart” to “paid”.
  Trace the path through the code, with file:line
  at each step. Don’t change anything.

> Why is this test disabled? Look in the Git
  history for who did it, when, and why.

> In src/pricing/discount.ts, the loyalty discount
  is applied before VAT. It must be applied after.
  First write the test that proves it, show it to me,
  then propose the fix.

> /plan Add pagination to the /orders API, by
  cursor and not by offset. First look at how
  /products does it. Propose a plan, and ask me
  your questions before coding.

> I described the need in docs/workstream-csv-export/
  NEED.md. Question me on what’s missing, then write
  PLAN.md: criteria, out of scope, steps, tracking.

  … (a few exchanges later, new session)

> step 2 of the file docs/workstream-csv-export/PLAN.md

> Make three very different mockups of the home
  page, in throwaway/home-a.html, -b and -c.
  Throwaway code: aim for the effect, not quality.

> [Image #1] B, but with A’s title and
  fewer colors.

$ claude -w auth-migration     # terminal 1
$ claude -w payment-tests      # terminal 2

> Launch three subagents in parallel to audit
  orders/, billing/ and shipping/: dead dependencies,
  duplicated code. Then give me a ranked summary.

$ claude -p "Fix the lint warnings without changing
  behavior, then summarize your changes." \
    --permission-mode dontAsk \
    --allowedTools "Read,Edit,Bash(npm run lint *)" \
    --max-turns 20 \
    --output-format json

Which one to choose?

The choice depends less on the size of the project than on three questions: what you’re trying to get, what will become of the code, and the cost of a mistake. The switchman below asks them in order.

And to keep the big picture in view, here are all seven side by side:

The seven ways of working all have their place, and I use each of them at one point or another. But for anything that goes to production, I have one, and only one. It follows directly from what I argued in the article “Will AI replace developers?”.

From editor to spec

There I wrote that developers move from the role of author to that of editor, and that the spec becomes the real code again. In practice, I go one step further, and that is the heart of this article. Not a metaphor: a concrete way of organizing the repository and the working day.

The history of the profession has seen this shift before. When developers moved from assembly to languages like Java, source code changed language. Compiled code didn’t disappear: it became a derivative, regenerated at every build, that no one writes by hand anymore. With Claude Code, I’m living through a shift of the same order. The source is the specification, written in English in a file in the repository. The code is derived from it.

The same intent, in three eras. The table follows the columns of the diagram, with one line of code each time:

Coding as a pair: who does what

I haven’t stopped coding. I code as a pair, and each of us has our own lines. The split is nothing theoretical: it’s the one I find in every workstream.

The cycle of a workstream

Here’s what the file looks like, for our Tuesday-morning CSV export:

# Workstream: CSV export of orders

> Temporary folder. Lasting decisions will go into docs/ARCHITECTURE.md,
> then this folder will be deleted.

## Need
At the end of every month, accounting matches paid orders against bank transfers.
Today, they copy and paste from the admin, page by page.

## Acceptance criteria
- “Export” button on /admin/orders; the list filters apply.
- Columns: no., date (YYYY-MM-DD), customer, total incl. tax, status.
- Semicolon separator, UTF-8 with BOM (otherwise Excel mangles accents).
- 50,000 rows without exhausting memory: streamed writing.
- Restricted to the `accounting` role; every export is logged.

## Out of scope
- No generic export for other entities. No PDF.

## Shared rules
- Follow docs/ARCHITECTURE.md § Admin. No new dependencies.
- Tests first. `npm test` and `npm run lint` green before each commit.
- Never modify an existing migration.

## Progress
| Step  | Content                                      | Status |
|-------|----------------------------------------------|--------|
| 1     | Format tests (headers, dates, BOM)           | ✅     |
| 2     | Streamed export service + `accounting` role  | ⬜     |
| 3     | Admin button + logging                       | ⬜     |
| 4     | Trial on 50,000 rows, documentation          | ⬜     |

With this file, Tuesday’s generic service would never have existed: it’s written in black and white under “Out of scope”. For Claude to know what to do with the file, a single rule in the project’s CLAUDE.md is enough:

When the user writes “step X of file …”, carry out exactly that
step following the file’s “Shared rules”, then update
its “Progress” table.

And the working session then fits in one line:

> step 2 of file docs/workstream-csv-export/PLAN.md

● Read docs/workstream-csv-export/PLAN.md · Read docs/ARCHITECTURE.md
● Step 2: streamed export service and “accounting” role.
● Update src/admin/orders/export.ts · Update src/auth/roles.ts
● Bash npm test       48 passed, 0 failed
● Bash npm run lint   ok
● Update docs/workstream-csv-export/PLAN.md  step 2: ✅

✓ Step 2 committed locally, ready for your review.
  Heads-up: the date filters use local time,
  and the spec says nothing about time zones. Decide before step 3?

The last line is my favorite. A good pair partner doesn’t just execute: it surfaces the gaps in the spec. And the answer, whatever it is, will go into the file, not into the conversation.

The review, the biggest part of the job

Reading a diff isn’t about hunting for typos. It’s where a developer’s experience weighs the most, and it’s where I spend the most time. It happens in a precise order.

Every question follows the same path. What matters is the second-to-last step: an approved change that doesn’t make it into the spec will be forgotten by the next session.

> Why csv-stringify? The shared rules say
  “no new dependencies”.

● Right. I added it to escape the fields. I can
  write a tested streaming generator of about thirty lines.

> Do it. And rename exportOrders to streamOrdersCsv: in this
  project, streaming functions start with stream. Add
  this convention to the plan’s shared rules.

● Update src/admin/orders/export.ts · Update package.json
● Update docs/workstream-csv-export/PLAN.md  rule added
● Bash npm test       51 passed, 0 failed

✓ Dependency removed, function renamed, convention in the plan.

This isn’t a lab method. I’ve tried it out.

The five rules I don’t negotiate

Why it works

There’s nothing magic about this method. It answers, point by point, the colleague’s limits described in Part 1:

I’m not the only one converging on this shape. For its agents that work over long periods, Anthropic describes a similar setup: a feature list and a progress file that the agent rereads at every new session, with work carried out one feature at a time. The spec-driven development tools cited in the article “Will AI replace developers?”, such as GitHub’s Spec Kit or AWS’s Kiro, point the same way. The name will change. The principle holds:

When I depart from my method

A method applied everywhere becomes a dogma. Here’s when I do things differently.

A good method rests on a well-organized workshop. Claude Code offers half a dozen configuration building blocks, similar enough to be easily confused. Back to our colleague: in Part 1, we saw its brain, its hands, its desk and its notebook. Time to equip it. This part says what goes where, what each block is for, and gives you files ready to adapt.

Equipping the colleague

Each configuration block matches an object you would hand a new colleague so they work well, and for a long time. The colors in this portrait are the colors of the labels throughout this part.

The workshop layout

Here is where to put all of this, in the tree of a well-equipped project. You don’t need everything on day one: a CLAUDE.md and a settings file are enough to start. The rest gets added when a need keeps coming back.

my-project/
├── CLAUDE.md                  the project’s welcome sheet, versioned
├── CLAUDE.local.md            your personal notes, outside Git
├── .mcp.json                  the team’s MCP servers
├── .worktreeinclude           files to copy into each worktree (.env)
├── .claude/
│   ├── settings.json          the team’s permissions and hooks, versioned
│   ├── settings.local.json    your settings for this project, outside Git
│   ├── rules/                 targeted rules: tests.md, api.md…
│   ├── hooks/                 the scripts called by the hooks
│   ├── skills/                one folder per piece of know-how
│   │   └── release/SKILL.md
│   └── agents/                one file per specialist
│       └── reviewer.md
├── docs/
│   ├── ARCHITECTURE.md        the map: the what and the how
│   ├── CONCEPTION.md          the decisions: the why
│   └── workstream-csv-export/ temporary: PLAN.md
└── src/ …

~/.claude/                     your settings, valid in all your projects
├── CLAUDE.md                  your preferences: language, style, habits
├── settings.json
├── skills/  agents/  rules/
└── keybindings.json

When to use what

All these blocks change Claude’s behavior, but not in the same way. The most important distinction fits in two words:

CLAUDE.md: short, precise, alive

/init writes a first draft of CLAUDE.md by reading your project. It’s a good starting point, and a bad end point: it often describes what Claude could find on its own. A good CLAUDE.md says what the code doesn’t. The documentation recommends staying under 200 lines; a good file often fits in far fewer.

# My project

This project is a modern, high-performance
web application.

Write clean, maintainable code.
Follow best practices.
Be careful about security.

The code is in src/. Components are
in src/components/. Tests are in
tests/.

[followed by 400 lines copied from the wiki]

# Shop: API and admin
Node 24, Fastify, PostgreSQL.

## Commands
- `npm test`: unit tests, fast
- `npm run test:e2e`: slow, only when asked
- `npm run check`: types + lint, after every edit

## Rules
- SQL only in src/db/queries/.
- Amounts in cents (integers), never floats.
- New table = new migration. Never
  modify an existing migration.
- Never run `npm run deploy`.

## Pointers
- Architecture: @docs/ARCHITECTURE.md
- “step X of file …”: run that step,
  follow its common rules, tick the tracker.

Treat it like code: it gets reviewed in pull requests, and it gains a line every time Claude repeats the same mistake. That’s rule 1 from part 3, applied to configuration.

Permissions: write down the rights once and for all

Rather than answering “yes” fifty times to npm test, write it into the permissions. Each rule targets a tool, and optionally a pattern: Bash(npm run check) for an exact command, Bash(git diff *) for every command that starts that way, Read(./.env) for a file. Denials (deny) take precedence over questions (ask), which take precedence over approvals (allow).

{
  "permissions": {
    "allow": [
      "Bash(npm test)", "Bash(npm run check)",
      "Bash(git status)", "Bash(git diff *)", "Bash(git log *)"
    ],
    "ask": [ "Bash(git push *)" ],
    "deny": [
      "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)",
      "Bash(npm run deploy *)"
    ]
  }
}

Settings stack up: yours (~/.claude/settings.json), the team’s (.claude/settings.json), yours for this project (.claude/settings.local.json), and, in companies, settings managed by the administrator, which override everything. /permissions shows the result, /status where each setting comes from. One limit to know: a deny rule on a shell command is a safety net, not a wall, because there are a thousand ways to write the same command. For truly sensitive files, add the sandbox (/sandbox), which filters at the system level.

Hooks: the law

A hook is a command Claude Code runs on a specific event: before or after a tool is used, when a message is sent, at the end of a turn, when a session starts, when Claude is waiting for your answer. There are about thirty of them. The hook receives the event details as JSON on its standard input. If it exits with code 2, the action is blocked, and its error message is sent back to Claude as an explanation.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command",
        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
    }],
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command",
        "command": ".claude/hooks/protect.sh" }]
    }]
  }
}

#!/usr/bin/env bash
# Blocks edits to sensitive files.
file=$(jq -r '.tool_input.file_path // empty')

case "$file" in
  *.env|*.env.*|*package-lock.json)
    echo "Protected file: $file" >&2
    exit 2 ;;
  */migrations/*)
    if [ -e "$file" ]; then
      echo "Existing migration: create a new one." >&2
      exit 2
    fi ;;
esac
exit 0

The first hook formats every edited file: no more “remember to run Prettier” in the CLAUDE.md. The second turns the rule “never modify an existing migration” from advice into law. Another use I recommend: a hook on the Stop event, which runs the tests when Claude thinks it’s done, and sends it back to work if they fail. /hooks lists the active ones. And remember that a hook is a program running with your permissions: one that comes with a cloned repository gets read like any other script.

Skills: the know-how

A skill is a folder containing a SKILL.md file: a name, a description, then instructions, and possibly scripts or templates alongside. Only the description is loaded at startup, one line per skill. The content only enters the context when the skill is used, either because you type /release, or because Claude recognizes the situation from the description. Like a binder where you only read the spines, you can have dozens of them without cluttering the desk. The old custom commands (.claude/commands/) still work, but skills replace them.

---
name: release
description: Prepares a new release (changelog, version number, tag).
  Use when asked to publish, ship or deliver a release.
disable-model-invocation: true
---

# Publish a release

1. Check that we’re on main, up to date, and that `npm test` passes.
2. List the commits since the last tag and sort them
   (additions, fixes, breaking changes).
3. Propose the version number (semver) and wait for my approval.
4. Update CHANGELOG.md, then run `npm version <number>`.
5. Don’t push anything: display the `git push --follow-tags` command.

The line disable-model-invocation: true reserves triggering for you alone: for a procedure with side effects, I don’t want Claude deciding on its own that the time has come. Skills follow an open standard, Agent Skills, which other tools read too. Anthropic publishes examples in the anthropics/skills repository (including those that handle Word, Excel, PowerPoint and PDF files), and an official plugin, skill-creator, helps you write your own.

Subagents: the specialists

A subagent is an instance of Claude with its own prompt, its own tools, its own model, and above all its own context. Claude Code ships three: Explore (search the code, read-only), Plan (prepare a plan) and a general-purpose agent. They serve three purposes: protecting the main desk from a search that would read fifty files (the specialist reads them on its own desk and comes back with one page), bringing fresh eyes to a piece of work, and parallelizing. You write your own in Markdown:

---
name: reviewer
description: Reviews a diff with fresh eyes. Use at the end
  of each step of a workstream, before the commit.
tools: Read, Grep, Glob, Bash
model: opus
---

You are a demanding reviewer. You are given a PLAN.md step and a diff.
Check, in this order:
1. The diff does what the step says, and nothing more (read “Out of scope”).
2. Edge cases: empty values, large volumes, time zones.
3. Security: access rights, personal data, injections.
Answer with a ranked list: blocking, to fix, suggestion.
Don’t modify any file.

This reviewer hasn’t seen the conversation that produced the code. That’s precisely what makes it useful: it doesn’t share the author’s blind spots. It prepares your review, it doesn’t replace it. Other options exist, like isolation: worktree so a subagent works on its own copy of the repository, or background so it runs while you keep working.

MCP: plugging the workshop into the rest of the company

The Model Context Protocol, introduced in the article “Understanding AI and mastering its jargon” as a standard socket, lets you plug Claude Code into your tools through MCP servers: tickets, production errors, database, browser, documentation. You add an MCP server with one command:

$ claude mcp add --transport http github https://api.githubcopilot.com/mcp/
$ claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
$ claude mcp add --scope project playwright -- npx @playwright/mcp@latest

Three scopes: local (the default: just you, this project), project (in .mcp.json, versioned, approved by each person on first use) and user (you, all your projects). /mcp shows their status and handles authentication. Since Claude Code only loads tool names at the start, plugging in several servers costs little context. The real cost lies elsewhere: each server is a door. Treat it like a dependency: a source you know, and minimal rights, for example a read-only token.

Plugins: the ready-made toolkit case

A plugin bundles skills, subagents, hooks, MCP servers or language servers (LSP) into a package you install with one command. /plugin opens the catalog. Anthropic’s official marketplace, claude-plugins-official, is added automatically; a community marketplace exists alongside it. Careful: “official” refers to the catalog. Most of the plugins in it come from partners, and Anthropic itself maintains a smaller selection. Here are the ones from that selection I find most useful:

> /plugin install code-review@claude-plugins-official

Claude Code also ships ready-to-use skills: /simplify to clean up a diff, /verify to check a change in the real application, /loop to repeat a task at an interval. And the /code-review command runs a local review at several levels of rigor, up to ultra, a multi-agent review in the cloud. For everything else, one rule: a plugin can contain hooks and MCP servers, which means code that runs on your machine. Install it the way you would install a dependency.

Four typical setups

To make this concrete, here are four typical workshops, from the lightest to the most fully equipped. Pick the one that looks like yours and remove what you don’t need.

Commands worth knowing

There are many more, and the list grows every month. Here are the ones I actually use, grouped by moment. Type / in a session to see every command available to you, and check the official list of commands, the list of keyboard shortcuts and the list of command-line options.

Everything above only counts if it makes it into your working days. This last part gathers the mistakes I see most often (I’ve made every one of them), what agents change about security, and a one-week program to get started without getting burned.

The ten mistakes everyone makes

Security: what an agent changes

An assistant that suggests code does nothing on its own. An agent does: it runs commands with your permissions, on your machine, and it reads a lot of text it didn’t choose. A dependency’s README, a GitHub issue, a web page, a comment in a file: any of them can contain instructions written for it. That’s prompt injection, and no model is fully immune to it. The Claude Code documentation says so plainly.

British developer Simon Willison gave the most dangerous case a name: the lethal trifecta. An agent that combines the three capabilities below can be manipulated into leaking your data. The defense is simple to state: always take away at least one of the three.

In practice, six habits cover the essentials:

Your first week

If you’re just starting, don’t read all this as a checklist to tick off in one go. Here’s the progression I recommend, one day per way of working.

The Robot and the Orchestra can wait until the second week. You only delegate well what you’ve first done yourself with the tool.

Your turn

As in the article “Will AI replace developers?”, I’ll end with the questions I’m still asking myself. I’d like to hear your answers.

$ git merge --no-ff my-method
Merge made by the 'ort' strategy.