A CLAUDE.md is the entry point. But a single file can't hold everything an AI needs to work effectively across a real project. What about decisions that were made three months ago? Architecture rules that apply only to the backend? The specific domain logic a new contributor would need two weeks to learn organically?
Context file patterns solve this by distributing project knowledge into purpose-built files. Each file has a specific job: one holds architectural decisions, one holds domain vocabulary, one holds the operational rules that change week to week. Together they form a system — and the system is what persists information across sessions, across contributors, and across time.
NIST MAP asks you to catalog what you know about your AI system's context and constraints. A context file system is how you do that in practice for an AI coding assistant. This module builds that system from scratch.
A developer returns to a project after six months away. The project is a subscription billing platform — Stripe integration, PostgreSQL, a React frontend, a Node.js API. There's a CLAUDE.md. It was written at project start and updated twice since.
The first AI session goes badly. The AI generates code that ignores a critical domain rule: subscription downgrades have a 30-day cooling-off period before they take effect, to prevent abuse of proration credits. This rule isn't in the CLAUDE.md. It was understood by everyone on the team when the billing logic was written. It was never written down.
The second session goes better, but the AI keeps reaching for an authentication pattern that was deprecated eight months ago when the team switched to a token-based approach. The migration is complete. The old code is still in the codebase for legacy support. The CLAUDE.md mentions the new approach but doesn't say the old one is banned.
The third session surfaces a different problem. The AI generates a database migration that violates the team's strict convention: all migrations must be backward-compatible for at least one release cycle. This convention exists because of a painful production incident. It's documented in a Notion page that the CLAUDE.md doesn't reference.
Each failure has the same root cause. The project has knowledge that lives in team memory, in historical incident notes, in documented conventions — but none of it is in the AI's context window. The CLAUDE.md was never designed to hold all of this. Something else has to.
Not all project knowledge belongs in the same file. The mistake teams make is treating the CLAUDE.md as a dump for everything the AI "should know." That file becomes bloated, inconsistently maintained, and eventually ignored. The solution is a typed system.
What it is: Technical constraints, project identity, architectural decisions, banned patterns, workflow rules. This is the file an AI reads before it does anything. It answers: what am I working on, what are the rules, what must I never do? Keep it focused. If you find yourself adding domain facts, move them elsewhere.
What it is: Business rules, domain vocabulary, invariants that are always true regardless of what the AI is building. "Subscription downgrades have a 30-day cooling-off period" is domain context. "All prices are stored in cents, never floats" is domain context. These are facts about the problem space, not the codebase. They belong in a dedicated file that can be updated independently of architectural decisions.
What it is: Team conventions, incident-derived rules, patterns that must be followed everywhere. These often originate from a painful experience — a production incident, a security review, a migration that broke things. They're operational rather than architectural. A rules directory with focused files (db-rules.md, api-rules.md, test-rules.md) keeps these scannable and maintainable.
What it is: The current state of work — what was done last session, what's in progress, what decisions were deferred, what the next session should pick up. This is ephemeral context, updated at the end of every session and read at the start of the next. It's the AI's short-term memory made durable. Module 6 goes deep on this pattern.
The MAP function asks organizations to catalog what they know about the context in which an AI system operates — including data characteristics, constraints, and limitations. A context file system is the practical implementation of MAP for an AI coding assistant. Each file type maps a different layer of project context that the AI must understand to behave reliably.
MAP also requires that tacit knowledge — the kind that lives in expert heads — be made explicit and documented. The "30-day cooling-off period" in the scenario is tacit knowledge that was never mapped. A context file system turns tacit knowledge into structured, AI-readable documentation without requiring anyone to relearn it every session.
Context files fail in two ways: too vague to be useful ("follow best practices") or so dense they overwhelm the context window. These patterns keep files effective.
Write facts, not justifications. "All prices are stored in cents as integers — never use floats." That's a usable assertion. "Due to floating-point precision issues in JavaScript we decided to store prices as integer cents" is an explanation. The AI doesn't need the history; it needs the rule. Put explanations in comments if you want them preserved.
The most useful context files are explicit about what's banned. "Never use the LegacyAuth class — it was deprecated in v2.3 and exists only for backward compatibility with the mobile app's old sessions." Without that line, the AI will use LegacyAuth confidently, because it's there and it works. Document what's off-limits as clearly as what's required.
Every context file section should carry a last-verified date. "Last verified: 2025-11 — Stripe webhook version." When the date is six months old, it's a signal to verify before trusting. Context that's never dated is context that will eventually mislead. The date costs nothing to add and provides critical signal about reliability.
Each file should answer one question. ai-context.md answers: "what is true about this domain?" The rules files answer: "what must always be done?" HANDOFF.md answers: "what is true right now?" When a piece of information doesn't clearly belong in one file, that's a signal you need to clarify the file's purpose — not add a catch-all section.