CLAUDE.md and Agent Context Files for Codebase Onboarding

How reliably a coding agent works inside an existing codebase depends less on which model sits behind it than on the context file it loads before the first prompt. CLAUDE.md and AGENTS.md are the infrastructure that shapes whether an agent writes code that fits the codebase or code that merely compiles. Every new agent session starts with no memory of what came before it, a condition structurally identical to onboarding an engineer who arrives each morning having forgotten the entire previous shift. An agent has none of that. It reads only what has been explicitly written into its context file, and that file loads in full before a single instruction is typed.

The failure mode that follows from this asymmetry is quiet. When an agent works without sufficient context, it does not throw an error and stop. It produces a plausible, syntactically correct solution that applies a deprecated pattern, ignores an architectural boundary the team cares about, or drifts from a convention nobody thought to write down. Given how much weight these files carry, the question that matters is structural: how should a team actually organize them, across tools, across a hierarchy, and across the life of a codebase, so that an agent entering unfamiliar code behaves like a well-briefed engineer rather than a confident stranger?

What CLAUDE.md and AGENTS.md actually do and how they differ

CLAUDE.md is Claude Code's native context file. It is injected into every conversation and supports a hierarchy: a global file at ~/.claude/CLAUDE.md, a project-root file at./CLAUDE.md or./.claude/CLAUDE.md, local per-project files at./CLAUDE.local.md, and per-directory files picked up through directory-tree traversal as the agent moves through the repo. CLAUDE.md can also import other files by reference, which keeps the root file organizationally short, but an imported file still loads fully into context at launch, so importing doesn't reduce what the model has to process, only how the content is organized on disk.

AGENTS.md serves a different purpose. It is not tied to one harness. If a team uses multiple coding agents built by different vendors, AGENTS.md is the one file every agent can read, so institutional knowledge stays in a single place instead of scattered across per-tool copies that drift out of sync with each other. So the two files are not opposites in capability. CLAUDE.md's edge is in its native integration with Claude Code's specific features, including file imports and tight coupling to hooks and subagents. AGENTS.md's edge is portability: a single file that every tool on a team can read without translation. Neither file is the obviously correct choice on its own. The choice depends on what a team values more, native depth for one tool or shared coverage across several.

Claude Code 2.1.277's AGENTS.md Fallback and the Maintenance Calculus

Anthropic shipped AGENTS.md support directly into Claude Code 2.1.277 on September 18, 2026. The behavior is straightforward: if a folder has no CLAUDE.md, Claude Code now checks for an AGENTS.md file and uses it instead. If both files exist in the same location, CLAUDE.md still takes precedence. AGENTS.md works as a fallback, not a replacement, so Claude-Code-specific capabilities such as file imports stay tied to CLAUDE.md, because a generic cross-tool file isn't built to carry harness-specific syntax.

The decision to implement this as a fallback rather than a merge matters for how predictable agent behavior stays. Merging two files that might give contradictory instructions would create ambiguity exactly where ambiguity is most expensive: inside an autonomous system making file-level decisions across a codebase. A clear precedence rule avoids that failure mode entirely, trading some flexibility for a result that is easy to reason about and easy to debug when something goes wrong.

The fallback was delivered as a Claude Code Mod, part of Anthropic's new system for customizing the harness itself, with the source published at anthropics/claude-code/tree/main/mods/agents-md. The practical consequence for most teams is simpler than the mechanism behind it: a project that has already standardized on AGENTS.md for cross-tool compatibility no longer needs a separate CLAUDE.md just to get Claude Code to pick up the same project context. One file now does the job that used to require two.

The dual-file pattern that gives teams cross-tool coverage without duplication

The fallback behavior in 2.1.277 makes a specific structural pattern the sensible default for most teams. Put all shared, tool-agnostic project context, build commands, architecture overview, conventions, testing rules, into AGENTS.md, and let CLAUDE.md defer to it.

Two implementations accomplish this. The wrapper approach takes a little more setup, but it leaves room for Claude-specific behavior that a symlink can't hold.

Vendor-specific behavior should stay out of the shared file regardless of which implementation a team picks. Hooks, skills, and model preferences belong in each tool's own configuration, not in AGENTS.md, where an agent from a different vendor would read them as irrelevant noise cluttering otherwise useful context.

Teams migrating toward this pattern should be careful about one thing in particular: simply renaming an existing CLAUDE.md to AGENTS.md and calling the migration finished leaves real performance on the table. If you write and tune content for how one model follows instructions, you don't automatically get the same compliance from a different model reading the same words. The underlying guidance may be sound, but the phrasing that made one agent reliable won't necessarily make another agent just as reliable.

The HZDigital team's production setup shows what the pattern looks like when it's working. The team built AGENTS.md as its provider-neutral onboarding file, covering the architecture map, build and test commands, security guardrails, and agent workflow rules including branch naming, PR templates, and commit style. In that setup, CLAUDE.md is just a thin file that imports AGENTS.md. Any agent on the team reads the same institutional knowledge no matter which harness runs the session, and Claude Code still gets its own layer of Claude-specific instruction, with no second copy of the shared material to keep in sync.

Structuring CLAUDE.md Hierarchically for Monorepos

The dual-file pattern solves cross-tool duplication, but a second structural problem appears at scale that the dual-file pattern alone doesn't address: a single long root file loads in full every session, and the more rules it accumulates, the less reliably an agent follows any individual one of them. A flat file that tries to cover an entire monorepo, every package, every service, every edge case a team has ever hit, becomes self-defeating. The volume of instructions competes against the depth of adherence to each.

