The obvious complaint about AGENTS.md is that it gets too long.

I get it. You open a repo, see a few hundred lines of instructions for the coding agent, and it looks like too much process.

I use coding agents on production apps every day. My AGENTS.md files get longer when the agent makes the same mistake twice.

The agent does not know your defaults

A coding agent starts with broad software knowledge. It knows common package managers, common frameworks, common test commands, common deployment patterns.

That is useful, but it also means it guesses.

It might use npm in a pnpm repo. It might run node when you use bun. It might restart a dev server that already hot reloads. It might edit generated SQL instead of the Drizzle schema. It might add a new dependency for something the standard library already handles.

AGENTS.md replaces generic defaults with project defaults.

- Use `pnpm` for installs, not npm
- Run scripts with `bun run`, not node
- Drizzle ORM; edit schemas in `shared/src/schemas/`, not `.sql` files
- Development servers live reload; do not restart them after frontend edits

Production rules are not obvious from code

Some instructions cannot be inferred safely from the codebase.

For example:

- Never remove log statements starting with "xxx"
- Never commit private data to deliverable directories
- Never commit without running prettier on changed files first
- Frontend `VITE_*` values used during Docker builds must be mounted as build secrets

The agent can read the files. It still cannot know which weird-looking log line is intentionally kept for debugging, or that a directory is shipped to customers and must not contain private company data.

It also cannot know that a deployment secret failed once because Vite needed it at build time.

These are not style preferences. They are operational constraints.

This is where a short AGENTS.md often fails. It documents the happy path. My files spend more space on the bad paths I already know about.

Long files happen when work crosses boundaries

A small frontend-only project can have a small AGENTS.md.

A production SaaS app usually crosses more boundaries:

  • frontend
  • backend
  • public API
  • shared types
  • database schema
  • background jobs
  • email
  • billing
  • deployment
  • DNS
  • logs
  • backups
  • AI agent workflow

Each boundary adds rules. Not because I want more documentation, but because the agent has more places to guess wrong.

The frontend has component conventions. The backend has validation and logging conventions. The database has migration rules. Stripe has webhook rules. Deployment has Kamal and Docker rules. The agent workflow has commit, review, and deploy rules.

If you do not write these down, the agent learns them the hard way.

Long does not mean good

There is a bad version of a long AGENTS.md.

It reads like a company handbook. It explains philosophy. It repeats the README. It has vague lines like “write clean code” and “follow best practices.” It documents commands the agent should never run.

That kind of long file is noise.

A good long AGENTS.md is dense. Each line should change behavior.

Bad:

We value high-quality code and thoughtful architecture.

Good:

- Use function declarations for top-level functions, not arrow functions
- Always use curly braces for `if/else/for/while`
- Use object parameters for functions with more than 2 arguments

The test is simple: would removing this line make the agent more likely to do the wrong thing?

If yes, I keep it. If no, I cut it.

Some instructions should become skills

AGENTS.md should not hold every workflow in full detail.

If an instruction is a standing rule, keep it in AGENTS.md.

If it is a repeatable task with steps, move it into a skill.

For example, this belongs in AGENTS.md:

- When I say "commit", use the `commit-succinct` skill

The commit workflow belongs in the skill:

  • inspect dirty files
  • run formatting
  • check tests if appropriate
  • write an atomic commit message
  • commit only the intended files

That split keeps AGENTS.md from becoming a giant procedure manual while still giving the agent enough routing information.

No need to put the whole workflow in the top-level file.

The file gets shorter after it gets longer

My AGENTS.md files grow reactively.

The agent does something wrong. I add a rule. The agent misses a command. I add the command. The agent makes a risky assumption. I add a constraint.

After a while, I review the file and cut.

Some lines become obsolete because the code changed. Some lines are too vague. Some lines belong in a skill. Some lines were only needed for an older model that behaved differently.

This is the part people skip. They keep adding rules and never prune.

Treat AGENTS.md like code:

  • add rules when they prevent real mistakes
  • delete rules that no longer matter
  • extract repeated workflows into skills
  • keep the top of the file for critical rules
  • keep commands exact

I do not care whether the file is short. I care whether the agent stops guessing.

Why I include this in Stacknaut

This is why I think a serious AI-era starter kit should ship with agent configuration.

The code is only half the product. The other half is knowing how to work on it:

  • how to modify it
  • how to test it
  • how to deploy it
  • where not to put secrets
  • what patterns to preserve
  • what mistakes have already been learned

I include a substantial AGENTS.md in Stacknaut because the starter kit is meant to be worked on by coding agents from day one.

The file is not long because I like documentation. It is long because auth, billing, deployment, infrastructure, and AI workflow all have edges.

If you are building a toy app, a tiny AGENTS.md is fine.

If you are building something that takes payments, sends emails, runs migrations, deploys containers, and gets edited by agents every day, the instruction file will grow.

That is fine, as long as the file earns its length.