Every AI coding tool now reads a config file from your project. Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Cursor reads .cursor/rules/*.mdc. If you're like most teams, each file was written at a different time, by a different person, in a different format.
One file uses numbered steps. Another uses bullet points. A third mixes tables with prose in a pattern the others don't follow.
You might think this is cosmetic. It's not.
The parsing tax
LLMs parse your config files on every session startup. When the format convention shifts between files, the model doesn't just read the content — it re-learns how to parse each file.
Think of it like driving. If every street in your city used a different traffic light system — red means stop on Elm but green means stop on Oak — you'd burn brainpower on decoding rules instead of navigating. Same thing happens when CLAUDE.md uses - bullets, AGENTS.md uses 1. numbered steps, and .cursorrules bounces between tables and prose.
The model wastes attention on format switching. Attention that should go to following your actual rules.
Real numbers
Our config system — four files accumulated over months — drifted into 6+ format styles. Bullet lists here, numbered lists there, tables where bullets would work, inconsistent header depth.
Before: 232 lines, 6+ format styles across 4 files
After: 168 lines, 3 format styles (−28%)
Behavior consistency improved. Not because the rules changed — but because the LLM stopped spending attention on format parsing and started spending it on rule following.
Three rules
1. One base format across all config files. Pick bullets or numbered steps as your primary format, not both. Use it in CLAUDE.md, AGENTS.md, skill files, rule files.
2. Tables are for comparison data only. WMS vs WMTS vs WFS? Table. A list of coding conventions? Bullets. Mixing them dilutes both and forces the LLM to context-switch.
3. Audit format drift like dependency drift. New config section? Check: does its format match the rest? If you didn't think about it, convert it.
A sixth common mistake
DeployHQ's guide lists five mistakes: writing a novel, duplicating across tools, auto-generators, including linter-handled rules, forgetting to update.
Here's the sixth: mixing format styles across config files. It's subtler than the others — each file looks fine alone. The problem only surfaces when the LLM reads them together, paying a parsing tax on every context switch.
Bottom line
You wouldn't write half your codebase in camelCase and half in snake_case. Don't do it to your AI config files. Format consistency isn't aesthetic — it's a performance optimization for the one reader that matters: the LLM.
Top comments (0)