---
title: "Write one instructions file for agents · Agent Wranglers"
url: https://agentwranglers.se/playbook/ai-assisted-development/setting-up-the-project/instructions-file
updated: 2026-10-20
licence: "All rights reserved"
---

# Write one instructions file for agents

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Required
- Chapter: [Setting up the project](https://agentwranglers.se/playbook/ai-assisted-development/setting-up-the-project)
- Rule: Keep one instructions file at the root of the repository that tells every agent how to build, test and change the project.
- How: Name it `AGENTS.md`, which most agents read. Claude Code reads it too, but only when the project has no `CLAUDE.md`. If you keep a `CLAUDE.md`, import the shared file from it with a line reading `@AGENTS.md`. Do not keep two copies that can drift apart. List the commands to install, test and run the project. Then add the conventions and the rules that must never break. Write each rule as a direct order, such as "Use `pnpm`, never `npm`". Keep it under 200 lines, because agents read it on every task. Add a nested `AGENTS.md` in a subproject only when its rules differ, since the nearest file wins. Name the one command that runs every check, as the [engineering playbook](https://agentwranglers.se/playbook/engineering/rules-as-code/run-one-check-before-every-deploy) describes.
- Check: A script confirms that `AGENTS.md` exists, has under 200 lines and names the check command. Then ask a fresh session how to run the tests. It answers from the file.

Example:

```markdown
# AGENTS.md

## Commands
- Install: `npm ci`
- Check everything: `./check.sh` (must pass before every commit)
- Run locally: `npm run dev`, then open http://localhost:3000

## Conventions
- TypeScript strict mode. No `any`.
- One feature per folder under `src/features/`.

## Never
- Never edit files under `migrations/` that have already run.
- Never commit `.env` files or keys.
```

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers ai development playbook: https://agentwranglers.se/playbook/ai-assisted-development/setting-up-the-project/instructions-file`.

- Next: [Keep code small enough for an agent to read](https://agentwranglers.se/playbook/ai-assisted-development/setting-up-the-project/agent-sized-modules)
- [Setting up the project](https://agentwranglers.se/playbook/ai-assisted-development/setting-up-the-project)