# 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.

Topic: Agents & review
Tested: 2026-10-27
Revision: 1
By Roman Vaisman
Page: https://eng.vaisman.me/entries/fleet-effect/

## 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

I have no time-saved figure. The counts show how much runs through the one pipeline and the one rules file.

| Label | Value | Kind |
| --- | --- | --- |
| Agents in my inventory (2026-10-27) | 21, 5 set up but not running yet | measured |
| Machines in my fleet | 10 | measured |
| Fleet-wide rules | 12 | configured |
| Design notes that went through a second review | 167 of 227 | measured |
| Tasks in the tracker, and archived as done | 221 and 123 | measured |
| Phone ask to a reviewed, merged fleet rule (2026-10-26) | 54 min | measured |

## 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

```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.
```

## Related

- [Back up your agent's memory, not just its code](https://eng.vaisman.me/entries/back-up-agent-memory.md)
- [A tmux wall to watch every agent](https://eng.vaisman.me/entries/tmux-wall.md)