# Rules Files vs a Context Engine: What Actually Works


URL: https://getunblocked.com/blog/rules-files-vs-context-engine/
Published: 2026-07-29T15:00:00Z
Author: Brandon Waselnuk
Categories: Comparisons, AI Agents

AGENTS.md cut agent runtime 28.64% in a 2026 study, yet rules files still rot. When to keep cursor rules and when a context engine wins, so agents stay current.

---
Cursor rules or a context engine: what actually works for teaching coding agents your team's conventions? For the few hard constraints that never change, a rules file works. For everything that moves with your codebase, a context engine works and a rules file quietly fails. The distinction is structural, not a matter of writing better files. A rules file is a snapshot. Someone captured the team's conventions on one particular day, and the file has been aging ever since. A context engine is synthesis. It reads the code, PRs, and decisions your team produces and assembles the current answer on demand. We diagnosed the symptom in our piece on [rules-file rot](/blog/rules-file-rot/). This article is the decision that follows the diagnosis. Which abstraction deserves your team's ongoing investment, and where does each one earn its place?

## What is a rules file actually promising you?

Every rules file makes the same promise: write your conventions down once and the agent will follow them forever. The vendors themselves hedge that promise. Anthropic's [Claude Code memory documentation](https://code.claude.com/docs/en/memory) tells teams to target under 200 lines per CLAUDE.md. Longer files consume more context and reduce adherence. The docs are also explicit that instructions are treated as context, not enforced configuration. The companion [best-practices guide](https://code.claude.com/docs/en/best-practices) goes further: bloated CLAUDE.md files cause the agent to ignore your actual instructions. Its own include/exclude table tells you to leave out information that changes frequently.

