Two CLAUDE.md files and a skills folder give Claude consistent behavior, full project awareness, and lean context — the combination that keeps output quality high across every session.
By William Rodriguez | Published: May 2026
TL;DR
Analytical Ants runs Claude Code across several active projects and machines. The question is not where to store config files — it is how to make Claude consistently good: aware of the codebase, working with lean context, and behaving the same way every session. This is the setup that achieves that.
Claude output degrades when the context window fills with things the current task does not need.
Social media posts — "Five folders. That's the entire system." — routinely misrepresent how Claude Code actually loads information. One common claim: put files in a CLAUDE.md/ folder and Claude auto-loads them by matching your task. This is not how it works. Claude Code reads two specific files at session start: ~/.claude/CLAUDE.md (global) and {project}/.claude/CLAUDE.md (project). Nothing else loads automatically. A folder named CLAUDE.md/ does nothing.
The real degradation pattern is manual overloading: pasting the entire ICP into CLAUDE.md, adding the design system, the blog conventions, the outreach templates. Now every session starts by burning hundreds of context lines on content that is irrelevant to most tasks. Instructions at the bottom of a long file get less weight. The model is effectively working with less bandwidth by the time it reaches your actual request.
The fix is not a more organized folder. It is loading less by default and loading the right thing at the right time.
Claude Code loads exactly two CLAUDE.md files automatically: the global file and the project file.
Global (~/.claude/CLAUDE.md) applies to every session on the machine, regardless of project. This is where behavioral rules live: which model to use for which type of task, how to handle context when it grows large, task tracking conventions, planning thresholds, code style principles. Keep it lean. If it does not apply to every project, it does not belong here.
Project (.claude/CLAUDE.md in the repo root) applies only to the current codebase. This is where project identity lives: the stack, the key routes, the available skills and when to invoke them, and a short index of what context files exist. It tells Claude what it is working on without requiring you to re-explain the codebase every session.
The rule that keeps both files clean: global handles HOW Claude works, project handles WHAT Claude is working on. Nothing from global gets repeated in project.
Skills are the mechanism that makes lean context practical.
A skill is a .md file in .claude/commands/. When you invoke one, Claude reads that file before proceeding. The skill instructs Claude to load a specific context file and carry out the task with that context active. When you are not doing that type of work, the context file never enters the session.
This is the correct mental model: skills are explicit triggers, not auto-invoked matchers. Claude does not detect the task type and pull in relevant context automatically. You invoke the skill and that loads it. The distinction matters because the default session starts with nothing extra — just the two CLAUDE.md files — and depth enters only when you ask for it.
The project CLAUDE.md acts as the index for this system. It lists each skill and the condition under which to invoke it:
/content — load when writing or editing structured long-form content with specific style rules/research — load when performing domain-specific analysis or building outreach/review — load when checking output against a defined standard or checklistEach skill file carries its own instructions — checklist items, formatting rules, tone constraints — that are too specific to belong in the main CLAUDE.md but too important to leave out when doing that type of work.
Here is what the chain looks like in practice.
Step 1 — Project CLAUDE.md indexes the skills
The project CLAUDE.md does not load context. It documents that skills exist and when to use them:
## Available Skills
- `/content` — load when writing or editing structured long-form content
- `/research` — load when doing domain-specific analysis or building outreach
- `/review` — load when checking output against a defined standard
Step 2 — The skill file loads the context
When you type /content, Claude reads commands/content.md. That file is where the actual loading instruction lives:
Read `.claude/context/style-guide.md` before proceeding.
Follow the style guide exactly. Key constraints:
- [formatting rule specific to this content type]
- [tone or structure requirement]
- [checklist item to verify before delivering output]
The first line is the trigger. Claude reads the referenced context file, absorbs its rules, and then carries out the task with that full context active. The context file itself can be as detailed as needed — it only loads when the skill runs.
Why this structure matters: the skill file is the gate. Context files stay inert until a skill opens them. A session doing none of that work loads none of that context.
Project-level Claude configs often contain competitive IP: ICP research, design systems, SEO and editorial conventions, outreach frameworks. These should not be committed to a public repo. But storing them only on one machine means a single disk failure wipes months of context work.
The solution is a private config repo — Azure DevOps, a GitHub private repo, or any version-controlled store — structured to mirror the two layers:
claude-configs/
├── _Global/
│ └── CLAUDE.md → ~/.claude/CLAUDE.md
└── my-project/
└── .claude/ → {project}/.claude/
├── CLAUDE.md
├── commands/
│ └── content.md
└── context/
└── style-guide.md
Setting up a new machine is a manual copy: pull the config repo, place _Global/CLAUDE.md at ~/.claude/CLAUDE.md, and drop the project .claude/ folder into the project directory. Add .claude/ to the project's .gitignore and the project repo stays clean. Edit configs in the config repo first, then re-sync — that keeps a single authoritative source.
Does Claude Code auto-load files from a CLAUDE.md folder?
No. Claude Code reads two specific files at session start: ~/.claude/CLAUDE.md and {project}/.claude/CLAUDE.md. A directory named CLAUDE.md/ has no special behavior. Sub-files in .claude/context/ are not loaded until a skill or explicit instruction references them.
Do skills auto-invoke based on what I am working on? No. Skills are explicit slash commands — you type the skill name and it runs. Claude does not detect the task type and load context automatically. The explicit trigger is what keeps sessions lean by default.
What is the right content for each CLAUDE.md? Global: behavioral rules that apply to every project — model selection, context management, code principles, planning thresholds. Project: codebase identity — stack, routes, available skills, context file index. If a rule applies everywhere, it goes global. If it is project-specific, it goes local. Nothing repeats between the two files.
Why keep a separate private repo instead of just using .gitignore?
.gitignore prevents accidental commits but does not back anything up. A private config repo gives you version history, the ability to set up a new machine in minutes, and a single place to review and update your full Claude configuration across all projects.
If you are exploring how to build AI tooling into a technical practice, the contact form is a good place to start a conversation.