Before AI Takes Over Your Project, Write Its Manual: A Practical AGENTS.md Guide

Why you need it: agents start every session with amnesia

You've seen this: you open a fresh agent session, ask it to fix a bug, and it spends twenty minutes hunting for the test command — then runs the wrong one. Or it cheerfully refactors the legacy code you explicitly wanted untouched. The agent isn't stupid — it has amnesia. Every new session is a blank slate, while your project runs on unwritten rules.

AGENTS.md (and its relatives README, CLAUDE.md, .cursorrules) solves exactly this: a project manual written for AI. The economics are excellent: one hour of writing saves twenty minutes of trial-and-error in every future session, plus a few avoided disasters. It's the highest-ROI hour in vibe coding.

The 5 things a manual must contain

1. One-line project summary + architecture map. Line one says what this is and who it's for. Then a directory map: what each top-level directory does, which files the core flows pass through. What agents fear most isn't hard code — it's not knowing where to start. The map fixes that.

2. Common commands — every single one. Install, dev server, tests, lint, build, deploy — each command must actually run, copy-paste ready. This is the densest-value section and the easiest to get wrong: the command you think works and the one that actually works are often different things. Run each one yourself after writing it down.

3. Conventions and forbidden zones. Code style (which formatter, naming habits), architecture rules (where new features go, how state is managed) — and most importantly, what not to touch. "Don't hand-edit the migrations directory." "This API serves third parties — keep backward compatibility." The forbidden list matters more than conventions, because an agent's default is "if it looks reasonable, do it."

4. Known gotchas. The traps you hit that every newcomer (and AI) will hit again: tests must run in order, an env var differs between local and CI, a third-party API has weird rate limits. One line per trap: symptom + correct action. This is knowledge only you have as the owner — it's not in the docs and you can't see it in the code.

5. Definition of done. What must happen after changing code: which tests to run, which docs to update, commit message format. Define "done" precisely, or the agent will hand you something that merely looks done.

Three anti-patterns: worse than writing nothing

Anti-pattern 1: writing prose. Agents don't read prose; they read checklists, commands, and rules. Three paragraphs of project vision are useless — what helps is "run tests with npm test, not npm run test:watch." List when you can, command when you can, describe only when you must.

Anti-pattern 2: stale docs. The most poisonous kind: an outdated manual is worse than no manual. The agent will trust what you wrote one hundred percent — when a command fails it will doubt itself first, take detours, and only suspect the docs last. Changing code without updating the manual is poisoning your own agent.

Anti-pattern 3: secrets in the manual. The manual gets stuffed into the prompt, and prompts go to model vendors and into logs. API keys, database passwords, internal hosts — not a single character belongs here. Where credentials are needed, write "read from environment variables," never the values.

Maintenance discipline: make the manual smarter over time

A manual isn't write-once; it should be alive. Two rules:

First: every pitfall the agent hits goes into the manual. This is the key discipline. The agent wandered into the wrong directory, ran the wrong command, misused an API — don't just curse under your breath; turn it into a forbidden rule or a gotcha. Next session, that pitfall no longer exists. Your manual should get thicker with use (and pruned regularly).

Second: have the agent review the manual periodically. Every few weeks, open a session and ask the agent to check the manual against the current code: which commands no longer run, which directory structures changed, which conventions nobody follows anymore. AI maintaining docs written for AI — the loop closes.

A minimal template you can copy today

Don't aim for perfect on day one — aim for existing. This skeleton covers most projects:

# Project name: one line on what and for whom
## Quick start (copy-paste runnable commands)
## Directory map (what each top-level dir does)
## Dev conventions (style, architecture, naming)
## Forbidden zones (don't touch, don't use, don't change)
## Known gotchas (symptom + correct action)
## Definition of done (what to run after changes)

After writing it, do one thing: open a fresh agent session, show it only the manual, and have it run the quick start. Wherever it breaks is where the manual needs fixing. Five minutes of testing filters out ninety percent of staleness and typos.

Our take: the manual is a contract between you and the agent

At a deeper level, AGENTS.md is a contract: you make the project's tacit knowledge explicit, and the agent commits to working by it. The clearer the contract, the less supervision you need — and that is what "one-person team" really means: not one person doing everything, but one person setting the rules while agents execute them.

Many people think vibe coding means "just talk and it works." The truth is the opposite: the more you let AI do, the more precisely the rules must be written. A casual sentence can start a project, but only a written manual keeps it alive. Spend the hour today; every agent session tomorrow will thank you.