One rules file for every agent

The problem

Claude Code reads CLAUDE.md. Codex reads AGENTS.md. A chat bot reads whatever you paste into it. If you copy the brain rules into each one, the copies drift. In a month, no two agents follow the same rules.

The fix

Keep the rules in one file, inside the brain. In the template it is prompts/AGENT-RULES.md. The first lines carry a version, such as Version: 2026-10-19.1. Every time you change the rules, you change the version.

Then each of your work repos gets a short section that says one thing: "Before you work, read the rules at this link." That section almost never changes. Only the rules file does.

When an agent finishes, it says which version it followed. Now you can tell if an agent used old rules.

Where each agent finds it

• Claude Code reads CLAUDE.md in the repo. Put the short section there.
• Codex and most other coding agents read AGENTS.md. Put the same section there. A neat trick: make AGENTS.md a link to CLAUDE.md, so there is only one file to keep.
• Cloud agents and chat bots cannot see files on your computer. Give them the GitHub link and read access to the brain repo.

At Ducktate we also use a small Claude Code start hook. It prints the brain index, the brain commit, and how old the local copy is, at the start of every session. That hook is not in the template yet. The short section works without it.

A link is not proof

An agent can have the link and still skip it. So you test it. Start a fresh session and ask it the fact you wrote down in module 1. A good answer names the page, quotes the fact, and gives the brain commit it read.

Set it up

1. Open prompts/AGENT-RULES.md in your brain. Fill in your brain repo link and your owner ID. Set the version line.
2. Commit it on a branch, open a pull request, and merge it.
3. Copy the GitHub link to that file on your main branch. This is the one link every agent gets.
4. In each work repo, add the short section from prompts/REPO-SECTION.md, with your link in it. Use the prompt below.
5. Give each cloud agent and bot read access to the brain repo.
6. Start a fresh session in one work repo. Ask it your test fact. Check that it names the page and the commit.

The prompt: add the brain section to a repo

Run this once in each work repo.

Add the company brain section to this repo.

The brain rules live at: <link to prompts/AGENT-RULES.md on your brain's main branch>

1. Read this repo's CLAUDE.md and AGENTS.md if they exist. Keep everything already in them.
2. Add this section to the end of CLAUDE.md. Create the file if it does not exist.

   ## Company brain
   Our company facts live in the private brain repo. Before you work, read the rules
   at <link> and follow them. Say which rules version you followed.
   Never edit the brain pages from this repo. Never put secrets or customer data in it.

3. If AGENTS.md does not exist, make it a link to CLAUDE.md. If it exists, add the same section to it.
4. Show me the change. Commit it on a new branch and open a pull request. Do not merge it.

The prompt: test that an agent can read the brain

Run this in a fresh session.

Read the company brain rules from the brain section in this repo's CLAUDE.md or AGENTS.md.
Then answer one question from the brain: <your test fact as a question>.

Tell me:
1. The rules version you read.
2. The brain commit you read from.
3. The page ID that holds the answer, and the exact line.
4. The page's last_verified date.

If you cannot open the brain, say so. Do not guess the answer.

You are done when

• Your rules live in one file with a version line.
• Every work repo has the short section.
• A fresh session answers your test fact and names the page and commit.

Next module

Module 4 shows how an agent reads the brain and leaves an update, the GitHub way.