The Note File: CLAUDE.md, AGENTS.md and GEMINI.md

An AI assistant forgets everything when a session ends. The note file fixes that. It is a plain text file (in Markdown format) with the facts and rules you want the assistant to know every time. The assistant reads it at the start of each session.

Each assistant uses its own file name:

~ means your home folder. Claude Code also reads a project's AGENTS.md when there is no CLAUDE.md, so one AGENTS.md can serve two assistants.

Let the assistant write the first version

Start your assistant in the project folder and type /init. All three assistants have this command. The assistant looks at your project and writes a starting note file. Read it and remove anything that is wrong.

Write down what you would explain again

Good things to put in the note file:

• The commands to build, test and start the project.
• Rules for style, for example "Use 2-space indentation".
• Where things are, for example "Pages live in src/pages/".
• Rules for safety, for example "Ask me before you add a new paid service".

Write rules that someone can check. Anthropic's examples: write "Run npm test before committing" instead of "Test your changes".

A small example:

# Notes for the assistant

## Commands
- Start the site: npm run dev
- Run the tests: npm test

## Rules
- Use plain English in all text on the site.
- Ask before you delete any file.

Add to it when the assistant repeats a mistake

When the assistant makes the same mistake twice, add a rule. When you type the same correction in two sessions, add it to the file. OpenAI and Anthropic both suggest this habit. You can also ask the assistant to add the rule for you.

Keep it short

The whole note file goes into every session, so a long file costs space and can make the assistant follow it less well. Anthropic suggests under 200 lines for each CLAUDE.md. Codex stops reading project note files after 32 KiB in total by default. Remove old rules and rules that contradict each other.

Move long step-by-step procedures out of the note file and into a skill, which loads only when needed. See Skills, agents and connectors explained.

Check that the assistant loaded it

Never put passwords, API keys or other secrets in a note file. Project note files are often shared with other people.