How to Write a Project Context File for AI Coding Agents

Two researchers at the University of California, Irvine read the rule files in 401 open-source repositories and sorted their content into five themes: conventions, guidelines, project information, LLM directives and examples (Jiang and Nam, arXiv). Guidelines, project information and conventions each appeared in more than eight in ten of those repositories. That matches what the tool makers recommend. A useful file answers six questions.

The commands section matters most. The agents.md FAQ notes that agents will try to run the testing commands you list and fix failures before finishing. If you list no commands, the agent guesses, and a guessed command that runs the wrong test suite gives false confidence.

The constraints section matters second. Real Python's AGENTS.md guide describes constraints as "the lines the agent must never cross, even when crossing one would make a test pass or finish a task faster." Write them short and blunt. Typical constraints are no added dependencies without asking, no changes to public interfaces, no blocking I/O in async code, and no direct writes to production.

The layout section saves search time. An agent that knows where things live goes straight to the right file instead of scanning the tree. Real Python's guide frames this as the principle of least privilege applied to agents: tell the agent which files it needs for the task and which to leave alone.

A long file is a worse file. Anthropic's engineering team describes context as a finite resource with diminishing returns, because a model's ability to recall information drops as the number of tokens grows, an effect called context rot (Anthropic). Their guidance is to find "the smallest possible set of high-signal tokens" that produces the outcome you want. Every line in a context file loads on every task, so every line has to earn its place.

Cursor's documentation lists four things to avoid (Cursor):

• Copying entire style guides. Use a linter instead.
• Documenting every possible command. The agent already knows npm, git and pytest.
• Adding instructions for edge cases that rarely apply.
• Duplicating code that already exists in the repository. Point to a canonical example file instead.

Add two more. Leave out abstract principles with no behavior attached. Packmind's review of real context files found that listing "SOLID, KISS, YAGNI" in a heading has almost no effect on output, because the model already knows the acronyms and gets nothing concrete to act on (Packmind). And leave out secrets. The file is committed to version control and read by every tool that opens the repository.

The most useful test for each line is whether someone could check that it was followed. Claude Code's documentation gives three pairs that show the difference (Claude Code memory docs):

• "Use 2-space indentation" instead of "Format code properly".
• "Run npm test before committing" instead of "Test your changes".
• "API handlers live in src/api/handlers/" instead of "Keep files organized".

Four more habits raise adherence:

1. Use headings and bullets. The same documentation says organized sections are easier for the agent to follow than dense paragraphs.
2. Remove contradictions. If two instructions conflict, the agent may pick one arbitrarily. This often happens when a root file and a nested file disagree.
3. Give the reason for anything surprising. "Do not use the ORM for reports, because the report queries need hand-tuned SQL" lets the agent handle a case the rule did not name.
4. Write at the right altitude. Anthropic describes two failure modes: brittle if-else logic that tries to script every step, and vague guidance that assumes shared context (Anthropic). Aim between them. State the rule and the reason, then let the agent handle the details.

Birgitta Böckeler, writing on Martin Fowler's site, separates instructions, which tell the agent to do a task a certain way, from guidance, which states conventions that apply everywhere (martinfowler.com). A project context file should be almost all guidance. Step-by-step instructions for one kind of task belong in a skill or a saved prompt that loads only when that task comes up.

One file at the root works for a single application. A monorepo needs more than one.

Nested files. The agents.md format supports one file per package. Agents read the nearest file in the directory tree, so the closest one takes precedence. As read on 2026-10-17, the agents.md site said the main OpenAI repository held 88 AGENTS.md files (agents.md). Put repository-wide rules at the root and package-specific commands and conventions next to each package.

Path-scoped rules. Claude Code supports rule files under .claude/rules/ with a paths field, so a rule about React components loads only when the agent works on matching files (Claude Code memory docs). Cursor rules do the same with globs and offer four modes: always apply, apply intelligently based on a description, apply to specific files, and apply manually when mentioned (Cursor).

Imports. A CLAUDE.md can pull in another file with @path/to/file. Imports keep a long file organized, but Claude Code's documentation points out that imported files also load at launch, so they do not reduce the context cost.

Size targets differ by tool. As read on 2026-10-17, Claude Code's documentation recommended keeping each CLAUDE.md under 200 lines, and Cursor's recommended keeping each rule under 500 lines. Treat both as ceilings, not goals.

The template below follows the sections above. Replace every line with facts about your project and delete any section that does not apply.

# AGENTS.md

## Project
Order management API for the web shop. TypeScript, Node, Postgres.
Customers never call this service directly; the storefront does.

## Commands
- Install: `pnpm install`
- Test one package: `pnpm test --filter <package>`
- Lint and typecheck: `pnpm lint && pnpm typecheck`
- Local database: `docker compose up db`, then `pnpm dev`

## Layout
- `src/api/handlers/`: HTTP handlers, one file per resource
- `src/domain/`: business rules; no database or HTTP code here
- `src/db/migrations/`: SQL migrations, append only
- `src/gen/`: generated client code; never edit by hand

## Conventions
- Money is integer cents. Never use floats for amounts.
- Endpoints follow the pattern in `src/api/handlers/orders.ts`.
- Errors return `{ error: { code, message } }` with a 4xx or 5xx status.

## Constraints
- Do not add a dependency without asking.
- Do not change a migration that has already been merged.
- Do not commit to `main` or push. Stage changes for review.

## Done means
- Tests, lint and typecheck pass.
- Changed behavior has a test.
- The summary lists every file changed.

Notice what is missing: no paragraph about clean code, no list of common git commands, no copy of the style guide. Every line describes something specific to this repository that the agent could not guess.

A context file decays like any documentation. A renamed folder or a retired command turns a helpful line into a misleading one, and an agent will follow a stale instruction with full confidence.

Three habits keep the file accurate:

1. Grow it from mistakes. Cursor's guidance is to start simple and add a rule only when the agent makes the same mistake repeatedly (Cursor). Böckeler gives the same advice: build rules files up gradually, because what a model needed months ago may no longer be necessary (martinfowler.com).
2. Review it like code. Commit the file, change it through pull requests, and let the whole team see each change. Packmind recommends making context review a normal part of code review (Packmind).
3. Audit it on a schedule. Check that every path and command in the file still exists. Claude Code's documentation describes a prompt audit that looks for references to missing files and for instructions that contradict each other (Claude Code memory docs).

When a section grows past a screen and only applies to some tasks, move it out. Narrow, task-specific guidance works better as a skill that loads on demand. Quanta Intelligence publishes skills and playbooks in that format, and the same rule applies to any you write yourself: the always-loaded file is for what matters on nearly every task.