Tools: Designing a CLAUDE.md Context System: How I Give AI Full Project Context Without Re-explaining Anything

The Two Ideas Behind the System ## The Three Layers ## Layer 1: Global Context (Always Loaded) ## Layer 2: Project Context (Loaded Per Directory) ## Layer 3: Deep Storage (Loaded On Demand) ## How Context Scoping Prevents Bleed ## Real Workflow Example ## Starter Template ## Scaling to More Clients ## What I Got Wrong at First ## Why This Matters Every time I open Claude Code on a new project, it knows who I am, which client I'm working on, what tech stack the project uses, who the key people are, and what my code standards look like. I never re-explain any of it. This is not magic. It is a file system. I run Syntora, a small consultancy with multiple active clients. Each client has its own codebase, its own Supabase project, its own conventions. Switching between them used to mean spending the first five minutes of every session re-teaching Claude what "OD" means or reminding it not to use global singletons. That friction compounds. Over a full day of context-switching, I was losing 30+ minutes to re-orientation alone. So I built a hierarchical context system using CLAUDE.md files. It draws from two ideas that have nothing to do with AI tooling. Real estate LLC isolation. In commercial real estate, the standard structure is one LLC per property with a parent LLC governing all of them. Each property is legally isolated, but the parent entity sets universal rules. If one property has a liability issue, the others are protected. The parent LLC does not contain property-specific details. It contains the rules that apply everywhere. Monorepos are about shared context. A backend architect I work with made this observation: "Monorepos aren't about code, they're about shared context." The value of a monorepo is not that the code lives together. It is that developers share a single source of truth for conventions, types, and standards. When you change a shared interface, every consumer sees it immediately. These two ideas gave me the architecture: isolated client folders (like separate LLCs) governed by a shared context layer (like the parent LLC), with on-demand deep storage for details that do not need to be in memory at all times. Location: ~/.claude/CLAUDE.md Claude Code automatically reads this file every time it starts, regardless of which directory you are in. This is your hot cache. It should contain only what Claude needs on every single session. Here is a sanitized version of mine: Notice what is NOT here: detailed tech stacks, API endpoints, database schemas, deployment procedures. Those belong in Layer 2. The global file is a routing table. It tells Claude who I am, who the clients are, what my universal preferences look like, and where to find everything else. The -> Details: ~/.claude/memory/clients/ pointers are important. Claude Code follows these references. When a conversation requires deeper client context, I can tell it to read the relevant memory file and it knows exactly where to look. Keep this file under 100 lines. Every token in the global context is loaded on every session. If you put your entire project documentation here, you are burning context window on information that is irrelevant 80% of the time. Location: <project-root>/CLAUDE.md When you open Claude Code inside a project directory, it reads both the global ~/.claude/CLAUDE.md and the local CLAUDE.md in that directory. This is where project-specific context lives. A typical project-level file looks like this: This file can be longer than the global one because it only loads when you are actually working in that project. I keep mine between 50 and 150 lines depending on the project's complexity. The critical thing here: client folders stay completely separate. When I am working in Client One's directory, Claude has zero context about Client Two's codebase, conventions, or data. This is security by architecture, not by policy. There is no prompt that says "don't mix up clients." The file system makes it structurally impossible. Location: ~/.claude/memory/ This is the reference library. It contains information that is useful but not needed on every session. My glossary file decodes every acronym I use. When I type "check the RLS policies on the OD Supabase project," Claude knows RLS means Row Level Security and OD means Open Decision because the global context points to this glossary. The tech standards file contains universal rules like dependency injection patterns, file organization conventions, and stack details per project. It only gets loaded when Claude needs to make architectural decisions. The key principle: reference, don't inline. The global context file points to deep storage. It does not duplicate it. This keeps the hot cache small while making the full knowledge base accessible. The isolation model is what makes this work for multiple clients. Here is how the layers interact depending on where I am working: Working in Client One's directory: Working in Internal/Syntora operations: Opening Claude Code from home directory: This means I can never accidentally reference Client Two's database schema while working on Client One. I can never accidentally apply Client One's code conventions to Client Two's codebase. The isolation is structural. Here is what a typical context switch looks like: No preamble. No "here is my project structure." No copy-pasting README files into the chat. The context system handled all of it before I typed a single word. If you want to build this yourself, here is the minimal structure: 1. Create the global context file: 2. Populate it with your identity and preferences: 3. Create deep storage for reference material: Add a glossary.md for acronyms and a tech-standards.md for universal coding conventions. 4. Add a CLAUDE.md to each project: That is the entire system. Four files minimum, scaling to as many as you need. When I onboard a new client at Syntora, the context system scales with three steps: The global file grows by one line. The deep storage grows by one file. The existing clients are completely unaffected. There is no monolithic config file that gets unwieldy at five clients. The system scales linearly. My first version put too much in the global file. It was 300+ lines with full tech stacks, all deployment procedures, and detailed client profiles. Claude Code loaded all of it on every session, wasting context window on information that was only relevant 10% of the time. The fix was aggressive: I cut the global file to under 100 lines and moved everything else to deep storage or project-level files. The rule I follow now is simple. If the information is needed on every session regardless of project, it goes in the global file. If it is needed only when working on a specific project, it goes in that project's CLAUDE.md. If it is reference material that is occasionally useful, it goes in deep storage. The developers who get the most out of AI coding tools are not the ones writing better prompts. They are the ones building better context infrastructure. A well-structured CLAUDE.md system means Claude starts every session with the equivalent of a senior team member's institutional knowledge. It knows the codebase, the conventions, the people, and the priorities. That is not a productivity hack. It is infrastructure. And infrastructure compounds. I'm Parker Gawne, founder of Syntora. We build custom Python infrastructure for small and mid-size businesses. syntora.io (https://syntora.io) Templates let you quickly answer FAQs or store snippets for re-use. This was huge for our productivity as a firm. Some comments may only be visible to logged-in visitors. Sign in to view all comments. Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse COMMAND_BLOCK: # Your Name - Company ## Identity Founder at CompanyName. Consultancy focus. Central Time. ## Active Clients | Short | Client | Supabase ID | |-------|------------------|----------------------| | CL1 | Client One | abc123def456 | | CL2 | Client Two | ghi789jkl012 | -> Details: ~/.claude/memory/clients/ ## Key People | Who | Context | |--------|-----------------------------------| | Alice | CL1 Product Owner | | Bob | CL2 Backend Lead | ## Preferences - Fast, direct, no fluff - Infrastructure over instructions - One thing per file, use dependency injection - NO em-dashes, NO emojis ## Folder Map Desktop/Company/ Clients/ -> Client projects Internal/ -> Company operations ## Shell Shortcuts | Command | Path | |---------|-----------------------------------| | cl1 | Clients/client-one/ | | cl2 | Clients/client-two/ | ## Critical Rules 1. Never commit .env or credentials 2. Use Context7 MCP for external library docs 3. Always verify build + test after changes Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # Your Name - Company ## Identity Founder at CompanyName. Consultancy focus. Central Time. ## Active Clients | Short | Client | Supabase ID | |-------|------------------|----------------------| | CL1 | Client One | abc123def456 | | CL2 | Client Two | ghi789jkl012 | -> Details: ~/.claude/memory/clients/ ## Key People | Who | Context | |--------|-----------------------------------| | Alice | CL1 Product Owner | | Bob | CL2 Backend Lead | ## Preferences - Fast, direct, no fluff - Infrastructure over instructions - One thing per file, use dependency injection - NO em-dashes, NO emojis ## Folder Map Desktop/Company/ Clients/ -> Client projects Internal/ -> Company operations ## Shell Shortcuts | Command | Path | |---------|-----------------------------------| | cl1 | Clients/client-one/ | | cl2 | Clients/client-two/ | ## Critical Rules 1. Never commit .env or credentials 2. Use Context7 MCP for external library docs 3. Always verify build + test after changes COMMAND_BLOCK: # Your Name - Company ## Identity Founder at CompanyName. Consultancy focus. Central Time. ## Active Clients | Short | Client | Supabase ID | |-------|------------------|----------------------| | CL1 | Client One | abc123def456 | | CL2 | Client Two | ghi789jkl012 | -> Details: ~/.claude/memory/clients/ ## Key People | Who | Context | |--------|-----------------------------------| | Alice | CL1 Product Owner | | Bob | CL2 Backend Lead | ## Preferences - Fast, direct, no fluff - Infrastructure over instructions - One thing per file, use dependency injection - NO em-dashes, NO emojis ## Folder Map Desktop/Company/ Clients/ -> Client projects Internal/ -> Company operations ## Shell Shortcuts | Command | Path | |---------|-----------------------------------| | cl1 | Clients/client-one/ | | cl2 | Clients/client-two/ | ## Critical Rules 1. Never commit .env or credentials 2. Use Context7 MCP for external library docs 3. Always verify build + test after changes COMMAND_BLOCK: # Client One - Frontend ## Stack - Next.js 14, TypeScript, Tailwind - Supabase (auth, database, storage) - Express.js backend on port 3001 ## Architecture - Dependency injection throughout - One component per file - Interfaces for all external dependencies ## Commands | Command | What It Does | |------------------|------------------------| | npm run dev | Dev server on port 3000 | | npm run validate | Lint + build + test | ## Key Patterns - All API calls go through src/lib/api-client.ts - Auth context provided via AuthProvider wrapper - Database types auto-generated, never hand-written ## Current Sprint - Feature: conversational AI assistant - Branch naming: feature/scout-{description} Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # Client One - Frontend ## Stack - Next.js 14, TypeScript, Tailwind - Supabase (auth, database, storage) - Express.js backend on port 3001 ## Architecture - Dependency injection throughout - One component per file - Interfaces for all external dependencies ## Commands | Command | What It Does | |------------------|------------------------| | npm run dev | Dev server on port 3000 | | npm run validate | Lint + build + test | ## Key Patterns - All API calls go through src/lib/api-client.ts - Auth context provided via AuthProvider wrapper - Database types auto-generated, never hand-written ## Current Sprint - Feature: conversational AI assistant - Branch naming: feature/scout-{description} COMMAND_BLOCK: # Client One - Frontend ## Stack - Next.js 14, TypeScript, Tailwind - Supabase (auth, database, storage) - Express.js backend on port 3001 ## Architecture - Dependency injection throughout - One component per file - Interfaces for all external dependencies ## Commands | Command | What It Does | |------------------|------------------------| | npm run dev | Dev server on port 3000 | | npm run validate | Lint + build + test | ## Key Patterns - All API calls go through src/lib/api-client.ts - Auth context provided via AuthProvider wrapper - Database types auto-generated, never hand-written ## Current Sprint - Feature: conversational AI assistant - Branch naming: feature/scout-{description} CODE_BLOCK: ~/.claude/memory/ glossary.md <- Acronyms and shorthand clients/ client-one.md <- Full client profile client-two.md <- Full client profile people/ alice.md <- Contact details, preferences bob.md <- Communication style, role context/ company.md <- Company overview tech-standards.md <- Universal code standards Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: ~/.claude/memory/ glossary.md <- Acronyms and shorthand clients/ client-one.md <- Full client profile client-two.md <- Full client profile people/ alice.md <- Contact details, preferences bob.md <- Communication style, role context/ company.md <- Company overview tech-standards.md <- Universal code standards CODE_BLOCK: ~/.claude/memory/ glossary.md <- Acronyms and shorthand clients/ client-one.md <- Full client profile client-two.md <- Full client profile people/ alice.md <- Contact details, preferences bob.md <- Communication style, role context/ company.md <- Company overview tech-standards.md <- Universal code standards CODE_BLOCK: mkdir -p ~/.claude touch ~/.claude/CLAUDE.md Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: mkdir -p ~/.claude touch ~/.claude/CLAUDE.md CODE_BLOCK: mkdir -p ~/.claude touch ~/.claude/CLAUDE.md COMMAND_BLOCK: # Your Name ## Identity Your role. Your timezone. ## Preferences - List your coding style preferences - List your communication preferences - List your absolute rules (things AI should never do) ## Folder Map Where your projects live. ## Critical Rules 1. Security rules (never commit secrets) 2. Architecture rules (DI, file organization) 3. Tool rules (which MCP servers to use) Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # Your Name ## Identity Your role. Your timezone. ## Preferences - List your coding style preferences - List your communication preferences - List your absolute rules (things AI should never do) ## Folder Map Where your projects live. ## Critical Rules 1. Security rules (never commit secrets) 2. Architecture rules (DI, file organization) 3. Tool rules (which MCP servers to use) COMMAND_BLOCK: # Your Name ## Identity Your role. Your timezone. ## Preferences - List your coding style preferences - List your communication preferences - List your absolute rules (things AI should never do) ## Folder Map Where your projects live. ## Critical Rules 1. Security rules (never commit secrets) 2. Architecture rules (DI, file organization) 3. Tool rules (which MCP servers to use) CODE_BLOCK: mkdir -p ~/.claude/memory/context Enter fullscreen mode Exit fullscreen mode CODE_BLOCK: mkdir -p ~/.claude/memory/context CODE_BLOCK: mkdir -p ~/.claude/memory/context COMMAND_BLOCK: # Project Name ## Stack What technologies this project uses. ## Commands How to run, build, test, deploy. ## Architecture Key patterns and conventions specific to this project. ## Current Focus What you are actively working on. Enter fullscreen mode Exit fullscreen mode COMMAND_BLOCK: # Project Name ## Stack What technologies this project uses. ## Commands How to run, build, test, deploy. ## Architecture Key patterns and conventions specific to this project. ## Current Focus What you are actively working on. COMMAND_BLOCK: # Project Name ## Stack What technologies this project uses. ## Commands How to run, build, test, deploy. ## Architecture Key patterns and conventions specific to this project. ## Current Focus What you are actively working on. - Loaded: Global CLAUDE.md + Client One's CLAUDE.md - Available on demand: Deep storage (glossary, tech standards) - Not loaded: Client Two's CLAUDE.md, Client Three's CLAUDE.md - Loaded: Global CLAUDE.md + Internal CLAUDE.md - Available on demand: Deep storage - Not loaded: Any client-specific context - Loaded: Global CLAUDE.md only - Available on demand: Deep storage - Not loaded: Any project or client context - I finish work on Client One. Close the terminal. - I open a new terminal in Client Two's directory. - Claude Code starts. It reads the global context (knows who I am, my preferences, all client shorthand). It reads Client Two's CLAUDE.md (knows the stack, conventions, current sprint). - I type: "Add input validation to the submission endpoint." - Claude already knows Client Two uses FastAPI, that validation should use Pydantic models, that tests go in tests/, and that I want dependency injection. It writes the code correctly on the first try. - Add one row to the Active Clients table in the global CLAUDE.md. - Create the client's project directory with its own CLAUDE.md. - Optionally add a client profile to ~/.claude/memory/clients/. - Email [email protected] - Location Chicago - Joined Feb 13, 2026