TL;DR
Choose one repository-owned source of truth, document the precedence rule, and generate or check provider files from that shared policy. Start with one real change and make the evidence visible beside the work. Check canonical rule, explicit precedence, drift check, conflict owner. If a reviewer still has to guess about scope, proof, or ownership, pause and repair that gap before scaling the practice. The result should be a workflow another qualified person can follow and challenge without relying on private chat or the original operator’s memory.
In this article
Last updated October 14, 2026
7 min read
The public wording behind this refresh can be seen in the question and discussion that surfaced the same practical uncertainty. It is a question source, not proof of the recommendation; the operational answer below is checked against the article’s authoritative sources.
Choose one repository-owned source of truth, document the precedence rule, and generate or check provider files from that shared policy. The useful question is not whether the team can produce an impressive output once. It is whether the work remains understandable, reviewable, and safe when another person follows it under normal delivery pressure.
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.
10 adapters paqad-ai lists 10 supported external agent adapters in its public README.
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.
CLAUDE.md: Claude Code gets a local entry file without owning a private version of repo policy.GEMINI.md: Gemini CLI can read tool-specific entry text while sharing the same underlying project rules.AGENTS.md: Codex receives the same repo contract instead of a manually copied variant..paqad/: Framework state records project profile, stack detection, decisions, and operational context.
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.
- List every agent entry file. Include
CLAUDE.md,GEMINI.md,AGENTS.md, Cursor rules, Copilot instructions, and local convention files. - Find duplicated rules. Look for test commands, module boundaries, design rules, security notes, and review requirements.
- Move the contract behind the entries. Keep provider files thin and point them to shared docs and framework state.
- Validate drift. Use health checks and refresh flows so the repo contract does not silently age.
This is not glamorous work. It is what makes multi-agent adoption manageable.
Use a four-part evidence check
The practical test is whether another qualified person can understand the work without the original operator narrating it. For what should you do when claude.md, gemini.md, and agents.md disagree?, inspect four things together. A polished output with a missing decision owner is still weak. A detailed policy with no repository evidence is equally weak.
| Review surface | Question to ask | If the answer is unclear |
|---|---|---|
| Canonical rule | Can the team point to it without reconstructing the story from chat? | Write it down beside the work. |
| Explicit precedence | Is the boundary explicit enough that two reviewers would reach the same starting point? | Narrow the scope before continuing. |
| Drift check | Does the evidence show what ran, what changed, and what remains unknown? | Retain the result as a review artifact. |
| Conflict owner | Is one person accountable for accepting, changing, or stopping the work? | Name the owner before the next handoff. |
This worksheet is intentionally small enough to use on a real change. Start with one recent item that felt slow, risky, or surprisingly hard to review. Follow it from the original request to its present state. Record where a reviewer had to guess, where evidence disappeared, and which decision arrived late. The gaps show whether the next improvement belongs in documentation, automation, planning, review capacity, or ownership.
For example, imagine that the final code looks plausible and the tests are green, but nobody can connect the change to an accepted requirement. More testing will not repair that missing intent. The team must recover the requirement, decide whether the implementation still fits it, and preserve that link for the next reviewer. The same logic applies when the request is clear but the executed checks, risk boundary, or approval are missing.
Use one stop rule: if the person responsible for the outcome cannot explain what evidence supports the next step, pause before widening the change. Choose one repository-owned source of truth, document the precedence rule, and generate or check provider files from that shared policy. This keeps speed connected to a decision the team can defend.
For adjacent decisions, use the Eliyce guides on how to handle developer documentation location and how to handle multiple coding agents.
If this problem is affecting live delivery, Eliyce can help you turn the diagnosis into a bounded agent operations change with explicit evidence and decision points. See the relevant Eliyce service.
Frequently Asked Questions
What should you do when CLAUDE.md, GEMINI.md, and AGENTS.md disagree?
Choose one repository-owned source of truth, document the precedence rule, and generate or check provider files from that shared policy. Apply it to one real change first, then keep the evidence beside that change so another reviewer can follow the reasoning.
Which instruction file takes precedence for coding agents?
Start with canonical rule and explicit precedence. Together they show whether the work has a clear boundary and whether the team can evaluate it without relying on memory.
Should instruction precedence change inside different repository folders?
It can, when a local file narrows rules for a specific service or language. The repository must state how local rules inherit from or override the root so an agent does not treat two valid files as equal competitors.
Can provider-specific instruction files be generated from one source?
Yes, when the shared policy is expressed in a neutral canonical file and adapters contain only provider syntax. Keep generated files clearly marked and fail the check when someone edits them by hand.
How can CI detect instruction drift?
Regenerate the provider files in CI and compare the result with the committed versions, or verify that shared rule IDs and hashes match. The check should show exactly which rule diverged.
How should a team handle a necessary exception to the canonical rules?
Record the exception beside the affected code with its reason, scope, owner, and expiry or review condition. Silent exceptions become a second rule system and recreate the conflict.
