AI Prime Directive: A Logical Fix for Multi-Model Fragmentation
Switching AI models shouldn’t mean rewriting your rules.
Spock had a particular way of registering disapproval. He didn’t shout. He’d raise an eyebrow, call a situation “illogical,” and let the silence do the work. If he were to observe how developers currently configure their AI coding agents, that eyebrow would be firmly lodged near his hairline.
We have entered an era of remarkable tooling. We give local agents direct access to our file systems We have entered an era of remarkable tooling. We give local agents direct access to our file systems through command-line tools such as Claude Code and OpenAI Codex. We use IDE agents like Cursor and Windsurf. We deploy autonomous engines that run unattended on virtual private servers and learn across sessions. The raw capability is real. The way we instruct them is a fragmented mess.
Having an AI on your machine is the easy part. Keeping every one of those models aligned on the same set of rules as you switch between them is where the chaos lives. There is a logical way to impose order: adopt an industry standard and a disciplined workflow.
The Tower of Babel problem
Until recently, the ecosystem was siloed. Every tool demanded its own proprietary instruction file. Claude Code looked for CLAUDE.md. Gemini’s CLI looked for GEMINI.md. Cursor relied on .cursorrules. Autonomous agents leaned on their own profile-specific files. None of them spoke to each other.
This fragmentation creates two practical bottlenecks.
Model blindness. Imagine building a project with Claude Code. You hit a persistent hallucination, so you swap to a Gemini-based agent to push past it. Except it isn’t seamless. The new agent arrives blind to the architectural constraints you spent hours writing into CLAUDE.md. It sees the raw code but lacks the reasoning. You start from zero.
The maintenance tax. Whenever you change your tech stack, tighten a styling rule, or add a core dependency, you manually edit four or five near-identical configuration files. It is dull, repetitive work that breaks quietly the moment you miss one file.
Two lessons from before the AI era
This friction isn’t new. It’s a solved problem in other industries.
On a physical manufacturing line, you don’t design a bespoke screw for every product. You standardise on common components. Standardisation keeps costs low and quality predictable. The moment you allow custom fasteners for every product, your stockroom descends into chaos. Centralisation isn’t about bureaucratic tidiness; it’s a mechanism to stop variance destroying your efficiency.
Traditional web development learned the same lesson. In the early days, styling was applied page by page. Changing the heading font across a 50-page site meant 50 manual edits. Then global Cascading Style Sheets arrived. You defined a rule on a single central sheet and it propagated everywhere. Today’s design systems run entirely on unified, global tokens.
AI development needs its “global CSS” moment. One rule, defined once, applied everywhere.
The solution: a standardised Prime Directive
The principle is straightforward. Your repository has exactly one single source of truth, and every agent points to it.
For a while, achieving this needed messy workarounds. That changed with the widespread adoption of AGENTS.md. It emerged in 2025 from a collaboration between Sourcegraph, OpenAI, Google, Cursor and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. It is an open, cross-tool standard, adopted across tens of thousands of projects.
Today AGENTS.md is read natively by Cursor, Windsurf, Cline, Codex, Google Jules, GitHub Copilot, Antigravity and others. Think of it as a README built for machines: a unified hub for build commands, test suites, styling conventions and architectural boundaries.
Adopt AGENTS.md as your Prime Directive and dozens of agents read your instructions natively, with no extra configuration. But what about the holdouts?
For tools that still look for their own proprietary files, the notable one being Claude Code, you add a thin pointer file. The old approach was a prose road sign: a CLAUDE.md that said “all rules live in AGENTS.md, read it now.” That works, but it relies on the agent choosing to obey a written instruction, which is only ever probabilistic. There is a better mechanism.
Claude Code and Gemini both support an import syntax that pulls another file’s contents into context mechanically, no obedience required. So the stronger pointer is a single line:
@AGENTS.mdThat one line turns a siloed tool into a compliant citizen of your system, and it does so deterministically rather than hopefully.
A note on symlinks and Windows
You may see the symlink method recommended elsewhere: ln -s AGENTS.md CLAUDE.md. It works well on macOS and Linux. It is unreliable on Windows, where symlinks need developer mode or elevated permissions and can arrive as plain text files after a git clone. The import approach sidesteps all of that. It’s an ordinary text file that behaves identically on every operating system. If you work across machines, prefer imports.
The discipline is simple
- Write your core rules once in AGENTS.md.
- Add a thin import pointer only for tools that can’t read it natively.
- Never duplicate your actual context.
Keep AGENTS.md lean while you’re at it. Aim for under 150 lines. Models follow short, specific files far better than long ones, and anything a linter already enforces doesn’t belong in there at all.
The shift handover: curing the cold start
Rules tell an agent how to code. They don’t tell it why the project is in its current state.
When a new model enters a codebase, it sees the physical structure but lacks the historical narrative. It doesn’t know you abandoned a library last Tuesday because of a fatal memory leak, or that a strange workaround exists to bypass a known API bug.
The original fix was a single build log. It works, but a chronological diary that records every file creation grows into noise nobody reads, and if it’s loaded into context on every session it quietly eats your instruction budget. A better structure borrows from how hospitals run shift changes. An incoming nurse doesn’t get the patient’s entire history recited at them. They get a short handover: current state, what’s in flight, what to watch. The full notes exist if they need to dig.
That splits into two files.
PROJECT_HANDOVER.md is the whiteboard at the nurses’ station. A fixed-size, overwritten document: current state in under 20 lines, what’s in flight, which decisions are settled, and who was last on shift (the tool, the model, the date). Read once at the start of a session, updated once at the end. It’s capped, so it never grows into the thing it’s meant to prevent.
BUILD_LOG.md is the patient’s notes. An append-only record of design decisions, pivots and milestones, newest first, always giving the reasoning. Not loaded into context routinely; consulted on demand when someone needs to know why the project looks the way it does. When it reaches 100 entries, the oldest half is moved to an archive.
Your AGENTS.md carries a short standing instruction telling any newly initialised agent to read the handover before it writes a line of code, and to log decisions as it goes. There’s a natural promotion path built in: a decision starts as a log entry, and if it turns out to be permanently binding, it graduates into AGENTS.md as an architectural constraint. The log records why; AGENTS.md records what still binds.
This pays off most with autonomous engines built to run unattended and learn across sessions. A fresh profile pointed at a good handover doesn’t start blind. It catches up on the state that matters and gets to work, largely removing the cold-start problem.
A logical future
Standardising our AI instructions isn’t about saving a few keystrokes. It’s about refusing to let avoidable fragmentation compound as the ecosystem expands. We’ve seen this play out in manufacturing stockrooms and early web design. We know how it ends when a system fails to centralise.
The components are already on the shelf: AGENTS.md as your single source of truth, thin import pointers for the holdouts, a capped handover document for shift changes, and a build log as the project’s long-term memory.
Adopt this architecture, and switching between models becomes a tactical advantage rather than an exhausting reset. Spock would approve. Not effusively, of course, but that raised eyebrow would finally come back down.
Created by Michael Hele, AI Visibility Strategist Consultant