One project's lesson becomes every project's rule
I run about 20 agents on very different projects. A lesson from one becomes a dated rule in one shared file, installed everywhere and checked by hash.
In 30 seconds
- Many different agent projects hit the same failures sooner than one project alone, so lessons come fast.
- A lesson that binds every agent becomes a rule in one shared rules file, with its date and a one-line why.
- The file is installed on every agent machine, checked by hash, and announced to each running agent.
- A rule that misfires is fixed the same way, often the same day.
Problem
I run about 20 agents across a fleet of 10 machines: Macs, Linux boxes and a Windows box. Their projects have little in common: a road-conditions site, a dictation app, an iOS app, 3D printing, a home board for my kids, my own writing, and a client project in a VM. The stacks differ too: Swift, TypeScript, Python.
That spread is why we iterate fast: with many different projects at once, I quickly see what works and what doesn’t. The more projects I run, the more I learn. The catch: a lesson learned in one project’s chat stays there unless something carries it to the rest.
What I tried
| Attempt | What happened |
|---|---|
| Each project kept its own review process | Only one had an enforced gate for every step. On 2026-10-10 I asked what our pipeline was on the other projects. |
| A lesson kept in an agent’s private memory | Memory is per machine and per project, and other sessions can’t see it. A lesson that must bind now goes in a versioned rules file. |
| Agents first reply with what they understood (2026-10-16) | They parroted my asks back. |
| Short updates whenever something changed | More than I wanted; on 2026-10-20 they went. |
| No message once the work is done, either | Overshot: I still wanted to know when my ask was finished. |
| Agents never message each other (2026-10-12) | Too strict for the agent that gathers material for this blog. On 2026-10-26 it got one exception, publishable material only. |
What worked
One rules file for the fleet. A rule that binds every agent lives in one shared file in a versioned repo; a rule for one project stays in that project’s own instructions. Each rule carries its date and a one-line why, often my words in quotes. The story goes in the project’s log, tagged as a lesson, or in the commit message if you keep no log. No third list: a separate lessons file drifts from both.
Installed everywhere, checked by hash. An installer copies the file to every agent machine as each agent’s global instructions: Claude Code’s user-level CLAUDE.md, or your tool’s equivalent. A line at the top says the file is managed and names its source, and the installer only replaces copies that carry it, never a hand-written one. After each install I check the file’s sha256 on every machine, and a versions report shows each agent’s rules hash and flags drift.
Announced to running agents. An agent reads its instructions when its session starts, so a running one misses a change. A relay message tells each live agent, and each acknowledges. When the first reply rule went out, all nine live agents answered.
The first lesson to travel was the pipeline. On 2026-10-10 I asked what our pipeline was on the other projects. That night the fleet adopted the flow three of them already ran: a written brief, a second model attacking the brief, implementation in its own worktree, a smoke test at the exact commit, independent model reviewers, then merge. Three projects’ habit became every project’s rule, and every later rule goes through it.
Small enough to be fast. A rule is a paragraph that goes through the same pipeline as code. On 2026-10-26 at 22:04 I asked from my phone for my writing agent to be able to ask any agent for material. By 22:58 the rule was written, reviewed by three models, smoke-tested and merged; the next morning, on my go, it was installed everywhere with matching hashes.
Misfires get fixed the same way. My first reply rule had agents open every reply with what they understood and would do. They parroted my asks back. On 2026-10-18 it became “answer first”: if the answer takes under a minute, just answer. On 2026-10-20 I said I didn’t need progress updates, and the new rule went too far: it dropped the done message too. Minutes after it was installed, I said I still wanted to know when my asks were finished. Twenty minutes later a reviewed fix was installed: one “done at” line, in the channel the ask came in. Each step was a dated edit to the same file, so every agent moved together.
Numbers
| Agents in my inventory (2026-10-27) | 21, 5 set up but not running yetmeasured |
|---|---|
| Machines in my fleet | 10measured |
| Fleet-wide rules | 12configured |
| Design notes that went through a second review | 167 of 227measured |
| Tasks in the tracker, and archived as done | 221 and 123measured |
| Phone ask to a reviewed, merged fleet rule (2026-10-26) | 54 minmeasured |
I have no time-saved figure. The counts show how much runs through the one pipeline and the one rules file.
When it stops being true
A running agent works under the old rule until the notice reaches it. A hand-written instructions file is skipped by the installer, so that machine drifts until the versions report flags it. Every shared rule lands in every agent’s context, so a rule only one project needs belongs in that project. The client project in a VM is carved out: its data never leaves the VM, and the rule that lets agents share material excludes it.
Agent brief
You are helping me turn lessons from one agent project into rules all my projects follow.
First ask me:
- Which projects and machines my agents use, and how each loads its instructions.
- Where each project keeps its own rules, its log and its tracker.
- How I message a running agent.
- Which projects hold client or private data.
Constraints:
- One shared rules file in a versioned repo; one-project rules stay in that project's file.
- Every rule carries its date and a one-line why; the story goes in the project's log, or the commit message if there's no log.
- Rules change only through my review path, never by hand.
- Nothing from a client project's data goes into a shared rule.
Steps:
- Collect each project's lessons; ask me whether each binds every project or one.
- Write the shared file with a top line saying it's managed and naming its source; the installer replaces only files that carry it.
- Install it as each agent's global instructions (Claude Code's user-level CLAUDE.md, or your tool's equivalent); record its sha256 on each machine.
- Tell each running agent; have it acknowledge, and list who didn't.
- Add a report that shows each agent's rules hash and flags drift.
- A misfiring rule changes the same way: dated, reviewed, installed, hash-checked, announced.
- Small setup (one machine, a few agents): restart sessions instead of announcing, skip the hash report, review with one PR and one reviewer.
Pitfalls:
- Lessons in private memory or a separate list drift: one binding place each.
- Running agents keep the old rule: wait for every acknowledgement.
- A fix can overshoot (no progress updates also dropped the done line): ask me afterwards if it feels right.
- A one-project rule is noise elsewhere: keep it there.
- A hand-written instructions file is skipped: the drift report must show it.
Done when:
- Every machine reports the same rules hash.
- Every live agent has acknowledged the current version.
- Each rule has a date, a why and a matching lesson entry.
- A fresh agent can explain this week's changes from the file and logs alone.