Twenty concepts, one shape

We built a field guide to Claude Code. It is live at concepts.intlo.com, it covers twenty concepts, and every entry answers the same eleven questions in the same order.

That last part is the whole idea. Everything else is execution.

The question documentation does not answer

Claude Code’s documentation is good. It is organised the way nearly all developer documentation is organised: one page per feature, each page written to whatever shape that feature needs. If you know hooks exist and you need the exact name of the event that fires before a tool call, the docs will tell you in about fifteen seconds.

The trouble starts one level up. The question most people actually have is not what is a hook. It is: I want the formatter to run after every edit — is that a hook, a skill, a slash command, or a line in CLAUDE.md?

Four features can plausibly do it. Each has a page. None of the pages is about the choice, because a page about a feature is written by someone who has already decided you want that feature. The comparison lives nowhere, so everyone reconstructs it themselves, badly, once.

A reference organised by feature is a dictionary. What was missing was a field guide — something organised so two options can be held against each other.

Fixing the shape instead of the topic

So the guide holds the structure fixed and lets the subject vary. Every one of the twenty entries has the same eleven sections: what it is, what it does for you, how it works, how to implement it, worked examples, use it when, avoid it when, common mistakes, best practices, a five-minute exercise, and its neighbours.

Once you have read one entry you know the location of everything in the other nineteen. To compare hooks against skills you read the same two paragraphs in each. The comparison the docs cannot make, the structure makes for you.

The section doing the most work is “Avoid it when.” Almost no reference has one, because documentation is written by people who want you to use the thing. But knowing that subagents get their own context window is close to useless next to knowing that spawning one for a two-file change costs more than it saves. Every entry has to state where it is the wrong instrument. Several were harder to write than the rest of the entry combined, which is a reasonable sign the section is earning its place.

A reference that is subtly wrong is worse than none

This is the part we took seriously, because it is where guides like this normally fail. A guide with plausible, slightly-wrong flag names is worse than no guide at all. It does not just fail to help — it costs the reader the time to discover it lied, and then costs them their trust in everything else on the page. Confident and wrong is the worst available outcome.

Nothing was written from memory. Every command, flag, path, settings key, and hook event name was read from the source documentation and recorded against the page it came from, with the date it was checked. Each entry links the exact page it was verified against, so a version-gated detail can be rechecked in one click rather than taken on faith.

The rules are enforced by the build, not by review. The content is twenty typed modules with a validator that runs when they are imported. A duplicate entry, a cross-reference pointing at something that does not exist, leftover placeholder text, an entry that has drifted outside its length rubric, a reading time that no longer matches its own word count — each one fails the build.

That distinction matters more than it sounds. A checklist protects the content until the author gets tired. A build failure protects it permanently, including six months from now, including from an edit made by someone who never read the rubric. The guarantee is inherited by every future change for free.

Claude Code ships weekly. Some of what is written there will be wrong eventually. The design goal was never to be permanently correct — it was to make the moment of going stale visible, dated, and cheap to check, rather than silent.

The details we spent time on

The diagrams. Each concept has one, purpose-built and animated: an event moving through a hook pipeline, a context window filling and compacting, a permission check resolving. They animate whenever they are on screen. They are also the thing we got most wrong on the first pass — the labels were rendering at seven and a half pixels, because SVG text scales with its box and it is the width, not the height, that sets that scale.

The reading paths. All twenty end to end is a little over two hours, and most people should not do that. There are four sequences worth following instead, depending on whether you have just installed it, it keeps forgetting things halfway through a task, you want it running unattended, or you are about to give it write access to something that matters.

Printing. It is called a field guide, so it prints like one. Send an entry to your printer and it inverts to ink on paper, drops the navigation, and prints the destination of every outbound link inline, so a paper copy is still a working reference.

And the limits, stated on the page rather than discovered by the reader. It is a snapshot of a weekly-shipping product. Twenty is a choice, not a census. Progress tracking is local to your browser and does not follow you anywhere. A search query only searches inside the filters you have selected, so a match can hide behind an active filter — that one is a bug we know about and have not fixed yet, which seems better to say than not.

Go and use it

concepts.intlo.com. No account, no email, nothing stored anywhere but your own browser.

Start with CLAUDE.md if you have just installed it. Start with Context Window if it keeps losing the thread. Start with Permissions if you are about to point it at production.

One instrument, one job. — See the instruments