Agent context files for real codebases

Most agent context files are too vague to help.

They say things like "write clean code," "follow best practices," "be concise," and "make sure tests pass." Those instructions are not harmful, but they are not enough for a real codebase. A useful agent context file should behave more like a project operating manual. It should tell the agent what to read, what not to touch, how to verify work, where the risky seams are, and how the team wants decisions made.

When an agent gets that context, it stops behaving like a generic code autocomplete tool and starts behaving more like a careful teammate inside the repo.

Start with the shape of the project

The first job is orientation. An agent needs to know what kind of system it is inside.

I want the file to answer:

• What framework owns routing?
• Where does content come from?
• Which database or CMS is authoritative in production?
• Which files are generated?
• Which commands are expected before a PR?
• Which directories represent product code, support scripts, assets, and migrations?

This does not need to be long. The goal is to prevent the first bad assumption. In this site, for example, it matters that the journal has fallback content in source files and production content in Supabase. If an agent adds a post only to local fallback, the local build may pass while production stays stale. That is the kind of rule a context file should make obvious.

Make verification concrete

"Run tests" is not a verification plan.

Good context names the exact checks:

• npm run build
• npm run seo:assert
• browser check /journal and two article pages
• verify generated OG assets exist
• check Supabase migrations were created with the CLI

The best verification instructions also include failure interpretation. If the local Supabase container is not running, say what still can be verified and what cannot. If a build falls back to bundled content because placeholder env vars are used, say whether that is expected. The agent should not have to infer the difference between a real failure and a known local condition.

Include examples of local taste

A context file should not try to describe every design preference. But it should capture the local style where a generic agent is likely to drift.

Examples:

• Use existing article visual classes instead of adding decorative images.
• Avoid landing-page hero patterns for product tools.
• Keep cards tight and functional.
• Use real route checks for UI work.
• Do not invent new resource relationships unless the file exists.
• Prefer existing content modules over new abstractions.

These rules are especially useful for frontend work. A generic agent will often produce a shiny screen that ignores the product's density, typography, or operating context. Local taste rules help keep generated work from feeling bolted on.

Write boundaries as hard rules

The most valuable lines in an agent file are often negative instructions.

Do not overwrite user changes. Do not create a migration filename by hand. Do not add a download link unless the file exists. Do not use service-role keys in client code. Do not change unrelated article dates. Do not refactor shared components while adding one content batch.

These are not style preferences. They protect the worktree.

Keep it short enough to be read every time

The context file should be dense, not huge. If it becomes a second documentation site, the important rules disappear. I like a file with sections for project shape, edit rules, verification, design standards, data rules, and deployment notes.

The test is simple: would this file prevent the next predictable mistake?

If yes, keep it. If not, move it elsewhere.

A small template is enough

The file I want most teams to keep is simple:

• Project shape: framework, routes, data source, generated assets, deployment target.
• Editing rules: where to add content, how to name migrations, what files are generated, what not to touch.
• Product rules: tone, visual standards, accessibility expectations, content constraints.
• Verification: exact commands, browser routes, sample pages, and known local failures.
• PR rules: branch naming, commit style, migration notes, and what belongs in the summary.

That is not a lot of text, but it changes the quality of the next agent run. The agent can start with local facts instead of broad assumptions. It can avoid refactoring the wrong layer. It can run the same checks the team expects. It can tell the user when a production-only verification step is genuinely blocked.

This is also why I do not like context files that only describe tone. Tone helps conversation. Project facts help code.

Update it after mistakes

The context file should evolve when the team sees a repeated miss.

If an agent keeps adding content without a Supabase migration, add that rule. If it keeps generating decorative visuals, add the visual standard. If it keeps using the wrong test command, add the exact command. If it keeps touching unrelated files, add the scope rule.

This makes the file a memory of operational friction. It does not need to be perfect on day one. It needs to become more precise whenever the team notices a predictable failure.

The best agent context file is not a prompt masterpiece. It is a practical record of how the repo wants to be changed.