Project instructions and memory

Every session starts with an empty desk (Module 02). Project instructions are the notes your tool puts on that desk automatically, so the agent knows your commands, layout and rules without being told each time. Written well, they're the highest-leverage file in your repository.

1. The idea

There are three kinds of persistent context, and each has its place:

1. Project instructions, committed to the repository and shared with the team: build and test commands, folder layout, conventions, and the traps you've hit. The open standard is AGENTS.md, now stewarded by the Agentic AI Foundation under the Linux Foundation and read by all five tools in this track. Some tools also have their own file (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md).
2. Scoped rules that load only when relevant: a file in a subfolder (frontend/AGENTS.md), or a rule tied to file patterns ("apply to **/*.sql"). The nearest instructions win.
3. Memory: notes the agent writes for itself as it works ("this repo's tests need Docker running"). Useful, but review it, because it can be wrong or go stale.

The rule of thumb: if it's true for the team, it goes in the repository; if it's true only for you, it goes in your personal file or memory. Secrets go in neither.

2. How it works

Step through an agent working in a monorepo. Watch which instruction files are active, and which rule wins when two disagree.

3. Try it yourself: the AGENTS.md checker

Paste your AGENTS.md (or start from an example). The checker estimates what it costs every session and flags the most common problems.

4. Why it matters at work

What makes instructions actually get followed:

1. Commands exactly as typed. Agents copy them literally: BAZEL_TEST=1 pnpm test, not "run the tests".
2. Say why, briefly. "Never use pnpm test alone: it silently runs 7 of 135 tests" is followed far better than a bare rule (Module 05).
3. Record traps you've actually hit. The most valuable lines are past mistakes. If you had to correct the agent twice, it belongs here.
4. Keep it short. It's loaded into every session and costs tokens every time. A few hundred lines at most; move long procedures into skills (Module 11), which load only when needed.
5. No history and no essays. "We migrated from X in 2023 because…" dilutes the rules that matter.
6. Make it the team's file. Review changes to it like code; update it in the same pull request that changes the build or conventions.

A compact example:

# AGENTS.md

## Commands
- Build: `pnpm build`
- Test: `BAZEL_TEST=1 pnpm test`  (plain `pnpm test` runs only 7 of 135 tests)
- Before every commit: `pnpm format && pnpm check`

## Layout
- `api/` Kotlin service · `web/` Angular app · `proto/` API contracts · `docs/` design notes

## Rules
- Never edit an applied migration; add a new `V{N}__name.sql` (others have already run them).
- Every colour comes from a `--bf-*` token; raw hex breaks dark mode.

## Never
- Commit to main, force-push, read `secrets/`, or paste customer data into prompts.

5. In your five tools

All five read AGENTS.md; each adds its own options. Checked October 2026.

6. Remember it

7. Common mistakes

8. Hands-on lab (roadmap week 9)

1. Draft it. Run your tool's starter (/init in Claude Code or Codex) or write AGENTS.md by hand: commands, layout, rules with reasons, a "never" list.
2. Check it in the checker above. Cut it below 200 lines.
3. Prove it loads. Start a fresh session in two tools and ask "what are the test commands for this repo?" without pointing at the file.
4. Add a scoped rule for one folder or file type (a nested AGENTS.md, or a glob rule) and confirm it applies only there.
5. Review memory in a tool that has it, and delete one stale or wrong note.

9. Self-check quiz

10. Go deeper