Context Files and Kits

Overview

In the previous lesson, we saw that context is a finite resource and that agents must be selective about what they load into their working memory. But if CLAUDE.md is the only place to put project context, you face a dilemma: make it comprehensive and burn context budget on every session, or keep it lean and leave agents without important details. Context files solve this by distributing context across the codebase, placing it where it is needed and letting agents load it on demand. Context kits take this further by automatically selecting and assembling the right context for each task.

The CLAUDE.md Scaling Problem

CLAUDE.md works brilliantly for small projects. You write 30-50 lines of build commands, conventions, and key rules, and every agent session starts with exactly the right context. But as your project grows, pressure builds to add more:

• API design patterns for the backend team
• Component conventions for the frontend team
• Database migration rules
• Deployment procedures
• Security constraints
• Service-specific debugging tips

Before long, your CLAUDE.md is 400 lines. Every agent session loads all 400 lines, even when the agent is only working on a single utility function that needs none of that information. You are paying the context tax on every session.

The CLAUDE.md scaling problem: a small project with a 30-line CLAUDE.md costs ~500 tokens (minimal). A growing project with 200 lines costs ~3,000 tokens (acceptable). A large project with 500 lines costs ~8,000 tokens (4% of the context window wasted on mostly irrelevant content).

The solution is not to stop documenting. It is to distribute the documentation so that each piece lives close to the code it describes and gets loaded only when the agent is actually working in that area.

What Is a .ctx File?

A .ctx file is a convention some teams adopt for describing a specific directory or component in their codebase. It lives alongside the code it documents and serves as a local context document for that area.

Unlike CLAUDE.md files (which Claude Code automatically discovers and loads), .ctx files are not a Claude Code platform primitive. They require custom tooling or explicit instructions for agents to find and read them. Think of .ctx as a team convention, not a platform feature.

That said, the pattern is useful. Think of it like a local tour guide. CLAUDE.md is the guidebook for the entire city. A .ctx file is the placard at a specific building explaining what it is, why it exists, and what you need to know to work on it.

The .ctx file answers the questions an agent would ask when it enters a directory: What is this? What matters here? What should I know before changing things? Note that agents need to be instructed (via CLAUDE.md or a system prompt) to look for .ctx files -- they will not discover them automatically.

Anatomy of a Good .ctx File

An effective .ctx file has four sections, each serving a distinct purpose:

Purpose. One to three sentences explaining what this directory does and how it fits into the broader system. This is the most important section -- it prevents the agent from misunderstanding the role of the code.

Key Files. A curated list of the most important files with one-line descriptions. Not every file -- just the ones the agent needs to know about to navigate effectively.

Patterns. The conventions specific to this part of the codebase. These are the rules that differ from or extend the root CLAUDE.md. If the API layer has specific patterns that do not apply elsewhere, they go here.

Testing. How to run tests for this specific area, especially if the command differs from the project-wide test command.

Key principle: .ctx files describe the why and the how, not the what. The agent can read the code to see what functions exist. What it cannot infer from code alone is why the code is structured this way and what rules to follow when modifying it.

.ctx Files vs. Nested CLAUDE.md

You might wonder: "Why not just use nested CLAUDE.md files in subdirectories?" Both approaches distribute context, but they have different tradeoffs.

Nested CLAUDE.md files are the platform-supported mechanism. Claude Code automatically discovers and loads them when working in a directory. They require no custom tooling. Claude Code also supports .claude/rules/ files with a paths frontmatter field for targeting specific file patterns. These are the native, built-in approaches.

.ctx files are a team convention that requires custom tooling or explicit CLAUDE.md instructions (e.g., "when entering a new directory, check for a .ctx file") for agents to discover and load. They offer a more structured format and can be indexed by custom tools, but they are not automatically processed by any standard agent platform.

In practice, many teams use nested CLAUDE.md for high-level package boundaries and .ctx files for finer-grained directory context where they have invested in the tooling. If you are starting fresh, nested CLAUDE.md and .claude/rules/ are the simpler choice because they work out of the box.

Context Kits: Automated Context Selection

Writing .ctx files distributes your documentation, but the agent still has to find and read the right ones. Context kits are a design pattern for automating this step. If you build or adopt a context selection tool, here is how the pattern works: given a task description, a context kit selects the most relevant context files and assembles them into a context pack -- a focused bundle of information tailored to the current task.

Context kit in action: a developer requests 'Fix the email retry logic.' The context kit selects relevant .ctx files (src/workers/ and src/services/email/) plus the root CLAUDE.md, skipping irrelevant ones (src/api/ and src/frontend/). The selected files are assembled into a focused context pack for the agent.

The context kit looks at the task, identifies which parts of the codebase are likely involved, and loads only those .ctx files. The agent starts with a focused view instead of a generic one.

Building a Context Index

For a context kit to select the right files, it needs an index -- a map of all .ctx files in the repository and what they cover. One possible implementation stores this in an index file at the root of the project. Here is an example of what such an index might look like:

An index like this would let a context kit quickly match a task to relevant directories without reading every .ctx file. When you ask the agent to "fix the email retry logic," the kit scans the index for topics matching "email," "retry," "workers," and "queues," then loads only those .ctx files.

Writing Effective .ctx Files

The difference between a helpful .ctx file and a wasteful one comes down to a few principles:

Be concise. A .ctx file should be 10-30 lines. If it is longer, you are probably duplicating information that is already in the code. Remember, every line costs tokens.

Focus on the non-obvious. The agent can read function signatures and class names from code. What it cannot infer is the intent behind design decisions, the relationships between directories, and the rules that are not enforced by the compiler.

Keep it current. A stale .ctx file is worse than no .ctx file. If it describes patterns that no longer exist, the agent will follow outdated guidance. Treat .ctx files like code: update them when you change the code they describe.

Link, do not embed. Instead of pasting example code into the .ctx file, reference the file that contains the canonical example. This keeps the .ctx file short and avoids duplication that drifts over time.

Practical Workflow

Here is how .ctx files fit into a typical development workflow:

1. Initial setup. When making a codebase agent-ready, create .ctx files for each major directory. Start with the ones agents visit most.

2. During development. When you create a new directory or significantly restructure an existing one, create or update its .ctx file.

3. During code review. If a PR changes the patterns in a directory, check whether the .ctx file needs updating. Some teams add this to their PR checklist.

4. Periodically. If you use an index, regenerate it to keep it in sync. Some teams automate this in CI.

Tip: Start with .ctx files for the three directories agents work in most often. You can expand from there. Do not try to cover every directory on day one.

Summary

• CLAUDE.md does not scale -- as projects grow, a single file becomes bloated with context that is irrelevant to most tasks
• .ctx files are a team convention (not a platform primitive) that distributes context across the codebase, placing documentation next to the code it describes
• Claude Code natively supports nested CLAUDE.md files and .claude/rules/ with paths frontmatter -- these are the platform-supported mechanisms for distributing context
• .ctx files require custom tooling or explicit instructions for agents to discover them
• A good .ctx file has four sections: Purpose, Key Files, Patterns, and Testing -- kept to 10-30 lines
• Context kits are a design pattern for automatically selecting relevant .ctx files based on the task, assembling a focused context pack
• A context index maps all context files in the repo, enabling fast lookup -- the format and tooling are up to your team
• .ctx files should describe the why and the how, not duplicate the what that agents can read from code
• Keep .ctx files concise, current, and referential -- link to canonical examples rather than embedding them