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.

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

Put Critical Rules at the Top

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

## Critical Rules

- Never generate database migrations unless explicitly told
- Never commit without running prettier on changed files first
- Never modify files under reference/ or screenshots/

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

Be Specific About Commands

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

## Commands

- Package manager: `pnpm` (not npm, not yarn)
- Dev server: `pnpm run dev`
- Type check: `pnpm run type-check`
- Lint: `pnpm run lint`
- Tests: `pnpm run test`
- Deploy: `scripts/push-and-deploy.sh`

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

Describe Architecture in 10 Lines or Less

The agent doesn’t need a detailed architecture document. It needs to know where things are and how they connect.

## Architecture

Monorepo with three packages:
- frontend/ — Vue 3 SPA
- backend/ — Fastify API server
- shared/ — shared types and schemas, keep flat

Path alias: `@` resolves to `src/` in both frontend and backend.
Database: PostgreSQL via Drizzle ORM. Edit schemas in shared/src/schemas/, not .sql files.

That’s enough. The agent will read actual files when it needs more detail.

Coding Conventions Change Behavior — But Only If They’re Concrete

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

## Code Style

- Function declarations for top-level functions (not arrow functions)
- Always use curly braces for if/else/for/while, even one-liners
- Prefer const over let; use ternary instead of reassignment
- No comments unless the code is genuinely non-obvious
- Object parameters for functions with more than 2 arguments

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

Tell It What You Don’t Want

Negative instructions are often more effective than positive ones — they prevent the specific mistakes the agent keeps making.

- Don't use axios — use fetch
- Don't create new directories without asking
- Don't add try/catch blocks unless the error is actually handled
- Don't install new dependencies without asking

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

Git Commit Style Is Worth Specifying

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

## Git

- Atomic commits, one logical change per commit
- Single-line commit messages, lowercase, no period
- Format: "add login page" not "Added login page functionality"

Skip Explanations, Write Instructions

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

Bad:

We chose Vue 3 because of its Composition API which provides better TypeScript 
support and more flexible code organization compared to the Options API. The 
reactivity system is built on JavaScript Proxies which gives us fine-grained 
reactivity tracking.

Good:

- Vue 3 with Composition API and <script setup>
- Use composables for shared logic (src/composables/)
- No Options API

The bad version wastes context window on information that doesn’t change the agent’s output.

Environment and Tooling Context Matters

I tell the agent about my development environment — things that aren’t in the code but affect how it should work.

## Environment

- Dev servers auto-reload — don't restart them after changes
- tmux session "main": window 0 = editor, window 1 = agent, window 2 = dev servers
- When I say "tmux 3.1" I mean session "main", window 3, pane 1

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

Skill Triggers Need Hints

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

## Skills

- "commit" → use the commit-succinct skill
- "review" → use the review-dirty skill
- "take over" → use the take-over-finish skill

Without these hints, the agent ignores the skill about half the time and tries to do the task from scratch.

Keep It Short

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

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

The Reflect Loop

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

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

What Doesn’t Work

A few patterns I’ve tried that didn’t help:

  • Long architecture explanations — the agent reads files when it needs detail. A brief map is enough.
  • Style guides copied from team documentation — too verbose, low signal per line. Extract the 5-10 rules that actually matter.
  • Conditional instructions (“if using TypeScript, do X; if JavaScript, do Y”) — the agent works better with unconditional statements. Pick one and state it.
  • Aspirational rules you don’t actually enforce — the agent learns to ignore instructions that don’t match what it sees in the codebase.

One File, Multiple Agents

I use CLAUDE.md as a single-line pointer to AGENTS.md:

@AGENTS.md

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

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