we have discovered a new way to write bad documentation.

it is called AGENTS.md.

the idea is good: give coding agents context about the repo. architecture, weird decisions, how to run things, what not to break.

then people put this in there:

- never use default exports
- don't import x from y
- filenames must be kebab-case
- don't use console.log
- functions must stay under 50 lines

congratulations. you just wrote eslint in english.

if a rule can be checked mechanically, it should probably be enforced mechanically.

write a linter.

write a test.

write a tiny script.

put it in CI.

because this:

never import database code from the api layer

is much weaker than this:

error: api/users.ts cannot import from db/

the second one does not depend on the agent remembering paragraph 37 of your instructions.

it just fails.

and coding agents are actually very good at this loop:

write code → tool complains → fix code.

that is a much better system than stuffing more rules into context.

AGENTS.md should be for things that require judgment:

  • why the architecture looks weird
  • which abstractions are intentional
  • dangerous parts of the codebase
  • how to validate a change
  • tradeoffs the agent cannot infer from code

my rule is simple:

if you can write a program that decides whether the agent violated the rule, write the program.

use AGENTS.md for context.

use linters for enforcement.

please stop using markdown as infrastructure.