What Is a Context File?
As AI coding agents went mainstream, a new kind of file started showing up in repositories: `CLAUDE
As AI coding agents went mainstream, a new kind of file started showing up in repositories: CLAUDE.md, AGENTS.md, and similar. These are context files — and they've quietly become one of the most discussed pieces of the agentic coding workflow. Here's what they are, what goes in them, and a counterintuitive finding about how to write them.
What is a context file?
A Markdown file, placed at a project's root, that gives AI agents operational guidance they can't infer on their own: build and test commands, coding conventions, architectural decisions, constraints to respect.
The spec for AGENTS.md describes it as a README for agents — a predictable place to give AI coding agents context and instructions for working on your project. CLAUDE.md is Claude Code's version of the same idea. The agent reads the file at the start of a session, so you don't re-explain the project's rules every time.
Both formats matured fast: AGENTS.md (pioneered by OpenAI for Codex) and Anthropic's Model Context Protocol were both donated to the Linux Foundation's Agentic AI Foundation in late 2025 — a sign these conventions are becoming shared standards rather than per-vendor quirks.
What goes in a context file?
Things the agent can't discover by reading the code:
- Build and test commands — how to run, build, and verify the project
- Conventions — code style, patterns, naming the team follows
- Architecture and rationale — why certain decisions were made, so the agent doesn't refactor against them
- Constraints — what not to touch, what to always check
The guiding principle: write only what the agent can't infer for itself. Restating what's obvious from the code adds token cost without improving anything.
Should you auto-generate context files?
This is where it gets interesting. Most agents offer to generate a context file for you (Claude Code's /init, for instance), and that's a fine starting point. But there's evidence this can backfire: in some evaluations, auto-generated context files reduced task success and raised costs compared to human-curated ones — because they tend to pad context with low-signal, redundant information.
The reason: auto-generated files tend to restate what the agent could already infer, padding context without adding signal, while occasionally introducing errors. Human-curated files — written deliberately, containing only what the agent genuinely can't discover — outperformed them. The takeaway: use auto-generation as a draft, then cut it down to what only a human would know. Less, but curated, beats more, but generated.
What context files don't cover
Context files are powerful for what they are: project-scoped, in-repo guidance. But that scope is also their limit.
A context file describes a project — this codebase, its conventions, its commands. It doesn't describe you: your role, your standards across every project, the client you're building for. And it lives in one repo, read by one tool. The context that should follow you — across projects, across Claude Code and Cursor and whatever you use next — has nowhere to live in a per-project file. You also maintain it by hand, so it drifts as the project evolves.
That's a different layer. Context files handle the project; a portable context layer handles everything that should travel with you regardless of which project or tool you're in. The two work together — the file for the codebase, the layer for you.
→ The most common context file: What Is CLAUDE.md?
→ The portable layer: What Is Personal Context for AI?