The fix is a three-tier architecture. The root CLAUDE.md should stay under roughly 200 lines: a repo-wide overview, shared commands, and the small set of gotchas that apply everywhere, kept lean enough that every rule in it is actually acted on. Above both sits an on-demand reference layer: directories such as.claude/skills/ for task-specific playbooks and docs/agent-guides/ for deeper reference material, structured so an agent pulls in only what the current job actually requires.

File imports help keep the root file short without sacrificing depth. A line such as @docs/architecture.md pulls existing architecture documentation into context by reference rather than requiring the content to be copied directly into CLAUDE.md. The imported file still expands fully into context at launch, so the benefit is organizational clarity on disk, not a reduction in what the model has to read.

Shared monorepos introduce one more wrinkle: ancestor CLAUDE.md files belonging to other teams get picked up automatically by directory-tree traversal, whether or not they're relevant to the work at hand. The claudeMdExcludes setting, configurable in.claude/settings.local.json or any other settings scope, suppresses specific files by glob pattern, keeping one team's context out of another team's sessions.

For codebases carrying genuine legacy weight, path-scoped rules earn their keep. A note such as "this module uses a deprecated pattern, migrate via X," placed in a.claude/rules/ file scoped to that specific path, loads exactly when the agent touches that code and stays out of context everywhere else. And for a codebase with no context file at all, the /init command reads the existing project structure, package.json, folder layout, an existing README, recognizable patterns, and generates a starting CLAUDE.md from what it finds. That output is a first draft, not a finished document.

What to Put in an Agent Context File

What a context file leaves out matters as much as what it includes. A file documented too heavily degrades compliance across every rule in it. A file documented too lightly leaves an agent to rediscover legacy traps the hard way, one mistake at a time.

Some material earns a place in the shared layer without much debate. Build and test commands belong there: what to run, in what order, and what a passing state actually looks like. Security and compliance guardrails specific to the codebase matter in any regulated environment.

Other material should be cut on sight. Anything a linter, formatter, or static analysis tool already enforces doesn't belong in prose instructions, because the agent will comply with the tool's hard constraint regardless of what the file says, making the written rule redundant. Anything derivable from a few minutes of reading the code is better left undocumented, since every line in the file competes for the model's limited adherence. Secrets of any kind have no place in a context file under any circumstance. And vendor-specific behavior, hooks, skills, model preferences, belongs in each tool's own configuration.

The sharpest constraint on all of this is a compliance ceiling that most teams never measure directly. Frontier models follow roughly 150 to 200 instructions reliably before compliance begins to drop off, and most long-lived context files exceed that threshold without anyone noticing the file has grown past it. The practical response to this ceiling is to treat it as a budget: a rule that has to happen every single time without exception shouldn't be an instruction competing for space in that budget. It should become a hook, enforced directly by the harness.

How agent memory layers extend context beyond what a static file can hold

A static context file has a hard limit: it captures what the team knew at the moment someone wrote it, not what an agent discovers while working. Every new session starts from that same fixed baseline, regardless of what a previous session figured out an hour or a week earlier.

Auto Memory addresses the implicit, learned side of that gap. Introduced in Claude Code v2.1.59, Auto Memory discovers project-specific patterns during a session and writes them back autonomously to MEMORY.md, with the first 200 lines or 25KB, whichever limit comes first, loading at the start of the next session. Over time, this accumulates build quirks and debugging insights that no one on the team ever sat down to document, because no one knew to document them until an agent ran into them directly.

Subagent Memory, introduced in Claude Code v2.1.33 in February 2026, extends persistence to a finer grain. Before this capability existed, every subagent invocation started from zero regardless of how many times that same subagent had run against the same codebase previously.

Claude Code Projects, launched September 17, 2026, shifts the unit of work itself, from a single chat session to a persistent workspace that spans many sessions over time. A context file and a memory layer together form the full picture: one holds what the team knows in advance, the other holds what the agent has learned in the course of doing the work.

How Context Files Rot and How to Maintain Them

A context file that was accurate the day it was written degrades over time without producing any visible error. None of this throws a warning. The file looks complete and unchanged, right up until the agent starts making mistakes it wasn't making months before, and no one traces the regression back to the file because the file has stayed visibly the same.

Treated correctly, though, the same file becomes a living institutional record. Every time an agent makes a mistake because it lacked some piece of context, that gap is a candidate for a new line in the file. Maintained this way over months, a context file accumulates knowledge that's useful well beyond agent sessions, becoming a document new human engineers can read to understand the same traps and conventions an agent has already been warned about.

Keeping it in that state takes deliberate maintenance, not periodic neglect followed by a rewrite. The file deserves a quarterly review with the same seriousness a team gives to CI configuration, an audit of what's still true. Any rule the agent could infer directly from reading the code should be deleted rather than left to compete for space with rules that actually need stating. If a rule must happen without exception, it should become a hook, because hooks are enforced deterministically by the harness, while instructions stay suggestions a model may or may not follow under pressure. And teams should watch directly for rules the agent appears to be ignoring, since that's a reliable sign the file has grown too long, too contradictory, or both at once.

The InstructionsLoaded hook offers a concrete diagnostic here: it logs which instruction files loaded in a given session and the reason each one loaded, which is useful for catching path-scoped rules that should have fired for a given directory and didn't. A context file is infrastructure, and like any other infrastructure a team depends on, it only stays trustworthy for as long as someone keeps checking that it still matches the codebase it describes.