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.

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. At most one of the two is read per directory.

Personal Instructions

An AGENTS.local.md in any of the same directories is read in addition to the shared file there. Use it for personal, machine-specific notes and add it to your .gitignore. When a subagent works in its own git worktree, its AGENTS.local.md files are read from the checkout it was started from, since an ignored file is not copied into the worktree.

Size limit

The combined instruction content is capped at 32 KB. Shared files are loaded first, and AGENTS.local.md files get whatever room is left, so a long personal file never pushes out your team's instructions. Anything beyond the cap is truncated, so keep instruction files short and high-signal.

Pull Request Templates

If the repository has a pull request template, pw code gives it to the agent so the pull requests it opens follow it. It checks these paths at the repository root, in order, and uses the first that exists: .github/pull_request_template.md, .github/PULL_REQUEST_TEMPLATE.md, pull_request_template.md, PULL_REQUEST_TEMPLATE.md, docs/pull_request_template.md, and docs/PULL_REQUEST_TEMPLATE.md. Templates longer than 4 KB are truncated.

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, pw code picks it up as-is.

pw code does not read CLAUDE.md or GEMINI.md. If your instructions live in one of those, rename it to AGENTS.md, or keep it and add a symlink:

ln -s CLAUDE.md AGENTS.md

pw code Overview: Feature overview and quick start
Slash Commands: Built-in and custom commands, including reusable prompt files
Settings: Configure pw code per workspace or globally
Permissions: Control what the agent can do
Hooks: The InstructionsLoaded event fires for each file loaded