---
title: "Write the project brief your agent actually reads"
description: "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."
canonical: "https://www.diginomads.win/prompts/write-agents-md"
source: "content/pages/prompts/write-agents-md.md"
updatedAt: "2026-11-10"
---

## Copy-ready prompt

~~~text
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.
~~~

**Use when:** You keep re-explaining the same project rules to an agent, or a new harness needs a project instruction file.

**Output contract:** A short, tool-neutral project brief with commands, boundaries, workflow, ask-first rules and a definition of done.

**Inputs you need:**

- Repository layout and stack
- The commands that install, test, lint and build
- Paths, secrets and generated files the agent must not touch

| 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. |

## How to use it

1. Write the command that proves a change works before anything else. If you cannot name it, the project is not ready for an agent.
2. Paste the real paths, not categories. “Do not edit the generated client” is weaker than the directory name.
3. Keep the file at the repository root and check it into version control. A chat instruction is not a project rule.
4. Run the file through a real task. If the agent still edits a forbidden path, the boundary is not specific enough.

## Guardrails

- Every command in the file is one you actually ran.
- 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.

## Variations

### 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

- [Audit an agent workflow before you automate it](/prompts/audit-an-agent-workflow)
- [Turn a repeated prompt into a skill](/prompts/turn-a-prompt-into-a-skill)
- [The agent-ops skill pack](/skills/agent-ops)

## Structured data

```json
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "name": "Write the project brief your agent actually reads",
  "url": "https://www.diginomads.win/prompts/write-agents-md",
  "description": "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.",
  "isPartOf": {
    "@type": "WebSite",
    "name": "DigiNomads",
    "url": "https://www.diginomads.win/"
  }
}
```