Hello Curious Coders,

Most developers treat AI configuration like sticky notes. A few good prompts saved in a notes app, some buried in a long chat history, a CLAUDE.md you copy from project to project when you remember to. It works well enough on a solo project for a week or two. Then you bring in a second developer, or switch to a different codebase, and half your workflow disappears.

That’s when the real question shows up: where should this tooling actually live?

Claude has a clear answer built into its design. Almost everything that shapes how Claude behaves can exist at one of two levels: global, meaning it follows you across every project on your machine, or local, meaning it lives in the project itself and travels with the code.

CLAUDE.md. agents.md. Skills. Scripts. Hooks. All of it can go either place. The question is which scope fits your situation.

One Decision, Two Answers

The global level is the natural starting point. You write a CLAUDE.md once, put it in your home directory where Claude looks by default, and every project you open inherits those preferences. Your coding style, your formatting conventions, the libraries you reach for first. All of it available without any per-project setup.

For a solo developer working across many short-lived projects, this works well. Your tools follow you. When you update a preference, every project benefits immediately.

But the global level has a real weakness: it’s yours, not the team’s. When a second developer joins the project, they don’t get your tooling. They bring their own global configuration, or nothing at all. Two developers, two different AI experiences on the same codebase.

The Project Level Changes the Equation

When you move AI tooling into the project itself, things shift in a useful direction.

A CLAUDE.md committed to the repo is code. It gets reviewed. It gets versioned. When the project’s approach to something changes, the tooling changes with it through a normal PR. When a new developer clones the repo, they get the AI workflow for free, the same way they get the formatter configuration and the test setup.

Bruce argues this is the right approach for long-running team projects: keeping the tooling in the repo forces it to evolve alongside the codebase, not drift away from it as individuals move on or update their personal setups.

The same logic applies to agents, scripts, and hooks. An agent defined globally is a personal preference. An agent committed to .claude/agents/ is team infrastructure, subject to the same review process as everything else in the codebase.

What Goes Where

A simple way to think about it: global is for what you bring to every project, and project-local is for what the project needs from you.

Global might include your preferred editing patterns, general conventions you carry everywhere, tools you use regardless of which codebase you’re in. These are personal preferences that happen to help Claude, and they don’t belong to any particular project.

Project-local is where it gets interesting for teams. This is where you encode what’s specific to this codebase: which libraries you’ve chosen and why, the naming conventions that come from the domain, the agents that understand this specific architecture, the slash commands that automate the workflows this team runs repeatedly.

When these live in the project, something useful happens. A code review on CLAUDE.md becomes a conversation about team conventions. A PR that adds a new sub-agent is visible to everyone. The decisions that shape how AI assists your team become legible and versioned, just like any other architectural decision.

Infrastructure Is a Placement Decision

What this comes down to is a design question you’ve already faced in other forms. AI tooling is infrastructure, and where you put infrastructure matters.

For a solo developer on a short project, global configuration is the right call. Low overhead, quick to update, follows you everywhere.

For a team working on a long-running codebase, the project level is the right choice. Not because global is wrong, but because shared tooling needs to be owned by the project, not by whoever set it up first. It needs to survive developer turnover, evolve with the codebase, and be visible to everyone on the team.

Once you see it that way, the question of where to put your CLAUDE.md is the same kind of question as where to put your formatter configuration. It belongs with the code it governs.

In the next post, we’ll look at what it takes to actually run these workflows as a team, once the infrastructure is in place.

See you in the next chapter.

— Paulo & Bruce