4 min read
The first CLAUDE.md feels helpful. The third agent file becomes a risk.
Agent instruction drift happens whenCLAUDE.md,GEMINI.md,AGENTS.md, Cursor rules, and Copilot instructions each describe the same repository differently. The team thinks it is supporting multiple tools. In practice, it is creating multiple versions of engineering memory. paqad-ai solves this by generating provider files from one shared project layer.
The file request is reasonable
Nobody starts by asking for instruction drift. The first request is usually practical.
A developer using Claude Code wants CLAUDE.md because the tool reads it. Someone testing Gemini CLI asks for GEMINI.md. Codex users need AGENTS.md. Cursor users want a rule file. Each request sounds small, and each person is trying to make the tool behave better.
The problem starts after the third file. One file says to run Pest. Another still says PHPUnit. One mentions the new module boundary. Another points to a folder that moved last month. The AI output now depends on which doorway the developer used.
That is not a tool problem. It is a memory problem.
You can spot it in review comments. Someone says the agent followed the instructions. Another person asks which instructions. A third person opens the repo and finds four files that all sound official. None of them is obviously wrong, which makes the issue harder to challenge. The company has a coordination problem disguised as helpful setup.
Drift hides in normal maintenance
Instruction files drift because the work looks too small to coordinate. A developer updates CLAUDE.md after fixing a test command. The Gemini file is left alone. A reviewer updates Cursor rules after a frontend incident. AGENTS.md still carries the old guidance.
| Situation | What the team thinks | What actually happens |
|---|---|---|
| One file updated | The repo rules improved | One provider is now different |
| New tool added | Adoption got easier | Another copy must be maintained |
| Command changed | The fix is documented | Only one agent learns it |
| Review rule added | Quality increased | Enforcement depends on entry point |
This is realistic because nobody is being careless. The team is moving fast, and the files are not treated as one system.
The reviewer sees the cost later
The cost appears during review, not during setup.
A pull request comes in with the right shape but the wrong test command. Another agent creates a new component even though the team decided to reuse an existing one. A third misses a security instruction that exists in one provider file but not another.
The reviewer should not need to ask which agent file produced the work.
That question is a signal. If the answer matters, the repository does not have one AI contract. It has a set of tool-specific memories.
Google DORA’s 2025 AI report frames AI as an amplifier of the surrounding software delivery system. In this case, the system being amplified is inconsistent instruction management.
paqad-ai makes provider files thin
paqad-ai treats provider files as entry points, not as the whole contract.
During onboarding, the framework can generate files for Claude Code, Gemini CLI, Codex CLI, Cursor, GitHub Copilot, Windsurf, Continue, Junie, Antigravity, and Aider. Those files point back to shared instruction bundles and framework-managed state.
The provider files still exist. They stop being competing sources of truth.
The practical fix is boring
Do not ask every team to debate which AI tool wins. That is the wrong fight.
This is not glamorous work. It is what makes multi-agent adoption manageable.
What next?
If your team is creating a new instruction file for every AI tool, pause before the copies become policy. paqad-ai lets you support Claude, Gemini, Codex, Cursor, and other tools without splitting the repository’s memory.
Make the files personal to the tool, not private to the tool.
