Stop writing rules: 6 problems your agent config should not solve

#ai #programming #devtools #opinion

Most agent config advice is about what to write. This is about the
opposite: the problems that keep landing in CLAUDE.md and AGENTS.md
that were never config problems. Every one of these costs context
budget, and none of them work well in prose. I have made most of
these mistakes myself.

1. What the linter already checks

"Use single quotes. Two-space indent. Semicolons." Delete all of it.
The linter is deterministic, runs on every save, and never suffers
attention decay. Any style rule your tooling can express is a wasted
line in config, and worse, a contradiction waiting to happen when
the two disagree.

Where it goes: .eslintrc, prettier, rustfmt, whatever your stack
ships. Prose config only earns style lines when the rule is
uncheckable, like "match the surrounding file's existing quoting
when the linter is not configured".

2. What the type system already guarantees

"Do not pass null where an Option is expected." The compiler
already enforces this, with certainty, at build time. Restating type
guarantees in prose adds nothing except drift risk when the types
change.

Where it goes: the types. If the type system cannot express it
(that this function must be called after init, say), that is a case
for a runtime assertion or an opaque type, not a config line.

3. Project-specific facts that belong in code comments

"Use the pagination helper in src/api/pagination.ts, the raw
pattern is deprecated." This is a comment at the deprecated pattern,
plus a @deprecated tag. Config is the wrong altitude: the fact
belongs within one line of the code it describes, where it survives
refactors that never touch config.

Config earns facts only when they are repo-wide: "generated files
live in src/gen, do not edit by hand" is fine. Pointers to specific
files are comments.

4. History and war stories

"We used to use moment.js but migrated in 2024 because bundle size."
Valuable knowledge, wrong file. Long tasks compact context and
history is exactly what does not survive; worse, history in config
spends always-on tokens on information that rarely changes behavior
this session.

Where it goes: a dated decisions ledger (DECISIONS.md), read on
demand. Config gets the surviving conclusion: "date library is
dayjs, see DECISIONS.md".

5. Aspirational process nobody follows

"All PRs require two approvals and a linear history." If your
config says this and your repo has 40% single-approval merges, the
config is fiction, and fiction in config teaches agents (and humans)
that config is advisory. Instructions lose authority when a
documented rule is visibly not enforced.

Where it goes: branch protection settings. Enforce it in the
platform or do not write it.

6. Prompt-shaped tasks

"Before responding, think step by step about the architecture."
This is prompt engineering, not configuration. It belongs in the
system prompt of the specific invocation where you want that
behavior, or in a skill file loaded on demand. Permanent, always-on
prompt tricks paid from the line budget are the most expensive way
to get the effect.

The budget argument, briefly

Always-on config lines cost attention on every call, and the file
has a compliance cliff past a few hundred lines. Every wasted line
dilutes the real rules. Cutting the six categories above typically
removes 30-40% of a bloated config, which is budget enough for the
safety rules and definition of done that actually need the space.

The test for any line, one more time: does a machine already check
it, would following it change behavior this session, is it a
command with a concrete trigger. Three noes, no line.

DEV Community