Org Context Layer: Four Layers That Make Claude an Insider (No Fine-Tuning)

First time you point Claude at a real codebase, it behaves like a brilliant contractor who has never seen your org chart, your deployment topology, or your naming conventions. Every question needs preamble. Every answer needs correction. The coordination tax is the entire interaction.

A context layer is the structural fix. Not fine-tuning. Not a custom model. A deliberate architecture of context files, skill definitions, live data connections, and entity relationships that load the right information at the right time, scoped to the task in front of it.^[4] Teams that build all four layers cut correction cycles by more than half inside the first month.

Four layers, each tuned to a different access pattern: always-on slow facts, on-demand domain skills, live real-time data, and a persistent entity graph. Most teams get Layer 1 right and stop. The teams that build all four report fewer corrections, fewer hallucinations about internal systems, and far less time spent re-explaining context the assistant should already have. One honest caveat: Layer 4 is hard to maintain. If your organizational data is scattered across Jira, Slack, and Notion with no source of truth, the entity graph will cost more than it returns for the first six months. Build it last, on purpose.

CLAUDE.md is the first file the assistant reads when it enters your project.^[1] Treat it as the employee handbook plus the architecture decision record plus the tribal knowledge that lives in three Slack threads and one engineer's head. Most teams treat it as a README. That is the mistake.

The always-on layer holds slow facts — information with a long shelf life that applies to almost every interaction. Tech stack and versions. Deployment targets. Naming conventions. Testing philosophy. Directory structure. The specific things a new hire would need on day one to avoid an embarrassing first commit.

Anthropics's own documentation recommends keeping CLAUDE.md under 200 lines.^[6] That number is a forcing function, not an aesthetic preference. CLAUDE.md loads at session start and stays loaded across every turn of every conversation. A 5,000-token file costs 5,000 tokens before you've typed a word — then again on every subsequent message. The fix is not to keep the file sparse; it's to move procedure and domain-specific knowledge into Layer 2 skills, where they cost nothing until invoked.

What does not belong here: anything that changes weekly, anything specific to a single feature, and anything that reads like a procedure rather than a fact. If a CLAUDE.md section has grown into a multi-step deployment workflow, it belongs in a skill. If it describes Stripe webhook handling, it belongs in a payments skill. The file passes when you can state its content as a set of invariants — things that are always true about this codebase — rather than a set of instructions.

Layer 2 fixes the budget problem. Your organization has deep knowledge about payments, authentication, onboarding, billing, compliance, and a dozen other domains. Loading all of it into every interaction wastes tokens and dilutes the signal until the assistant treats noise like instruction.^[2]

Skill files are domain-specific context packages that load on demand. Each skill is a directory with a SKILL.md file holding instructions, conventions, and resources for that domain. Task is about payments — the payments skill loads. Task shifts to authentication — the auth skill loads, the payments skill drops out.^[2]

The mechanism that makes this work is YAML frontmatter in the SKILL.md file. The description field tells the assistant what this skill covers and when to activate it. The content below the frontmatter carries the actual instructions. Claude reads the description first (low cost), then loads the full skill body only when the task matches.^[6] This is progressive disclosure: metadata first, instructions on match, supporting resource files only when explicitly referenced.

The mechanism lets you maintain a library of 50+ skills without any of them consuming context until the task makes them relevant. Without progressive disclosure, you'd be choosing between coverage and budget. With it, you stop choosing.

One failure mode to watch: skills whose description field is too broad. A skill described as 'handles backend work' activates on nearly every engineering task — defeating progressive disclosure entirely. Write descriptions as trigger conditions: 'Use when working with Stripe payments, webhooks, or refund flows.' Specific triggers mean the skill loads when it should, stays dormant when it shouldn't.

Layers 1 and 2 carry static knowledge — things you write down and update on a cadence. Layer 3 carries the information that changes faster than anyone documents it. Current database schema. State of the CI pipeline. The Notion page edited an hour ago. The latest production error log.

MCP connections give the assistant runtime access to external systems.^[1] Instead of pasting a schema or describing an error log by memory, the assistant queries the source and operates on the current state. The source is the truth. The doc is a snapshot that lies the moment it stops being maintained.

Here is the failure mode most teams discover after they've already committed to twelve MCP servers: each well-documented MCP tool definition consumes 500–1,500 tokens at initialization.^[7] A server with 50 tools costs 25,000–75,000 tokens before you've typed a single prompt. A typical enterprise stack — GitHub MCP, Jira, Notion, database schema, CI/CD — can consume 100,000–200,000 tokens before the conversation starts, leaving almost no room for actual work on a 200,000-token context window.^[7]

Claude Code's answer to this is deferred loading: by default, MCP tool definitions are not injected up-front; only tool names enter context until Claude calls a specific tool.^[6] That deferred model only holds if you're running a current version and haven't overridden the behavior. Verify it. Run /mcp to see what's connected and /usage to see how much of your context window the current configuration is consuming.

The leverage point in Layer 3 is which connections live always-on versus which sit behind explicit invocation. Database schema is relevant to almost every code task — keep it always-on. Production logs only matter during debugging — keep them on-demand. Analytics only matter during reporting tasks. Default to on-demand. Promote to always-on only when the connection earns it across most interactions.

Layer 4 is where the context layer stops being useful and starts being structural. An entity graph stores the relationships between projects, teams, people, decisions, and systems. When the assistant knows that the payments team owns the Stripe integration, that Sarah is the tech lead, that the team migrated from REST to tRPC last quarter, and that there's an open RFC about webhook retry logic — answers start accounting for organizational reality, not just technical correctness.

Context graphs connect entities, events, decisions, policies, and evidence so the assistant can answer why, not just what.^[3] Most implementations converge on a durable master graph plus query-specific subgraphs that load into context based on the task in flight.^[3]

This is the hardest layer because the data is the most dispersed. Team ownership lives in the 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 the docs nobody updates. Building the graph means pulling from every one of those sources and maintaining edges as they drift.

Drift is the default state of any graph without an owner. Knowledge graphs reduce hallucination rates significantly when properly maintained — but 'properly maintained' is the constraint.^[8] Pick the owner before you pick the schema. Define the update cadence before you write the first edge. If neither of those decisions can happen in the next sprint, skip Layer 4 for now and revisit in six months when you have more organizational context on where the assistant's blind spots actually hurt.

The most common failure mode in building a context layer is shoving everything into CLAUDE.md. The second most common is having no framework for placement, which produces the same result eventually.^[5]

Three variables decide where knowledge belongs.

Access frequency. How often does this matter? Almost every interaction — Layer 1. Only when working on payments — Layer 2. Only during production debugging — Layer 3.

Update rate. How fast does it drift? Slow facts (monthly or less) — Layers 1–2. Fast facts (daily or weekly) — Layer 3. Relationship data that evolves gradually — Layer 4.

Context size. How many tokens does it cost? Large knowledge — full schemas, complete API docs — never always-on. Load through Layer 2 skills or Layer 3 MCP. Small knowledge — naming conventions, deploy targets — can earn the always-on slot.

Run every new piece of knowledge through these three. The answer falls out. The mistake comes from skipping the question.