The Engineering Journal — Boluwaji Joshua Adedigba

Move semantics, and why copies are expensive

Tue, 01 Sep 2026 00:00:00 GMT

Here is a class small enough to fit in your head and broken in a way that takes a while to see.

class Shallow {
private:
    int *data;
public:
    Shallow(int d);
    ~Shallow();
};

Shallow::Shallow(int d) {
    data = new int;    // grab some heap
    *data = d;
}

Shallow::~Shallow() {
    delete data;       // give it back
}

Constructor allocates, destructor frees. That is the deal, and it holds right up until someone copies the object.

The default copy is a member-wise copy

Write no copy constructor and C++ writes one for you. It copies each member across, one at a time. data is a member, so data gets copied.

data is a pointer. Copying a pointer copies the address, not the thing at the address.

  before                          after  Shallow b {a};

  a.data ──▶ [ 42 ]               a.data ──┐
                                           ├──▶ [ 42 ]
                                  b.data ──┘

Two objects. One buffer. Both destructors will run, and both will call delete on the same address. The first free is fine. The second is undefined behaviour, which in practice means a crash somewhere unrelated, minutes later, in code that did nothing wrong.

Worse: while both are alive, writing through a changes what b sees. They are not two accounts. They are one account with two names.

The fix is to copy what is pointed at

A deep copy allocates its own buffer and copies the value into it:

Shallow::Shallow(const Shallow &source) {
    data = new int;            // my own storage
    *data = *source.data;      // my own copy of the value
}

  a.data ──▶ [ 42 ]
  b.data ──▶ [ 42 ]      two buffers, two owners, two clean frees

The rule this produces: if your class holds a raw pointer to something it owns, you owe it a copy constructor that deep copies. The compiler’s default is correct for int and std::string and wrong for anything you allocated yourself.

And now the class is correct and slow.

The copy you did not ask for

C++ copies a lot, and most of it is invisible. Return an object from a function, pass one by value, push one into a vector that needs to grow, and you have paid for a deep copy. Do that inside a loop over a large buffer and the copies dominate the profile.

Some of those copies are unavoidable. Many are not, because the source was about to be destroyed anyway.

total = combine(a, b);

combine builds a result, copies it out, and the original is thrown away. You allocated a buffer, copied every byte into a second buffer, then freed the first. The second buffer is byte for byte what the first one was.

Nobody would write that by hand. The language wrote it for you, because the only tool it had was “copy”.

L-values, r-values, and the second ampersand

To avoid that copy, the language needs to know something it previously could not express: is this thing about to disappear?

That is the distinction between l-values and r-values. An l-value has a name and a place you can point at. An r-value is a temporary, the unnamed thing an expression produces before it is used.

int x {100};

int &lref = x;      // l-value reference, binds to something named
int &&rref = 200;   // r-value reference, binds to a temporary

// int &&bad = x;   // error: x has a name, it is not going anywhere

&& is not “reference to a reference”. It is a separate thing, and it means “this binds only to a temporary”.

That distinction lets you overload on it:

void func(int &num);    // A: takes something with a name
void func(int &&num);   // B: takes a temporary

func(x);     // calls A
func(200);   // calls B

Which is how the compiler picks between copying and moving without you writing a single if.

Moving is stealing

A move constructor takes an r-value reference, so it only ever runs on an object that is about to die. That permission changes everything, because it no longer has to leave the source intact.

Shallow::Shallow(Shallow &&source) noexcept
    : data{source.data}        // take the pointer, not the buffer
{
    source.data = nullptr;     // and make sure they cannot free it
}

  before move                     after move

  src.data ──▶ [ 42 ]             src.data ──▶ nullptr
                                  dst.data ──▶ [ 42 ]

No allocation. No byte copying. Two pointer assignments, and the buffer has a new owner. Whether it held four bytes or four megabytes, the move costs the same.

Two details in that signature earn their place. There is no const, because the whole point is modifying the source. And noexcept matters more than it looks: std::vector will only move your elements while reallocating if the move cannot throw. Leave it off and the vector quietly deep copies instead, which is the exact cost you wrote the move constructor to avoid.

The compiler was already ahead of you

Before you conclude that every copy in your codebase is a bug, know that the compiler elides many of them outright. Return value optimization builds the returned object directly in the caller’s storage, so neither a copy nor a move happens. C++17 made this mandatory in common cases.

This is worth knowing mainly so you are not surprised in a debugger, watching a copy constructor you carefully wrote never get called.

What this explains elsewhere

Once you have seen a double free caused by a copied pointer, other languages read differently.

A Go slice is a small struct holding a pointer, a length, and a capacity. Assigning it copies those three fields, not the backing array. That is a shallow copy, exactly the one above. Go does not crash, because the garbage collector will not free an array that something still points at, but the aliasing is real, and it is the reason append sometimes mutates a slice you thought you had copied and sometimes does not.

JavaScript objects behave the same way. const b = a gives you two names for one object, and this is why the ecosystem keeps reinventing structured cloning.

Neither language will hand you a double free. Both will hand you two names for one buffer, and the debugging session that follows is the same one.

A skill is a loading strategy with some knowledge attached

Tue, 01 Sep 2026 00:00:00 GMT

For about a week I opened every session by pasting the same set of prose rules. No em dashes. Straight quotes only, sentence case headings, and never bold the label at the front of a bullet. Different task each time, same paste, because the writing that ships out of this project has a house style and nothing in the model knows it until I say so.

The obvious fix is to put them in CLAUDE.md, and it is the wrong fix. Those rules have nothing to say about a failing Terraform plan or a Lighthouse budget, and that is most of what I do in this repo. Memory files load into every conversation whether or not the conversation is about writing. Paying for a style guide while debugging a build is exactly the tax that context is the budget is about.

A skill is the same knowledge with a load condition attached. That condition is the entire product.

The two-stage load

A skill is a directory with a SKILL.md inside it. Two places to put one:

~/.claude/skills/<skill-name>/SKILL.md    every project on this machine
.claude/skills/<skill-name>/SKILL.md      this project only

The directory name is what you type to invoke it. ~/.claude/skills/humanize-writing/ gives you /humanize-writing, and if the same name exists at both levels the personal one wins.

