Put verified setup and check commands, important code boundaries and repository-specific conventions in AGENTS.md. Leave out broad summaries that duplicate the code, stale plans and claims you have not checked.
The file is useful when it saves an agent from repeating a mistake somebody has already paid for.
It is expensive when the next job starts by reading instructions that no longer describe the repository.
01which commands belong in AGENTS.md?
If the tests run with npm test, say so. If they need a service, a fixture or a particular working directory, include that detail.
Verify the command before writing it down. An instruction copied from an old README can send every new agent into the same failure.
For a repository with several packages, distinguish the checks for the package being changed from the checks for the whole repository. Keep the repository's required checks explicit.
That is a better starting point than "ensure code quality", which makes the agent invent what quality means here.
02how should you describe an architecture boundary?
"Core code must not import Electron" is a boundary an agent can check. "Keep the architecture clean" is an opinion it has to interpret.
The reason helps when a job reaches the boundary: core tests run outside the desktop shell, so an Electron import breaks that property.
Name the shared interface a change must preserve. If changing it needs coordinated work, say where that work is specified.
Keep the instruction near the scope it governs when your agent supports directory-level instructions. The exact loading rules depend on the host; check that host's documentation before relying on them.
03which conventions should you write down?
A useful convention explains something a new reader would reasonably get wrong.
Perhaps a generated file must never be edited directly. Perhaps a legacy identifier is still the app's on-disk identity. Perhaps a hook must answer immediately even when its side effect fails.
Record the rule and the reason. An unexplained oddity looks like cleanup work to a fresh agent.
Do not copy every naming preference into the file. The neighbouring code already demonstrates many of them.
04when should repository instructions be updated?
A retired feature can survive in a guidance file long after its screen is deleted. The next agent reads it as the build order and starts putting the feature back.
Mark historical documents clearly. Keep the current scope decision easy to find. When two documents disagree, name which one wins.
Review the instructions when the commands, package layout or product scope change. A document does not become current because its filename is familiar.
05what belongs in instructions and what belongs in the ledger?
An instruction says what should happen. A record says what did happen, at a particular commit.
Keep successful check commands and recurring failures with the evidence that produced them. If the paths they depend on change, reconsider the record before using it again.
Wayari keeps that history in the repository ledger. Its atlas derives facts from Git, while the ledger holds observed commands, failures and conventions. Your existing AGENTS.md and CLAUDE.md remain where they are.
The thread documentation explains how to read what happened across jobs.
06what should you keep and what should you remove?
Use the next job as the test of whether an instruction earns its place.
| Candidate instruction | Keep or change it | Reason |
|---|---|---|
| Run the package typecheck from its working directory. | Keep after verifying the command. | Saves a repeat setup failure. |
| Keep core modules independent of Electron. | Keep with the reason and affected paths. | Names a boundary the agent can check. |
| Build a feature the product has retired. | Remove or mark as history. | Gives the next job a stale scope. |
| This repo is high quality. | Replace with a required check or omit. | Gives no decision an agent can apply. |
07does more context make an agent better?
More text can contain useful instructions and outdated distractions at the same time. Length alone cannot tell you whether it helps.
Check the outcome on comparable jobs. Did the agent use the right command? Did it respect the boundary? How often did a person have to correct it?
Wayari has not established a measured improvement from repository memory. The memory post describes the control arm it keeps for that question.
For the next edit to your instructions, remove one stale rule and verify one command. Then give the next job a brief with a finish line.
08should AGENTS.md contain secrets?
No. Document the approved source of credentials and how the repository expects them to be supplied. Keep the actual values out of instructions and version control. A job-specific acceptance check belongs in the brief, rather than the repository's permanent rules.
