Skip to content
ML2
Vibe-Coding & Prompt-to-AppSetupAGENTS.mdCLAUDE.mdcontexthabits

Write one AGENTS.md that every coding agent reads

Added ⧉ Copyable prompt below

Our verdict

The cheapest upgrade to any vibe-coded or agent-built project. AGENTS.md is an open format read by Cursor, Codex, Gemini CLI, Aider, goose and others, and Claude Code reads it when there is no CLAUDE.md. Keep it short and universal: practitioners report agents start ignoring bloated files.

Who it's for
Anyone using more than one coding agent, or handing a repo to agents regularly
Leverage
Every agent session starts with the same project context
Effort
Low
Date added

What it does

AGENTS.md is plain Markdown at the repo root, a README for agents with no required fields. The format site recommends a project overview, build and test commands, code style, testing instructions and security notes, with nested files in monorepo packages (the closest file wins). HumanLayer's guide adds: cover what, why and how; keep it to universally applicable instructions; point to separate docs instead of pasting them in; leave style to linters; and write it by hand rather than auto-generating it.

How builders use it

  • Create AGENTS.md at the repo root with the build, test and lint commands an agent must run before finishing.
  • If you use Claude Code with an existing CLAUDE.md, symlink one to the other (ln -s AGENTS.md CLAUDE.md) so both stay in sync.
  • Move task-specific detail into an agent_docs/ folder and list those files with one-line descriptions.
  • For Aider add read: AGENTS.md to .aider.conf.yml; for Gemini CLI set context.fileName to AGENTS.md in .gemini/settings.json.
  • Edit it whenever an agent makes the same mistake twice.

What to expect

Agents run your real test commands and follow project conventions without being told each session, and switching tools doesn't mean rewriting your instructions.

Copy this: AGENTS.md starter

# AGENTS.md

## Project
<one paragraph: what this app does and who it is for>

## Map
- app/: <what lives here>
- lib/: <what lives here>

## Commands
- Install: <cmd>
- Dev: <cmd>
- Test: <cmd>
- Typecheck/lint: <cmd>
Run test and typecheck before you say a task is done; fix failures.

## Rules
- Keep diffs small; don't refactor unrelated code.
- Never commit secrets; use env vars.

## More docs (read only if relevant)
- agent_docs/database.md: schema and migrations
- agent_docs/deploy.md: how releases work

Related discoveries

Want more like this?

Practical discoveries, without the noise.

Get the newsletterMore in Vibe-Coding & Prompt-to-App