Then the part that matters:

  at startup       ┌───────────────────────────────────────┐
                   │  every skill's name + description     │ always
                   └──────────────────┬────────────────────┘
                                      │ description matches
                                      ▼
  on invoke        ┌───────────────────────────────────────┐
                   │  the SKILL.md body                    │ stays for
                   └──────────────────┬────────────────────┘ the session
                                      │ SKILL.md points at it
                                      ▼
  on need          ┌───────────────────────────────────────┐
                   │  references/*.md                      │ once
                   └───────────────────────────────────────┘

  never            scripts/*  ──▶  executed, only the output is read

Only the top row is unconditional. A listing of every skill’s name and description sits in context from the first token of the session so the model knows what it has; the body arrives when something actually triggers it. That is the whole difference from a memory file, and it is why a twenty-file reference library costs you almost nothing until the day you need it.

Once a skill does load, its rendered content enters the conversation as one message and stays there across later turns. Claude Code does not re-read the file each turn, so every line in the body is a recurring cost for the rest of the session, not a one-off. Write standing instructions, not step-by-step narration you expect to be forgotten.

The description is the product

Everything else in a skill is downstream of one string. The description is what the model matches your request against to decide whether to load the skill at all, so a description like “help me with docs” either never fires or fires on everything, and in both cases the knowledge inside is irrelevant.

A good one answers two questions in the same breath: what does this do, and when should it be used. Third person, because it gets injected into the system prompt and “I can help you with X” reads as the model talking to itself. Real keywords, the ones a person would actually say. The description on the skill I ended up writing for those prose rules runs to 921 characters and spends most of them on the second question. Abridged, because it does not fit here:

description: Strips machine-written tells out of prose before a human
  reads it. Apply automatically to any prose drafted or edited for the
  user that they might publish, submit, or send, including emails, chat
  and Slack messages, blog posts, social captions, articles, docs and
  README prose, bios, cover letters, PR and commit descriptions, and
  academic work such as papers, theses, and literature reviews.
  Does not apply to code, tests, config, or data files.

That is not padding. Every noun in the second half is a trigger phrase, and the last sentence is a negative trigger that keeps it from firing on a .tf file.

The Agent Skills spec caps description at 1,024 characters and name at 64, lowercase letters, numbers and hyphens only. Claude Code adds a budget on top: the listing of names and descriptions gets a share of the context window (1% by default) and when it overflows, descriptions are dropped starting with the skills you invoke least. Names always survive; descriptions do not. So the failure mode of installing thirty skills is not that they stop existing, it is that the ones you rarely use silently lose the text that would have made them fire. /doctor estimates what the listing is costing you.

Two spelling traps while you are in the frontmatter, because the fields are not consistent with each other. Tool restrictions are hyphenated, allowed-tools and disallowed-tools. Extra trigger phrases go in when_to_use, with underscores. Everything is optional, including name, which for a personal or project skill is only a display label; get it wrong and the skill still loads under its directory name.

Keep the body small and the rest on disk

The rule of thumb is under 500 lines for SKILL.md. Past that, split, and the split is the interesting part.

~/.claude/skills/humanize-writing/
├── SKILL.md                 260 lines, the rules I always want
├── references/
│   ├── INDEX.md             routes to everything below
│   ├── academic-writing.md  loaded for a thesis, never for a tweet
│   ├── word-lists.md
│   └── ...21 more
└── scripts/
    └── mechanical-scan.sh   greps for em dashes and curly quotes

SKILL.md holds the instructions that apply every single time. Everything conditional goes into references/, and the trick that makes the structure work is one line of prose in the main file that names the condition:

Academic work is in scope with overrides. For a paper, thesis chapter,
or literature review, read `references/academic-writing.md` first.

Without that line the reference file is dead weight on disk. With it, the model has a rule for when to spend the tokens. Keep those pointers one level deep: a reference that points at another reference tends to get skimmed with head rather than read, and you get half a file’s worth of instructions with no error to tell you so.

Scripts are the part I did not expect. A script in a skill is executed, not read. Claude runs it through bash and consumes the output, and the source never enters context at all, so a 400-line Python converter and a two-line shell alias cost exactly the same until one of them runs. That inverts the usual advice. If a piece of your skill is deterministic, pushing it into scripts/ is not just more reliable than prose instructions, it is cheaper than prose instructions, because prose you have to keep paying for and a script you pay for once per run.

A skill is not a sub-agent

Both are ways to stop repeating yourself and they are not interchangeable. A skill joins the conversation you are already in: its instructions sit alongside your context and shape the work you are doing right now. A sub-agent gets its own window, does the work out of sight, and hands back a summary, which is a context decision rather than a knowledge one.

They compose in both directions. Put context: fork in a skill’s frontmatter and the skill body becomes the prompt for a forked sub-agent. Going the other way, a custom sub-agent takes a skills list in its frontmatter, and the full content of each named skill is injected at startup. That field controls preloading, not permission: a sub-agent with no skills list can still discover and invoke your skills itself. If you want it to have none, take the Skill tool away.

Plugins are how anyone else gets it

A skill in .claude/skills/ is committed with the repo and everyone who clones it has it. A skill in ~/.claude/skills/ is yours alone, and telling a teammate to copy a directory is not distribution.

A plugin is a directory with a manifest and the components beside it:

my-plugin/
├── .claude-plugin/
│   └── plugin.json        name, description, version
└── skills/
    └── pr-review/
        └── SKILL.md

Only plugin.json goes inside .claude-plugin/. Put skills/ in there too and nothing loads, with no complaint. Test with claude --plugin-dir ./my-plugin before you ship anything, and run claude plugin validate ./my-plugin before you publish. Publishing means a marketplace: a git repository that lists plugins, added with /plugin marketplace add <owner>/<repo> and installed from with /plugin install <name>@<marketplace>. A private repo works fine for that, which is the usual answer for a team.

When it will not fire

The first thing to check is the thing you wrote last, which is the description. Read it as a stranger and ask whether the words in it are the words you actually typed at the prompt. Nine times out of ten they are not: the skill says “quality assurance procedures” and you said “check my work”.

The rest of the list is short. Ask “what skills are available” and confirm yours is listed at all. Invoke it by name with /skill-name to prove the body works, which separates a matching problem from a content problem. If the skill is somehow present but has no description attached to it, the frontmatter did not parse, and claude --debug prints the error; claude plugin validate .claude/skills will find that across a whole directory.

Then there is the case where the skill fires reliably and the model does something else anyway. No amount of description tuning fixes that one. You do not have a knowledge problem, you have an enforcement problem, and that is what hooks are for.

The trap in all of this is writing a skill that is really a memory file: a body so general it applies to everything, a description so broad it matches everything, loaded permanently for no reason. If the answer to “when should this load” is “always”, you did not need a skill. Write the load condition first and the knowledge second, and the file mostly writes itself.

Sub-agents are a context decision

Mon, 31 Aug 2026 00:00:00 GMT

I asked a question I did not think was expensive. Which service handles refunds? The codebase was about three weeks old to me. Claude grepped, opened a file, followed an import, opened four more, found an interface, went hunting for implementations, and answered correctly a minute later.

Then I looked at what the answer had cost. Fifteen files were sitting in my context window, and they were going to sit there for the rest of the session, because a context window only ever grows. I wanted one sentence. I got one sentence and a research trail I had no intention of reading.

That is the whole case for sub-agents, and it has nothing to do with expertise. The model does not get better at Kubernetes because you told it that it is a Kubernetes specialist. It already knows what it knows. What a sub-agent actually changes is the size and cleanliness of the working set the answer gets produced in, and whether the wreckage of producing it lands in your window or somebody else’s.

Two windows, one paragraph between them

A sub-agent runs in its own context window with its own system prompt and its own tool permissions. It works on its own, and when it finishes, only its report crosses back. Everything else, the searches, the file contents, the reasoning it did to get there, is discarded with the context it lived in.

  main thread                         sub-agent

  ┌───────────────────────┐   task    ┌───────────────────────┐
  │ system prompt         ├──────────▶│ system prompt (agent) │
  │ CLAUDE.md             │           │ task description      │
  │ the conversation      │           │ 4 searches            │
  │                       │◀──────────┤ 15 file reads         │
  │ + one paragraph       │  report   │ the reasoning         │
  └───────────────────────┘           └───────────────────────┘
                                       discarded on return

Same refunds question, run through a sub-agent: the left box grows by a paragraph instead of by fifteen files. If you have read part one, this is the same budget argument with a second window attached.

Now the honest half. You lose the journey. When the answer is right this is exactly what you wanted, and when it’s wrong you have no idea where it went wrong, because the evidence has been thrown away. You can’t scroll up and find the file it misread. All you can do is ask again and hope the second run is better, which is a worse debugging position than reading fifteen files would have been.

There’s a second cost that surprised me more. A sub-agent starts cold. It does not inherit your conversation history, the files Claude already read, or the skills already loaded in your session. For a self-contained question that’s free. For a task that only makes sense given the last forty minutes of discussion, you pay for it to rediscover all of that, and the isolation you bought is worth less than the context you burned re-establishing. When that’s the shape of the work, /subtask is the escape hatch: it forks the current conversation, so the delegate inherits your history along with the system prompt, tools, and model.

You are already relying on this before you configure anything. Three sub-agents ship with Claude Code and launch on their own judgement. Explore holds read-only tools with Write and Edit denied, and handles file discovery and code search, which is my refunds question answered the way it should have been. Plan does the same read-only research behind plan mode. General-purpose gets every tool available to sub-agents and takes multi-step work that has to act, not just look.

If you would rather watch the searches happen, you can turn the read-only two off:

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(Plan)"]
  }
}

I leave them on. Exploration is the single best thing to keep out of a window, and the built-ins are doing it for free.

The parent writes half the prompt

A sub-agent receives exactly two things. Its system prompt, from its configuration file, which you wrote and can read. And a task description, written by the parent agent, based on what it thinks you asked for.

The second one is where delegation quietly goes wrong. You typed a request with three constraints in it. The parent compressed that into a brief. The sub-agent sees only the compression, has no access to what you actually typed, and cannot ask you a clarifying question. If the constraint you cared about did not survive the compression, you find out when the report comes back confidently wrong about something you thought you had specified.

I ran into this at scale on this site. It was built by dispatching parallel agents across ten git worktrees, one per slice, and the thing that made it survive was a preamble every dispatched agent had to receive verbatim. Two of the five points exist entirely because of the compression problem:

Write only within your owned paths. If you need something outside them, report it, do not create it.

Report: files created, contracts published, and anything you needed but could not own.

Neither is about capability. Both are about the fact that a delegated agent is working from a summary of my intent, and if I don’t nail the boundaries into the brief, the summary loses them. When you write your own task description, be specific in a way that feels excessive. You are not talking to the model, you are talking through a paraphrase of yourself.

Configuring one

Sub-agents are markdown files with YAML frontmatter. .claude/agents/ for a project, ~/.claude/agents/ for every project on your machine. Both directories are scanned recursively, so subfolders are free organisation. Identity comes from the name field, not the filename.

Only name and description are required. Here is one I’d actually get value from here, where hardcoded colours are the convention that breaks most often:

---
name: token-auditor
description: Finds colour literals outside tokens.css. Run after CSS work.
tools: Read, Grep, Glob
model: haiku
---

You audit styling changes against src/styles/tokens.css. A hex literal
or an rgb() call in any .astro or .css file outside that one is a
finding.

Report each finding as one line: file path, line number, the literal,
and the token that should have been used. If there are none, say so in
a sentence and stop.

tools is a comma-separated list, and leaving it out means the sub-agent inherits every tool available to sub-agents in the main conversation. That default is worth overriding more often than not. The agent above physically cannot modify a file, which is a stronger guarantee than instructing it not to, and it does a second job too: three tools describe a role more precisely than a paragraph of system prompt does. There’s a disallowedTools field if a denylist fits better, applied before tools is resolved.

model pins a model per agent. It takes sonnet, opus, haiku, fable, a full model ID, or inherit, and it defaults to the main conversation’s model. A grep-and-report agent on Haiku while the main thread stays on Opus is one of the few genuinely free wins in this whole system. There’s more in the frontmatter than most people need, including maxTurns, permissionMode, a skills list for preloading skills a custom agent would not otherwise get, and an isolation: worktree setting that does in one line what the eighty-five lines of my spawn-worktrees.sh do by hand.

Now the field that decides whether any of this fires. description is the trigger: the main agent reads it and decides, on its own, whether the task in front of it belongs to this agent. Vague descriptions fail in both directions. Write “helps with code quality” and it either never launches or it launches on everything, and the second failure is worse, because you’ll be paying for a delegation you didn’t want on tasks that were fine in the main thread. Say what it does and when to use it, in that order. When you want it regardless, @agent-token-auditor guarantees the run.

An output format is a stopping condition

This is the least obvious property of the whole feature, and the one that fixed the most for me once I understood it.

A sub-agent with no defined output has no way to know when it has done enough research. It cannot ask you. It has no sense of your patience. So it keeps going, because one more file might improve the answer, and there is always one more file. The runs that go on forever are almost always this, and it reads like a model problem when it’s a specification problem.

Define the shape of the report and the problem mostly evaporates. “Return each finding as file path, line number, and the token that should have been used” tells the agent what finished looks like. It can check its own work against the shape and see that the shape is full. That’s a stopping condition, and it’s the reason my token-auditor prompt spends more words on the output than on the audit. maxTurns exists as the blunt version, and it stops a runaway rather than fixing one: you get a partial result instead of a bounded one.

While you’re defining the output, add a section asking for obstacles. Something like this, near the end of the system prompt:

## Obstacles encountered

Report anything that got in your way: setup problems, workarounds you
found, commands that needed unusual flags, dependencies or imports that
caused trouble.

The reasoning is better than it first looks. A sub-agent hits a broken import, works out that the build needs a flag, solves it, finishes the actual task, reports on the actual task, and the fix dies with its context. Twenty minutes later the main thread hits the same broken import and solves it again from scratch. You paid twice for one piece of knowledge, and the only reason is that nobody asked for it. Ask.

The failures worth knowing about

Expert personas buy nothing. “You are a senior Python engineer” adds tokens and no capability. Launching a sub-agent has real costs, the lost visibility and the cold start, and a persona pays none of them back. The overhead is only worth it when the sub-agent does something the main thread cannot: keeping exploratory work out of your window, or running under tools and permissions you deliberately narrowed.

Multi-step pipelines are more fragile than they look. The tempting one is reproduce the bug, then debug it, then fix it, three agents in a chain. It fails because each step depends on what the previous step discovered, and what crosses between them is a summary. The debugger gets a paragraph about a reproduction it never watched. The fixer gets a paragraph about reasoning it never followed. Pipelines work when the steps are genuinely independent, which a debugging chain is the exact opposite of.

And do not delegate test runs. When a test fails, the thing you need is the failure output: the assertion, the diff, the stack, the line. A sub-agent hands back “the auth tests failed” and a tidy summary of what it believes went wrong, and now you’re writing a debug script to recover output you would have seen for free. This one is worth stating as a rule, because the temptation is real. Test output is verbose, verbose output looks exactly like the thing sub-agents are for, and it’s the one kind of verbose output you actually wanted to read.

That’s the test, in the end. Delegate the work whose intermediate state you don’t want, and keep the work whose intermediate state is the answer.

Hooks run whether the model agrees or not

Sat, 29 Aug 2026 00:00:00 GMT

There is a file in this site’s content directory called draft-should-not-appear.md. Its frontmatter sets draft: true, its body opens with “do not delete it”, and its only job is to be the thing that goes wrong first. If it ever renders on the live site, the draft filter is broken and I want to find out from a fixture rather than from someone reading a half-written post.

The filter itself is one function. getPublishedPosts() in src/lib is the only place in the codebase allowed to call getCollection('blog'). Every page imports the helper. The rule exists because a second entry point to the collection is exactly how an unpublished draft reaches production, and there is no version of that bug that gets caught in review, because the diff looks fine.

I wrote that rule into AGENTS.md. I wrote it into CLAUDE.md too. Both of those are text the model reads and mostly follows.

Mostly is doing a lot of work in that sentence.

The rule that could not be a request

Everything else in Claude Code persuades the model. CLAUDE.md is a document loaded into the prompt. A skill is a document loaded on demand. A slash command is a document you triggered by hand. They all work by being convincing, and they all compete for the same finite window, which means their influence decays exactly when you need it most: forty tool calls in, near the compaction boundary, on the run where the model is holding six other constraints at once. See part one for why that decay is structural rather than a bug.

A hook is not a document. It is a shell command the harness runs at a fixed point in its own lifecycle, with the model nowhere in the decision. The model does not read the hook, cannot see the hook, and has no ability to weigh it against anything else it was told. It just finds out afterwards.

That is the whole value proposition. You are trading expressiveness for certainty, and for a small number of rules that trade is obviously correct.

Here is the one wired into this repo, in .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/check-draft-filter.sh\"",
            "timeout": 10,
            "statusMessage": "Checking draft filter"
          }
        ]
      }
    ]
  }
}

matcher matches tool names. If it contains only letters, digits, spaces, underscores, hyphens, commas and pipes, it is read as an exact string or a pipe-separated list of exact strings, so Edit|Write is two exact matches rather than a regex. Put any other character in it and the whole thing is treated as an unanchored JavaScript regular expression instead, which is how you match a whole MCP server at once: mcp__playwright__.*.

$CLAUDE_PROJECT_DIR resolves to the directory the session started in and stays put even when Claude moves into a git worktree. That matters here, because this project spawns ten of them.

Hook config can live in ~/.claude/settings.json for every project, .claude/settings.json for one project, .claude/settings.local.json for one checkout, or in managed policy settings your admin controls. It can also ride along in a plugin, a skill’s frontmatter, or a subagent’s. The levels merge rather than override, so a project hook does not replace your personal one.

Where the hook fires

The event list is long now, past thirty entries, covering compaction, model switches, worktree creation, config changes and subagent lifecycle. Most of them you will never touch. Four carry almost all the weight.

PreToolUse runs before a tool call and can stop it. PostToolUse runs after a tool call succeeded and can only talk. UserPromptSubmit runs on your prompt before the model sees it. SessionStart runs once at the top.

The split between the first two is the thing to internalise:

   Claude proposes a tool call
             │
             ▼
      ┌─────────────┐
      │ PreToolUse  │──── deny ────┐   the tool never runs
      └──────┬──────┘              │
             │ allowed             │
             ▼                     │
       permission flow             │
             │                     │
             ▼                     │
        the tool runs              │   files are already written
             │                     │
             ▼                     │
      ┌─────────────┐              │
      │ PostToolUse │─── block ────┤   reason rides along with
      └──────┬──────┘              │   the tool result
             │                     │
             ▼                     ▼
        tool result ──────▶ Claude's next turn

PostToolUse cannot undo anything. By the time it fires, the file is on disk, the command has run, the request has left the machine. Its decision: "block" does not roll the edit back and the name is misleading: it attaches a reason to the tool result, and Claude still sees the original output alongside it. So it is feedback, not enforcement.

Which is fine, because feedback is what I actually want for the draft filter. Blocking a Write after the write has happened would leave the file there and the model confused. Handing back a sentence explaining what is wrong lets it fix the file on the next turn, which is the correct repair for a bad import.

UserPromptSubmit and SessionStart have a property the others do not: their plain stdout is added to context as something Claude can read. Everywhere else, a successful hook’s stdout goes to the debug log and nobody sees it. This catches people. You write echo "remember to run the tests" in a PostToolUse hook, watch nothing happen, and conclude hooks are broken.

Blocking and feedback are different tools

A hook communicates two ways and you should pick one per script rather than mixing them.

The blunt one is the exit code. Exit 0 is success. Exit 2 is a blocking error on the events that can block, and the message Claude sees is whatever you wrote to stderr. Every other exit code, including 1, is a non-blocking error: the transcript shows a notice, and the action proceeds anyway.

That last part deserves a moment. exit 1 is the conventional Unix failure and it does not block. Neither does a crashed script, and neither does a hook whose path you mistyped, which exits 127 from the shell and leaves your policy gate silently disabled while looking configured. If a hook is enforcing something, exit 2 or return JSON, and watch the first run to confirm it is actually firing.

The precise one is JSON on stdout. Exit 0, print an object, and the harness reads fields off it. PreToolUse puts its verdict inside hookSpecificOutput and gets four outcomes: allow skips the permission prompt, deny kills the call, ask forces a prompt, defer parks it for a -p caller to resume. The top-level decision and reason fields are deprecated for PreToolUse specifically, though they remain the current format for PostToolUse and Stop. It is the kind of asymmetry you only discover by having a hook quietly do nothing.

The draft-filter script uses the PostToolUse form. It reads the edited path off stdin, exits early for anything under src/lib where the helper legitimately lives, and only then greps:

if grep -Eq "getCollection\([[:space:]]*['\"]blog['\"]" "$f"; then
  call="getCollection('blog')"
  reason="${f} calls ${call} directly, bypassing the draft filter..."

  jq -n --arg reason "$reason" --arg note "$note" \
    '{decision: "block", reason: $reason, systemMessage: $note}'
fi

exit 0

reason goes to Claude. systemMessage goes to me, on screen, so I know the guard fired rather than discovering it in a transcript later. Building the string outside the jq program is not stylistic: the literal getCollection('blog') contains an apostrophe, which would close the single-quoted jq program mid-flight.

Determinism cuts both ways

The hook has a bug. I hit it while writing this post.

grep does not parse TypeScript, and it has no concept of a comment. So the guard fires on any file that merely mentions the call, and two files here mention it for entirely good reasons:

site/src/types/content.ts:41
  * component should be handling a raw `getCollection('blog')` result.

site/src/pages/rss.xml.ts:5
  * lives. Never call `getCollection('blog')` here: a feed is cached and

Both are doc comments. Both are telling a reader not to do the thing. The second is a comment that exists to explain the rule, and it trips the guard that enforces the rule. Editing either file blocks every single time, and the model gets handed a paragraph accusing it of a violation that is not there.

The cheap fix is to drop comment lines before matching, which is one more grep in the pipeline and handles both cases:

grep -vE '^[[:space:]]*(\*|//|/\*)' "$f" | grep -Eq "getCollection\(..."

It is still a heuristic. It would miss a trailing comment on a line of real code, and it would fire on a string literal. The correct fix is parsing the file, which is more machinery than this rule is worth.

The failure is worth sitting with, though, because it is not a quirk of one badly written script. It is the property I wanted, seen from the other side. A hook does not weigh context. It cannot notice that the match is inside a block comment, that the file declares types and runs no code, or that the sentence wrapped around the match is an instruction not to do it. It matched, so it fired, and it will keep firing that way on every run until I go and edit the shell myself.

That is the same reason it works. What stops the hook being talked out of a real violation on turn ninety is exactly what stops it being reasoned into ignoring a comment on turn one, and you do not get to have one without the other.

Which sets the design rule: make the pattern as narrow as you can while still catching the thing, and plan to pay for the false positives out of your own pocket rather than expecting the model to route around them. Mine is too wide. A guard that cries wolf at prose is a guard you start waving through, and at that point it has quietly turned back into a suggestion.

Arbitrary shell, with your credentials

A hook is a command running as you, with your environment, your keys, and write access to everything you can write to. The docs say this plainly and I will repeat it: review a hook before you add it, the same way you would review anything else that runs unattended.

The part worth knowing beyond that is the trust boundary. In an interactive session, Claude Code holds every settings-file hook back until you accept the workspace trust dialog for the folder, including hooks from your own ~/.claude/settings.json. In a -p or SDK session there is no dialog and the folder is treated as trusted, which means hooks committed into a repository’s .claude/settings.json run on a checkout you have never opened by hand. If you are scripting claude -p across repositories you did not write, read their .claude/ directory first, or pass --settings '{"disableAllHooks": true}' for that run.

You do not need to restart after editing a hook. Hook config is not snapshotted at session start: a file watcher picks up direct edits to settings files while the session is running, and a restart is the fallback for when the watcher misses a change rather than the routine. /hooks lists what is currently registered, with the source file for each, which is the fastest way to answer “is this thing even loaded”.

The tempting move, once hooks click, is to push everything into them. Resist it. Anything that needs the model to weigh a situation belongs in a skill, which loads when the request looks relevant and then argues its case. Hooks are event-driven and skills are request-driven, and the test for which one you want is whether you would accept the rule being skipped on a bad day.

For the draft filter the answer was no. So it is forty lines of bash that will go on being wrong about two comments until I get round to fixing them, and I will take that over a rule that only holds while the context is short.

MCP servers are capabilities, not knowledge

Fri, 28 Aug 2026 00:00:00 GMT

For most of a week I kept telling Claude that every colour in this site lives in tokens.css and nowhere else, and it kept writing #0f1115 into component files anyway. Somewhere in that week I caught myself scrolling a list of MCP servers looking for the one that would fix it.

There isn’t one. There cannot be one. Working out why is most of what you need to know about MCP.

A client, a server, and a list of tools

Claude Code is an MCP client. A server is a separate thing that speaks the protocol: either a process on your machine that the client launches and talks to over stdin and stdout, or an endpoint it talks to over HTTP. Four transports are supported. stdio for local processes, http for remote servers, sse for remote servers using server-sent events (deprecated, use HTTP where it exists), and ws for a persistent WebSocket, which you can only configure as JSON because claude mcp add --transport doesn’t accept it.

Adding one is a line of shell:

claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest
claude mcp add --transport http context7 https://mcp.context7.com/mcp

At session start the client connects to each configured server and asks what it offers. What comes back is a tool list: names, descriptions, and JSON input schemas.

  Claude Code = the MCP client
       │
       ├── stdio ──▶ playwright     npx, local child process
       ├── http  ──▶ aws-knowledge  knowledge-mcp.global.api.aws
       └── http  ──▶ context7       mcp.context7.com/mcp
                            │
                    tool list at session start
                            ▼
  ┌────────────────── context window ──────────────────┐
  │ system prompt · built-in tools · CLAUDE.md · files │
  │ ·················································· │
  │ MCP tool names       definitions fetched on demand │
  └────────────────────────────────────────────────────┘

Nothing in that exchange is knowledge. browser_navigate arrives as a name, a sentence of description, and a schema saying it wants a URL. That is a function signature plus a way to call it across a process boundary. The model still decides when to call it, and everything it knows about my project it knows from my files.

So a server is the right answer to “Claude cannot open a browser” and the wrong answer to “Claude keeps forgetting our conventions”. The second problem is a file that gets read, or an event that fires whether the model agrees or not. It is never a new tool.

Scope is the decision people skip

Three scopes, and the difference between them is who else gets the server.

Local is the default. The server goes into ~/.claude.json under the entry for the current project’s path, so it loads in that project and nowhere else, and stays private to you. Project scope writes .mcp.json at the repository root, which is the only scope that travels with a clone. User scope also lives in ~/.claude.json, at the top level, and loads in every project on your machine.

When the same server name is defined in more than one place, precedence runs local, then project, then user, then plugin-provided servers, then claude.ai connectors. The whole entry from the winning source is used. Fields are not merged across scopes, which is worth knowing before you try to override one URL from a shared config and quietly lose the rest of the entry.

Commit the project file. This repo’s is three servers and no secrets:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "aws-knowledge": {
      "type": "http",
      "url": "https://knowledge-mcp.global.api.aws"
    },
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

That file is the difference between “here is how I verify a rendering change” and “here is how I verify a rendering change, and it works on your machine too”. A local-scoped server is a thing you have to describe to a teammate in Slack.

The safety catch is that a repository cannot approve its own servers. Claude Code prompts before it will use anything from .mcp.json, because otherwise cloning a repo would be enough to run a command from it. Approve one and the choice lands in your untracked .claude/settings.local.json under enabledMcpjsonServers, which is where mine still is, three names and nothing else in the file. claude mcp reset-project-choices throws those choices away.

The same key can go in the tracked file, which is what this repo does:

{
  "enabledMcpjsonServers": ["playwright", "aws-knowledge", "context7"]
}

That copy lives in .claude/settings.json, committed, and it still doesn’t skip the gate. A committed approval is ignored in a folder nobody has trusted yet, so a fresh clone shows the servers as pending until someone runs claude there and accepts the workspace trust dialog. After that, the approval is already made and no one has to think about it again. That is the right shape: one human decision per checkout, not one per server per person.

Allowing a whole server is a decision, not a shortcut

MCP tools are namespaced mcp__<server>__<tool>, so Playwright’s navigate tool is mcp__playwright__browser_navigate. Permission rules use the same names, and how much of the name you write is the whole question.

A bare mcp__playwright matches every tool the server provides. So does mcp__playwright__*. A full name matches exactly one tool. Wildcards in an allow rule only work after a literal mcp__<server>__ prefix, so the server segment has to be spelled out; an unanchored allow glob like "*" or "mcp__*" is skipped with a warning and approves nothing. Deny and ask rules are looser and take a bare mcp__*, and a deny that matches by glob removes those tools from Claude’s context entirely rather than just refusing the call. MCP rules also take no parentheses, so you cannot match on an argument. Write one anyway and it is dropped at load time and reported in the invalid-settings dialog and in claude doctor output, which is the kind of failure you can stare past for a week.

So the shape of a rule I would write for a browser:

{
  "permissions": {
    "allow": [
      "mcp__playwright__browser_navigate",
      "mcp__playwright__browser_take_screenshot",
      "mcp__playwright__browser_snapshot"
    ]
  }
}

Three tools, named, all of them read-shaped. Navigating and screenshotting a localhost build is not a decision I want to re-approve forty times an hour. The version that saves more typing is "mcp__playwright" on its own, and that one also hands over browser_run_code_unsafe, which does exactly what the name promises.

The reason to bother is that the allow-list is where blast radius is actually set. Take the GitHub server, which authenticates with a fine-grained personal access token you generate yourself. Put mcp__github in allow and you have said yes, in advance, to every tool it exposes, including the ones that open pull requests and file issues. Claude will use them correctly almost every time. The failure case is not a model that turns on you, it’s a model that misreads a sentence and opens a PR against the wrong repository at two in the afternoon, and the token you minted decided how far that goes.

Scope the token to the repositories you meant. Name the tools you meant. “Proceed with caution” is not a setting.

One asymmetry to know: allow rules in the shared project settings file wait for workspace trust before they apply, while deny and ask rules apply immediately. Restrictions you commit take effect on a fresh clone. Permissions you commit do not, until someone says yes.

What a connected server costs

It used to be that every tool definition from every server sat in the window before you typed anything, and a chatty server with forty tools was a tax you paid on the first message of every session. That is now the opt-out rather than the default. Tool search is on by default: only tool names and each server’s instructions load at session start, and the full definitions are fetched when Claude decides it needs them. Descriptions and server instructions are truncated at 2KB each, so a server author who buries the important sentence at the bottom loses it.

You can change the trade. ENABLE_TOOL_SEARCH=false puts everything back upfront. auto loads definitions upfront while they stay under 10% of the context window and defers them all past that line, and auto:5 moves the line to 5%. A single server can opt out with "alwaysLoad": true in its config entry, which also makes startup wait for that server’s tool list, capped at the five second connect timeout. Worth it for two tools Claude needs on every turn. Not worth it for a server you touch twice a week.

The cost that still bites is output, not definitions. Claude Code warns when a single MCP tool result exceeds 10,000 tokens and truncates at 25,000 by default, with MAX_MCP_OUTPUT_TOKENS to raise the ceiling. One call to a documentation server that returns a whole page is a larger context event than the entire tool list it came from. Everything in part one about context being a budget applies here, except the spending decision is being made by a process you did not write.

The one that earned its place

Playwright is the server on this project I would fight to keep, and it is the clearest case of a capability I cannot fake with a shell.

The site is visual. Claude cannot see it. Left alone, it writes a component, reads the file back, and tells me the layout is correct, which is an assertion about source code dressed up as an observation about a page. With the browser attached, the loop closes: build, serve the output, navigate, take a screenshot, look at what actually rendered, then change the code. The repo’s own CLAUDE.md puts it more bluntly than I would, that screenshots are the only way to verify rendering rather than assume it.

It comes with a real constraint. The Playwright server cannot open file:// URLs, so the freshly built dist/ directory sitting on disk is unreachable. Something has to serve it first:

npm run build && npx astro check
npx serve dist

Then navigate to localhost and start looking. The checklist that follows is boring on purpose: screenshot the affected routes, toggle the theme and screenshot again because this site ships dark and light and a token fix in one can break contrast in the other, then re-run with reduced motion emulated and confirm the animation genuinely stopped rather than got faster.

None of that is knowledge Claude gained. It is a feedback signal it could not previously obtain, which is a different thing, and it changes what the model is able to be wrong about. Before, it could be wrong about the rendered page and never find out. Now it finds out in the same turn.

That is the test I run before adding anything now. Finish the sentence “Claude cannot do this with a shell and a filesystem.” If the sentence won’t finish, what I wanted was for the model to remember something, and remembering is a file or an event, not a tool. The hex literals were the second one. No server was ever going to catch them, because catching them means running a grep on a file the instant it is written, which is a hook, and a hook does not need the model’s cooperation.

Custom commands for work that repeats

Thu, 27 Aug 2026 00:00:00 GMT

I typed the same paragraph into three sessions in one afternoon. It said that every colour on this site comes from a token in tokens.css, that a hex literal anywhere else fails npm run no-hex, and that dark is the default theme when localStorage is empty. By the third time I had shortened it. The short version dropped the dark-default sentence, and the component I got back looked right in light and wrong in dark.

That is not a prompting problem. It is a version control problem. I had three copies of one instruction, all slightly different, none of them authoritative, and no way to tell which was current except by reading my own scrollback.

The fix is not clever. Put the paragraph in a file.

The file is the command

A markdown file in .claude/commands/ becomes a slash command named after the file. .claude/commands/audit.md gives you /audit. Commit it and everyone who clones the repo has /audit too. The same file in ~/.claude/commands/ gives you /audit in every project on your machine instead. There is no registry to update, nothing to declare, and no build step.

Anthropic has since folded custom commands into skills, and the two are now the same mechanism. A file at .claude/commands/deploy.md and a directory at .claude/skills/deploy/SKILL.md both produce /deploy and behave identically. Existing command files keep working. What the skill form buys you is a directory, so a reference doc or a helper script can sit next to the prompt instead of being inlined into it. For anything longer than a screen, take the directory.

Precedence, when the same name exists twice: enterprise beats personal, personal beats project, and a skill beats a command file. Plugin skills carry a plugin-name:skill-name namespace and cannot collide with anything you wrote. In a monorepo, a .claude/skills/ directory below your working directory loads the first time Claude reads or edits a file inside it, and if its name clashes with one at the root it appears under a directory-qualified name like apps/web:deploy while plain /deploy still runs the root one.

On restarting: Claude Code watches skill directories. Add or edit a SKILL.md under ~/.claude/skills/ or the project’s .claude/skills/ and the change lands in the session you are already sitting in. Two cases still need a restart. One is a top-level skills directory that did not exist when the session started, because there was nothing to watch. The other is a command or subagent file inside a directory you passed with --add-dir, which Claude Code never watches at all.

Arguments, and the ways to spell them

$ARGUMENTS is everything you typed after the command name, as one string. It is the right choice when the argument is a description rather than a value, which is most of the time.

For values, you can index. $ARGUMENTS[0] is the first argument and $0 is shorthand for the same thing. Zero-based, which will catch you exactly once. Indexed arguments use shell-style quoting, so /component ThemeToggle "swaps the theme and remembers it" puts the whole quoted phrase in $1. If you would rather not count, declare names in the frontmatter with arguments: [component, brief] and write $component and $brief in the body.

The two behave differently when an argument is missing. A named placeholder expands to an empty string. An indexed one stays in the text as the literal characters $2, which then reaches the model as part of your instructions. And if you pass arguments to a command whose body has no placeholder at all, Claude Code appends ARGUMENTS: <what you typed> to the end rather than dropping them, so a command you forgot to parameterise is untidy rather than broken.

Here is the paragraph I kept retyping, as a file:

---
description: Build a new Astro component to this site's conventions
argument-hint: [component-name] [what it should do]
---

Build a component called `$0`.

What it needs to do: $1

Conventions that are not negotiable:

- Every colour, space and font size comes from a token in
  `src/styles/tokens.css`. A hex literal in an `.astro` or `.css`
  file fails `npm run no-hex`.
- Dark is the default theme when `localStorage` is empty. Render
  and check both themes before calling it done.
- Islands cost page weight. `node scripts/budgets.mjs --check`
  exits 1 when a route goes over its budget.

When the dark-default rule changes, it changes in one place, and the change shows up in a diff that someone can argue with.

Frontmatter turns a prompt into a contract

Command files take the same frontmatter as skills, with two exceptions: name and paths are ignored in a command file. The fields that earn their line:

description says what the command does and when it applies. It is also what Claude reads when deciding whether to reach for the command without being asked, so vague descriptions cause both mis-triggering and silence.
argument-hint shows in autocomplete. [component-name] [what it should do] is worth ten seconds of typing because it is the only documentation anyone will read.
allowed-tools lists tools Claude may use without a permission prompt during the turn that invoked the command. The grant clears when you send your next message, so it is per-turn, not per-session.
disallowed-tools removes tools from the pool while the command is active, on the same per-turn basis.
model and effort pin the model or the effort level for the command. A mechanical formatting command does not need your expensive model.
disable-model-invocation: true means only you can invoke it. I set this on anything with side effects. You do not want Claude deciding your code looks ready to deploy.

One thing worth knowing about allowed-tools before you clone somebody’s repo and start a session in it: workspace trust does not gate that field. A project command can grant itself broad tool access, and Claude Code honours it whenever the command is invoked. Read the frontmatter of commands that arrive with a checkout.

Keep the body short for a reason that has nothing to do with taste. Once a command is invoked, its rendered content enters the conversation as a message and stays there for the rest of the session. Claude Code does not re-read the file on later turns. Every line you wrote is a recurring cost against the same window your actual work is competing for, so write standing instructions rather than a tutorial, and move the long reference material into a skill directory where it can sit unread until something needs it.

The backtick that runs before Claude reads anything

This is the feature that turns a saved prompt into something closer to a script. A !`command` in the body runs before the file is sent to the model, and the output replaces the placeholder. Claude receives data, not an instruction to go and fetch data. For several commands in a row, open a fenced block whose info string is a single ! and put one command per line inside it.

The ! is only recognised at the start of a line or immediately after whitespace. Put it after another character, as in KEY=!`cmd` , and the placeholder stays as literal text and the command never runs.

Now the part that cost me an afternoon. A non-zero exit code aborts the entire invocation, not just that placeholder. Claude never sees any of the file, and you get Shell command failed for pattern "..." instead of an answer. My no-hex script exits 1 precisely when it has found something worth telling me about, which is the exact case I wanted the command for. Append || true to anything that exits non-zero by design.

Injected commands also never prompt for permission. If the permission check returns anything other than allow, including a rule that would normally ask you, the invocation aborts. Pre-approve with allowed-tools.

---
description: Find and fix vulnerable dependencies, then prove
  nothing broke
allowed-tools: Bash(npm audit *) Bash(npm run *) Bash(npx astro *)
disable-model-invocation: true
---

## Current state

Advisories: !`npm --prefix site audit || true`
Outdated: !`npm --prefix site outdated || true`

## What to do

1. Apply what `npm audit fix` resolves on its own. Do not pass
   `--force`. A major version bump is a decision, not a fix.
2. For anything left, read the advisory and say whether it reaches
   shipped code. A prototype-pollution finding in a build-only
   dependency of a static site is not the same risk as one in
   something that goes to the browser.
3. Run `npm run build`, `npx astro check`, and
   `node scripts/budgets.mjs --check`. All three, in that order.
4. Report every advisory you did not fix, with the reason.

Both npm audit and npm outdated exit non-zero when they find something, so both need the || true. That is not a quirk of those two commands. It is true of most check tools, because exiting non-zero on a finding is what makes them usable in CI, and it means the tools most worth injecting are the ones most likely to abort the command that injects them.

You can also name files with an @ reference in the body and Claude Code attaches them, the same way @ works when you type it into the prompt. Putting @site/src/styles/tokens.css at the top of the component command saves a lookup Claude would otherwise do on its own.

A command is invoked, a skill is reached for

That is the whole distinction, and since the two are now one file format, it comes down to a frontmatter field. disable-model-invocation: true makes something invocation-only: it stays out of Claude’s context until you type the slash. user-invocable: false makes it reach-for-only, for background knowledge that is not a meaningful action to take. Leave both off and you get both behaviours. Part 6 covers what that second mode is actually for.

The line that matters more day to day is the one between a command file and CLAUDE.md. CLAUDE.md loads at the start of every session, relevant or not, and that is the entire cost model. It should hold facts that apply broadly: the build commands, the conventions that differ from the language defaults, the gotchas nobody could infer from reading the code. A procedure that only matters when you are doing one particular thing has no business being in context while you debug something else.

My test is a grammar test. If it reads as an instruction, it goes in CLAUDE.md. If it reads as a procedure with steps, it goes in a file with a slash in front of it.

The paragraph I kept retyping is now eleven lines in a file that anyone on the project can open, and the last time it was wrong, it was wrong in exactly one place.

Context is the budget

Wed, 26 Aug 2026 00:00:00 GMT

This site was built by nine agents working in parallel on disjoint sets of files. The rule that makes that safe is written down in the repo: an agent that needs something outside its owned paths reports it instead of creating it. One evening I finished the layout slice and, instead of starting a fresh session, pasted the next brief into the same one.

Twenty minutes later the content agent had imported a component from the layout group and written into a directory it did not own.

Nothing about that was a reasoning failure. It had read the ownership rules. It had also sat through two hours of me approving edits across the whole src/ tree, and as far as the transcript was concerned that was the established shape of the work. The rule was one line in a file loaded at startup. The counter-evidence was a hundred tool calls deep and much fresher.

I have come to think that is what almost every bad session actually is. Not the model being stupid, the window being wrong. And a bigger window does not rescue you: a million tokens of capacity just means you can accumulate more irrelevant material before you notice the answers getting vaguer. The skill worth building is not prompting. It is deciding what Claude is allowed to see.

The spend before you type

/context prints the window as a grid with a breakdown by category. Here is a reading from one of my sessions, a few dozen messages in, on a model configured with a one-million-token window:

  one session, one million tokens available
  ┌───────────────────────────────────────────────────────┐
  │ system prompt         8.9k  ┐                         │
  │ tool definitions       11k  │  fixed overhead, ~23k,  │
  │ skill descriptions    2.1k  │  spent before I typed   │
  │ agent definitions      778  ┘                         │
  ├───────────────────────────────────────────────────────┤
  │ conversation         21.4k     everything I actually  │
  │                                said and did           │
  ├───────────────────────────────────────────────────────┤
  │ autocompact buffer     33k     reserved, not mine     │
  └───────────────────────────────────────────────────────┘
             43k of 1M used

Your numbers will be different. The shape is the part that generalises: when I ran this, the setup cost more than the conversation did. Twenty-three thousand tokens of system prompt, tool schemas, skill descriptions and agent definitions were in the window before I said a word, and none of it was about my project.

Two entries in that list are worth understanding rather than skimming. The autocompact buffer is reserved space, not free space. Claude Code compacts automatically as you approach the limit, and it needs room to do the summarising, so the working ceiling is lower than the headline number.

The skill descriptions line is one sentence per skill, not the skills themselves. Bodies load only when a skill is used, which is a deliberate design and the subject of part six. But the descriptions are unconditional. Install thirty plugins and you are paying rent on all thirty in every session, including the ones about Postman collections while you are debugging a CSS grid.

Where the instructions live

Persistent instructions come from a hierarchy of CLAUDE.md files, loaded from the broadest scope down to the most specific and concatenated rather than overridden. All of it lands in context together.

  loaded at launch, machine-wide first, working dir last
  ┌───────────────────────────────────────────────────────┐
  │ managed policy   /Library/Application Support/        │
  │                  ClaudeCode/CLAUDE.md                 │
  ├───────────────────────────────────────────────────────┤
  │ user             ~/.claude/CLAUDE.md                  │
  │                  ~/.claude/rules/*.md                 │
  ├───────────────────────────────────────────────────────┤
  │ project          ./CLAUDE.md or ./.claude/CLAUDE.md   │
  │                  .claude/rules/*.md                   │
  ├───────────────────────────────────────────────────────┤
  │ local            ./CLAUDE.local.md   (gitignored)     │
  └───────────────────────────────────────────────────────┘

  loaded later, only when Claude reads a file they match
  ┌───────────────────────────────────────────────────────┐
  │ nested           src/api/CLAUDE.md                    │
  │ path-scoped      .claude/rules/*.md with paths:       │
  └───────────────────────────────────────────────────────┘

Every directory above your working directory contributes, so launching in foo/bar/ picks up foo/CLAUDE.md too. In a monorepo that is how you end up reading another team’s conventions all day, and claudeMdExcludes in your local settings is the fix.

The split between the two boxes is the useful part. Everything in the first is always present. Everything in the second is conditional, which makes it nearly free until it is relevant. So the question for each rule you write is not “is this true?” but “is this true often enough to pay for on every single turn?”

/init writes the first version of the project file for you by exploring the codebase and summarising what it finds. Treat that output as a draft. What it produces well is the derivable stuff, directory layouts and build commands, and that is exactly the material worth deleting later: Claude can rediscover a folder structure in one tool call, and paying for it on every turn is a bad trade. What earns permanent residence is the opposite, the things no amount of reading the code will reveal. Which decisions are already settled. Which mistake this codebase invites.

Keep each file under about 200 lines. That is a real threshold rather than a stylistic one, because a longer file measurably reduces adherence: your rule ends up competing with everything else in the window for attention. This repo’s CLAUDE.md opens by declaring a budget for itself and pointing at AGENTS.md for everything about the project. That structure is not tidiness. CLAUDE.md holds the handful of facts needed on every turn, and the rest is a document Claude reads when the task calls for it.

That distinction is worth being precise about, because @ means two different things. Inside a memory file, @AGENTS.md is an import: the file is expanded and loaded at launch, so splitting content across imports organises your instructions without saving a single token. A plain markdown link is not an import. It costs one tool call at the moment the information is needed, and nothing at all the rest of the time. I use links.

The part of the budget you did not write

There is a second memory system alongside CLAUDE.md, and it is on by default. As you work, Claude saves notes to itself: your role and working preferences, corrections you gave it, project decisions it cannot derive from the code, and pointers to things outside the repo. They live per repository under ~/.claude/projects/<project>/memory/, with a MEMORY.md index whose first 200 lines load at the start of every session and topic files that are read on demand.

I like it more than I expected to. It absorbs the corrections you would otherwise type twice, and unlike CLAUDE.md it costs you nothing to maintain. But it is worth being clear-eyed about what it is: instructions in your startup budget that you did not author and have not read. Run /memory occasionally and look. Mine holds a note that this project’s commits must never list Claude as an author, which is correct and which I am glad I do not have to repeat, and it got there because I said it once in a session I no longer remember.

One detail matters if you work the way this repo does. Auto memory is keyed to the git repository, so every worktree of the same repo shares one directory. Ten worktrees off one repository, all reading and writing the same notes.

Naming the file instead of hunting for it

In a prompt, @ is a file path mention with autocomplete behind it, and its value is almost entirely about what it prevents.

Ask “where do we validate the JWT?” and Claude does what you would do: globs for likely filenames, greps for the term, opens four files, discards three. Every one of those reads lands in your window permanently and the three wrong ones stay there, being wrong, for the rest of the session. File reads dominate context usage in practice, and the reads that cost the most are the speculative ones.

Say @src/lib/auth.ts and the search phase does not happen. One read, one file, and the window contains exactly the file you meant.

This is the same instinct as delegating exploration to a subagent, which is the right move when you genuinely do not know where something lives, and which part five is about. When you do know, just say so. Being specific in a prompt is a token optimisation dressed as politeness.

Compact keeps what it learned, clear throws it away

Two commands free space and they are not interchangeable.

/compact replaces the conversation with a structured summary and keeps going. Startup content comes back from disk: project-root CLAUDE.md, auto memory, the plan from plan mode, and up to five of the most recently modified files Claude touched. What gets summarised away is the conversation itself, which is where every correction you typed lives. This is the single best argument for writing rules down: an instruction you gave in chat may not survive compaction, and one in CLAUDE.md is re-injected every time.

You can steer it. /compact focus on the auth bug fix keeps what you choose instead of what the automatic pass guesses, and a “Compact Instructions” section in CLAUDE.md sets that preference permanently.

/clear starts a new conversation with an empty context. Everything learned is gone.

The rule I use: same problem, compact; different problem, clear. And the second half of that matters more than people expect, because carrying context across unrelated tasks is not merely wasteful, it is actively misleading. Old conversation crowds out the files you need next, and it costs tokens on every subsequent message. Worse, it is evidence. The model is reasoning about what you appear to be doing, and two hours of layout work is a strong argument that you are still doing layout work. That is precisely how my content agent talked itself into editing another group’s files.

Mid-turn there are two smaller levers. Esc interrupts immediately and keeps the work done so far, which is how you stop a plan that has expanded past what you asked for without discarding the useful half. Press Esc twice on an empty prompt and you get the rewind menu, which restores files and conversation to an earlier point, and can also summarise from or up to a chosen message when only part of the session is worth keeping.

Buying reasoning on purpose

Plan mode is the one place I spend context deliberately. Shift+Tab cycles the permission modes and plan is one of them, or prefix a single prompt with /plan. Claude reads, explores, and writes a proposal without touching your source. You approve it or send it back.

The trade is real. Planning costs a research pass you then pay for again during implementation, and for a two-line fix that is silly. For anything touching more than about three files it has been consistently worth it, because the failure it prevents is the expensive one: forty minutes of confident edits in the wrong direction, which you now have to read, understand, and unpick.

Reasoning effort is the other dial, set with /effort and running low, medium, high, xhigh, max on current models, with high as the usual default. These are token spend, straightforwardly. xhigh and max buy deeper reasoning by generating a great deal more of it, and max is prone to overthinking a task that did not need it. If you want one turn to think harder without changing the session, put ultrathink in the prompt.

None of these levers help if the window is already full of yesterday’s problem. Clear first, then spend.

Designing a Read-Heavy Service That Survives Its Own Success

Wed, 26 Aug 2026 00:00:00 GMT

Most services that fall over in production do not fall over because a write path got slow. They fall over because a read path that was cheap at a thousand requests per minute stayed structurally identical at a hundred thousand, and nobody re-derived the assumptions underneath it.

This is a long fixture post. It exists so the article template has something with real structural depth to render: nested headings, code, a wide table, a blockquote, and enough sections that the table of contents crosses the point where part numbering needs zero-padding. If you are reading it as content rather than as a test, the engineering in it is still meant to be correct.

The shape of the problem

A read-heavy service is one where the ratio of reads to writes is high enough that read cost dominates every capacity decision you make. Catalogue services, profile lookups, feed rendering, pricing, and permission checks all land here. The characteristic failure is not a slow query. It is a query that was always slow and only became visible once concurrency rose far enough that the queueing delay in front of it exceeded the service time inside it.

That distinction matters because the two problems have different fixes. A slow query wants an index. A queueing problem wants fewer arrivals, more servers, or shorter service time, and adding an index only helps through the third.

Establish the read and write ratio first

Before choosing any mechanism, write down the actual ratio. Not the ratio you assume from the domain, the ratio your logs report. Teams routinely guess 100:1 for a workload that measures 6:1, then spend a quarter building cache infrastructure that saves very little.

Measuring it without a metrics stack

If you have no instrumentation yet, the database will usually tell you. On PostgreSQL:

SELECT
  schemaname,
  relname,
  seq_scan + idx_scan            AS reads,
  n_tup_ins + n_tup_upd + n_tup_del AS writes
FROM pg_stat_user_tables
ORDER BY reads DESC
LIMIT 20;

Those counters are cumulative since the last stats reset, so take two samples an hour apart and diff them. A single reading tells you about the lifetime of the process, which is rarely the period you care about.

What a low ratio implies

If reads and writes are within an order of magnitude of each other, caching buys less than it costs. The invalidation logic, the extra failure mode, and the operational surface of another stateful system are all real, and they are worth paying for at 100:1 and usually not at 5:1.

The latency budget

Give the endpoint a number before you design it. Something like: 95th percentile under 120 milliseconds at the edge, of which 30 milliseconds is network and TLS, leaving 90 milliseconds of server time.

Then decompose the 90 into the calls the handler actually makes. A handler that makes four sequential dependency calls has roughly 22 milliseconds each, and any dependency whose own p95 exceeds that is a design problem you now know about in advance rather than after launch.

A latency budget is useful mainly because it converts an argument about taste into an argument about arithmetic. “This feels slow” is hard to resolve. “This call has 22 milliseconds and takes 60” is not.

Caching is a consistency decision

The reason cache design is hard is that it is not really a performance decision. Choosing a cache is choosing how stale a reader is allowed to be, and that is a product question wearing infrastructure clothes.

Cache-aside

The application checks the cache, misses, reads the database, and populates the cache itself. Simple, and the default for good reason. The cost is that every caller must implement the pattern correctly, and one caller that forgets to populate turns into a permanent miss for that key shape.

Read-through

The cache sits in the read path and fetches on miss. Callers see one interface. This removes the class of bug above and moves it into whatever component implements the fetch, which is usually a smaller and better tested surface.

Write-through and write-behind

Write-through updates cache and database together, so readers never see a stale entry the writer just replaced. Write-behind acknowledges the write after the cache update and persists asynchronously, which is faster and introduces a window where an acknowledged write is not yet durable. Use write-behind only where losing that window is genuinely acceptable.

Choosing a cache key

Cache keys are a schema. Treat them like one.

Include a version prefix, so a shape change is a deploy rather than a flush: v3:user:1234:profile.
Include every input that affects the value. Locale, currency, and permission scope are the three most commonly forgotten.
Do not include anything that varies per request but not per value, such as a trace identifier. That is how you get a cache with a zero percent hit rate and a very confident owner.

A key that omits an input does not produce a cache miss. It produces a correct-looking response containing another user’s data, which is why this list is short and worth re-reading.

Stampedes and how they actually happen

The textbook stampede is a popular key expiring and a thousand concurrent requests all missing at once, all querying the database, all writing the same value back. The database sees a thousand identical queries where it expected one.

The version that actually bites is subtler. Keys written at the same time expire at the same time. A deploy that warms a cache, a cron job that populates a batch, or a Redis restart all create cohorts of keys with synchronised expiry, and the stampede arrives on a schedule.

Two mitigations, applied together:

// 1. Jitter the TTL so cohorts decorrelate.
ttl := base + time.Duration(rand.Int63n(int64(base/4)))

// 2. Collapse concurrent misses onto one fetch.
var group singleflight.Group

func (c *Cache) Get(ctx context.Context, key string) ([]byte, error) {
	if v, ok := c.redis.Get(ctx, key); ok {
		return v, nil
	}
	v, err, _ := group.Do(key, func() (any, error) {
		val, err := c.origin.Fetch(ctx, key)
		if err != nil {
			return nil, err
		}
		c.redis.Set(ctx, key, val, jitter(c.ttl))
		return val, nil
	})
	if err != nil {
		return nil, err
	}
	return v.([]byte), nil
}

singleflight deduplicates within one process. Across a fleet of fifty processes you still get fifty origin fetches instead of fifty thousand, which is usually sufficient. If it is not, a short distributed lock on the key is the next step, with a timeout so a crashed holder cannot wedge the key permanently.

Read replicas and the replication lag tax

Replicas move read load off the primary and hand you a new correctness problem in exchange. A user who writes and then immediately reads may hit a replica that has not applied the write yet, and the interface appears to have lost their change.

The usual fixes, in increasing order of cost:

Route reads that follow a write from the same session to the primary for a short window. Cheap, covers the common case, needs session affinity.
Track the write position and require the replica to have applied at least that position, falling back to the primary if it has not. On PostgreSQL this is pg_current_wal_lsn() compared against pg_last_wal_replay_lsn().
Read from the primary for anything the user can observe as their own action, and use replicas only for aggregate or third-party views.

Whichever you choose, alert on replication lag as a first-class signal. Silent lag growth turns a correctness guarantee into a coin flip without producing a single error.

Denormalisation and the write amplification it buys

Precomputing a read shape at write time converts an expensive join into a single key lookup. The cost is write amplification: one logical write becomes several physical writes, and every additional copy is a place the data can diverge.

Denormalise when the read is hot, the write is rare, and the divergence is detectable. A materialised view with a scheduled refresh and a consistency check that runs nightly is a reasonable middle position, because it fails loudly rather than quietly.

Pagination that survives deep offsets

LIMIT 20 OFFSET 100000 asks the database to produce a hundred thousand and twenty rows and discard all but twenty. It gets slower linearly with depth, and it produces duplicate or missing rows when the underlying data changes between page requests.

Keyset pagination fixes both:

SELECT id, title, published_at
FROM articles
WHERE (published_at, id) < ($1, $2)
ORDER BY published_at DESC, id DESC
LIMIT 20;

The tuple comparison requires a matching composite index on (published_at DESC, id DESC). The tradeoff is that you lose the ability to jump to an arbitrary page number, which almost no user does and almost every specification asks for.

Backpressure at the edge

When a dependency degrades, a service without backpressure converts a slow dependency into an outage. Requests queue, memory grows, garbage collection pauses lengthen, and the service fails at something unrelated to the original problem.

Bound the queue. Set a concurrency limit per dependency, reject over the limit with a 503 and a Retry-After, and set client timeouts shorter than the upstream’s own timeout so retries do not stack. A load shedder that returns errors quickly is a better neighbour than one that accepts everything and answers nothing.

Send less over the wire

Serialisation and transfer are part of the latency budget and are usually the part nobody has looked at. A handler that assembles its response in 8 milliseconds and then serialises 400 kilobytes of JSON has not been optimised, it has been measured in the wrong place.

Trim the response shape

Return the fields the caller uses. A sparse fieldset parameter, or separate summary and detail representations, removes more bytes than any compression setting. This is also the change that most often reveals a client quietly depending on a field nobody documented, so ship it behind a flag.

Compression is not free either

Gzip at level 9 on a large payload can cost more CPU than the transfer time it saves on a fast connection. Level 4 to 6 is the usual sweet spot, and Brotli at level 4 beats gzip at level 6 on both size and speed for text. Measure on your own payloads rather than trusting a benchmark run on someone else’s.

Idempotency makes retries safe

Once clients retry, every non-idempotent write becomes a duplicate risk. Accept an Idempotency-Key header on writes, store the key with the response for a bounded window, and replay the stored response on a repeat. Retries then stop being a correctness hazard and become the ordinary traffic they should have been.

What to measure

Signal	Where it lives	Healthy	Investigate	Page
Cache hit rate	Redis / app metrics	> 92%	80 to 92%	< 80% sustained 10 min
Origin fetch rate	App metrics	Flat	Rising with traffic	Step change after deploy
Replication lag	Database	< 500 ms	0.5 to 5 s	> 5 s for 2 min
Endpoint p95	Edge / RUM	< 120 ms	120 to 300 ms	> 300 ms for 5 min
Endpoint p99	Edge / RUM	< 400 ms	400 ms to 1 s	> 1 s for 5 min
Connection pool saturation	App metrics	< 60%	60 to 85%	> 85% for 2 min
Shed request rate	Load shedder	0	Any sustained	> 1% of traffic

The table is deliberately wider than the prose column. On a narrow viewport it should scroll inside its own container rather than forcing the page body to scroll sideways, which is one of the things this fixture is here to check.

Failure modes worth rehearsing

Design reviews catch design problems. Operational problems need rehearsal.

Cache cold start

Restart the cache in a staging environment under production-shaped load and watch what the origin does. If the database saturates, your warmup path is the real capacity limit and the steady-state numbers are fiction.

Replica promotion

Promote a replica during business hours in staging. Measure how long connection pools take to notice, how many requests fail during the switch, and whether any code path silently kept a stale connection.

Dependency brownout

Inject 2 seconds of latency into a downstream call rather than failing it outright. Slow dependencies are harder to survive than dead ones, because nothing trips a circuit breaker configured only for errors.

When to stop optimising

Stop when the next change costs more in complexity than it returns in capacity or latency, measured against the budget you wrote down at the start. A service that meets its p95 target with a 92% cache hit rate and one replica does not need a second cache tier. It needs to be left alone so the team can work on something else.

Further reading worth the time: Marc Brooker on timeouts and retries, and the AWS Builders’ Library entry on caching challenges and strategies. Both are more careful about failure modes than most conference talks on the same subject.

RAII and deterministic destruction versus a garbage collector

Tue, 25 Aug 2026 00:00:00 GMT

C++ has no finally. It has no defer, no with, no using, no try-with-resources. Every other language I work in has grown some version of that construct, and the one with manual memory management never needed it.

The reason is a single guarantee about destructors.

The guarantee

A destructor is the method named after the class with a tilde in front. One per class, no arguments, no return type, and you never call it:

class Player {
private:
    std::string name;
public:
    Player(std::string n);
    ~Player();
};

It runs automatically when the object is destroyed. For an object with a name, declared inside a block, that moment is when control leaves the block. Not eventually. Not at the next collection. At the closing brace.

{
    Player slayer;
    Player josh {"Josh", 100, 4};
    Player hero {"Hero"};
    // ... use them
}   // three destructors have now run

Three objects on the stack, three destructors, all before the next line executes. The compiler emits those calls. You cannot forget them, and there is no path out of that block that skips them.

That last part is the interesting one.

It holds on the paths you did not write

Early return, break, an exception thrown four frames down: all of them leave the block, so all of them run the destructors. An exception propagating through unwinds each scope on the way out and destroys every local object it passes.

Which means this is complete:

void process() {
    std::ofstream log {"run.log"};   // opened here
    risky();                         // may throw
}                                    // closed here, thrown or not

There is no second code path to write. Compare the shape you would write in a language without the guarantee:

FileWriter log = null;
try {
    log = new FileWriter("run.log");
    risky();
} finally {
    if (log != null) log.close();
}

The C++ version is not shorter because C++ is terser. It is shorter because the cleanup moved into the type. Anyone who uses ofstream gets the correct behaviour without knowing it needed handling, and cannot get it wrong by writing the call site badly. That is the pattern people mean by RAII: acquire the resource in the constructor, release it in the destructor, and let scope do the rest.

The name is about memory but the idea is not. File handles, sockets, mutex locks, database transactions, anything with a matching pair of operations.

Construction and destruction are mirror images

The order is fixed and worth knowing, because it is what makes composed objects safe.

Within a scope, objects are destroyed in reverse order of construction. Under inheritance, the base is constructed first and destroyed last:

  Derived d;

  construction              destruction
  ───────────────▶          ◀───────────────
  Base()                    ~Derived()
  Derived()                 ~Base()

The base part has to exist before the derived constructor runs, because the derived class may use it. On the way out, the derived part has to be dismantled before the base it was built on disappears. Reverse order is not a convention, it is the only order that is safe.

The same logic covers members. A class holding a connection and a buffer built from it destroys them in an order where the dependency still exists while it is needed.

What you give up

This guarantee only applies to objects the compiler knows the lifetime of, which means objects with a name and a scope. Reach for new and you leave that world:

Player *enemy = new Player {"Enemy", 1000, 0};
delete enemy;    // destructor runs here, because you said so

Now the destructor runs when you call delete, and the compiler will not remind you. Forget it and the destructor never runs at all. Between the new and the delete, any early return leaks.

That is the trade the whole language argument is about. The compiler gives you exact, predictable cleanup, and charges you for being wrong about ownership.

Modern C++ mostly buys its way out with unique_ptr and shared_ptr, which are objects with destructors that own a heap allocation. The scope guarantee comes back, applied to something on the heap. RAII solving the problem RAII created.

Against a garbage collector

Go and Java give you the opposite trade. Memory is never your problem, and in exchange you lose the timing.

A garbage collector answers “is anything still referencing this?” and it answers it whenever it feels like it. That is exactly right for memory, where the only question is whether the bytes can be reused. It is wrong for a file handle, a socket, or a lock, because those have a limit that is nothing to do with memory pressure. You can exhaust a connection pool while the heap is nearly empty, and the collector has no reason to act.

So the construct comes back, out in the open:

f, err := os.Open("run.log")
if err != nil { return err }
defer f.Close()

defer is the same guarantee, scoped to the function rather than the block, and opted into per call site. It is a good design. It is also visible in a way RAII is not: every caller has to remember it, and forgetting is silent.

Java’s finalizers tried to be destructors and are deprecated for the reason above. They run at collection time, which is to say at no time you can plan around.

Neither model is the better one. Deterministic destruction costs you the ownership question on every allocation. Garbage collection costs you the timing on every non-memory resource. Knowing which cost you are paying is what tells you where the bug is going to be, and after six years the resource leaks I have chased were never in the C++.

Go Worker Pools: Bounded Concurrency Without Leaking Goroutines

Mon, 24 Aug 2026 00:00:00 GMT

This post exists in a different category to the AWS material, which makes it the fixture that proves /blog/category/go/ renders independently of /blog/category/aws-cloud/.

Why bound anything

An unbounded go func() per item is fine until the input is a million rows. Then you discover that goroutines are cheap but the file descriptors, database connections, and downstream rate limits they contend for are not.

The shape

func Process(ctx context.Context, items []Item, workers int) error {
	g, ctx := errgroup.WithContext(ctx)
	in := make(chan Item)

	g.Go(func() error {
		defer close(in)
		for _, it := range items {
			select {
			case in <- it:
			case <-ctx.Done():
				return ctx.Err()
			}
		}
		return nil
	})

	for i := 0; i < workers; i++ {
		g.Go(func() error {
			for it := range in {
				if err := handle(ctx, it); err != nil {
					return err
				}
			}
			return nil
		})
	}

	return g.Wait()
}

The part people get wrong

The producer must select on ctx.Done(). Without it, a worker returning an error cancels the context, the remaining workers stop reading, and the producer blocks forever on a send that nobody will receive.

Sizing the pool

For CPU-bound work, runtime.GOMAXPROCS(0) is the starting point. For IO-bound work the right number is whatever the slowest downstream dependency tolerates, which you find by measurement rather than by arithmetic.

AWS Disaster Recovery Strategies: RTO, RPO, and the Four Recovery Patterns

Fri, 21 Aug 2026 00:00:00 GMT

This one is not part of the study-notes series. It sits in the same category, which makes it the post that proves category pages list series and non-series articles together.

The two numbers

Recovery time objective is how long you can be down. Recovery point objective is how much data you can afford to lose. Every DR pattern is a point on the curve between those two numbers and what you are willing to pay.

Backup and restore

Cheapest, slowest. Snapshots go to S3 or a cross-Region copy, and recovery means provisioning infrastructure from scratch. RTO in hours, RPO in hours.

Pilot light

A minimal core of the system runs continuously in the recovery Region, usually the database replica and nothing else. Compute is provisioned on failover. RTO in tens of minutes.

Warm standby

A scaled-down but functional copy of the whole system runs in the second Region. Failover is a traffic switch followed by a scale-up. RTO in minutes.

Multi-site active-active

Both Regions serve production traffic. RTO approaches zero and so does RPO, and the cost is a full second environment plus the work of keeping data consistent across it.

Picking one

The pattern is chosen by the business, not by the platform team. Ask what an hour of downtime costs. If nobody can answer, that is the finding to report before you build anything.

AWS Global Infrastructure: Regions, Zones, and Edge Locations

Wed, 19 Aug 2026 00:00:00 GMT

The hierarchy is small enough to memorise and precise enough that the exam will punish a loose reading of it.

Regions

A Region is a named geographic area containing multiple Availability Zones. Regions are isolated from each other by design: nothing replicates between them unless you configure it to.

Choosing a Region

Compliance first, then latency to your users, then service availability, then price. Newer services do not launch everywhere at once, so the third check catches more people than expected.

Availability Zones

An AZ is one or more discrete data centres with independent power, cooling, and networking, connected to sibling AZs over low-latency links. Spreading across AZs is the standard answer to “how do I survive a data centre failure”.

Edge locations

CloudFront’s cache sits at edge locations, of which there are far more than Regions. Route 53 and AWS Global Accelerator use the same footprint.

The specialised zones

Local Zones place compute close to a metropolitan area for latency-sensitive workloads. Wavelength Zones sit inside telecom providers’ 5G networks. Both are extensions of a parent Region rather than Regions in their own right.

Direct Connect

A dedicated private link between your premises and AWS. It is not part of the Region hierarchy, but questions about consistent network performance usually want it as the answer.

What compiling actually means

Tue, 18 Aug 2026 00:00:00 GMT

The first C++ error that genuinely stopped me was not a syntax error. It was this:

undefined reference to `Account::withdraw(double)'
collect2: error: ld returned 1 exit status

Every line of my code was correct. The class was declared, the method was declared, the call matched the declaration. The compiler had no complaint at all. Something called ld did, and I had never heard of it.

That error is only confusing if you think “compiling” is one step. It is at least three, and they fail in different ways for different reasons.

The pipeline

  main.cpp ─┐
            │  preprocessor      compiler        linker
  file1.cpp ─┼──▶ (text only) ──▶ (per file) ──▶ (whole program) ──▶ main.exe
            │                        │                 ▲
  file2.cpp ─┘                       ▼                 │
                                 main.o ───────────────┤
                                 file1.o ──────────────┤
                                 file2.o ──────────────┤
                                                       │
                          C++ standard library ────────┘
                          other libraries    ─────────┘

Four source files go in. One executable comes out. In between, each source file is turned into its own object file, and only at the very end does anything look at the program as a whole.

That last sentence is the whole article, really. Everything confusing about C++ builds follows from it.

The preprocessor does not understand C++

Before the compiler sees anything, a separate program rewrites your source as text. It handles the lines beginning with #, and it has no idea what a class is.

#include <iostream> does not “import” anything. It opens that file, pastes its entire contents where the directive was, and does the same for every #include inside it, recursively. Comments are stripped here too. By the time the compiler runs, your 40-line file might be 30,000 lines.

This is why include guards exist:

#ifndef ACCOUNT_H
#define ACCOUNT_H

class Account {
    // ...
};

#endif

If two files both include account.h, the naive paste would define Account twice in the same translation unit, and defining the same class twice is an error. The guard makes the second paste expand to nothing. It is a textual fix for a textual problem, which is exactly the level the preprocessor works at.

Each source file is compiled alone

The compiler takes one preprocessed file and produces one object file: your code in machine form, plus a table of the names it defines and the names it still needs.

The important word is alone. When the compiler builds main.o, it has never seen account.cpp. It cannot check whether Account::withdraw exists, because it has no way to look.

So it takes your word for it. That is what a declaration is:

double withdraw(double amount);   // I promise this exists somewhere

The compiler needs the shape of the thing to generate a correct call: how many arguments, what types, what comes back. It does not need the body. It emits the call with a hole where the address should go, records “I need Account::withdraw(double)” in the object file, and moves on.

The linker resolves the promises

The linker collects every object file and every library, and matches each unresolved name against the definitions. Fill in the addresses, write out one executable.

When it cannot find a match, you get the error I opened with. ld is the linker. The message is not saying your code is wrong. It is saying you promised a function existed and nobody delivered one.

Once you know that, the causes are a short list:

You declared it and never wrote the body.
You wrote the body but never added that file to the build.
You wrote the body with a slightly different signature, so the name the linker wants and the name you defined are two different names.
It lives in a library you did not link.

The third one catches everyone at least once. withdraw(double) and withdraw(int) are separate functions to C++, and the mismatch is invisible until link time.

The rule of thumb that has never failed me: if the error names a line, it is the compiler and the problem is in that file. If the error names a symbol, it is the linker and the problem is somewhere else in the build.

What “build” and “clean” mean

Building is compiling plus linking. Your IDE does both when you press the button and hides the object files, which is why the two stages blur together.

“Clean” deletes the object files. It is useful for exactly one reason: object files are cached, and if the build system’s idea of what changed is wrong, you can be linking last week’s file2.o against today’s main.o. Clean, then rebuild, forces everything through both stages again. On Windows the result is .exe; on macOS and Linux it usually has no extension at all.

Why this matters if you write Go or Node

You may never run a linker by hand. The model still explains things you do hit.

go build runs the same stages and prints a single error stream, so the distinction is invisible until you use cgo. Then a missing C library produces a linker error in Go’s output, with the same shape and the same causes as the one above.

Node has no build step for your own code, but native modules do. When npm install fails partway through compiling something with node-gyp, it is running this pipeline. “Symbol not found” from a native module at require time is a link failure that got deferred to runtime.

Dynamic libraries are the same idea with the last step postponed. A .so or .dylib is resolved when the program starts rather than when it is built, which is why you can ship a working binary and still get “library not found” on someone else’s machine.

The pattern underneath all of them: something recorded a name it needed, and later something else had to find it. Knowing which half failed tells you where to look.

Six Advantages of Cloud Computing

Sun, 16 Aug 2026 00:00:00 GMT

AWS publishes six advantages and the exam quotes them almost verbatim, so it is worth knowing them as phrases rather than as concepts you can paraphrase.

Trade capital expense for variable expense

You stop buying servers ahead of demand and start paying for what you consume. The exam wording is “capital expense” and “variable expense”, not CapEx and OpEx.

Benefit from massive economies of scale

Aggregate demand across all AWS customers produces lower per-unit prices than any single organisation could negotiate.

Stop guessing capacity

Capacity planning becomes a runtime decision rather than a procurement one. This is the advantage most often confused with elasticity in questions.

Increase speed and agility

New resources are minutes away rather than weeks, which changes what experiments are worth running.

Stop spending money running and maintaining data centres

Racking, cooling, and physical security stop being your problem.

Go global in minutes

Deploying into additional Regions is a configuration change, not a project.

A note on the update

This part was revised after the CLF-C02 refresh reworded the fourth advantage. The updatedDate field on this post exists so the article template has a real case to render.

Cloud Computing Models and Deployment Strategies

Fri, 14 Aug 2026 00:00:00 GMT

Two axes get confused constantly in exam questions: what layer you rent and where the hardware lives. They are independent, and questions frequently combine them to see whether you have noticed.

The service models

IaaS gives you the virtual machine and leaves the operating system to you. PaaS hands over the runtime and keeps you out of patching. SaaS gives you the finished application and no infrastructure surface at all.

Where the boundary moves

EC2 is IaaS. Elastic Beanstalk sits at PaaS because it manages the platform underneath your deployable artifact. WorkMail is SaaS. The useful test is to ask what you are still responsible for patching.

The deployment models

Public cloud means everything runs on provider infrastructure. Hybrid keeps some workloads on-premises and connects them, usually over Direct Connect or a site-to-site VPN. On-premises with virtualisation is sometimes marketed as private cloud, which the exam accepts.

Why hybrid persists

Data residency rules, latency-bound machinery, and depreciation schedules on hardware that still has years left on it. Hybrid is rarely a technical preference and usually a constraint someone inherited.

What the AWS Cloud Practitioner Exam Actually Tests

Wed, 12 Aug 2026 00:00:00 GMT

The Cloud Practitioner exam is often described as the easy one. That framing is unhelpful. It is a broad exam rather than a deep one, and breadth is its own kind of difficulty when the service catalogue keeps growing.

The four domains

CLF-C02 splits into cloud concepts, security and compliance, cloud technology and services, and billing. The weighting matters more than the names: roughly half the exam sits in the services domain, so time spent memorising the pricing calculator UI is time badly spent.

How the questions read

Associate-level questions describe a scenario and ask you to pick an architecture. Practitioner questions usually describe an outcome and ask which service produces it. The distinction sounds small and changes how you study: you need recall of what each service is for, not how to configure it.

What to read first

Start with the shared responsibility model. Almost every security question resolves to a single judgement about which side of the line a task falls on, and getting that instinct early makes the rest of the security domain cheap.

Notes on this series

Each part stands alone. They are numbered because the concepts compound, not because you have to read them in order.

What a function call does to memory

Tue, 11 Aug 2026 00:00:00 GMT

RangeError: Maximum call stack size exceeded

Node throws that. Go prints fatal error: stack overflow and takes the process with it. C++ usually just segfaults and tells you nothing. Three languages, three levels of politeness, one cause, and for years the best I could do was “I recursed too far”.

Which is true and explains nothing. Why is there a maximum at all? Why does the heap never fail this way? Why can I run a hundred thousand goroutines on a machine that would fall over at a hundred thousand threads?

Same question, three times. C++ is where I had to answer it.

The stack is a stack

The data structure, not a metaphor for one. A stack of books: last one on is the first one off.

The call stack holds one entry per call currently in progress. Each entry is a stack frame, or an activation record if you prefer the older name: that call’s parameters, its local variables, and the address to jump back to. Calling a function pushes one. Returning pops it.

You cannot jump into the middle of the stack or out of it. A function returns to its caller and nowhere else, so frames come off in exactly the reverse of the order they went on.

One call, in detail

void func2(int &x, int y, int z) {
    x += y + z;
}

int func1(int a, int b) {
    int result {};
    result = a + b;
    func2(result, a, b);
    return result;
}

int main() {
    int x {10}, y {20}, z {};
    z = func1(x, y);        // 60
}

Three functions, and at the deepest point all three are live at once. main is waiting on func1, which is waiting on func2.

result lives in func1’s frame. y and z live in func2’s frame, as copies of what was passed in. And x is a reference, so it holds the address of result and points down into the frame below:

  ┌──────────────────────────────┐
  │ func2   y=10  z=20  x ───────┼──┐
  │         return address       │  │
  ├──────────────────────────────┤  │
  │ func1   a=10  b=20           │  │
  │         result = 30 ◀────────┼──┘
  │         return address       │
  ├──────────────────────────────┤
  │ main    x=10  y=20  z        │
  └──────────────────────────────┘

func2 adds 10 and 20 to whatever that reference points at, so result becomes 60. Then its frame is gone, func1 returns 60, and that frame goes too.

The bookkeeping underneath is mechanical, and the compiler emits all of it: push the parameters and the address to come back to, jump, and on the way out restore the caller’s frame along with any registers the callee saved.

ABIs differ in the details and much of it happens in registers, but the shape holds. A fixed cost per call, paid whether or not the function does anything. That is why inline exists.

Why a local dies at the closing brace

Local variables are not preserved between calls. That gets taught as a scope rule, and scope is real: an identifier is visible only inside the block where it was declared.

But the reason the value is gone next time has nothing to do with visibility. The frame it lived in was popped.

One keyword changes the answer:

void tick() {
    static int calls {0};   // not in the frame
    calls++;
}

static moves that variable out of the activation record entirely. It is initialised once, the first time control reaches the declaration, and holds its value across every later call because there is no frame to take it away. Leave off the initialiser and it is zero rather than garbage. Globals are the same storage with wider visibility.

Storage duration, not scope.

The four regions

Everything a running program has is one of four things:

  ┌──────────────────────────────────────────────┐
  │  Heap, also called the free store            │
  │  new and delete, sized at run time           │
  │                                              │
  │                          ▼ grows             │
  ├──────────────────────────────────────────────┤
  │                          ▲ grows             │
  │                                              │
  │  Stack                                       │
  │  one frame per call in progress              │
  ├──────────────────────────────────────────────┤
  │  Static and global                           │
  │  one slot each, alive for the whole run      │
  ├──────────────────────────────────────────────┤
  │  Code                                        │
  │  the compiled instructions themselves        │
  └──────────────────────────────────────────────┘

That is a schematic, not an address map: on Linux the stack sits high and grows down while the heap sits low and grows up. What holds everywhere is the regions and their lifetimes. Code never changes, the static area lasts the whole run, the stack tracks call depth exactly, and the two growable regions face each other because they compete for the same unallocated space.

Why the stack has a ceiling and the heap does not

A frame is not an object anything tracks. It is a range of bytes underneath a pointer, and the pointer lives in a register. Pushing subtracts from it. Popping adds. Allocation and deallocation are one arithmetic instruction each, with no free list, no metadata and no fragmentation, which is why stack allocation is effectively free.

The price is contiguity. Every live frame sits at a known offset from that pointer, and pointers into those frames are scattered through registers and other frames. Growing the region means moving it somewhere bigger, which invalidates all of them. C++ cannot find them: it has no idea which words in a frame are addresses and which are integers that happen to look like addresses.

So the size is chosen once, when the thread is created, and never changes. On Linux the main thread typically gets eight megabytes, set by ulimit -s; additional threads get whatever you asked for at creation.

The heap never made that promise. It hands out individual blocks that need not be near each other, and can ask the operating system for more pages anywhere in the address space. new fails when the machine runs out, not when a region fills up.

Run off the end and you hit a guard page the kernel put there for exactly this. The program dies. Handling it would mean calling a function, and there is no room left for the frame.

Two ways to get there, and only one is famous. A single frame can be too large by itself: a local array of a few million elements is a few million elements of stack, requested in one instruction. The other route is recursion, which changes nothing about the mechanism. Each call gets its own frame, so factorial(n) bottoms out at n+1 of them, one per multiplication waiting on the one below.

So a recursion limit is a frame budget, not an arbitrary rule, and how many frames fit depends on how large each one is. That is why nobody quotes a precise number: add a local buffer to the recursive function and the depth you can reach drops. The limit did not change. The frames got fatter. C++ does not guarantee tail-call elimination either, so a recursion that is fine at -O2 can be a crash at -O0.

What this explains in Go and Node

V8 gives each isolate a fixed stack, well under a megabyte by default and raisable with --stack-size. It surfaces as a RangeError, which makes it look like an ordinary catchable exception, and the appearance is the only thing that differs. The depth at which it throws shifts with what your functions carry.

Go genuinely does something else. A goroutine starts with a two kilobyte stack, and the compiler emits a check in the prologue of every function that needs one: is there room for this frame? If not, the runtime allocates a larger stack, copies the live frames into it, rewrites every pointer that referred to the old location, and lets the function carry on as though nothing happened. The stack grows by moving.

Copying is exactly what C++ cannot do. Fixing up those pointers requires knowing which words in every live frame point into the stack, and the Go runtime knows because it already needs precise maps for the garbage collector. That information does not exist in a compiled C++ binary.

You feel that twice. A goroutine costs two kilobytes to start rather than a thread’s full reservation plus a kernel task, so a hundred thousand of them is unremarkable. And deep recursion behaves differently: the goroutine keeps growing until it hits the runtime’s own ceiling, one gigabyte on 64-bit by default, instead of dying at whatever its thread was handed. When it does, you get fatal error: stack overflow, and recover will not save you for the same reason C++ cannot.

It is also why cgo forbids C code from keeping a Go pointer after the call returns: the stack it points into may not be there later.

All of it comes down to one decision, made once per language: is the region allowed to move? Go said yes and pays a bounds check in every function prologue. C++ said no and hands you a segfault instead.

Pointer, reference, or value, and how to choose

Tue, 04 Aug 2026 00:00:00 GMT

Four spellings of the same function, and nothing compiles until you pick one:

void process(Report r);          // a copy, yours to wreck
void process(Report &r);         // the caller's report, under another name
void process(const Report &r);   // the same, read-only
void process(Report *r);         // its address, or nothing at all

Most languages settle this by category and then never mention it again. Primitives copy, objects don’t, and the call site looks identical either way. C++ puts the answer in the signature of every function you write, and the answer is load-bearing: it decides what the call costs, whether the caller’s data can change under them, and whether “no report” is a thing you are able to say.

What a copy actually costs

Pass by value and the parameter is a fresh object built from the argument. For an int that is four bytes into a register. There is no cheaper thing a function can do, and no reason to complicate it. If the parameter is an int, a char, a double, a bool, take it by value and stop thinking about it.

The trap is that sizeof does not tell you what a copy costs. On my machine sizeof(std::string) is 24 bytes, and sizeof(std::vector<std::string>) is also 24. Those 24 bytes are a pointer, a length, and a capacity. Copying the object runs its copy constructor, which allocates a fresh buffer and copies every element in, and for a vector of strings that is one allocation for the vector and another for each string it holds. A parameter that measures 24 bytes can cost you a dozen trips to the heap. Those go by reference.

Arrays were never given the choice

There is one type C++ refuses to copy for you, and it teaches the rest of the model. This compiles, and it does what the name says:

void zeroArray(int numbers[], size_t size) {
    for (size_t i {0}; i < size; i++)
        numbers[i] = 0;
}

int main() {
    int myNumbers[] {1, 2, 3, 4, 5};
    zeroArray(myNumbers, 5);      // myNumbers is now all zeros
}

No & in that signature. No * either. The function still reached into main and overwrote data it does not own, because an array argument decays to a pointer to its first element, and what arrives is an address. It is also why the size has to be handed over separately: the length did not survive the decay, and sizeof inside the function measures a pointer.

If you did not want that, say so:

void printArray(const int numbers[], size_t size);

Now any write through numbers is a compile error. Same address, less authority. Handing over the address and withholding permission to write is exactly what a const & parameter is, arrived at from the other direction.

One name or two

A reference is an alias. It has to be bound to something that already exists at the moment you declare it, and from then on it is a second name for that storage.

int num {100};
int &ref {num};

num = 200;      // ref is 200
ref = 300;      // num is 300

  int num {100};
  int *ptr {&num};
  int &ref {num};

  ptr:  [ 0x61ff1c ] ──┐             a pointer is an object,
                       │             its value is an address,
                       ▼             and it can be reassigned
                    [ 100 ]
                    ▲     ▲          num and ref are two names
                num ┘     └ ref      for one piece of storage

Everything else about references falls out of that picture. One cannot be null, because there was an object there when you bound it. One cannot be left uninitialised. And one cannot be pointed somewhere else afterwards, because assignment writes through to the object it names. That is precisely what you want from an alias and precisely what makes it useless as a cursor. A reference behaves like a const pointer that dereferences itself.

The property that catches people is subtler:

int square(int &n) { return n * n; }

square(num);    // fine
square(5);      // error: 5 has no storage to alias

Add const and it compiles, because the compiler may materialise a temporary and bind a const reference to it. So dropping const from a reference parameter also declares that callers may not pass an expression result. Correct for an out-parameter. Baffling the first time it fires on f(a + b).

A pointer is a variable whose value is an address

Which sounds like a definition and is actually the whole feature list. It can be reassigned, it can be null, and it can be uninitialised and full of garbage that happens to read as a plausible address.

double highTemp {100.7};
double lowTemp {37.2};

double *tempPtr {&highTemp};
tempPtr = &lowTemp;        // now names something else
tempPtr = nullptr;         // now names nothing

A reference answers “which object” once, at birth. A pointer keeps that answer in a variable you are free to change. That freedom is also how an uninitialised pointer sits in a codebase for a year before somebody dereferences it on a Friday afternoon.

Picking one

Take it by value when the type is small and cheap to copy and the function has no business touching the original. Simple types, mostly, and you will know them by name.

Take it by const & when the copy is expensive and the function only reads. This is the default for std::string, std::vector, and any class of yours with an allocation inside it. The function gets an address, the compiler enforces the read-only half, and callers can still pass a temporary.

Take it by & when the function is meant to modify the caller’s object and there is always an object to modify. swap(int &a, int &b) has no better spelling.

Reach for a pointer when absence is a legitimate answer. This is the case people try to be clever about and lose, because references cannot express it at all. Half the data structures worth writing depend on a pointer going null: end of list, empty subtree, no parent. If your parameter might mean “no node”, it has to be a pointer. When you want absence without mutation, const T *const gives you something that may be null, may not be repointed, and may not write through. C++17’s std::optional covers optional values you own outright; a pointer remains how you say “maybe a handle to something someone else owns”.

Go asks the same question with different punctuation

Go has pointers and it has values, and nothing in between. There are no references in the C++ sense, which means there is no way to declare a parameter that aliases the caller’s variable and is guaranteed not to be nil. So every time you want the callee to see your object rather than a photograph of it, you pass a pointer, and you have taken on nil as a possible value whether the domain wanted one or not.

That absence is why receivers are the thing Go developers get wrong first:

func (c Counter) IncValue() { c.n++ }   // increments a copy, discards it
func (c *Counter) IncPtr()  { c.n++ }   // increments the caller's Counter

IncValue compiles, runs, mutates nothing, and reports no error anywhere. It is void scale(Report r) with different punctuation, and the fix is the same one: the callee needs the caller’s storage, not a snapshot of it.

The cost side matches too. A value receiver copies the whole struct on every call, so a method set hanging off a struct with a few slices and a time.Time in it is copying that struct on each invocation to no purpose. Go then adds a wrinkle C++ does not have: the method set of T holds only the value-receiver methods while *T holds both, so mixing receivers on one type gives you interface satisfaction that depends on whether the thing in your hand is a value or a pointer. The usual advice, pick one receiver kind per type and stick to it, is really advice to make this decision once for the type instead of thirty times for its methods.

JavaScript deserves precision here, because “objects are passed by reference” is the phrase everyone uses and it is wrong. JavaScript passes everything by value. For an object, the value being passed is a reference. Reassign the parameter inside the function and the caller sees nothing; mutate the object it refers to and the caller sees everything. That is Report *r, minus the null check and minus any way to ask for the other three.

Every language decides this at every function boundary. Most decide for you, once, by category, and leave you to discover at runtime which one you got.

What virtual actually changes

Tue, 28 Jul 2026 00:00:00 GMT

Two lines that do not do what they look like they do:

Account *p = new Trust();
p->withdraw(1000);        // Account::withdraw

Trust inherits from Account and defines its own withdraw. The object sitting on the heap is a Trust. The call runs the Account version.

The first time I hit this I assumed I had broken the inheritance somewhere. I had not. That is C++ behaving exactly as specified, and the specification is the reverse of what every other language I write had trained me to expect.

The compiler binds to the type of the pointer

Deciding which function a call refers to is called binding, and C++ does it at compile time by default: the compiler reads the declared type of the expression you called through and picks that type’s method.

p is declared Account *. That is the whole input to the decision. The compiler does not know, and will not go looking, that the new Trust() one line above put a Trust at that address. The pointer says Account, so the call is wired to Account::withdraw before the program ever runs.

On objects with names this is invisible: declared type and actual type are the same thing.

Savings b;
b.withdraw(1000);    // Savings::withdraw, as expected

Redefining a base method in a derived class works fine, and you can still reach the original on purpose:

class Savings : public Account {
    void deposit(double amount) {
        amount += interest;
        Account::deposit(amount);   // the base version, deliberately
    }
};

That is a real technique, and it is also the ceiling of what static binding gives you. Hold a mixed collection of accounts, want each one to behave like the thing it is, and you are stuck:

void displayAccount(const Account &acc) {
    acc.display();     // Account::display. Always.
}

Four account types can be passed to that function. One implementation runs.

virtual defers the decision

Mark the base method virtual and every one of those call sites changes behaviour without being edited:

class Account {
public:
    virtual void withdraw(double amount);
    virtual void display() const;
    virtual ~Account();
};

virtual is an instruction to the compiler to stop resolving the call. Emit a lookup instead, and let the running program ask the object what it is.

Three conditions have to hold together: inheritance, a virtual method, and a call made through a base-class pointer or reference. Call on a plain object and you get static binding again, correctly, because a Savings variable can only ever contain a Savings.

The reference case matters more than it looks. It gives you dynamic dispatch with nothing on the heap:

Trust t;
displayAccount(t);   // Trust::display

displayAccount was not touched. Only display was.

Virtual is sticky. Once a method is virtual in a base class it is virtual in every class beneath it, whether or not the derived declaration repeats the keyword.

Getting the signature wrong is silent

An override has to match the base declaration exactly: name, parameters, const qualification, return type. Miss any part and you have not overridden anything, you have redefined, and redefinition is bound statically.

class Base {
public:
    virtual void sayHello() const { /* ... */ }
};

