Configuration Structure

Where do all these instructions actually live? Not in some abstract sense. They live in real folders, with real names, sitting on your hard drive where you could find them yourself in under a minute once someone actually tells you where to look, and you can open every one of them in whatever editor you already use every day. This page walks through that layout.

The hidden folder, and why it's hidden

Start with one small fact first. It isn't really about Claude Code at all. Across many dev tools, a folder name that starts with a dot, .hidden, .claude, and so on, stays out of view in a normal file browser, simply because that's the shared convention nearly every tool on your machine already agrees to follow. Claude Code didn't invent that rule. It just uses it. A related but separate habit covers folders like node_modules: no dot prefix, so it isn't filesystem-hidden the same way, but still a folder that shows up on its own once you use npm and that convention says to leave alone all the same. You don't need to touch it.

Claude Code's own .claude folder leans on that same hidden-folder habit, so it stays out of your way until you go looking for it on purpose, the same instinct that leaves node_modules alone once you know to expect it, even if the two are hidden by different mechanisms. Figure 5 lays out a typical structure.

FIGURE 5 — The .claude directory: shared vs. personal configuration. The split that actually matters is the colour, not the folder name, since anything amber never leaves your machine, on principle. settings.json holds team-shared permissions and gets committed to the repo. settings.local.json holds your own personal overrides and stays out of version control entirely, forever. CLAUDE.md holds project instructions, shared like any other file. CLAUDE.local.md holds personal notes that never leave your machine. The folder can also hold agents/ for subagents, skills/ for reusable workflows, rules/ for split-out instructions, and .mcp.json for MCP server setup.

That .local naming pattern reaches further than just these two files, and it's worth carrying as a general habit for anything you don't want a teammate to accidentally commit on your behalf, even though I only ever demonstrate it inside Claude Code's own folder. Anything named .local stays put. It never reaches a shared repo. That rule matters most for anything sensitive: keys, tokens, personal settings a teammate shouldn't be able to overwrite by accident.

Here's a habit worth copying, straight from my own workflow. I don't build the full structure on every project. I always use CLAUDE.md, full stop, no exceptions, and only add a skills/ folder or an agents/ folder once a specific project genuinely needs one, rather than scaffolding the entire structure by default on day one just in case it turns out to be useful later. Treat the whole layout as a menu. It is not a checklist you must clear before you're allowed to start real work.

Splitting one file into several

A single CLAUDE.md can grow unwieldy fast. The fix is simple: split it into smaller, topic-scoped files inside .claude/rules/, things like code-style.md, testing.md, security.md, or a frontend/ folder holding react.md and styles.md on their own. Each file stays small. Each one covers just one concern, which makes it far easier to read on its own than one giant file ever could be.

I showed this directly, on a real project. One existing CLAUDE.md had workflow rules, technical defaults, and design rules all crammed into a single file. I asked Claude to split it apart. Claude created three separate files instead, workflow.md, technical-defaults.md, and design-rules.md, each one holding its own slice of the original, shown in the split below.

FIGURE 6 — Splitting one file into several. One crammed file becomes three, each covering just one concern.

The lesson reaches past this one example. It says something more general about the tool itself: Claude Code can restructure its own configuration files just as competently as it restructures the application code you're actually building with it every day.

Splitting pays off twice over. You get finer control, because the workflow file can change without touching design rules at all. And it scales to teams. One person can own styling rules while someone else owns the overall workflow, with each file's edits easier to track and merge than changes buried inside one shared block of text.

Local versus global

Every folder discussed so far belongs to one project. But Claude Code also reads from ~/.claude, a folder that lives in your home directory instead, not inside any one project. The tilde is just shorthand for "home." Figure 7 shows how the two interact. Global configuration applies across every project on your machine, and it wins whenever it conflicts with project-level settings, which is worth pausing on, because that's backward from what most tools do.

FIGURE 7 — Global, project, and enterprise CLAUDE.md layers. Global beats project when the two disagree, the reverse of how most tools resolve settings, which is exactly why it's worth a second look.

As a general rule of thumb, most other tools let the more specific setting win: a project file beating a user-wide default, a user-wide default beating whatever the application shipped with out of the box. Here, it's the reverse. Global wins instead.

A third layer exists too. It's a managed, enterprise-level configuration, for organizations that need one. I name this layer without saying exactly how it ranks against the other two when all three genuinely disagree with each other. Treat that detail as open, not settled, until you've checked your own organization's real setup for yourself. I don't think this layer will apply to most people watching the course, and I move on within a sentence or two, without spending any real time walking through how it actually behaves in practice.

One pattern is worth considering here. It's an idea, not a rule. A team lead sets high-level global rules, never delete this file, always follow this style, while individual engineers keep their own project-level folders for whatever's specific to their own work. It's an emerging pattern, in my own words, not an established practice with years of proof behind it yet. Knowing where a file lives is only half the job. Writing one well is the other half, covered next.