Several AI coding agents from different vendors assist me as I build my projects, often side by side in one workspace. Each one is capable on its own. Getting them to work the same way was the hard part.
My first fix was the obvious one: write my rules down once and give every agent a copy. It did not hold. The copies drifted as I edited one and forgot another. When I moved a task from one agent to another, the new one started cold. It did not know what was done, what was decided or what I had already said no to. And an agent that fills gaps with guesses can invent a file path, assume a cloud region or push a commit nobody approved.
A shared instruction file turned out to be the easy part. My agents started behaving like one team only when I ran their rulebook like software: versioned releases, proof that every agent loaded the current version, a handoff file that carries work between them and approval rules sized to what cannot be undone.
What I Wanted
- One source of truth for every agent in every project.
- A way for any agent to continue another agent's work without me repeating myself.
- Clear limits on what an agent may do without asking.
- Proof that each agent actually loaded the rules, not just the hope that it did.
One Source of Truth, Versioned Like Software
I moved all my instructions into a private Git repository and treated it like a code library, with a version number, a changelog and release tags. A change to required behavior is a major release, a new standard is a minor release and a wording fix is a patch.
Every session starts with a version check. The agent pulls the repository, confirms that its copy matches the newest release and names the loaded version in its first reply. If the repository is unreachable, it says so instead of pretending.
A release also reaches my projects, not just my agents. When an agent opens a project after a new release, it first compares the project with the new rules, lists the gaps, fixes them and records the version the project now meets. Only then does it start the task I asked for.
Rules and Standards: What the Rulebook Says
The rulebook has two layers. The split matters as much as the content.
The rules are the small core that every agent loads in every session. They cover how an agent behaves on every turn and on every change:
- Ask, do not assume: Before it acts, an agent confirms what I want, where the work happens and how the result will be checked. When it is unsure, it asks one clear question and waits. Silence is not approval.
- Protect secrets and personal data: Credentials never appear in chat, code, logs or commits. A privacy scan checks every project file on every commit.
- Claim only what the evidence shows: Results are reported as completed, pending, failed or blocked, with a note on what was and was not tested.
- Report errors plainly: Every error comes with its location, cause and fix. After three failed fixes for the same problem, the agent stops and asks instead of trying a fourth.
- Change code with care: End-to-end tests come first and leave a saved report. Code must be safe to rerun and give the same result from a clean checkout. Commits follow one message convention. Local checks pass before every commit.
- Never lose documentation: When an agent edits a document, no valid information may disappear.
The standards hold the detail. Each one loads only when the task calls for it, such as writing infrastructure code, making a Git commit, handling personal data, building a data pipeline or starting a local server. The core keeps a map that pairs each situation with the standards to load, so an agent does not have to guess which ones apply.
Each project also gets a project standard with its verified facts, such as where the repository lives and what the project is for, plus any requirement deferred until a later stage. A deferred requirement is reported as pending, never as done.
Three more ideas keep the layers honest:
- Precedence: The host's own safety rules come first, then mine. A project standard can tighten a rule but never quietly weaken it. Only I can change a rule.
- Proposed is not binding: A new section stays marked as proposed until I confirm it. Until then, agents may not cite it as a decision.
- Every rule declares its enforcement: A reference table records whether each rule is enforced by a pre-commit check, by continuous integration or by an agent's judgment. A check fails if a rule has no entry, so no rule can be added without saying how it is enforced.
The split started as a workaround. One agent could read only a short instruction file, so the core had to stay small. It turned into the better design. An automated size budget now keeps the core from quietly growing.
Generated Loaders Instead of Copies
Copies drift, so the rulebook keeps none. A small installer writes each agent's global instruction file from one list of files, in whatever form that agent understands. It rewrites a file only when the content changed. The version check runs it after every update. The loaders cannot fall behind the rules.
An early test showed why the loaders must put the rules straight into the agent's context. My first loader asked the agent to open the rules file itself. In testing, the agent skipped that step. Now nothing depends on an agent choosing to read its rules.
Proving Every Agent Loaded the Rules
Instructions you cannot test are only hopes. The rulebook has two end-to-end tests that run the real agents.
The load test starts each agent without tools and asks it to quote specific lines from the core files. An agent that did not load the rules cannot quote them. The questions target lines that exist only in the newest release, so an out-of-date loader fails.
The handoff test makes the agents take turns in a scratch repository. It checks that each one records the latest exchange, that the task's goal never changes, that a stale handoff is detected and that no handoff file ever appears in Git. It also resumes an old conversation after other agents have written, to confirm that it catches up. Finally, it asks an agent without the right tool for a task that needs one, to confirm that the agent proposes a handoff instead of trying.
The tests found real bugs. One agent's command-line tool waited silently for more input and hung until the test timed out; closing its input fixed it. Another agent's sandbox ran an older Python version than my machine, so the scripts are now tested on that older version too.
A Handoff File That Carries the Work
Agents cannot share memory, but they can share a file. Each project has one rolling handoff file with fixed sections: the latest request and answer, a task card, status, completed work, decisions, checks, blockers and next steps.
The task card is the part I value most. It states the goal, the constraints, what "done" means and when to stop and ask. It is written when a task starts and changes only with my approval, so the next agent continues the same task instead of quietly swapping in an easier one.
Here is a short, made-up example of a handoff's core:
- Last exchange: I asked for a dark-mode toggle. The agent added it and the checks pass.
- Goal: readers can switch to dark mode on every page.
- Constraints: no change to the approved colors and no new dependencies.
- Done when: the end-to-end run passes at three screen widths and its report is saved.
- Escalate when: a change would touch the approved color palette.
- Decision: the toggle remembers the reader's choice on their device (approved).
- Status: ready for review.
- Next steps: I review the screenshots, then approve or reject the deploy.
The habits around the file matter as much as the file itself:
- At the start of every turn, the agent checks whether the handoff or the rulebook changed. If either did, its own memory is stale, so it catches up from the file before continuing.
- After every reply, it records the latest exchange, so any conversation in any app can pick up from the last answer.
- Handoff files never enter Git. The installer keeps them out of every repository.
- Only one agent writes in a working tree at a time. Parallel work happens in separate Git worktrees.
The Git repository stays the hard checkpoint. The handoff file only carries context between checkpoints. When the two disagree, the repository wins.
Limits Sized to What Can't Be Undone
Not every action deserves the same caution, so actions are tiered by how hard they are to undo. Reading files and running local checks happen on their own. Deploying, deleting, publishing and rewriting history wait for my approval of the exact action shown. An agent can never approve its own request. It also prefers the recoverable option when one exists.
Agents also know what they cannot do. A capability map records which app has which tool. When a step needs a tool the current app lacks, the agent writes a handoff that names the right app and the next step, then stops instead of trying and failing. If that app fails too, the task comes back to me rather than bouncing between agents.
Preferences and Failures Become Releases
My preferences change often, but I do not want agents editing the rulebook in the middle of a task. When I state a new preference in any project, the agent drafts the exact change and asks whether to record it. If I agree, it opens an issue in the rulebook repository. Later I review the open issues and release them together as one version, which every agent picks up on its next turn.
Failures get the same treatment. When a mistake repeats, the answer is to fix the cause, not to retry with a stronger prompt. I classify the cause as missing context, a fragile tool, a missing guardrail or weak verification. The fix lands where it will stop the next run from failing.
What I Would Tell Someone Starting Out
Running the rulebook like software changed how my agents work together. Any agent can pick up another agent's task from the handoff file. Deploys, history rewrites and publishing wait for me. When I change a rule, every agent and every project moves to the new version.
If you use more than one AI coding agent, you do not need all of this on day one. I would build it in this order:
- Write the rules down once. Keep them in one repository with a version number and a changelog.
- Split rules from standards. Keep a small core that always loads and move the detail into standards that load when a task needs them.
- Load the rules for the agent. Generate each agent's instruction file instead of asking the agent to fetch its rules.
- Prove the rules loaded. Ask each agent to quote a line that exists only in the newest version.
- Share a handoff file. Give it a task card that only you can change.
- Set limits by consequence. Let agents move fast on what they can undo and wait for you on what they cannot.
Each step works on its own. Each one also made the next one easier.