class Derived : public Base {
public:
    virtual void sayHello() { /* ... */ }   // no const. Not an override.
};

That compiles clean. It runs. Through a Base * it calls Base::sayHello forever, and the word virtual sitting right there in the derived class makes it look correct. I lost an afternoon to the missing-const version.

C++11 turned the silence into a compiler error:

virtual void sayHello() override;   // error: does not override

override costs nothing at runtime and catches the entire family of typo. Put it on every override you write.

And any class with a virtual function needs a public virtual destructor. Delete a derived object through a base pointer without one and the derived destructor never runs, which the standard calls undefined behaviour.

Where the cost lives

The standard describes the behaviour, not the machinery. Every implementation I have looked at builds the same machinery anyway: a table.

A class with virtual functions gets one table of function pointers, laid out at compile time and shared by every object of that class. Each object gets one hidden pointer to its class’s table, written in during construction.

                            Trust vtable, one per class
    p ──▶ ┌──────────┐      ┌────────────────────────┐
          │ vptr ────┼─────▶│ [0]  Trust::withdraw   │
          ├──────────┤      │ [1]  Trust::display    │
          │ balance  │      │ [2]  Trust::~Trust     │
          │ name     │      └────────────────────────┘
          └──────────┘

A virtual call becomes: read the vptr out of the object, index a fixed slot, call through whatever pointer is in it. The slot number is decided at compile time, so nothing is searched. withdraw is slot 0 in Account’s table and slot 0 in every table derived from it, which is why the call site never needs to know which class it landed in.

