CLAUDE.md and project context: what an AI agent needs to know about your codebase

Part 2 of 3 in the series "AI development with guardrails". Part 1: specs before code · Part 3 (automated quality gates) appears on 12 November.

Imagine you get a new developer every morning. Very good, very fast, knows every framework, and has never seen your project. In the evening they forget everything again.

That is how an AI agent works. Every session starts from zero. What it knows about your project it reads from the code, and whatever isn't in the code, it guesses.

The fix is so simple it often gets overlooked: a file the agent reads at the start of every session. In Claude Code it is called CLAUDE.md; other tools have their own names (AGENTS.md, .cursorrules). The principle is the same.

Where the agent gets it wrong without context

bauernjobs.de, my job platform for agriculture, has had a CLAUDE.md since February 2026. Almost every rule in it came from a mistake. A few examples:

The folder structure. The application runs on Laravel 13 but kept the Laravel 10 layout: middleware in app/Http/Kernel.php, schedules in app/Console/Kernel.php. A model that knows Laravel 13 puts new middleware in bootstrap/app.php, where it is never loaded. The code looks right and doesn't run. One line of context prevents it: "Laravel 10 structure, no bootstrap/app.php. Follow the existing layout."

The runtime. My machine has an older PHP version installed than the project uses. Without a hint, the agent runs php artisan on the host, gets odd errors and starts fixing "compatibility problems" that don't exist. The rule: "All PHP runs in the Docker container, never on the host."

Behaviour you can't see. Messages between farmers and seasonal workers are translated, but not instantly: in batches every three minutes. Anyone who doesn't know that will "fix" the supposedly missing real-time translation. So the context file says which commands run on which schedule, and that this is intended.

What belongs in a context file

After three years with bauernjobs.de and rebuilding this website (ghinea.net), my list is short:

1. What the project is, in three sentences. Who it is for, what it does, what makes it different.
2. How to run and check it. The exact commands for tests, formatting and static analysis. The agent should run them, not invent them.
3. Where things live when it differs from the framework default. Only the differences, not the whole folder tree.
4. Conventions you can't see in the code. On ghinea.net, for example: never hand-write JSON-LD in Blade, use the helper class. No Google Fonts, because the privacy notice doesn't cover them.
5. What is intended even though it looks odd. The batched translation. A folder that is committed although it is generated. A page that deliberately exists only in German and English.
6. What the agent must not do. In my case: no commits unless asked, no changes on the production server.

What doesn't belong in it

• Anything the code already says. A list of every model or controller goes stale with the next commit and costs context in every session.
• Generic advice. "Write clean code" changes nothing. "Format to PSR-12, pint --test must pass" changes something.
• Secrets. No passwords, no API keys. The file lives in the repository.

Two levels: rules and roadmap

A CLAUDE.md describes how work is done in the project. It says nothing about what is being worked on right now, or why.

For that I use a second file. On ghinea.net it is openspec/project.md: the current state, the offers, open decisions and a roadmap with numbered items (A1, B4, D9 …). CLAUDE.md points to it: "Read it first for any non-trivial task."

On top of that there is a configuration for OpenSpec that sets rules for every planning step. Mine include:

• Every proposal names the roadmap item it belongs to.
• Every proposal has a "non-goals" section.
• Every new public page needs German and English language files and a sitemap entry.

The third rule exists because the first offer page went live without a sitemap entry and returned a 404 at its German URL. Since then it is in every task list the agent writes.

The most dangerous context file is the outdated one

The September 2026 audit of bauernjobs.de turned up a wrong path for the admin panel in CLAUDE.md. The path had been changed at some point; the context file had not.

That is worse than no information at all. An agent without information looks in the code. An agent with wrong information trusts it, with the same confidence it gives to correct information.

So my rules are:

• The context file changes in the same commit as the code. If a route moves, the line describing it changes too.
• The agent maintains it. Checking whether anything in CLAUDE.md is no longer true is part of finishing a change, like running the tests.
• Facts with dates. "The old server was shut down on 25 September 2026" can be checked. "The old server is no longer used" can't.

What you can take from this

If your team uses AI agents and there is no context file, it is the cheapest lever you have. One hour of work:

1. Have the agent generate a first draft from the code (in Claude Code: /init).
2. Delete everything the code already says.
3. Add the five things every new colleague gets wrong in their first week.
4. From now on, treat the file like code: review, commit, maintain.

Context tells the agent what applies. It doesn't guarantee the agent sticks to it. That takes checks that run automatically and are not negotiable, which is what the third part, out on 12 November, is about.

Your team works with Claude Code, Cursor or Copilot, but everyone does it differently? As a fractional tech lead I write the context files and rules with you, so the agents across your team work to the same standards. Book an intro call