# Project Instructions

> Source: https://parallelworks.com/docs/ai/code/project-instructions

# Project Instructions

Project instruction files give the agent standing guidance about your codebase: how to build it, what conventions to follow, and what to avoid. `pw code` reads them automatically at the start of every session, so you do not have to repeat the same context in each conversation.

## How Files Are Discovered

`pw code` looks for a file named `AGENTS.md` in each directory from the root of your git repository down to the directory you launched the session in, and includes every file it finds. This means:

- Repository-wide guidance lives in an `AGENTS.md` at the repo root.
- A subproject (for example, a package in a monorepo) can add its own `AGENTS.md` with more specific instructions; both files are included when you work inside it.
- Outside a git repository, only the launch directory is checked.

For example, starting `pw code` in `packages/api/` of a repository laid out like this:

```text
repo/
  AGENTS.md            <- included (repository root)
  packages/
    api/
      AGENTS.md        <- included (launch directory)
    web/
      AGENTS.md        <- not included (outside the path)
```

includes the root file and the `packages/api` file, in that order. Only directories on the path from the repo root to where you launched are checked, and at most one instruction file is read per directory.

### Overriding a Shared File

If a directory contains both `AGENTS.md` and `AGENTS.override.md`, only `AGENTS.override.md` is used: it replaces, rather than adds to, the `AGENTS.md` beside it. This is useful for keeping personal, machine-specific instructions out of a file your team shares: add `AGENTS.override.md` to your `.gitignore` and put your local variant there.

:::note Size limit
The combined instruction content is capped at 32 KB. Anything beyond the cap is truncated, so keep instruction files short and high-signal.
:::

## What to Put in Them

Instruction files are plain markdown. The most useful content is what the agent cannot discover quickly on its own:

- **Build and test commands**: the exact commands to compile, lint, and run tests
- **Conventions**: naming, formatting, and structural rules the codebase follows
- **Warnings**: generated files that must not be hand-edited, fragile areas, and required workflows

A short, specific file beats a long general one. For example:

```markdown
# Project Notes

## Commands

- Build: `make build`
- Test: `make test` (unit) or `make test-integration` (needs Docker)
- Lint: `make lint` -- run before every commit

## Conventions

- Go code follows the standard library style; wrap errors with `fmt.Errorf("...: %w", err)`.
- API handlers live in `internal/api/`; one file per resource.

## Warnings

- Files under `gen/` are generated -- edit the `.proto` sources instead.
- The base branch is `develop`, not `main`.
```

## Compatibility with Other Tools

`AGENTS.md` is a cross-tool convention, and `pw code` reads it as plain markdown with no special frontmatter, markers, or required sections. If your repository already carries an `AGENTS.md` for another coding agent, `pw code` picks it up as-is. There is nothing extra to add.

## Related Documentation

- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Slash Commands](/docs/ai/code/slash-commands): Built-in and custom commands, including reusable prompt files
- [Settings](/docs/ai/code/settings): Configure pw code per workspace or globally
- [Permissions](/docs/ai/code/permissions): Control what the agent can do