That buys two costs. Every object of a polymorphic class carries a pointer it did not ask for: eight bytes on a 64-bit target, the same eight whether the class declares one virtual function or forty.

The bigger cost never shows up in sizeof. The compiler cannot inline through the table, because it does not know the target, so the call blocks every optimisation that inlining would have unlocked downstream. Once per request, this is nothing. In a tight loop over a million elements, it is why somebody starts talking about templates.

Which is the argument for making it opt-in. You pay for dispatch at the point where you asked for it.

A class doing an interface’s job

C++ has no interface keyword. It has enough parts lying around that you can build one.

A pure virtual function is a virtual function declared with = 0 and usually no body:

class Shape {
public:
    virtual void draw() = 0;
    virtual void rotate() = 0;
    virtual ~Shape() {}
};

One pure virtual function makes the class abstract, and an abstract class cannot be instantiated. Shape s; will not compile. Neither will new Shape(). You reach a Shape only through a pointer or reference to a concrete class derived from it, and a class becomes concrete only by overriding every pure virtual function it inherited.

Now take a class that is nothing but public pure virtual functions. It names a set of services and implements none of them, and any class that wants to provide them says so by inheriting and implementing all of them. Every method, exactly matching. That is an interface, assembled from parts that were not designed for the job.

The example that made it land for me was a printable interface:

