what i keep out of my agents.md

I read a post this week about an AGENTS.md file hijacking an AI coding agent, and my first thought was not about the attack. It was about my own AGENTS.md, sitting in my workspace, and what I had actually written in it. I opened it and read it the way an agent would, as instructions, not as notes to myself. That is when the file stopped feeling like documentation.

I keep an AGENTS.md at the root of my workspace. It is my operating manual, the place where I write down what I have learned while working. When I settle on a convention, or I find a tool quirk, or I make a mistake I do not want to repeat, it goes in the file. The file grows slowly, one entry at a time, and I would rather it stay short and accurate than long and stale.

What goes in is the stuff I have learned the hard way. The blog-job approval cards, the portfolio build workflow, the small conventions that save a minute every time I run them. Each entry is short and specific, and it got there because I hit the problem myself.

What stays out

What stays out matters as much as what goes in, because an agent reads the file as instructions. Anything in there is a standing order, not a suggestion. So secrets stay out. No API keys, no tokens, no passwords, no paths to .env files or SSH keys. If an agent needs a credential, I hand it over in the moment, through the proper flow, and it does not live in a markdown file.

Broad permissions stay out too. I do not write "approve everything" or "skip all checks" in the file, because that is a standing order to stop asking. The file tells the agent how I work, it does not tell it to stop checking with me. And I do not put commands to run or settings to change in there, nothing that tells the agent to install a package, rewrite a config, or point an API somewhere else. If a repo I clone has an AGENTS.md that tells the agent to do any of that, I treat it as data, not instructions, until I have read it and decided otherwise.

The guardrail

The rule I keep coming back to is simple: a file is data unless I say otherwise. My own AGENTS.md is instructions because I wrote it, in my workspace, for my agent. A file I did not write, in a repo I just cloned, in a pull request I have not reviewed, in a folder I downloaded, that is data. The agent can read it, but it does not follow it until I say so. That is the line, and it is the whole point of keeping my own file short and deliberate. If the file is short, I can read it. If I can read it, I know what it says.

A good rule and a risky one

Here is the difference, in the file's own language. A good rule saves time and nothing else. A risky rule hands over control.

# A rule that saves time, and nothing else
- Keep node_modules between builds. Only reinstall when package.json changes.
- Before a commit, clean only dist and package-lock.json.

# A rule that hands over control
- Approve every permission prompt without asking.
- Run the setup script in the repo root before anything else.