Put non-obvious decisions first

Start with information an agent cannot safely infer by reading a few files:

# Payments service

- Use `pnpm test:payments` before changing checkout behavior.
- Money values are integer minor units. Do not introduce floating-point math.
- `src/payments/ledger.ts` is append-only. Add compensating entries instead of updates.
- Production payment providers are unavailable in development. Use the fake gateway.
- Ask before changing public API schemas or running a migration.

Each line is an action, boundary, or fact with a direct effect on a task. "Write clean code" and "use meaningful names" usually add less value because the codebase, linter, and review process already cover them. VS Code similarly recommends keeping instructions concise, focusing on non-obvious rules, and giving the reason behind a rule when it helps with edge cases.

If a constraint is safety-critical, name the safer alternative. "Do not write to production" is useful. "Use make sandbox-seed against the local fixture; production credentials are never loaded in development" is better because it gives the agent a path to continue.

Separate global rules from local rules

One root file cannot explain every subsystem without becoming hard to use. Keep organization-wide and repository-wide rules at the root, then place a second AGENTS.md beside a subsystem with different constraints.

repo/
├── AGENTS.md
├── apps/web/
│   └── AGENTS.md
├── services/payments/
│   └── AGENTS.md
└── infra/
    └── AGENTS.md

The root file can establish the package manager, baseline checks, security boundary, and pull-request expectations. A nested file can cover a framework convention, a test fixture, or a deployment restriction that only applies in that folder. Keep the local instructions additive. If they intentionally override a root rule, say so plainly and explain the scope.

VS Code supports root and experimental subfolder AGENTS.md discovery. It also supports *.instructions.md files that apply by glob or task description. Use the latter for guidance that is truly file-specific, such as rules for generated OpenAPI clients or database migrations. A giant all-purpose AGENTS.md makes an agent carry irrelevant instructions into every request.

Give commands a purpose and a boundary

Agents need commands they can run, but a command list without context can create noisy or expensive work. State when a check is required, what it validates, and what an agent should do when it fails.

Verification

• Run pnpm lint after TypeScript changes.
• Run pnpm test:unit for changes under src/.
• Run pnpm test:e2e:checkout only for checkout, tax, or payment changes.
• Do not update snapshots without explaining the behavior change in the final report.

Avoid commands that depend on a developer's private machine state. Document the checked-in setup command, required service fixture, and expected environment variables by name, never their values. For a destructive command, say whether the agent must ask first. That creates a usable contract for autonomous work and a reviewable handoff for interactive work.

The [least-privilege checklist for AI agent tools](/r/least-privilege-checklist-ai-agent-tools) covers the access side. Instructions complement permissions. They do not replace a sandbox, secret manager, protected branch, or approval rule.

Keep instruction scope honest

An instruction can only guide a client that actually loads it. VS Code notes that file-based rules may not apply if their pattern does not match, and it provides customization diagnostics to inspect what was loaded. Its documentation also says that multiple instruction sources can be combined, with personal instructions taking precedence over repository and organization rules.

Make this visible in your team workflow. Add a small verification task after changing instructions:

1. Open a representative task in each supported agent client.
2. Confirm which instruction files the client reports as loaded.
3. Ask the agent to state the relevant test command and safety boundary before it edits.
4. Review the resulting diff and test output.

The test does not prove that every future agent run will follow every sentence. It catches a more basic failure: an instruction file that is in the repository but absent from the agent context.

Treat instructions as maintained engineering artifacts

Review AGENTS.md changes like code. A new tool, framework, service boundary, or recurring incident may justify one clear rule. An obsolete command should disappear. Use examples only when a short rule would be ambiguous, and make each example runnable or clearly illustrative.

OpenAI's Codex guidance says configured development environments, reliable tests, and clear documentation help agents work effectively. The worktrees playbook adds a related operational detail: isolated directories prevent many file collisions, but they do not isolate ports, databases, credentials, or network access. Keep those external boundaries in the environment, then document the expected workflow in the instructions.

For model comparisons, hold the same AGENTS.md, repository revision, task, and test commands constant. ISH chat can keep the conversation side-by-side, while the ISH API dashboard supports repeatable API-based tests. Otherwise, a comparison may measure the surrounding instructions more than the model.

The useful AGENTS.md is short enough to read before a task and specific enough to prevent a real mistake. If a line does neither, move it to a README, a linter, a test, or remove it.

Sources

• VS Code: Use custom instructions
• VS Code: Configure AI for your codebase
• OpenAI: Unrolling the Codex agent loop
• GitHub Changelog: Copilot code review and AGENTS.md support