What Goes Into My AGENTS.md File

After hearing about a study from the ETH Zürich university, I drastically reduced what goes into my AGENTS.md files.

The study determined that more documentation can hurt agents’ output instead of improving it, and this was amazing news for me as I’m always eager to find new ways to optimize in my AI workflow.

I applied this immediately: what used to be extensive instructions—about how I approach coding, general best practices and an overview of my project’s structure—became a short and lean document limited to the following: 

Non-Derivable Facts: Critical context and design choices that cannot be inferred merely from reading the source code.

Working Preferences & Methodology: Explicit conventions like Test-Driven Development (TDD) and quality standards.

Specific Execution Commands: Precise build or test commands for specific parts of the repository that agents tend to guess incorrectly.

Product Invariants & Non-Negotiable Rules: Core design constraints and product safeguards that the agent must never violate (e.g., SQL rules to prevent injections).

Commit Discipline: Boundaries around git workflows, such as preventing the agent from committing code automatically without explicit approval.

And that’s pretty much it. I’m happier than ever with this document because it’s simpler, shorter, and yet more valuable than before.

What is there is crucial to the project and will likely remain crucial for a long time, so it also became more evergreen as a result of this update.

As a side effect, maintenance becomes easier—I can keep working with it for a few weeks and see how it feels. If something’s off, it’s easier than ever to come back to it to inspect a shorter, friendlier file.

AI models are getting better by the day. 

One must keep oneself updated as well.