CLAUDE.md: The Core Concept

One file matters most. Permission modes, planning, subagents, all of it assumes you already understand what CLAUDE.md does, why it comes first, and why I keep coming back to it in nearly every chapter that follows this one. So this page stands on its own before anything else builds on top of it.

The brain of the workspace

I have a simple phrase for CLAUDE.md: "the brain of the workspace." It holds project-level instructions. Those instructions shape how Claude acts inside that folder, for everything you ask it to do there, from a tiny one-line fix to a whole new feature built from scratch. Mechanically, it works like a prompt inserted at the very start of a session, before you type your first message. Claude reads it first. That single fact is why it matters so much. It sets expectations and direction before Claude responds to anything you actually ask.

That ordering is not a minor detail. It's the whole point, and nearly every recommendation later in this course, from permission modes to how you structure a multi-agent build, traces back to this one idea about what Claude reads first and why.

Why the order matters

I reach for a ship analogy here. A small angle error at the start of a long voyage compounds over distance, so that even a tiny mistake made in the first minute can end up mattering more than any decision made later in the trip. Left uncorrected, the ship ends up far from where it should have arrived. Applied to a long Claude Code session, a vague or inaccurate starting direction can push later responses steadily further from what you actually wanted, one small decision at a time.

Where does the analogy break down? A ship drifts through simple physics: hold a fixed wrong angle, and the error just grows on its own, without anyone making a new mistake. A Claude Code session drifts through a chain of decisions instead, each one shaped by everything said before it, which is a softer and more forgiving kind of drift than a fixed heading ever could be. You can correct a conversation mid-stream in ways you can't correct a ship that has already drifted off course over thousands of kilometres of open water.

I have my own word for the underlying idea: steerability. It means reducing the number of directions the model could plausibly take, the same way a narrow hallway leaves you far fewer wrong doors to open than an open field does. A well-written CLAUDE.md narrows Claude's output toward a smaller, more relevant set of outcomes. Small deviations can still happen. I don't claim otherwise. The range of wrong turns shrinks a lot.

The practical advice, then, is simple. Treat CLAUDE.md as the session's starting trajectory, in a terminal or a graphical tool alike, and give it the same care you would give a set of directions handed to a new employee on their very first day. You repeat yourself less. Later decisions, file edits, and implementation choices stay closer to what you meant, instead of drifting toward whatever the model happened to guess.

It's also about cost, not only behavior

CLAUDE.md does something else too. It manages context, quietly, but constantly. A session already carries global instructions, project instructions, tool definitions, and your own message, and every one of those pieces takes up space in a window that is large but not infinite. Forcing Claude to reread every project file on top of all that, every time a session starts, adds real weight to a window that's already full.

That repeated reading costs you twice over. Quality can slip. Tokens and cost climb too, sometimes by a lot on a big project, because every extra file read is tokens spent before the actual work has even begun. Put both effects together and CLAUDE.md's real job comes into focus. It steers Claude with high-level instructions, and it acts as a compressed map, so a fresh session starts already knowing roughly how the project fits together.

Bootstrapping one from scratch

One question follows naturally from here. Once the concept makes sense, the next thing worth knowing is where these files actually live on disk, and how a project-level file interacts with a personal or team-wide one. That's the configuration structure covered next.

Say you inherit a codebase with no CLAUDE.md at all. No map, no instructions, nothing written down anywhere, just files and folders that make sense to whoever wrote them and to nobody else. I demonstrated exactly this, on an existing marketing site with no configuration file prepared in advance. I ran the /init command, which tells Claude Code to study the current codebase and write a CLAUDE.md describing it: Claude reads the files, looks for patterns that repeat, and produces a summary aimed at its own future sessions. The generated file landed at the workspace root, not automatically tucked inside a .claude folder. You handle that yourself, if you want it organized.

Try this with AI "Run /init on a codebase I already work in, then read the CLAUDE.md it generates and tell me one thing it got right and one thing you'd correct yourself."

Here, the result described the site as a marketing property for an AI automation agency, and it covered deployment, architecture, the design system, and key files, in roughly the same amount of detail you'd expect from a short internal wiki page written by someone who actually knew the codebase well. But the real lesson isn't about that one site. It's that /init produces a working project brief in minutes, from code that had zero documentation to start with.