class Printable {
    friend std::ostream &operator<<(std::ostream &os, const Printable &obj);
public:
    virtual void print(std::ostream &os) const = 0;
    virtual ~Printable() {}
};

std::ostream &operator<<(std::ostream &os, const Printable &obj) {
    obj.print(os);
    return os;
}

One operator<<, written once, taking a reference to something abstract. obj.print(os) is a virtual call through a base reference, so it runs the concrete class’s print. Anything that inherits Printable and implements print becomes streamable, and the streaming code never learns its name.

You will see these named I_Shape or IShape out in the wild, a convention that exists because the compiler has nothing to say about intent here. It sees an abstract class. Only the name tells you it was meant as a contract.

Go was told nothing

Go’s interfaces satisfy structurally. *os.File has a Write method with the right signature, so *os.File is an io.Writer. Neither type was ever told about the other, and the check happens at the assignment, on the shape of the method set. C++ cannot do that: Circle has to name Shape in its own declaration, which means you can never make a type you do not own satisfy an interface you just wrote.

Go still dispatches through a table. An interface value is two words wide:

    var w io.Writer = f

    w ──▶ ┌──────────────┐
          │ itab ────────┼──▶ methods of *File, as io.Writer
          │ data ────────┼──▶ the *File itself
          └──────────────┘

