The first time you use Claude on a new codebase, it feels like onboarding a brilliant contractor who has never seen your org chart, your deployment process, or your naming conventions. Every question requires preamble. Every answer needs correction. The context layer fixes this.
Building your org's context layer is the practice of structuring organizational knowledge so that Claude operates with the same baseline understanding as a senior team member. Not through fine-tuning or custom models — through a deliberate architecture of context files, skill definitions, live data connections, and entity relationships that load the right information at the right time.[4]
The architecture has four layers, each optimized for a different access pattern: always-on slow facts, on-demand domain skills, live real-time data, and a persistent entity graph of your organizational knowledge. Most teams get the first layer right and stop. The teams that build all four report a measurable difference in output quality — fewer corrections, fewer hallucinations about internal systems, and dramatically less time spent re-explaining context.
Layer 1: Always-On Context — CLAUDE.md and Slow Facts
The foundation. Information that is true today and will be true next month.
CLAUDE.md is the first file Claude reads when it enters your project.[1] It is the organizational equivalent of the employee handbook plus the architecture decision record plus the "things we do differently here" tribal knowledge document. And most teams underutilize it dramatically.
The always-on layer should contain slow facts — information with a long shelf life that applies to virtually every interaction. Your tech stack and versions. Your deployment targets. Your naming conventions. Your testing philosophy. The directory structure and what lives where. The things a new hire would need to know on day one to avoid making embarrassing commits.
What does not belong in Layer 1: anything that changes weekly, anything specific to a single domain or feature, and anything that consumes more than 10-15% of the context window. CLAUDE.md is not a knowledge dump — it is a carefully curated set of universal truths about your organization.
CLAUDE.md# Acme Corp — Engineering Context
## Tech Stack
- Framework: Next.js 16 (App Router) with React 19
- Language: TypeScript 5 (strict mode)
- Database: PostgreSQL 16 via Drizzle ORM
- Deployment: Vercel (production), Railway (staging)
- Package manager: pnpm
## Conventions
- File naming: kebab-case for files, PascalCase for components
- Tests colocated with source files as `*.test.ts`
- API routes return `{ data, error, meta }` envelope
- All database queries go through `/lib/db/queries/`
- Never import from `@internal/` packages directly
## Architecture Decisions
- Server Components by default; Client Components only for interactivity
- No global state management — use server state + URL state
- Feature flags via LaunchDarkly, accessed through `/lib/flags.ts`
## What NOT to do
- Never commit .env files or API keys
- Never use `any` type — use `unknown` and narrow
- Never bypass the lint-staged hooksLayer 2: On-Demand Context — Skill Files per Domain
Domain-specific knowledge that loads only when the task requires it.
Layer 2 solves the context window budget problem. Your organization has deep knowledge about payments, authentication, onboarding, billing, compliance, and a dozen other domains. Loading all of that into every interaction wastes tokens and dilutes the signal-to-noise ratio.[2]
Skill files are domain-specific context packages that load on demand. Each skill is a folder containing a SKILL.md file with instructions, conventions, and resources specific to that domain. When Claude encounters a task related to payments, the payment skill loads. When the task shifts to authentication, the auth skill loads instead.[2]
Claude's progressive disclosure system handles this in three tiers: metadata loads first (skill name, description, trigger conditions), then instructions load when the skill is activated, and finally resources and examples load when they are specifically needed. This means you can maintain a library of 50+ skills without any of them consuming context until they are relevant.
Skill File Organization
tree.claude/
├── commands/
│ ├── deploy.md
│ ├── create-migration.md
│ └── generate-api-route.md
└── skills/
├── payments/
│ ├── SKILL.md
│ ├── stripe-conventions.md
│ └── refund-flow.md
├── auth/
│ ├── SKILL.md
│ ├── session-management.md
│ └── rbac-model.md
└── onboarding/
├── SKILL.md
├── wizard-steps.md
└── trial-logic.md| Characteristic | Layer 1 (CLAUDE.md) | Layer 2 (Skill Files) |
|---|---|---|
| Update frequency | Monthly or less | Weekly to monthly |
| Scope | Entire organization | Single domain or feature area |
| Loading behavior | Always loaded | Loaded on demand when relevant |
| Token budget | 10-15% of context window max | 5-10% per skill when active |
| Content type | Stack, conventions, architecture | Domain logic, API patterns, edge cases |
| Who maintains it | Tech lead or platform team | Domain team or feature owner |
| Examples | Naming conventions, deploy targets | Stripe webhook handling, auth session flow |
Layer 3: Live Context — MCP Connections for Real-Time Data
When Claude needs current state, not documented knowledge.
Layers 1 and 2 handle static knowledge — things you write down and update periodically. Layer 3 handles the information that changes too fast to document: your current database schema, the state of your CI pipeline, the contents of a Notion page that was edited this morning, the latest error logs from production.
Model Context Protocol (MCP) connections give Claude real-time access to external systems.[1] Instead of you copy-pasting a database schema or describing an error log, Claude queries the system directly and works with the current state.
The key design decision in Layer 3 is which connections to make always-available and which to keep behind explicit invocation. A database schema browser might be always-on because schema knowledge is relevant to almost every code task. A production log viewer might be invocation-only because it is only needed during debugging sessions. An analytics MCP might only connect during reporting tasks.
Always-On MCP Connections
- ✓
Database schema browser — relevant to most code generation tasks
- ✓
Git status and recent commit history — relevant to understanding current work
- ✓
Project configuration and environment variables (names, not values)
- ✓
CI/CD pipeline status — relevant to deployment and testing decisions
On-Demand MCP Connections
Production error logs — activated during debugging workflows
Analytics and metrics dashboards — activated during reporting tasks
Notion or Confluence pages — activated when referencing documentation
Slack channel history — activated when researching team decisions
Calendar and scheduling — activated for planning and coordination tasks
Layer 4: Episodic Context — The Organizational Entity Graph
Projects, teams, people, and their relationships — the knowledge that makes Claude feel like a colleague.
Layer 4 is where the context layer goes from useful to transformative. An entity graph stores the relationships between projects, teams, people, decisions, and systems in your organization. When Claude knows that the payments team owns the Stripe integration, that Sarah is the tech lead, that the team recently migrated from REST to tRPC, and that there is an open RFC about webhook retry logic — it can provide answers that account for organizational reality, not just technical correctness.
Context graphs connect entities, events, decisions, policies, and evidence so that the assistant can answer why, not just what.[3] Most implementations converge on a durable master graph plus query-specific subgraphs that are loaded into context based on the current task.[3]
The entity graph is the hardest layer to build because the data is the most dispersed. Team ownership lives in your org chart tool. Project relationships live in Jira or Linear. Decision history lives in RFCs, Slack threads, and meeting notes. Architecture relationships live in code and documentation. Building the graph requires pulling from all of these sources and maintaining relationships as they evolve.
- 1
Start with Layer 1 — write a comprehensive CLAUDE.md
Audit your existing onboarding docs, architecture decisions, and coding conventions. Distill the slow facts into a single file. Test it by asking Claude to explain your project structure — if it gets it wrong, your CLAUDE.md is missing information.
- 2
Build Layer 2 — create skill files for your top 3 domains
Identify the three domains where Claude is most frequently wrong or needs the most correction. Write skill files for those domains first. Each skill should contain domain-specific conventions, common patterns, and edge cases.
- 3
Connect Layer 3 — add MCP servers for your most-referenced data
Start with the data sources your team references most during coding: database schema, CI status, and documentation. Add production monitoring and analytics connections as on-demand servers.
- 4
Design Layer 4 — map your organizational entities and relationships
Start with a simple graph: teams, the systems they own, and the people on each team. Expand to include project dependencies, decision history, and RFC references. Update the graph as part of your regular team processes.
The Placement Decision Framework
Access frequency, update rate, and context size determine which layer a piece of knowledge belongs in.
The most common mistake in building a context layer is putting everything in CLAUDE.md. The second most common mistake is not having a principled framework for where new knowledge goes.[5]
Three factors determine placement:
Access frequency — how often is this knowledge relevant? If the answer is "almost every interaction," it belongs in Layer 1. If it is "only when working on payments," it belongs in Layer 2. If it is "only when debugging production issues," it belongs in Layer 3.
Update rate — how often does this information change? Slow facts (monthly or less) go in Layers 1-2. Fast facts (daily or weekly) go in Layer 3. Relationship data that evolves gradually goes in Layer 4.
Context size — how many tokens does this knowledge consume? Large context (database schemas, full API documentation) should never be always-on. It should load on demand through Layer 2 skills or Layer 3 MCP connections. Small context (naming conventions, deployment targets) can afford to be always-on.
How large should CLAUDE.md be?
A practical starting range is roughly 500–1500 words, though this varies by project complexity. Anything substantially longer likely contains domain-specific knowledge that belongs in Layer 2 skill files. The CLAUDE.md should be readable in 3–5 minutes by a human — if it takes longer, you are likely overloading it. Anthropic's documentation suggests keeping it focused on universal project truths rather than comprehensive documentation, though the right length for your team should be validated empirically.
Can I have multiple CLAUDE.md files?
Yes. Claude supports CLAUDE.md at multiple levels: project root, subdirectories, and user-level. A monorepo might have a root CLAUDE.md with shared conventions and per-package CLAUDE.md files with package-specific context. The files merge hierarchically — more specific files override more general ones.
How do I measure whether my context layer is working?
Track two metrics: correction rate (how often you have to correct Claude's output about internal systems or conventions) and context re-explanation rate (how often you paste the same context into conversations). A well-built context layer should reduce both by 50% or more within the first month.
What about sensitive information in the context layer?
Never put secrets, credentials, or personally identifiable information in CLAUDE.md or skill files. For sensitive organizational data, use Layer 3 MCP connections with appropriate access controls — the data stays in the source system and is queried on demand rather than stored in plaintext files. Layer 4 entity graphs should store roles and relationships, not personal details.
Context Layer Design Rules
Never put fast-changing data in CLAUDE.md
Information that changes weekly or more frequently belongs in Layer 3 (MCP connections). Stale CLAUDE.md content is worse than no content because it teaches Claude incorrect facts about your current state.
Every skill file needs a clear trigger condition
If Claude cannot determine when to load a skill, it will either load everything (wasting context) or load nothing (missing critical domain knowledge). Write explicit trigger conditions in each SKILL.md.
Monitor context window utilization monthly
As you add layers, total context consumption grows. If always-on context (Layer 1 + always-on Layer 3) exceeds 25% of the context window, you are leaving too little room for actual conversation and code.
Treat the context layer like code — version it, review it, test it
CLAUDE.md and skill files should go through pull request review. Changes to context affect every team member's interactions with Claude. Untested changes can introduce subtle errors that are hard to trace.
We built the first layer — a solid CLAUDE.md — and it immediately cut our correction rate by roughly half. Adding skill files for payments and auth was the second-biggest win. The entity graph is where we still invest ongoing effort, because the data is scattered across so many systems.
- [1]Anthropic — Claude Code MCP Documentation(code.claude.com)↩
- [2]Intuition Labs — Claude Skills vs MCP: When to Use Each(intuitionlabs.ai)↩
- [3]Adnan Masood — Context Graphs: A Practical Guide to Governed Context for LLMs, Agents, and Knowledge Systems(medium.com)↩
- [4]Data Science Dojo — What Is Context Engineering?(datasciencedojo.com)↩
- [5]LangChain — Context Engineering for Agents(blog.langchain.com)↩