AGENTS.md Is Programming for Your AI Agent, Not Documentation for Humans

If you use a coding agent for any real length of time, you hit the same wall: the agent keeps making mistakes you already corrected. Wrong package manager. Banned patterns. Edits to files that shouldn't be touched. You fix it, it happens again, you fix it, and eventually you're supervising the tool more than it's saving you time. The standard advice is "write better prompts" — which treats a memory problem as a wording problem. The actual fix is architectural: give the agent a permanent, project-level context file it reads at the start of every session. It's called AGENTS.md, and it's the closest thing your agent has to a memory. But here's the catch: most people create one and see no change, because they filled it with prose. They wrote a document, and the agent ignored it — because a document isn't what it's supposed to be. Prose is ambiguous, and it gives the agent nothing it doesn't already assume about a generic project. AGENTS.md is programming for an AI agent, not documentation for humans. This article explains why that distinction is everything — and what the file looks like when you write it as code. Why your agent forgets everything Coding agents are stateless. Between sessions, they retain nothing. Every conversation starts from scratch: a blank context, plus a set of guesses derived from code the agent saw in training — which is other people's code, not yours. That's the entire reason you repeat yourself. It's not that the model is bad, and it's not that you're bad at prompting. The agent genuinely does not know that your project uses pnpm, that your tests need a running database, or that dist/ is generated and must never be edited. It has to guess, it guesses wrong, you correct it, and the correction evaporates the moment the session ends. Anthropic's numbers confirm how wide this gap is: engineers use AI in roughly 60% of their work but fully delegate only 0–20% of tasks. The missing piece isn't model capability — it's setup. A well-configured agent can run autonomously; a stateless one requires constant babysitting. The file fixes this because of a mechanism that almost no guide explains: the agent re-reads it at the start of every session. Instructions you type in a chat get buried under newer tokens and drift out of attention — that's context drift, and it happens in every long conversation. Instructions in a file don't decay, because they're re-read, not remembered. The agent doesn't recall your rules from a previous session; it loads them fresh, every single time. Think of it as onboarding documentation for an AI employee. A README tells humans what the project is. AGENTS.md tells the agent how to work here: the exact commands, the conventions, the "don't touch" zones, and the traps that have already hurt someone. AGENTS.md is code, not prose Here's the mental shift that changes everything. Documentation describes a system. Code causes behavior. When you write AGENTS.md like a README — descriptive, warm, comprehensive — you're writing prose the agent reads and mostly ignores, because prose is ambiguous and the agent already has a default behavior baked in. When you write it like code, every line has a job. A line that doesn't change an edit, doesn't earn its place. The rules for writing it well are the same rules you'd apply to good code: Token cost is real. Every word in this file is loaded into context at the start of every single session, for every single task. A 500-word backstory about your team's engineering philosophy displaces 500 words of actual task context. And context bloat isn't free — Chroma's 2025 study found that all 18 frontier models tested degrade in accuracy as input grows, some dropping from 95% to 60% past a threshold. A bloated file isn't neutral; it's actively making the agent worse. Keep it under ~200 lines. If removing a line wouldn't change the agent's output, delete it. Specificity beats aspiration. "Write clean, maintainable code" does nothing — the agent already tries to do that. Only include rules that are specific to your project and that the agent couldn't figure out from reading the code. "Use pnpm, not npm" changes behavior. "Follow best practices" doesn't. Every "never" needs an "instead." Pure prohibitions create dead ends. "Never use any" leaves the agent guessing what to do. "Never use any — use unknown and narrow it with type guards" gives it an escape route. The same rule in miniature: "Use pnpm" is a fact the agent will forget; "Never use npm — install and run everything with pnpm" changes a behavior and names the alternative in one line. Structure aids parsing. Headers, bullets, and exact commands are easier to prioritize than paragraphs. The same content, organized, is ten times more useful. One more thing worth being honest about: this is leverage, not magic. As Martin Fowler puts it, context engineering raises the probability of useful results — it can never guarantee them. No matter how good your file is, an LLM is still an LLM. When a rule absolutely must hold, don't write it in Markdown; enforce it deterministically with a hook. Treat the file as your agent's guidance, and hooks as its guardrails. The drop-in template Here's the skeleton. It deliberately mixes two kinds of content. The lean core — sections 1, 5, 6, 7, 9 — is the part that changes edits: exact commands, conventions, guardrails. The workflow contract — sections 2, 3, 4, and the "when in doubt" checklist in section 8 — tells the agent how to operate: plan before code, an approval gate, a skills whitelist. That's not filler; it programs how the agent works with you. It reflects one popular workflow — supervised "vibe engineering," where the agent writes its own implementation prompts and you approve them. Run that workflow and it pays off; work more autonomously or manually and drop it — the lean core works everywhere. Either way, this is a template, not a finished file: anything that isn't true for your project gets deleted, not kept. # AGENTS.md You are a principal-level engineer and AI implementation agent working on , . Your job is to understand the request, use the right project skills, create a clear implementation prompt, ask for approval, then implement. --- # 1. Product . Build only: - - Do not overbuild. --- # 2. Workflow For every implementation request: 1. Read `AGENTS.md`. 2. Read the skills explicitly mentioned by the user. 3. Read clearly needed supporting skills from the approved skill list. 4. Inspect relevant code. 5. Ask a focused question only if the task has meaningful ambiguity. 6. Create a detailed prompt file in `prompts/`. 7. Ask: "I prepared the implementation prompt at `prompts/.md`. Is this good to execute?" 8. Implement only after user approval. 9. Run available checks. 10. Share exact steps to test or run the completed feature. Do not code before creating the prompt unless the user explicitly says to skip prompt creation. --- # 3. Skills Use only these skills: - `.agents/skills/` Do not invent new skills. --- # 4. Prompt files Prompt files live in the `prompts/` directory. Each prompt must include: - goal - skills read - existing code inspected - decisions or assumptions - files likely to change - implementation requirements - security requirements - acceptance criteria - checks to run - exact manual test steps expected after implementation --- # 5. Architecture Keep these layers separate: - : - : --- # 6. Tech stack Use: - Do not use: - --- # 7. Source of truth