> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerotwo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Project instructions with AGENTS.md

ZeroTwo reads project instruction files before doing Cowork or ZeroCode work in a local folder. Use them to set repository norms, test commands, and working agreements so every run starts with the same context.

## Which file ZeroTwo uses

In a local project folder, ZeroTwo loads **exactly one** instruction file, chosen by priority:

1. `ZEROTWO.md`
2. `AGENTS.md`
3. `CLAUDE.md`

The first file that exists at the project root with non-empty content wins. Lower-priority files are ignored — they do **not** merge.

Instruction files can include other markdown with `@include` paths. Content is capped for prompt size; very large files are truncated.

You can also keep global defaults under `~/.zerotwo/` for preferences that apply across projects.

## Create project instructions

1. In your repository root, add `AGENTS.md` (or `ZEROTWO.md` if you want ZeroTwo-specific guidance to win over other tools' files):

```md theme={null}
# AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Prefer `pnpm` when installing dependencies.
- Ask before adding new production dependencies.
- Document public utilities in `docs/` when you change behavior.
```

2. Open the folder in the ZeroTwo desktop app (Cowork or ZeroCode).
3. Start a task and ask ZeroTwo what instructions it loaded to confirm the file is active.

## Global guidance

Create reusable defaults in your ZeroTwo home directory:

```bash theme={null}
mkdir -p ~/.zerotwo
```

```md theme={null}
# ~/.zerotwo/AGENTS.md

## Working agreements

- Always run tests after modifying application code.
- Prefer focused diffs over broad refactors unless asked.
```

Project-root `ZEROTWO.md` / `AGENTS.md` / `CLAUDE.md` still take precedence for that folder when present.

## What to put in instruction files

Good instruction content is short, actionable, and stable:

* Build, lint, and test commands for the repo
* Style or architecture constraints
* Files or directories to avoid
* How to open PRs or name branches
* Links to deeper docs the agent should read when needed

Avoid pasting large API references or generated docs into `AGENTS.md`. Point ZeroTwo at those files instead.

## Related

* [Subagents](/agent-configuration/subagents)
* [Permissions](/permissions)
* [Config file basics](/config-file/config-basic)
* [Local environments](/environments/local-environment)