The itab is that table. It holds the concrete type’s descriptor plus pointers to exactly the methods this interface requires, and it is keyed by the pair of types rather than by the concrete type alone. *os.File used as an io.Writer and *os.File used as an io.ReadWriteCloser produce two different itabs. The compiler and linker build the ones that are statically obvious; the runtime builds and caches the rest on first use.

So the itab is not the type’s method table, and it is not carried by the value. That second part is the real difference. The pointer lives in the interface value, which means an *os.File you never assign to an interface has no itab near it and pays nothing. C++ puts the vptr inside the object, so every instance of a polymorphic class pays whether or not one call is ever dispatched dynamically. Go moved the cost to the boundary where dispatch happens.

Java went the other way entirely: instance methods are virtual by default and you opt out with final, the C++ default read backwards, with a JIT that claws back most of the cost by devirtualizing call sites it can prove see only one type.

All three end up calling through a table of function pointers. What differs is who holds the pointer to that table, and when somebody filled it in. C++ is the one that makes you say out loud which methods were worth it.

Exception hierarchies, and what Go rejected

Tue, 21 Jul 2026 00:00:00 GMT

Account::Account(std::string name, double balance)
    : name{name}, balance{balance} {
    if (balance < 0.0)
        throw IllegalBalanceException{};
}

