Write useful AGENTS.md instructions in Markdown

Short answer: use AGENTS.md as a small, task-aware map of your project. Describe the repository, important conventions, commands that actually work, and boundaries agents must respect. Link to deeper documentation when a task needs it. A Markdown file is only useful when the coding tool discovers and reads it.

What an instruction file does

Files such as AGENTS.md hold durable repository context: what the project is, how its parts fit together, which commands verify work, and which constraints are easy to miss. Some tools also support their own instruction files or referenced Markdown. The names and loading rules differ between products, so confirm the current documentation for each agent instead of assuming that every tool reads every filename.

For example, OpenAI describes AGENTS.md as repository guidance for Codex, while GitHub documents support for AGENTS.md and .github/copilot-instructions.md in Copilot CLI. Their details are product-specific. The shared idea is simpler: put stable project knowledge in a place the tool actually loads, and keep the user's current task in the prompt.

Keep it focused and current

Instructions can become counterproductive when they repeat entire architecture guides, insist on reading unrelated files for every task, or list commands nobody has run recently. A useful file points to a source of truth and says when that source matters. For a small typo, an agent should not need to load database and deployment manuals; for a storage change, it should.

• Prefer facts over slogans. “Run npm run typecheck:landing after changing landing TypeScript” is more actionable than “write high-quality code.”
• Name the scope. Say which files define production behavior and which route, package, or test covers the feature.
• State real boundaries. Mention data loss, secrets, production, or compatibility risks that are specific to this repository.
• Link selectively. Point to a deeper guide for the matching task instead of copying it into the instruction file.
• Review it after the project changes. Remove old test counts, dead paths, retired scripts, and temporary restrictions.

A starter AGENTS.md template

Copy this outline and replace each placeholder with verified repository details. Delete sections that do not help the next contributor.

# Project instructions

## Purpose
One or two sentences describing the product and its main runtime.

## Where to look
- [Feature or route]: path/to/source and its relevant test.
- [Storage or API]: path/to/source; read docs/storage.md before changing it.

## Working conventions
- Keep changes within the requested feature.
- Follow the nearest existing implementation pattern.
- Do not place secrets, credentials, or user content in source or logs.

## Verification
- Install: npm ci
- Focused check: npm run typecheck
- Full check: npm test

## Boundaries
- Never deploy or change production settings from this repository task.
- Preserve existing user data and migration compatibility.

A nested instruction file can give narrower guidance for one directory when the agent supports that behavior. Keep overlapping rules consistent: a child instruction should refine the parent, not quietly contradict it.

Check that it helps

1. Open the target coding tool and confirm the file's discovery rules.
2. Ask it to make a small, reversible change in the relevant folder.
3. Check that it uses the right source files and verification command without loading unrelated manuals.
4. Review the diff yourself. Instructions guide work; they do not replace code review or tests.

Do not put API keys, credentials, private customer information, or instructions to expose secrets in an agent file. Repository guidance can be shared with tools and contributors, so treat it as ordinary project documentation.

Want to inspect a small example? Try it in a Markdown preview, then verify your publishing destination.