A Short AGENTS.md
A handful of standing rules that stop an agent from building like an intern: no compatibility layers, no speculative abstraction, no reinventing what the project already has.
The prompt
"Do not preserve backward compatibility. Remove obsolete paths instead of adding compatibility layers" (@MarcosHernanz)
The whole file, written after about 60 billion tokens of agent work, is seven lines: remove obsolete paths instead of adding fallbacks or migrations; choose the simplest implementation that meets current requirements, with no speculative abstraction or configuration; grow the system in layers from the smallest version that works end to end; keep components modular; prefer established libraries over reimplementing; check the project's existing dependencies, including their docs and types, before adding packages or writing your own; and make long-term architectural choices instead of stopgaps. Source: X/@MarcosHernanz, 2026-08-02, screenshot reviewed A widely shared summary adds an eighth: see how mature products solve the same problem before inventing a solution. Source: X/@AYi_AInotes, 2026-08-04
Why it works
AYi's summary puts the cost on volume rather than errors: agents pull in packages and abstraction layers where a few standard-library lines would do, and each request for a fix adds more code. Each rule removes one default that produces that excess. Because AGENTS.md is read by every major coding agent, the rules apply before the first line is written, where a review skill like Ponytail catches the same problems after. Source: X/@AYi_AInotes, 2026-08-04
The first rule has a cost. The author warned that "no backward compatibility" nearly led an agent to drop production database tables, and that the file suits side projects, internal tools and prototypes. In production, soften the first rule or scope it to code paths, never to data. Source: X/@AYi_AInotes, 2026-08-04
When to use it
- New projects and prototypes, from the first commit.
- Any repository where agents keep adding fallbacks and wrappers.
Never let the compatibility rule reach migrations or stored data without a human decision.
Which skill runs it
codebase-design removes special cases, fallbacks and tech debt and plans the smallest correct version. The wiki's Cutover, Not Compatibility and private page pages hold Kevin's version of the first rule, with the data boundary made explicit.
A full Chinese translation of the eight rules circulated as a token saver, a sign of how widely the file spread. Source: X/@Saccc_c, 2026-08-03
The same stance packaged as a skill: /zero-tech-debt, used for planning features and reviewing code. Source: X/@iamsahaj_xyz, 2026-08-01
Timeline
- 2026-11-03 | Page created from the 60B-token
AGENTS.mdand its production warning. Source: X bookmarks, 2026-08-02 and 2026-08-04