Write Repository Instructions Like an Operational README
A useful instruction file contains only what can't be reliably derived from the code: the real commands, non-standard constraints, architectural boundaries, dangerous zones, and the evidence format. Everything else is noise that crowds out the useful.
Here's the companion project's AGENTS.md: briefly about scope, verification, and safety.
# Project instructions
## Scope
- This repository is the runnable companion to the Russian book about coding agents.
- Preserve strict TypeScript and the dependency-free runtime.
- Make the smallest patch that satisfies the task contract.
## Verification
- Run `npm run check` after code changes.
- Treat command output as evidence. Do not claim success without the exit status.
- Do not weaken tests, TypeScript flags, path checks, or command allowlists to make a check pass.
## Safety
- Never execute a command assembled as one shell string.
- Keep `shell: false`, a contained working directory, a minimal environment, a timeout, and an output limit.
- Resolve and validate every user-controlled path before reading or writing.
- Never add credentials, tokens, private keys, or real `.env` files.It's worth including the install, focused-test, and full-check commands; the runtime and package-manager versions; module boundaries and the source of truth; forbidden operations and generated files; the final-report format. It's not worth including generic advice like "write clean code," full API documentation, a list of every file, requirements the linter already enforces strictly, and secrets.
The key move is a verifiable rule instead of an adjective.
Weak · Verifiable
- Write safely - Don't build a shell string; use argv and shell: false
- Don't break the code - Run the focused test, then npm run check
- Change carefully - Don't change files outside the agreed write scope
- Follow the architecture - Business rules stay in src/domain; adapters don't own them
Anthropic recommends keeping CLAUDE.md short and checking each line with the question: would deleting it lead to a recurring mistake. Cursor advises focused, actionable, and scoped rules; Codex, a short practical AGENTS.md. This is a consistent recommendation of the docs, not a magic length.
Update after an actual mistake. Every new rule should answer an observed recurrence. If the agent runs the wrong command twice, add the right one. If a rule no longer affects behavior, delete or rewrite it.
A static instruction isn't always enough. When you need an ordered sequence with inputs and stop conditions, the process is packaged as a skill.