Skip to content
← All guides

One set of rules for your agents

Why a rule you wrote often reaches only one agent, how to share it, and which agents that works for.

4 min readUpdated

You write rules for your agents. Never delete this folder. Never open that file. Ask before you force push. You put them in a file and expect your agents to follow them.

It does not work that way. Each agent reads its own file. A rule written for one often never reaches another.

Why a rule reaches only some agents

Agents look for rules in different places. One reads CLAUDE.md. Another reads AGENTS.md. A rule in your own home folder's file applies only to the agent that reads that file, on that Mac.

So the rule you wrote last month may be known to one agent and unknown to the one you used today. You will not see that from inside either of them. Our field notes on rules that two agents do not both read show how to check by hand.

In one eight-submission Codex test, every submission contained the requested feature. Four needed a missing label added when the project's label rule was only in CLAUDE.md. All four passed when the rule was also in AGENTS.md. Read the experiment and its limits.

See which rules reach only one

Excellent reads your own instruction files. It looks at those in the folders your agents worked in, and at the top of projects in common folders such as ~/Sites, ~/code and ~/Developer.

Then it lists the rules that reach only one agent. They show in the menu, in their own list. With Pro, you also get a notification when you write a new rule that reaches only one.

Read that list first. It is the list of rules you thought were working.

Share them

Press Share… in the menu, on the Rules page, or in Settings under Rules.

  1. Excellent shows you exactly what it will write. Nothing is written yet.
  2. On your OK, it adds one marked block with the missing rules to the file the other agent reads.
  3. It backs up each file first.

By default it writes to your own home-folder files. In Settings, you can have it write to each repository's file instead, so the rules travel with the repository.

To undo it, use Take Shared Rules Out… in Settings. It takes the block back out.

Which agents this works for

Sharing works for the agents that support it. Today that is two: the agents that read the two files above. The other agents Excellent works with do not get your rules from it.

That does not leave them out of everything. With Pro, Excellent's live check runs in those agents too, and it protects the folders and files your rules close. The agents it supports says what each agent gets, one by one.

Remind an agent of a rule

Reminders need Pro. They run in the live check.

With Remind agents of my rules on, Excellent watches for an agent about to break a rule you wrote. It refuses that action once and quotes your rule, in your words, with the file it is in. If the agent tries the same thing again, the normal check decides. It reminds an agent of the same rule at most three times a session.

Reminders are off until you turn them on, and they need protection on. Turn them on in Settings, or on the Protection page under the written-rules row. A reminder becomes part of the agent's conversation, which goes to its provider like the rest of it.

Make a rule hold

A rule an agent reads is a request. An agent can still break it. Two things make it firmer.

Never-delete and never-open. When your rules say a folder must never be deleted, or a file never opened, Excellent's check protects it. A few are protected from the start: ~/.ssh, ~/.aws, ~/.gnupg and your keychains, with everything in them.

The sandbox. The live check reads what a command says. The sandbox does not care how a command is worded: macOS itself refuses. With Pro, Excellent can turn your never-delete and never-open rules into the sandbox, for the agents that support it. Before anything changes, it shows what will be written and what may stop working. It backs up both settings files, and Turn Off… takes it back out.

A short routine

  1. Write each rule once, in plain words, in the file one agent reads.
  2. Open the menu and read the list of rules that reach only one agent.
  3. Press Share… and read what Excellent will write.
  4. Put the rules your team keeps in each repository's files and commit them.
  5. With Pro, turn on reminders, and turn your never-delete rules into the sandbox.

Your rules, shared has every setting.

Related guides

View all