What agent rules and context files are
An AI agent rules file — also called a context file or an instructions file — is a document you keep in your repository that tells an AI coding agent how to work on your project. Your conventions, your commands, your architecture decisions, the things you'd say to a new teammate on day one: you write them down once, and the agent reads them automatically at the start of a session.
They exist because of a simple, repetitive pain. Without a rules file, every new chat starts from zero. You re-explain that the project uses pnpm, that tests run with a specific command, that the API layer lives in a certain folder, that secrets never go in the client bundle. The agent guesses at everything you don't say — and a guessing agent is a hallucinating agent. A rules file turns those repeated explanations into persistent instructions the agent always has in front of it.
The idea isn't tied to one tool. Claude Code, Cursor, Windsurf, GitHub Copilot and others each look for their own file. The names and formats differ; the concept is identical. The rest of this guide maps the landscape, shows what separates a good rules file from a useless one, and points you to the deep dives for each.
The landscape at a glance
Here are the main rules files across today's AI coding agents — one row each. This is the overview; for a proper head-to-head on formats, scoping, and which to actually use, read the full CLAUDE.md vs AGENTS.md vs .cursorrules comparison.
| File | Tool | Status |
|---|---|---|
CLAUDE.md | Claude Code | Active |
AGENTS.md | Many agents (open format) | Emerging standard |
.cursorrules / .cursor/rules | Cursor | Legacy → .cursor/rules |
.windsurfrules | Windsurf | Active |
.github/copilot-instructions.md | GitHub Copilot | Active |
Different filenames, same purpose. The names will keep changing as new tools ship; the concept — a place to write down what the agent should know before it touches your code — won't.
What makes a good rules file
The file format barely matters. What matters is what you put in it and how you maintain it. The same principles apply whether you're writing CLAUDE.md, AGENTS.md, or a Cursor rule:
Vague instructions produce vague behaviour. "Follow our style" tells the agent nothing. "Use 2-space indentation, named exports only, and never import from the barrel file" tells it exactly what to do. Write decisions, not vibes.
The agent needs to know how to build, test, lint, and run your project before anything else. Put those commands near the top so the agent can verify its own work instead of guessing the right invocation.
A stale rules file is worse than none — it gives the agent confident, wrong instructions. When a convention changes, update the file in the same commit. Treat it like code, not a README you wrote once and forgot.
A monorepo rarely has one set of rules. Most tools let you nest rules files in subdirectories (or scope them with globs) so the frontend gets frontend rules and the API gets API rules, instead of one giant file the agent has to filter every time.
The rules file belongs in the repo, committed alongside your code. That way every teammate and every agent reads the same instructions, changes show up in review, and you have a history of how your conventions evolved.
Learn more: the deep dives
This page is the map. Each of these goes deep on one piece of the landscape:
How to write CLAUDE.md
The context file Claude Code reads automatically. What to put in it, how to structure it, and where it lives.
Read the guideAGENTS.md: the open standard
One tool-agnostic file many agents can read. Why it exists, what goes in it, and when to lead with it.
Read the guideThe full comparison
CLAUDE.md vs AGENTS.md vs .cursorrules head-to-head — formats, scoping, which to use, and how to keep them in sync.
Read the guideSpec-driven development
The methodology these files serve: write the spec first, then let the agent build against it.
Read the guideFrom a file to a system
Here's the limit of any rules file, no matter how well written: a file is instructions, not enforcement. It tells the agent what you want. It doesn't make the agent keep doing it — across a long session, after the context window compacts, three features deep when the easy move is to cut a corner and ship. You've probably seen it: the agent reads the rules at the start, follows them for a while, then quietly drifts. The file was fine. The following was the problem.
Free, unopinionated scaffolds — GitHub's Spec Kit, AWS Kiro and others — give you a blank structure to write rules and specs into. They're genuinely useful if you want to assemble your own workflow. But by design they hand you the scaffold and leave the quality bar, the hard decisions, and the enforcement to you.
That's the leap Keeborg makes. It's the opinionated, battle-tested spec-driven development system for AI coding agents — the practice we shipped real projects with before the industry settled on the name "spec-driven development." On top of generating your rules and specs, it adds the layer that makes them stick:
Every piece of work is scored against a rubric. Below 95/100 means it isn't done — the agent re-runs instead of handing you half-built code that technically compiles.
Decisions, changes, and where you left off are recorded. When the context window resets, the agent re-reads them and picks up exactly where it was — still following the rules.
Rules files describe the happy path. The audit checks the things they usually forget — exposed keys, missing auth, unsafe defaults — before anything ships.
A rules file is the right place to start — and if you only need the file, the free generator below gets you one in seconds. But if you've written a good one and still watched the agent wander off, the enforcement layer is the piece you were missing.
Generate a CLAUDE.md free
Describe your project and get a structured rules file in seconds — the same context your agent needs, without writing it from scratch.
Try the free generatorTurn the file into a system
The Keeborg dev system adds the enforcement a file can't — a 95/100 quality gate, session continuity that survives compaction, and a security audit that blocks deploy. Personalised to your stack.
Get the dev system