1. A handbook beats repeating yourself
Every new session starts without the last chat. If the only copy of “we use npm test, and do not hand-edit the generated pages” lives in yesterday’s scrollback, you will type it again. Or you will forget, and Grok will invent a reasonable, wrong command.
Put that handbook in AGENTS.md at the root of the repository. Grok reads project rules when a session starts. The first time you open a folder, it asks you to confirm that you trust it. Rules and project skills load after that trust. Do not trust a repository you have not looked at. Trust means you are willing for its instructions to be part of the session.
2. Four kinds of lines, and no secrets
Write the things a new teammate would ask in the first hour:
- How to build and how to run the tests. The exact command.
- Conventions you actually enforce. “Match the function next to you” is enough when it is true.
- Gotchas. Generated files. A test that needs a local service. A directory that is frozen.
- What not to do. The last mistake that cost you an afternoon.
Do not put passwords, keys, or customer data in the file. It is a document in the repo, and it is loaded into the conversation. If a command needs a secret, say where the secret comes from. Do not paste the secret.
A handbook that fits on one screen is easier to keep true. This one is for a made-up invoice app, so you can see the length. Yours should be about this long, with your real commands in place of these:
Tests: run "make test" from the repository root.
Build: run "make app". Do not invent a second build command.
Gotchas
Files in generated/ are produced by the build. Edit the source, then rebuild.
Do not put passwords or customer rows in this file.
Conventions
Match the neighboring function.
A new dependency needs one sentence on why it is there.
3. One handbook, not two that argue
Grok also recognizes a few other names, including CLAUDE.md, so a repository that already has a Claude Code handbook is not invisible. If both AGENTS.md and CLAUDE.md are present, both are loaded. Two files that disagree will both be in the prompt. Pick one place to edit, and make the other point at it or delete the duplicate advice.
Personal preferences that are about you, not about this repository, can live in rules under your Grok home directory. Project facts stay in the repository, so the next person gets them too.
4. A folder can add a rule. The closer rule wins.
A directory can have its own AGENTS.md. Grok loads from the repository root down to the folder you started in. When two lines conflict, the file closer to your current directory is the one that wins, because it is read later.
Use that for a real local difference. “Files under docs/ are prose, not code, so do not run the formatter on them.” Do not use it to hide a contradiction you did not want to resolve at the root. A stranger, and Grok, will follow the closer file.
5. Short rules get followed. A novel does not.
The handbook spends the same budget as the rest of the conversation. A 30-page style guide shoved into the prompt crowds out the task. Keep the file to the commands, the conventions, and the gotchas that have already burned you. When a new burn happens, add one line.
The next page is for a procedure that is too specific for this handbook and too long to retype: a skill for work you repeat.