put the commands, boundaries and repository facts in AGENTS.md that a coding agent cannot safely infer from the code. leave out the things a good agent can discover by reading.
the file is not a company handbook. it is a practical map for the next task. its value comes from preventing expensive guesses before they become edits.
01start with how to check a change
the highest-value lines are usually the commands that establish whether a change is ready. name the package manager, the standard test command, typecheck, lint and any browser or integration check that is required before review.
be precise about location when it matters:
apps/web: pnpm test
apps/web: pnpm test:e2e
run pnpm typecheck from the repository root
an instruction like "run tests" is not enough in a monorepo with several suites. an agent that finds a fast passing command may believe it has done the job.
02record boundaries, not preferences
write the things an agent must not silently change: do not modify generated migrations, do not use production credentials locally, do not add packages without asking, do not edit the billing provider or do not touch main.
these are not style notes. they are boundaries around risk. they make a pull request smaller and make a surprising change easier to spot.
avoid a long list of generic advice. "write clean code" cannot settle a decision. "keep the existing authentication provider and session format" can.
03name the confusing parts of the repository
include facts that are true but hard to infer quickly. perhaps prices are stored in cents, the public API is versioned in a separate package or every permission check must use one helper.
link to the source of truth when you have one. an agent can then inspect the current schema or design system rather than treat a sentence in AGENTS.md as a stale copy.
04make ownership visible
if certain directories have different rules, put a smaller AGENTS.md close to them. the web app may have a browser-check requirement while the shared package only needs unit tests. local instructions reduce the chance that a global file becomes a page nobody updates.
the same approach helps with sensitive code. a short file in payments or authentication can name the review expectation without making every ordinary task carry it.
05keep it true
review AGENTS.md when a command changes, a failure surprises the team or an agent needs a decision it should have received. remove rules that no longer apply. a short accurate file is more useful than an exhaustive one people learn to ignore.
Wayari can serve standing instructions to every agent that joins the repository. the work still starts fresh, but the boundary that protects the repository does not have to be rediscovered in every chat.
06a small template to adapt
# repository instructions
## checks
- Install dependencies: <verified command>
- Typecheck: <verified command and working directory>
- Test changed behaviour: <verified command>
## boundaries
- <name a boundary and why it exists>
## repository facts
- <one convention a reader would otherwise get wrong>
Replace every placeholder with a fact you have verified. The repository instructions guide explains which rules earn their place.
Keep task-specific goals in the brief. Keep observed history in the repository ledger. See the thread documentation.
