Every command in the file is one you actually ran.
Agent operations
Write the project brief your agent actually reads
Turn the commands, boundaries and review path of a repository into a short AGENTS.md that an agent can follow without a long preamble in every chat.
You are writing the project instruction file for an AI coding agent.
Inputs:
- Repository and stack: [REPO]
- Commands: [COMMANDS]
- Boundaries: [BOUNDARIES]
- Review and release process: [REVIEW]
Produce a Markdown file with these sections, in this order:
1. What this repository is, in one paragraph. Name the user and the main artifact.
2. Commands: install, dev, test, lint and build. Mark the one command that proves a change works.
3. Boundaries: paths not to edit, secrets, generated files, production data and vendored code.
4. Workflow: branch, commit, test, changelog and pull request. State who reviews.
5. Ask first: the decisions the agent must bring back to a human, with examples.
6. Definition of done: the checks a change must pass before it is proposed.
7. Known traps: environment quirks, flaky tests and slow commands, if I listed any.
Rules:
- Keep it under 400 words. An instruction file that is longer than the task will be skimmed.
- Do not invent a command, a path or a policy. Write "confirm" where the input is silent.
- Do not include secrets, tokens, internal URLs or customer names.
- Write for any harness. Do not name a model or a vendor-specific file.
- Prefer one concrete example over three abstract rules.
| Variable | What to put there |
|---|---|
[REPO] | The repository name, the main language or framework and the one artifact it produces. |
[COMMANDS] | The exact commands, including the working directory. “Run the tests” is not a command. |
[BOUNDARIES] | What the agent must not touch: secrets, migrations, generated files, production config, vendored code. |
[REVIEW] | How a change reaches production: branch naming, review, CI, deploy and rollback. |
Run it
How to use this template
Write the command that proves a change works before anything else. If you cannot name it, the project is not ready for an agent.
Paste the real paths, not categories. “Do not edit the generated client” is weaker than the directory name.
Keep the file at the repository root and check it into version control. A chat instruction is not a project rule.
Run the file through a real task. If the agent still edits a forbidden path, the boundary is not specific enough.
Checks
Guardrails before you trust the output
The forbidden paths are named, not described as categories.
The ask-first list contains decisions, not chores.
No secret, token or customer name appears in the file.
Adapt
Variations worth keeping
If the repository has several apps
Add a path table: app, command, owner and deploy target. The agent should not run the root test command for a package that has its own.
If the project is a client repository
Add a data-handling section: what may leave the machine, which environment is safe to read, and who approves a dependency. Do not paste the client's credentials.
Why a project brief beats a longer prompt
Every chat starts with the same context: the stack, the test command, the folder not to touch, the way a change ships. Repeating that in a prompt is expensive and easy to get wrong. A project file is read once per session and stays with the repository.
The brief is also a test. If you cannot write down the command that proves a change works, the agent will invent one. If you cannot name the forbidden paths, the agent will guess which ones matter.
What belongs in it
- The proof command. One command that fails before the change and passes after it.
- The boundaries. Named directories, files and environments. A boundary without a path is a suggestion.
- The ask-first list. Decisions with money, data, production or scope consequences.
- The done definition. Tests, lint, changelog, review. The agent can then check itself before asking you.
What does not belong in it
- A copy of the README. Link to it instead.
- A list of every coding preference. Keep style rules in the linter.
- Vendor-specific syntax. If the file needs a harness feature, put that in a separate adapter.
- Secrets or customer data. Ever.
Adapt it to your work
For a small script, the brief can be five lines. For a client repository, add the data-handling section and the approval path for a new dependency. For a monorepo, add the path table and the package-level commands.
Failure modes
- The file is a wish list. If every rule starts with “always”, it will be skimmed. Use concrete examples.
- The agent ignores the boundary. The path is probably ambiguous. Make it exact and add a test that fails if the file changes.
- Nobody updates the file. Add it to the review checklist; an outdated instruction file is worse than none.
Related templates
This page is part of the free library.
The prompt is also in the Markdown mirror at
/prompts/write-agents-md.md. If the scenario is close but not right, send the gap to the help desk with the output you expected.
Found a gap in the library?
Send the scenario, the prompt that failed, or the harness change that broke your setup. The help desk takes questions and corrections from humans and agents, and every accepted fix updates the page date.