{
  "$type": "site.standard.document",
  "description": "What to put in AGENTS.md for coding agents: critical rules, commands, architecture notes, coding conventions, workflow rules, and maintenance habits.",
  "path": "/how-to-write-an-agents-md-that-actually-works/",
  "publishedAt": "2026-03-29T04:22:00.000Z",
  "site": "at://did:plc:bryys25pc2fnagnyxqgsglhd/site.standard.publication/3mn26bjkkmh23",
  "tags": [
    "AI",
    "Tools"
  ],
  "textContent": "I wrote about how I write and maintain AGENTS.md a few weeks ago. That post covered my process. This one is more prescriptive — what actually changes agent behavior, what doesn't, and what I've learned after maintaining these files across all my projects for over a year.\n\nI ship an AGENTS.md as part of Stacknaut, my SaaS starter kit. Every project I work on has one. I use Droid, Claude Code, and Codex daily — all reading the same file.\n\nPUT CRITICAL RULES AT THE TOP\n\nThe agent reads your file top to bottom, and earlier lines carry more weight in practice. Put the things that matter most — the things the agent must never do — at the very top.\n\n## Critical Rules\n\n- Never generate database migrations unless explicitly told\n- Never commit without running prettier on changed files first\n- Never modify files under reference/ or screenshots/\n\nEvery rule here came from a real mistake. The agent ran a Drizzle migration without asking once. I added the rule, and it never happened again.\n\nBE SPECIFIC ABOUT COMMANDS\n\nDevelopment commands are the highest-signal section. Agents guess wrong constantly about how to run tests, which package manager to use, how to build. Tell them exactly.\n\n## Commands\n\n- Package manager: `pnpm` (not npm, not yarn)\n- Dev server: `pnpm run dev`\n- Type check: `pnpm run type-check`\n- Lint: `pnpm run lint`\n- Tests: `pnpm run test`\n- Deploy: `scripts/push-and-deploy.sh`\n\n\"Use pnpm not npm\" is one line that saves me from correcting the agent every other session. The negative instruction matters — without it, agents default to npm about half the time.\n\nDESCRIBE ARCHITECTURE IN 10 LINES OR LESS\n\nThe agent doesn't need a detailed architecture document. It needs to know where things are and how they connect.\n\n## Architecture\n\nMonorepo with three packages:\n- frontend/ — Vue 3 SPA\n- backend/ — Fastify API server\n- shared/ — shared types and schemas, keep flat\n\nPath alias: `@` resolves to `src/` in both frontend and backend.\nDatabase: PostgreSQL via Drizzle ORM. Edit schemas in shared/src/schemas/, not .sql files.\n\nThat's enough. The agent will read actual files when it needs more detail.\n\nCODING CONVENTIONS CHANGE BEHAVIOR — BUT ONLY IF THEY'RE CONCRETE\n\nVague instructions like \"write clean code\" or \"follow best practices\" do nothing. The agent already tries to write reasonable code. What changes behavior are specific, testable rules.\n\n## Code Style\n\n- Function declarations for top-level functions (not arrow functions)\n- Always use curly braces for if/else/for/while, even one-liners\n- Prefer const over let; use ternary instead of reassignment\n- No comments unless the code is genuinely non-obvious\n- Object parameters for functions with more than 2 arguments\n\nEach of these prevents a specific pattern I don't want. Without the curly braces rule, the agent writes braceless one-liners half the time. Without the arrow function rule, I get a mix of styles across the codebase.\n\nTELL IT WHAT YOU DON'T WANT\n\nNegative instructions are often more effective than positive ones — they prevent the specific mistakes the agent keeps making.\n\n- Don't use axios — use fetch\n- Don't create new directories without asking\n- Don't add try/catch blocks unless the error is actually handled\n- Don't install new dependencies without asking\n\nI add these reactively. Every time the agent does something I don't like, I add a negative rule. Over a few weeks, the file accumulates exactly the guardrails this project needs.\n\nGIT COMMIT STYLE IS WORTH SPECIFYING\n\nWithout guidance, agents write commit messages like \"Updated auth module to handle edge case where user session expires during OAuth flow.\" I want single-line messages that describe the change, not a paragraph.\n\n## Git\n\n- Atomic commits, one logical change per commit\n- Single-line commit messages, lowercase, no period\n- Format: \"add login page\" not \"Added login page functionality\"\n\nSKIP EXPLANATIONS, WRITE INSTRUCTIONS\n\nThe agent doesn't need to know why you chose Vue over React. It needs to know what to do and what not to do. Save the rationale for specs and prompts during development — that's where explaining why helps the agent explore solutions and make good decisions on its own. But AGENTS.md is for standing instructions, not reasoning.\n\nBad:\n\nWe chose Vue 3 because of its Composition API which provides better TypeScript \nsupport and more flexible code organization compared to the Options API. The \nreactivity system is built on JavaScript Proxies which gives us fine-grained \nreactivity tracking.\n\nGood:\n\n- Vue 3 with Composition API and <script setup>\n- Use composables for shared logic (src/composables/)\n- No Options API\n\nThe bad version wastes context window on information that doesn't change the agent's output.\n\nENVIRONMENT AND TOOLING CONTEXT MATTERS\n\nI tell the agent about my development environment — things that aren't in the code but affect how it should work.\n\n## Environment\n\n- Dev servers auto-reload — don't restart them after changes\n- tmux session \"main\": window 0 = editor, window 1 = agent, window 2 = dev servers\n- When I say \"tmux 3.1\" I mean session \"main\", window 3, pane 1\n\nWithout the auto-reload line, agents sometimes try to restart the dev server after every file change. Without the tmux context, they can't check server output when debugging.\n\nSKILL TRIGGERS NEED HINTS\n\nI use skills for common workflows — commit, review, deploy. But the agent doesn't always pick up the right skill, especially for common trigger words. A hint in AGENTS.md fixes this.\n\n## Skills\n\n- \"commit\" → use the commit-succinct skill\n- \"review\" → use the review-dirty skill\n- \"take over\" → use the take-over-finish skill\n\nWithout these hints, the agent ignores the skill about half the time and tries to do the task from scratch.\n\nKEEP IT SHORT\n\nA bloated AGENTS.md is almost as bad as none. The agent has a finite context window, and every unnecessary line competes with lines that matter. I aim for under 150 lines. If a section grows past 20 lines, I consider extracting it into a skill.\n\nI review the file regularly and cut anything that isn't actively preventing problems or improving output. If a rule hasn't been relevant in a month, it probably doesn't need to be there.\n\nTHE REFLECT LOOP\n\nAt the end of a session, I sometimes tell the agent to reflect on what it learned and suggest updates to AGENTS.md. It adds things like \"API routes follow the pattern routes/{resource}/index.ts\" or \"always run just check before committing.\"\n\nI review what it suggests, keep the useful parts, and cut the rest. Over time, the file gets better without me having to remember every detail.\n\nWHAT DOESN'T WORK\n\nA few patterns I've tried that didn't help:\n\n * Long architecture explanations — the agent reads files when it needs detail. A brief map is enough.\n * Style guides copied from team documentation — too verbose, low signal per line. Extract the 5-10 rules that actually matter.\n * Conditional instructions (\"if using TypeScript, do X; if JavaScript, do Y\") — the agent works better with unconditional statements. Pick one and state it.\n * Aspirational rules you don't actually enforce — the agent learns to ignore instructions that don't match what it sees in the codebase.\n\nONE FILE, MULTIPLE AGENTS\n\nI use CLAUDE.md as a single-line pointer to AGENTS.md:\n\n@AGENTS.md\n\nThis way I maintain one file. Droid, Claude Code, and Codex all read it. The instructions are about the project, not the agent — \"use pnpm\" is the same regardless of which agent executes it.\n\nStart with commands and architecture. Add rules when things go wrong. Cut rules that don't matter anymore. Treat it like code — review it, refactor it, keep it tight.",
  "title": "How to Write an AGENTS.md That Actually Works",
  "updatedAt": "2026-05-23T00:00:00.000Z"
}