DEV Community: Piekwerk

Your CLAUDE.md is probably too long

Piekwerk — Tue, 15 Sep 2026 11:43:16 +0000

Contexts are not compliance. A year of agent configs points the same
direction: shorter instruction blocks get followed better — and the
ceiling arrives earlier than you think.

There's a failure mode spreading through agent configs, and it feels
productive. Every time an agent does something you don't like, you add
a rule. Six months later your CLAUDE.md is 600 lines, and — this is
the part nobody wants to hear — the agent is following less of it
than when it was 80.

The compliance curve

Instruction-following is not a bucket you fill. It's closer to a
signal-to-noise problem: every rule competes with your source code and
with every other rule for a finite attention budget. A short list of
concrete rules gets followed. A long list gets skimmed — and skimming
is not 50% compliance, it's unpredictable compliance, where the rules
that survive are not the ones you'd have picked.

The pattern I've seen in my own configs and others':

Under ~100 lines: rules function as rules. Adding one more visibly changes behavior.
100–300 lines: the comfortable zone for a full baseline plus tool-specific guidance, if every line earns its place.
300–600 lines: redundancy sets in (the same idea phrased twice, then three times, added on different bad days). Compliance becomes selective. Review comments go up, not down.
600+: the file is a cargo cult. Nobody reads it — including, in every way that matters, the model.

Why more rules make each rule weaker

Three mechanisms, all boring:

Competition. Attention spent on rule 47 is not spent on rule 3.
When everything is emphasized, the model's choice of what to emphasize
is arbitrary — and your priorities lose to recency and position.

