Three tools, three context files, one team decision

We already ran the good version of the fix.

One source file, a script that generated the copies, and a CI job that failed if a copy drifted from the source. It held for Claude Code. We were happy with it, and I think we were right to be.

Then on 2026-09-11 we measured it. Codex reads its instructions from whichever home directory it is pointed at, and we run it from several. Four of those homes had no instructions file at all. The shared skills folder Codex reads had drifted 24 skills behind the one Claude Code reads. Nothing crashed. The generator simply had no idea those places existed.

Our fix was a second sync script.

The source file was fine. The copies were not.

A generator with a CI guard is the right answer to the one-harness problem. Its edge sits wherever a harness reads from a place the generator was never pointed at, and that edge has nothing to do with how good the file is.

Where a shared context file stops being enough

The most cited fix in the practitioner threads we read is a shared context file, one AGENTS.md or CLAUDE.md that every session loads.

The most careful version we found belongs to u/Minute_Visual_3423 on r/dataengineering (2026-05-08), whose team keeps a shared ai-docs repo with a root file. His win, as he describes it, is that the need-to-know context is already in the window when a new session starts. That is a real win. The file costs nothing, loads without a tool call, and holds exactly what you put in it.

If that is your setup and it works, keep it. It starts to strain at two moments, a second tool and a second repo.

One file loads at a time: the limit you hit first

Each harness looks for its instructions under its own name and in its own place. With one harness that never comes up. With three, you have three files, and every changed decision means three edits.

The cross-repo version is blunter. "If I put a CLAUDE.md in each repo, I can only load one at a time," u/Minute_Visual_3423 wrote in the same thread. His team's shared docs repo is a sound answer to that limit.

It still leaves the context inside every other repo where it was. u/dylannalex01 named that gap in the same thread: "We have incredibly valuable context trapped in siloed repos, meaning an agent (or dev) working on Project A has zero context about a critical system decision made in Project B."

A file per repo is a good design for one repo. At two it is upkeep, and at five it is a consistency problem.

Cross-tool and cross-repo consistency as one problem

Keeping Claude Code, Cursor and Codex consistent is one consistency problem, not three copy-paste jobs.

The decisions in those files are the same decisions. How to handle the billing schema, which test harness to use, what counts as a migration. None of that changes because the harness changed. When those decisions live in three hand-kept files, one change is three writes, and none of those writes has a reviewer on it.

This is where drift starts, at the ordinary pace of a team that decides things faster than it can copy them everywhere.

u/mm_cm_m_km described the failure on r/AI_Agents (2026-05-09): "you ship with a CLAUDE.md and some hooks saying one thing, six months in someone adds a hook that contradicts, the agent silently picks the wrong branch. by the time you notice failure rates climbing, nobody can repro the original behaviour because the rules layer doesnt match what you think it says."

Another practitioner on the same subreddit, u/dan-does-ai (2026-04-29), made a related point. Shared-state failures like this rarely crash. They show up as slow drift that is hard to pin on any one cause.

With copies, the contradiction lands in one file and the other two keep the old rule. Then the team re-litigates a decision it already closed.

You can check your own exposure in an afternoon. Put the context files from every tool and repo side by side and compare the decisions they encode. Count the rules that live in one place and nowhere else. That count is your upkeep.

What the installed fix covers and where it ends

The five-second argument is true. As jedbrooke put it in one thread, it takes about five seconds to add a CLAUDE.md with a quick style guide. It is fast, it is free, and it works, which is exactly why it is the most cited fix in the threads.

The cost was never writing the file. It is five seconds per file, per tool, per repo, and then keeping every copy saying the same thing after a second engineer edits one.

A generator plus a CI guard is the incumbent at its best, and it is what we built. One source, one generator, one drift check. If you run one harness against one set of targets, I think it is the right thing to build.

It covers the targets you told it about. A harness that reads from somewhere else drifts, as ours did. A new tool next quarter means a new target to wire in, and the person who maintains the sync pays for each one. The upkeep grows with the number of targets.

What a company-scope context substrate adds

A company-scope context substrate serves one set of decisions to every tool over MCP, instead of a copy of the rules pasted into each one.

The decisions live in one place, and people and agents read and write the same store. When a decision changes, one write reaches every harness and every repo that reads from it. Nothing waits to sync, because every tool reads the same record.

That is the shape we built Synthweave around. It is a company-wide context substrate of snips, bases and projects with hybrid search, read and written by people and agents alike. Agents reach it over a live MCP surface of 70+ tools and an agent registry of 100+ tools. Any harness that reads context over MCP reads the same store as every other harness.

A fourth tool then means one more MCP connection to configure, and no fourth file to keep current.

Some writes can also be held for a person to accept before they land. That gate covers snip_rewrite and snip_patch only, creation and metadata are ungated, and it depends on autoAccept being off.

What this does not replace

A solo repo with one tool and one author is well served by its context file. Keep it. It loads with no dependency and needs no infrastructure.

An always-loaded file also keeps its job as the session's starting point. With a shared store, a short local file can still point the agent at what matters for this repo. The file says where to start, and the store holds the decisions every tool and repo needs.

MCP is a real dependency with a real attack surface, and adding it is a cost.

The platform is org-scoped, with per-org row-level security at the data plane. It is not isolated per org on compute, and that one is currently unanswerable. There is no self-hosting.

So count how many places your team's last decision now lives. Then ask what happens when the second harness arrives, or the second repo, or the second person writing context the whole team has to trust.

Our four empty homes were the second harness arriving faster than the fix could follow.

<script type="application/ld+json"> { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "Three tools, three context files, one team decision" } </script>