I tested the AI agent config formats so you don't have to

#devtools

A teardown of the four formats your coding agents read — what each
does, where each breaks, and the setup that stopped me maintaining
four copies of the same rules.

I have the same standards in every repo I touch: small diffs, tests
that fail before the fix, conventional commits, no secrets in code.
For about a year, I maintained those standards by hand in every format
my agents read. This is what I found when I actually audited them —
and what I'd tell myself a year ago.

The four formats, one audit

AGENTS.md is the community's tool-neutral convention: a plain
markdown file at the repo root, discovered by walking up the tree.
No schema, no activation model — whatever you write loads. Its
strength is its boringness. Its weakness is that "loaded" is not
"followed": my 140-line baseline was loading in full, and my agents
were still committing messy messages, because rule compliance drops as
instruction blocks grow.

CLAUDE.md is Claude Code's memory file, and the only format with a
native import mechanism (@import path). This is quietly the most
powerful feature in any of the formats: it means a tool file can
reference a baseline instead of copying it. My first version didn't
use it — I had a full copy of my baseline inside CLAUDE.md with a few
Claude-specific lines on top. When I changed the baseline, I forgot
the copy. The file was lying to my agent for a month.

.cursor/rules/*.mdc is Cursor's per-rule format, and the only one
with activation control: frontmatter can scope a rule to globs
(globs: "**/*.test.ts") or make it always-on. The audit found my
favorite failure: I had written alwaysApply: true on a testing rule
— meaning it loaded for every request, eating budget, and the glob I'd
carefully written did nothing. Frontmatter is invisible when wrong.
Nothing errors. The rule just loads when it shouldn't (or never).

copilot-instructions.md is one repo-wide file for GitHub Copilot
with the tightest budget of the four. Mine was a 60-line copy of my
CLAUDE.md — which is to say, useless twice over. Copilot's instruction
following is the loosest of the three tools; a wall of text doesn't
get followed, it gets skimmed. The version that works is ~20 lines of
the conventions that matter most in inline completion.

What the audit added up to

Four copies of the same standards, in four states of currency.
Two rules that had never fired (glob defeated by alwaysApply; a rule in a file one tool didn't read).
One month of drift between baseline and tool copies.
~700 lines of instructions where maybe 150 were earning their keep.

None of this is exotic. Every developer running multiple agents has
some version of this; most haven't audited yet.

The setup that fixed it

The fix wasn't writing better rules. It was structure:

One baseline (AGENTS.md) holds the standards: command table, style, testing, commits, safety. Tool-neutral, committed, versioned like code.
Tool files become projections. CLAUDE.md opens with @import AGENTS.md and adds only what's Claude-specific (my verification loop, stack notes). The Cursor rules are four scoped files — two always-on (core, safety), two glob-scoped (stack, testing). Copilot gets a hand-triaged 20-line digest.
Scoping discipline. If a rule only matters for test files, it does not belong in anyone's always-on context. Globs are budget management.
Validation. A script checks the structural contract: required files present, CLAUDE.md under 300 lines, frontmatter parses with a declared activation mode, no placeholder text, baseline sections present. It runs in CI. My alwaysApply: true bug is now impossible to ship silently.

The result is ~150 load-bearing lines instead of ~700 duplicated ones,
and rule changes land in one place instead of four.

The honest caveats

This is maintenance work. The structure reduces the tax; it doesn't eliminate config as a discipline. Budgets still creep.
Copilot remains the weakest follower even with a perfect file. Set expectations at "fewer review comments," not "perfect compliance."
Formats are young. Cursor's frontmatter schema and Claude Code's import semantics have both moved since I started. Whatever you build, record what you validated it against — you'll want that context when behavior shifts.

If you'd rather not build it

The setup above is exactly what our stack kits ship: AGENTS.md
baseline, imported CLAUDE.md, four scoped Cursor rules, a triaged
Copilot digest — generated per stack so the projections can't drift,
with the validator included. Twelve stacks in the full pack; the
complete Next.js/TypeScript kit is free (MIT) if you want to see the
structure before trusting it. Details on AgentConfig Studio on Gumroad — all 12 kits.

DEV Community