What to Put in AGENTS.md

AGENTS.md is a small contract between a repository and the coding agents that work inside it.

The best version is not a giant policy document. It is a short, practical guide that helps an agent answer the questions it would otherwise guess at: what the project is for, what quality means here, what style to follow, what commands to run, and what not to change.

Start with the mission

Open with the reason the repository exists. Agents are very good at local edits, but they can lose the larger product shape if the repo does not state it clearly.

For a personal website, the mission might explain the intended audience, the desired first impression, and the kind of content the site should privilege. For a backend service, it might explain the business domain, reliability expectations, and the boundaries the service owns.

Good mission statements are specific enough to constrain decisions:

Build a trust-first, writing-led personal site for a staff-level backend engineer.
The site should feel calm, credible, readable, and fast.

That tells an agent much more than “make it look modern.”

Describe the architecture

Agents need to know where things belong. Add a compact map of the important folders and the responsibility of each area.

src/lib/config/       site facts and reusable configuration
src/lib/content/      content loading and normalization
src/lib/components/   reusable Svelte components
src/routes/           public routes and page composition
src/content/posts/    Markdown and mdsvex blog posts

This keeps future changes from drifting into random files. It also makes review easier because each edit has an obvious home.

Name the style rules that actually matter

Do not list every preference in your head. Focus on rules that protect the codebase from common failure modes.

For this site, useful rules are:

• Prefer semantic HTML and plain CSS.
• Keep the site statically generated unless there is a clear reason not to.
• Add dependencies only when they remove real complexity.
• Keep claims grounded in verified personal facts.
• Do not publish generic AI-written posts as finished personal essays.

Those rules are small, but they shape many decisions.

Include commands

Every repository instruction file should tell agents how to verify their work.

pnpm check
pnpm lint
pnpm build

If there are narrower commands for unit tests, end-to-end tests, formatting, or content validation, include those too. The goal is to make the correct verification path obvious.

Define done

The most useful part of AGENTS.md is often the definition of done. It turns vague intent into a checklist.

For a website, done might mean:

• The page is responsive and readable.
• Metadata is present and specific.
• Navigation still works without JavaScript.
• The build passes.
• The change supports the positioning of the site.

For a service, done might include tests, migrations, observability, backward compatibility, or rollout notes.

Keep it short enough to be read

The file should be long enough to encode judgment, but short enough that an agent can load it and use it. A good AGENTS.md is not a replacement for architecture documents. It is the first page of context: the part that keeps everyday changes aligned with the project.

When in doubt, write the instruction that prevents the next bad diff.