AGENTS.md: standing instructions

Every session starts with no memory of the last one. AGENTS.md is the file that stops you explaining the same things every morning.

Codex builds an instruction chain when it starts. It reads a global file from your Codex home directory, then walks from the project root down to the directory you are in, joining what it finds.

# Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

That is the global one: your preferences, in every repository you open. Project specifics do not belong here.

The project file

# Link shortener

Codes are generated in `shorten.py`. Storage is in-memory in `store.py`.

## Rules
- Never edit `store.py` without being asked.
- When you describe a function, name the file it is in.
- Run `python3 demo.py` after changing how codes are generated.

Facts and rules a new colleague would need. Nothing about Python in general, nothing the agent could work out by reading the code.

How the files combine

• Global first, from your Codex home directory.
• Then the project, from the root down to where you are.
• Closer wins. A file nearer your working directory overrides earlier guidance.
• There is a size limit. Codex stops adding files at project_doc_max_bytes, 32 KiB by default.

That last point is the practical argument for keeping these files short. So is the fact that every line is read at the start of every session.

What belongs in it