A constructor has no return value. It cannot hand back false, it cannot hand back an error code, and there is no half-built object it would be safe to give you instead. When the arguments are wrong, or the file it was told to open is not there, or the memory it needed did not arrive, there is exactly one way out.

That is the strongest argument for exceptions I know, and it is not really about style. Some functions have no channel to report failure through.

Where a class can throw, and where it must not

Methods throw the way plain functions do. Nothing new there.

Constructors are the interesting case. If you cannot establish the invariant the class promises, throw, and the object never comes into existence:

try {
    auto moes = std::make_unique<CheckingAccount>("Moe", -10.0);
    // use moes
}
catch (const IllegalBalanceException &ex) {
    std::cerr << "Couldn't create account\n";
}

The program continues. There is no partially valid Account sitting in a variable waiting for someone to forget to check it.

Destructors are the opposite rule, and it is absolute. Do not throw from one. Since C++11 they are noexcept by default anyway, so the compiler already assumes you won’t. The reason is the unwinding machinery: when an exception isn’t caught in the current scope, C++ walks back up the call stack looking for a handler, and every scope it leaves on the way runs the destructors for the objects in it. A destructor that throws at that moment is throwing a second exception while the first is still in flight. The original handler is never reached. The program terminates instead, and you debug a crash whose actual cause was three frames and one type away.