Read that last clause again. Team conventions are information that changes frequently. [Cursor's rules documentation](https://cursor.com/docs/context/rules) makes the same concession from the other direction. Keep rules under 500 lines, and reference files instead of copying their contents, because copied content becomes stale. The official guidance for cursor rules and CLAUDE.md amounts to "keep it short, and don't put changing things in it." That is the vendors telling you the abstraction has a narrow safe zone. Most teams write files far outside it.

## Why does every rules file become three rules files?

The maintenance problem multiplies by tool. GitHub's [Copilot custom-instructions documentation](https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot) now reads four different instruction files, including AGENTS.md, CLAUDE.md, and GEMINI.md. It caps generated instructions at two pages. The [AGENTS.md standard](https://agents.md/), now stewarded under the Linux Foundation, is supported by roughly twenty tools. It is used in over 60,000 open-source projects.

Consolidation helps, but it changes the failure mode rather than removing it. A team running Claude Code, Cursor, and Copilot faces a choice. Maintain one CLAUDE.md, one set of cursor rules, and one AGENTS.md, each drifting independently. Or symlink everything to a single file that still rots on its own schedule. A 2026 study of 2,853 GitHub repositories found context files dominate the configuration landscape ([Galster et al., arXiv, 2026](https://arxiv.org/abs/2602.14690)). They are often the only mechanism teams use at all. Staying on files for now? We cover the mechanics of [keeping CLAUDE.md, AGENTS.md, and .cursorrules in sync](/blog/keeping-claude-md-agents-md-cursorrules-in-sync/) separately. The decision question here is whether syncing snapshots is the right job in the first place.

## What does a context engine synthesize that a snapshot can't?

A context engine is not a better rules file. It removes the file from the loop for anything that changes. Instead, it derives the answer from live sources at the moment an agent asks. Unblocked defines the category by [six requirements](/blog/what-is-a-context-engine/): unified context across code and non-code sources, conflict resolution between them, targeted retrieval, data governance, token optimization, and personalized relevance.

The synthesis-versus-snapshot difference shows up in what each can encode. A snapshot holds whatever a human thought to write down, phrased at whatever altitude they chose. It is current only as of the last commit that touched it. Synthesis pulls the convention from where it actually lives. That means the pattern in the last five merged PRs, the Slack thread where the team rejected an approach, and the design doc that explains the constraint. Giving an agent access to your repos is not the same as giving it understanding. Access hands over files, while understanding requires the reasoning around them. That gap is also why pointing a tool at more context files doesn't fix retrieval failures inside the editor. We unpack that problem in [why Cursor hallucinates and forgets context](/blog/why-cursor-hallucinates-and-forgets-context/).

## Rules files vs a context engine: the head-to-head

The head-to-head comes down to who does the updating: a human editing prose, or a system reading live sources. Researchers at ETH Zurich ran one 2026 evaluation across multiple models and agents. Repository context files did not generally improve task success, and they raised inference cost by more than 20% ([Gloaguen et al., arXiv, 2026](https://arxiv.org/abs/2602.11988)). A file can be present, obeyed, and still not helping.

| Dimension | Rules files (CLAUDE.md, cursor rules, AGENTS.md) | Context engine |
| Source of truth | Hand-written snapshot, current as of the last edit | Live code, PRs, and decisions, synthesized at request time |
| Maintenance burden | Every convention change needs a human to notice it, phrase it, and commit it | No file to edit; sources update as the team works |
| Staleness risk | High and silent; nothing fails when a rule goes stale | Low; answers derive from what merged this week |
| Multi-tool consistency | One file per tool, each drifting independently | One synthesized source serving every agent over MCP |
| What it can encode | Static instructions someone remembered to write down | Current conventions plus the reasoning and rejected approaches behind them |
| Failure mode | Agent confidently follows last quarter's rules | Coverage gaps if a knowledge source is not connected |
| Best use | A short list of hard, rarely changing constraints | Everything that moves with the codebase |


The rows compound in one direction. Maintenance burden causes staleness, and staleness multiplies across tools. The multi-tool copies then disagree with each other as well as with the codebase. Synthesis pays none of those taxes. Its main cost, connecting sources, is paid once rather than per convention per file.

## When Are Cursor Rules Still the Right Call?

Honesty requires the other column. The efficiency evidence for lean files is real. Across 10 repositories and 124 pull requests, the presence of an AGENTS.md file was associated with a 28.64% lower median runtime ([Lulla et al., arXiv, 2026](https://arxiv.org/abs/2601.20404)). Output token consumption was 16.58% lower, with comparable task completion. The agent spends less time exploring because the file hands it the map.

Reconcile that with the ETH Zurich result and a usable rule emerges. Files help when they contain short, stable, non-discoverable facts. Think of the build command that isn't guessable, the one security boundary that must never be crossed, or the tool versions your CI pins. Files stop helping, and start costing, when they carry conventions, architecture narration, and everything a team learned last quarter. A solo developer on a small repo may never outgrow the file. A team shipping daily across multiple services will. Has your file already ballooned past the vendors' own line-count guidance? Our companion piece on [auditing and fixing a bloated CLAUDE.md](/blog/audit-fix-bloated-claude-md/) covers the triage. Shrink the file; don't delete it.

## How does Unblocked serve every tool from one source?

Unblocked provides institutional context for coding agents. Its context engine connects code repos, PRs, Slack, Jira, Notion, and Confluence. It serves synthesized answers to any agent over MCP. Claude Code, Cursor, and Copilot all query the same source. There is no per-tool file to drift and no sync job to forget. Instead of a snapshot, the agent gets the current convention with the decision trail attached. That trail includes the approaches your team already rejected. It also surfaces things engineers didn't know to look for.

That changes how teams structure agent workflows. At Clio, engineers put the context step before the code step:

> I built a step called 'enrich' that runs before any code gets written. The agent asks Unblocked for everything — the ticket, the Slack context, what's been done in related repos — and then it starts implementing. It's especially powerful for cross-repository work where you'd otherwise have to do all that archaeology yourself.
>
> — Arthur Rodolfo, Software Engineer, Clio

Notice what the enrich step replaces. It is exactly the content teams try to freeze into rules files. Here it is gathered fresh per task instead of copied into prose that ages.

## Frequently asked questions

**Do I still need a CLAUDE.md if I use a context engine?** Yes, a lean one. Keep the constraints that are hard rules and genuinely non-discoverable: build commands, security boundaries, environment quirks. Move conventions, architecture explanations, and anything that changes with the codebase to the engine. The file shrinks to a page and mostly stops needing edits.

**Is AGENTS.md enough to keep Claude Code, Cursor, and Copilot consistent?** It fixes duplication, not drift. One shared file means the tools agree with each other. The file still disagrees with the codebase a little more each week. Consolidation is a maintenance win; freshness requires a source that updates itself.

**Isn't a context engine just a bigger rules file?** No, and size is the wrong axis. A rules file of any length is a snapshot someone wrote in the past. A context engine synthesizes the answer at request time from current code, PRs, and decisions. The difference is when the truth was assembled, not how much of it there is.

**Should cursor rules hold anything once an engine is in place?** Editor-specific mechanics, and little else. Scoped instructions like "use this component library in this directory" fit well in cursor rules because they are stable and local. Team-wide conventions, the part that rots, belong to synthesis.

**What should move out of the rules file first?** Anything an agent can discover by reading the code, and anything that encodes a decision. Directory layouts and architecture overviews go first. The ETH Zurich evaluation found repository overviews were not helpful despite being widely recommended. Decision context goes next, because a file can't keep it current.

## So Which One Should Your Team Maintain?

Both, in very unequal proportions. Maintain a rules file the size the vendors actually recommend. That means a short page of hard constraints that would surprise an agent reading the code. Let a context engine carry everything else. Conventions live in your merged PRs and decision threads, and only synthesis reads those where they live. The teams hitting rules-file rot are not bad at maintaining files. They are using a snapshot to track a moving target. Point your agents at a system that answers WHY, not just WHAT. The treadmill of re-editing cursor rules after every convention change simply ends. Write down the few things that never change. Connect the sources for everything that does.