𝗪𝗵𝗮𝘁'𝘀 𝗔𝗰𝘁𝘂𝗮𝗹𝗹𝘆 𝗜𝗻 𝗠𝘆 𝗔𝗚𝗘𝗡𝗧𝗦.𝗺𝗱

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 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 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.

𝗧𝗵𝗲 𝗗𝗶𝗳𝗳𝗲𝗿𝗲𝗻𝗰𝗲 𝗕𝗲𝘁𝘄𝗲𝗲𝗻 𝗚𝘂𝗶𝗱𝗮𝗻𝗰𝗲 𝗔𝗻𝗱 𝗘𝗻𝗳𝗼𝗿𝗰𝗲𝗺𝗲𝗻𝘁

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.

𝗧𝗿𝘂𝘀𝘁 𝗧𝗵𝗲 𝗖𝗵𝗲𝗰𝗸, 𝗡𝗼𝘁 𝗧𝗵𝗲 𝗖𝗹𝗮𝗶𝗺

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.

𝗧𝗵𝗲 𝗟𝗼𝗴 𝗢𝗳 𝗦𝗰𝗮𝗿𝘀

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