Redundancy is noise. People add duplicates on purpose ("I'll say
it in both files so it sticks"). The model doesn't experience
repetition as emphasis. It experiences two similar-but-not-identical
rules, which is exactly the input shape that degrades all
instruction-following.

Staleness compounds. Long files rotate slower. Rules for problems
you fixed months ago stay in context forever, contradicting the newer
rules that replaced the practice. Conflicts don't error; they resolve
randomly, per session.

The diet that works

1. Cut by checkability. For each rule ask: what observable diff
would violate this? If there's no answer, the rule is a mood, and
moods don't steer agents. "Write clean code" goes; "no unused imports"
stays.

2. Scope instead of delete. The testing rule that's wasting budget
on every request but only matters for test files doesn't need to die —
it needs a Cursor glob. Claude Code reads CLAUDE.md whole, but
Cursor's rules load per-glob, and most repos run more than one tool.
Put the rule where its scope is expressible.

3. Extract procedures. The TDD ritual, the investigation checklist,
the release dance — these aren't context rules, they're procedures.
Move them to skill files and import them where the work calls for
them. Your always-on budget stops paying for content that only matters
during specific tasks.

4. One home per rule. The baseline (AGENTS.md) holds standards
once; tool files reference or triage. The moment the same rule lives
in two places, you've started a drift clock.

5. Count it in CI. wc -l CLAUDE.md with a ceiling — we use 300 —
turns budget creep into a failed check instead of a slow surprise. The
ceiling isn't magic; the enforcement is.

What a dieted config looks like

Ours, after the same diet: an imported baseline (commands, conventions,
safety — ~70 lines), a verification loop, three to five stack notes,
and a short anti-pattern list. Under 100 lines in most repos. Rule
compliance is visibly better than the 600-line version it replaced —
same standards, fewer words, no contradictions to resolve.

The uncomfortable summary

Your CLAUDE.md's length is a ledger of unresolved decisions. Every
paragraph of prose is usually a rule you haven't made concrete; every
duplicate is a file you haven't unified. The diet isn't editing — it's
deciding.

If you'd rather start from a pre-dieted, pre-validated baseline: our
kits keep every CLAUDE.md under a validated 300-line ceiling, with
stack detail pushed into scoped rules instead of the always-on block,
for twelve stacks. The Next.js kit is free (MIT) on
AgentConfig Studio on Gumroad — all 12 kits.

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

Piekwerk — Tue, 15 Sep 2026 11:36:56 +0000

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.

How we validate 12 agent config kits (and what validation can't do)

Piekwerk — Tue, 15 Sep 2026 11:36:25 +0000

Our validator checks every kit before release: files, budgets,
frontmatter, sections, placeholders. Here's exactly what it checks,
why those checks exist, and — more interestingly — what it cannot
check, because pretending otherwise is how trust dies.

Agent config has a trust problem, and it's deserved. The market is
full of markdown with confident READMEs and no contract. "Validated
against real projects!" is the new "military-grade encryption." So
instead of adjectives, this post is the actual spec of our validation
harness — the same script that ships in the pack — including the
failure it caught, and the honest list of what it does not check.

The contract

A kit is a set of files with structure. Structure is checkable;
therefore the contract is structural. Every kit must pass all of:

1. Required files exist.
AGENTS.md, CLAUDE.md, copilot-instructions.md, and a
.cursor/rules/ directory with 3–5 .mdc files. Trivial? Every
missing-file bug in our own builds was "trivial" until it shipped.

2. The CLAUDE.md line budget.
Fewer than 300 lines, enforced, not suggested. The number is a design
decision (see the compliance-curve argument in our longer piece), but
the enforcement is the point: budgets without gates become
suggestions, and suggestions become 900-line files.

3. Cursor frontmatter parses, with a declared activation mode.
Each .mdc must open with parseable YAML frontmatter containing a
non-empty description, and either alwaysApply: true|false or a
globs entry. This check exists because of the nastiest silent
failure in the format: a malformed frontmatter block doesn't error —
Cursor treats the file as broken or ignores it, and a rule you
believe is protecting your test files simply never loads. The
validator makes "the rule never loads" a build failure.

4. The baseline has its sections.
AGENTS.md must contain: Project context, Commands, Code style,
Testing expectations, Commit conventions, Safety rules, Definition of
done. These aren't bureaucratic — they're the sections agents act on
most (the command table above all). A kit missing "Safety rules" is
missing the file's most important content, so it fails.

5. No placeholder text, anywhere.
TODO, TBD, FIXME, lorem ipsum, XXX — case-insensitive,
across every kit file. Config rot starts as a placeholder that
outlived its author.

6. No unrendered templates.
The kits are generated, so generation bugs are a risk class: the
validator scans for unrendered variables ({lint_cmd, and friends)
in output. This check exists because it caught exactly that bug —
a double-formatting trap left the literal text lint_cmd_placeholder
inside every kit's definition-of-done. The validator flagged it on
its first real run; the fix took one line; the check stays forever.

7. Skills exist and are non-trivial.
All eight workflow skills must be present and above a minimum size.
A stub skill file is a broken promise.

Output: human-readable by default, --json for CI. Exit code is the
release gate: non-zero, no release.

The proof it works: we break things on purpose

A validator that has never failed is a validator that has never been
tested. Before trusting ours, we negative-tested it — deliberately
corrupting a kit and watching:

Appended TODO: fix this to a kit's AGENTS.md → failed, named the file, named the check.
Restored the file → all green again.

That loop — break, catch, restore — is the entire basis on which we
ask you to trust the green checkmark. The check that caught the
unrendered-template bug was added the same way: a real bug, then a
check that makes it permanent history.

What validation cannot do

Now the honest part, because this is where most tool marketing lies by
implication.

It cannot check whether the advice is good. The harness knows
"Commands" exists; it cannot know your test command is right for your
repo. That's why kits mark the command table as the first thing to
edit — and why the validator refuses to pretend otherwise.

It cannot check semantics. Whether the baseline contradicts a
Cursor rule, whether your anti-pattern list matches your actual codebase
— these need human review or much cleverer tooling. We structure the
generation so contradictions are hard (tool files are projections of
one source), but hard is not impossible, and we won't claim the
validator catches what it doesn't.

It cannot check real-repo firing. We don't claim globs were
"tested against N production repos," because they weren't. The glob
syntax and mode declarations are validated; whether your repo's
layout matches the glob is checked by you, in your repo, in one
minute, using the harness we ship. Any product claiming automatic
firing-verification across arbitrary repos is claiming to have run
your build — ask them what that means, exactly.

Why structural validation is still the right contract

Because everything downstream depends on it. A rule that never loads
is zero percent as good as written, no matter how wise. A budget that
silently creeps degrades compliance in ways nobody attributes to the
cause. Structural checks are the difference between "config" and
"markdown with aspirations" — and unlike vibe-based claims, they're
runnable on your machine, against our kits, and against your own
edits, before you spend a cent.

That's the offer, verified: the validator ships in the pack, the
release output (12/12 kits, 8/8 skills, green) is in the changelog,
and the free MIT sample kit runs through the same harness. Trust the
check, not the adjective — and run it yourself.

AgentConfig Studio's twelve kits and the harness they ship with are on
AgentConfig Studio on Gumroad — all 12 kits.