Parallel Works
View as Markdown
Share:

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:

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.

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:

# 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