What's Actually In My AGENTS.md

My AGENTS.md file started as a junk drawer. I thought it needed style notes and tech stack details. I was wrong.

An AI agent will ignore your formatting rules. It will follow your rules that fight its worst instincts.

Here is what I learned from testing these files against my own code.

The Permission To Stop

The first rule is not about code. It is about permission.

Agents want to look helpful. They resolve ambiguity by picking an answer silently. This leads to hundreds of lines of wrong code.

I tell my agents to stop and ask when things are unclear. I tell them to state assumptions. I tell them that saying "I am not sure" is a success, not a failure.

The Rules Of Forbidden Habits

The most useful rules name a bad instinct and forbid it.

• Do not over-build. Write the minimum code to solve the problem. No speculative frameworks. • Do not over-reach. Touch only what you must. A ten-line change should not become a two-hundred-line diff. • Do not average patterns. If you see two different coding styles, do not mix them. Pick one and explain why.

The Difference Between Guidance And Enforcement

Models drift from instructions. A rule in a markdown file is a suggestion, not a contract.

I split my file into two tiers:

  1. Guidance: Style and philosophy. This lives in prose.
  2. Enforcement: Hard requirements. Do not put these in the file. Put them in a CI check or a script.

If a rule must happen every time, make it impossible to merge if it fails. An instruction is a courtesy. A gate is a guarantee.

Trust The Check, Not The Claim

Agents often claim tests pass from memory. They do not always re-run them.

I tell my agents to define success through tests. Instead of "fix this bug," I say "write a test that reproduces this bug, then make it pass."

Never trust a claim without a fresh check.

The Log Of Scars

I keep a section for lessons learned from mistakes. I call these scars.

An agent has no memory of past pain. It will step on the same landmine every single time.

Write down the specific errors, the weird API behaviors, and the silent failures. Mapping these landmines saves you hours of lost time.

The goal of this file is to encode judgment. Formatting rules write themselves. Judgment is what you must write down.

Source: https://dev.to/miteshethos/whats-actually-in-my-agentsmd-434e

Optional learning community: https://t.me/GyaanSetuAi