Throw objects, catch references

Throw an object, not a primitive. throw 0; compiles fine and a catch (int &ex) somewhere up the stack will handle it, but now the integer zero is your error protocol and any other function that throws an int is competing for the same handler. A named type is unambiguous:

class DivideByZeroException { };
class NegativeValueException { };

double calculateMpg(int miles, int gallons) {
    if (gallons == 0)
        throw DivideByZeroException();
    if (miles < 0 || gallons < 0)
        throw NegativeValueException();
    return static_cast<double>(miles) / gallons;
}

Throw by value, catch by reference. Catching by value copies the thrown object into the handler’s parameter, and if the handler’s type is a base class, the copy is only the base part. The derived half is sliced off, and a virtual call that should have reached your override reaches the base implementation instead. Catch by const reference and you get the actual object.

The tree

The standard library ships a hierarchy, rooted at std::exception. Every class in it implements one virtual function:

virtual const char *what() const noexcept;

It returns a C-style string describing what happened. That is the entire interface.

  std::exception
  │
  ├── logic_error          a bug in your code
  │   ├── invalid_argument
  │   ├── domain_error
  │   ├── length_error
  │   └── out_of_range
  │
  ├── runtime_error        a condition from the world
  │   ├── range_error
  │   ├── overflow_error
  │   ├── underflow_error
  │   └── system_error
  │
  └── bad_alloc            the allocator gave up

That split down the middle is the part that travels. A logic_error means a precondition was violated by the caller: you indexed past the end, you passed an argument the function documented as illegal. It was checkable before the call and somebody didn’t check. A runtime_error means the world said no. The number didn’t fit, the syscall failed, the resource wasn’t there.

The two need completely different handling. One is a defect and the correct response is usually to fail loudly, because retrying a bug just runs the bug again. The other is a condition, and retrying, backing off, or degrading is exactly right. Almost every error taxonomy I have seen since is trying to draw this same line, usually badly.

bad_alloc hangs off the root rather than either branch, which is honest. Running out of memory is not your logic and not really the world’s either.

Deriving into it

Nothing stops you from adding to the tree. Derive publicly from std::exception and your class is one, so it can be caught anywhere a std::exception is expected:

class IllegalBalanceException : public std::exception {
public:
    IllegalBalanceException() noexcept = default;
    ~IllegalBalanceException() = default;

    const char *what() const noexcept override {
        return "Illegal balance exception";
    }
};

Dynamic dispatch does the rest at runtime. Real error codes, offending values, and context all go in as members, set by the constructor, and what() reports them. Keep noexcept on it and mean it: throwing from a function marked noexcept doesn’t propagate, it terminates.

And now catching by category works:

try {
    reconcile(batch);
}
catch (const std::out_of_range &ex) {  // the one I want to report
    report_bad_index(ex.what());
}
catch (const std::logic_error &ex) {   // anything else that is my fault
    abort_batch(ex.what());
}
catch (const std::runtime_error &ex) { // the world's problem, try again
    requeue(batch, ex.what());
}

Handlers are tested in source order and the first type that matches wins, so the ordering is load-bearing. Swap the first two and the specific handler is dead code, because out_of_range is a logic_error and the broader one gets there first. There is also catch (...), which catches everything and gives you no object at all, so you learn that something failed and nothing else.

Written down like that, it looks like a clean win. One handler covers a branch of the tree, new exception types slot in without touching call sites, and the categories mean something.

What it costs, which is real

I have maintained the TypeScript version of this idea: a base AppError, a dozen subclasses, instanceof checks at the boundary. Same design, same two problems.

Look again at calculateMpg. Its signature is double calculateMpg(int, int). Nothing in that tells you it can throw, or what. To find out, you read the body, and then you read the bodies of everything it calls, and then you read the bodies of those. The information exists and it is nowhere near where you need it.

C++ did try to fix this. You could once list the types a function might throw in its signature, and it was removed in C++17, because the check happened at runtime rather than at compile time. A violation didn’t fail your build. It called std::unexpected in production. What survives is noexcept, which carries one bit: throws, or doesn’t.

The deeper cost is that every call becomes a potential exit. reconcile(batch); looks like a statement that runs and returns. It is also a jump to a handler somewhere up the stack that you cannot see from here, possibly skipping the rest of this function, and the only clue is the try block wrapped around it. Control flow that doesn’t appear at the call site is control flow you will forget exists, and the place you forget is the place the resource leaks.

Java took the other road and made the compiler enforce it: throws IOException is part of the method contract, and callers must handle it or declare it themselves. It works exactly as advertised, and what people do with it is wrap everything in an unchecked exception to make the compiler stop talking.

Where Go landed

Go looked at all of this and refused the mechanism entirely. Errors are ordinary values, returned like any other value:

cfg, err := loadConfig(path)
if err != nil {
    return fmt.Errorf("starting worker: %w", err)
}

The %w verb wraps rather than formats, so the returned error carries the original inside it. Do that at each layer and you build a chain. Then you interrogate the chain:

if errors.Is(err, fs.ErrNotExist) {
    // matched a sentinel value anywhere in the chain
}

var pathErr *fs.PathError
if errors.As(err, &pathErr) {
    // matched a type, and pathErr now points at it
    log.Printf("bad path: %s", pathErr.Path)
}

errors.As walks the chain, finds the first error whose concrete type is assignable to your target, and assigns it. Which is catch-by-base-class, arrived at from the opposite direction. C++ starts with a type hierarchy and searches the call stack for a handler that matches. Go starts with values and searches a wrapped chain for a type that matches. Both are a type-directed search for the first thing that fits.

The difference is not expressiveness. It is where the search happens. In Go it is a function call on a line you wrote, in the function you are reading, and if you delete it nothing invisible takes over. In C++ it is the language, and it runs whether or not anyone is looking.

I’ll be honest about the part that doesn’t favour Go: (Config, error) doesn’t tell you what can fail either. It is one bit. C++ hands you a genuinely richer description of the failure and hides it; Go hands you almost nothing and puts it directly in your face on every line. Neither signature answers the question you actually have.

But one visible bit beats a taxonomy you have to go looking for. The errors that have cost me real time were never the ones whose type I knew. They were the ones I didn’t know could happen at all.