A shared notes file your team's coding agents all read

Your instruction file (AGENTS.md or CLAUDE.md) holds the rules that stay true for weeks. It is the wrong place for what changed this morning: who is on the billing bug, that the API now returns accountId, that nobody should upgrade the test runner yet. That belongs in a second, short file that every agent reads before it starts and adds to when something changes. Below is a template, the rules that keep it useful, and the line that points each agent at it.

Why not put it all in AGENTS.md?#

Because the two files change at different speeds. An instruction file is read at the start of every session, so every line in it costs context in every session, and it should only hold what is true for everyone, every day. Notes change hourly. Mix the two and the instruction file grows a log at the bottom that nobody prunes, and the rules people need get lost under it.

Keep them apart:

The template#

# Team notes
Read this before you start. Keep it under 60 lines.

## Who is on what
- billing-retry: Sam, branch fix/billing-retry
- export-csv: Priya, branch feat/csv-export

## Decisions (newest last, one line each)
- 2026-11-05 API returns accountId, not userId. Clients updated. (Alex)
- 2026-11-06 Don't upgrade the test runner until the flaky suite is fixed. (Sam)

## Open questions
- Should refunded orders appear in the export? Default: yes, with a column. (Priya)

## Don't touch right now
- src/payments/: mid-migration, ask Alex

Four sections, each answering one question an agent would otherwise get wrong. Every line carries a name, so an agent knows who to ask, and every decision carries a date, so stale lines are easy to spot.

How do I make every agent read it?#

Add one rule to the shared instruction file:

## Team notes
- Before starting a task, read NOTES.md.
- Add your task and branch under "Who is on what" before you edit code.
  If someone else already has it, pick something else.
- When you decide something other code depends on, add one dated line
  under "Decisions" with your name.
- Remove your line under "Who is on what" when your branch merges.

Codex reads AGENTS.md itself, and Cursor and OpenCode read it too. Claude Code reads CLAUDE.md, so give it a one-line CLAUDE.md that imports the shared file:

@AGENTS.md

One rule, every agent. How to connect Codex and Claude Code has more on the import.

What keeps it short?#

Most shared notes files die the same way: they grow until nobody reads them, the agents included. Four rules prevent that:

1. A line limit at the top. Sixty lines is plenty. When the file passes it, the oldest decisions move into the instruction file (if they became rules) or get deleted (if they are done).
2. One line per entry. If a decision needs a paragraph, link the pull request that explains it.
3. Owners remove their own lines. A task whose branch merged is not "on" anyone any more.
4. No session summaries. "Today I refactored the export and fixed three bugs" helps nobody. What the next person or agent needs is the decision you made along the way.

To check who added what, and when, ask git:

git log --oneline -5 -- NOTES.md
git blame NOTES.md

Who keeps it tidy?#

Give one person the job for the week, and make it a five-minute task at the end of the day: delete lines for merged branches, move decisions that became rules into the instruction file, and answer or delete open questions older than two days. An agent can do most of it. Ask it to list stale lines with the reason each one looks stale, then approve the deletions yourself, because an agent that deletes a decision it didn't understand loses the one thing the file was for.

Where it stops working#

The file works well when everyone pulls often. Its weak spot is the gap between a teammate writing a line and your agent reading it: the line sits on their branch, or on main while you are on yours, until somebody merges. Two agents can also claim the same task within a minute of each other, both believing the file said nobody had it.

That gap is what Joxo closes. The team's agents share one task board and one list of decisions, so a claim or a decision reaches every agent on its next turn instead of after a merge, whichever agent each person uses. If your team sits at one desk and merges every hour, the file alone is enough. Our comparison page sets out when a team chat, notes in the repository or a shared board fits best.

Frequently asked questions#

What should go in a shared notes file for coding agents?#

Who is working on what and on which branch, the decisions made today that other code depends on, open questions with a default answer, and anything nobody should touch right now. Rules that stay true for weeks belong in the instruction file instead.

Should the notes file be committed to git?#

Yes. Committing it is what lets every agent and every teammate see the same version, and git shows who added each line and when. Keep it short, so it stays cheap to merge.

How long should a shared notes file be?#

Short enough to read in a minute: about sixty lines at most. When it grows past that, move decisions that became rules into the instruction file and delete the ones that are done.

Do Claude Code, Codex and Cursor all read AGENTS.md?#

Codex, Cursor and OpenCode read AGENTS.md. Claude Code reads CLAUDE.md, so give it a CLAUDE.md that imports AGENTS.md with one line, and every agent follows the same rule to read the notes file.