Minimal Starter AGENTS.md Template
A deliberately short starting point for any project, with placeholders to replace rather than prescriptions to follow. It covers the six sections that earn their place in almost every repository. Use it when you want something in place today and will grow it as the agent gets things wrong.
# AGENTS.md
<!-- Replace every placeholder. Delete anything that does not apply. A short accurate file beats a long aspirational one. -->
One line: what this project is and who uses it.
## Project
Stack: <languages, framework, database, hosting>.
Where things live:
- `src/` application code
- `src/lib/` shared helpers
- `tests/` tests, mirroring the source tree
- `scripts/` one off and maintenance scripts
- `docs/` documentation
Entry points: <the two or three files that explain how the app starts and how requests flow>.
Anything unusual a newcomer would trip over: <describe it here, or delete this line>.
## Commands
```bash
<install> # install dependencies
<dev> # run locally
<build> # production build
<test> # run the test suite
<test one file> # run a single test while iterating
<lint> # lint
<typecheck> # type check, if the language has one
```
Use <package manager> only. The lockfile is <lockfile name>.
Run <lint> and <test> before returning work.
## Code style
Keep this list short and specific. Add a rule the second time you have to correct the same thing.
- Formatting is handled by <formatter>. Do not hand format.
- <a naming convention that is actually enforced here>
- <where business logic belongs, and where it does not>
- <how errors are handled: exceptions, result types, logging>
- <how configuration is read: never inline, always through one module>
- No commented out code and no TODO without an owner.
## Boundaries
Do not touch without explicit instruction:
- `.env` and any file containing a credential. New variables go in `.env.example` with an empty value.
- The lockfile. Add dependencies through the package manager so the diff stays minimal.
- Generated code and build output: <list the directories>.
- Database migrations that have already been applied.
- `.github/workflows/` and deployment configuration.
Needs human review before merge: <auth, payments, anything that deletes data, anything that talks to a customer>.
If a task appears to require one of these, describe the change and stop.
## Testing
- Run the suite with <test command>. Run one file with <single test command>.
- Must have tests: <the layer where bugs actually hurt, for example business logic and API handlers>.
- Does not need tests: <the layer where tests are not worth it here>.
- A bug fix ships with a test that fails without the fix.
- Do not weaken a test to make it pass. If the expected behavior changed, say so in the PR.
## Git workflow
- Branch from `<default branch>`: `feat/short-description`, `fix/short-description`, `chore/short-description`.
- Conventional commits: `feat(scope): add thing`, `fix(scope): correct thing`. Imperative mood, lowercase subject, no trailing period.
- One logical change per commit. Do not mix a refactor with a behavior change.
- Never commit directly to `<default branch>` and never force push a shared branch.
- PR description: what changed, why, and how it was verified. Note any migration, environment variable, or manual step.
What each section does
Project
One paragraph telling an agent what the project is and where the important files live saves it from reading the whole tree. This is the single highest value section in any AGENTS.md. Keep it to what someone joining today would need on their first hour.
Commands
An agent that knows the real commands can verify its own work instead of handing back untested changes. Even three accurate lines here change the quality of output noticeably. Include how to run a single test, since that is what iteration actually needs.
Code style
Only write rules a reviewer would actually enforce, and let a formatter handle everything else. Two or three specific conventions beat a page of general advice. Add a rule the first time you have to correct the same thing twice.
Boundaries
Naming what must not be touched is the cheapest safety measure available, and it works even when the rest of the file is thin. Secrets, lockfiles, generated code, and CI config are the usual list. Add anything expensive or irreversible in your project.
Testing
Stating what must have tests prevents both extremes: no tests at all, and a pile of tests nobody wanted. One sentence about the required coverage is enough to start. Say how to run the suite even if the answer is one command.
Git workflow
Branch and commit conventions let an agent produce work that fits your history without being corrected. It also sets the expectation that it never pushes to the default branch. Keep it to the rules you would actually mention to a new contributor.
Which agents read this file?
Claude Code looks for CLAUDE.md. Most other agents and editors read AGENTS.md. Rather than maintaining both and letting them drift, keep one real file and symlink the other:
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.mdGit stores the symlink, so it survives cloning on macOS and Linux. On Windows it needs developer mode or a stub file that references the real one. The full comparison is in CLAUDE.md vs AGENTS.md.
Other templates
Next.js SaaS
App Router SaaS with Supabase auth, Postgres, and Stripe billing.
Turborepo Monorepo
Multi-package workspace with shared UI, config, and typed contracts.
Python / FastAPI
Async FastAPI service with SQLAlchemy, Alembic, and pytest.
Django SaaS
Django app with per-app structure, Celery jobs, and Stripe billing.