Prompt divergence: When the team’s most-used tool isn’t standardized

One codebase, two conversations

We standardize everything. Formatting is enforced by tooling, logging follows convention, API design has guidelines. But the tool the team uses most in a day – the conversation with AI – is often the least standardized.

One developer asks: “How should we structure this, given that we use vertical slices?”
Another asks: “Give me a quick solution.”

Both get good answers. The answers differ. And both end up in the same codebase. This is prompt divergence, and it’s more expensive than it looks.

Two seniors + two AI answers = four directions

In Tech lead in the AI age I described how AI amplifies the differences between experienced developers. The prompt is the mechanism behind it.

A prompt carries:

• context (or the lack of it)
• preferences
• level of ambition
• assumptions about the system

When the context varies, the answers vary. Not a little. A lot. And because each answer can look professionally defensible, the divergence can slide through review: no single PR is the problem, the sum is. It’s the same pattern as in Technical debt as a team phenomenon (in Norwegian) – the sum of many small decisions that were never aligned.

Context is the new standard

Dictating how people phrase things would be both impossible and pointless. What can be standardized is the context the AI receives. In practice:

1. Context files in the repo

A short file – ideally at the project root – describing:

• the architectural principles (“we use vertical slices, not layered architecture”)
• the conventions (“structured logging with correlation IDs, always”)
• what must not be done (“no new mapping libraries without a TDR”)

The point is that this isn’t a file you invent from scratch for every tool, and you probably only need one shared source of context. By late 2025, several major tools had their own instruction conventions: .github/copilot-instructions.md for GitHub Copilot, .cursor/rules/ for Cursor, CLAUDE.md for Claude Code, .windsurf/rules/ for Windsurf. Keeping the same guidance in multiple places can create another divergence problem.

That fragmentation is now starting to resolve. AGENTS.md was released by OpenAI in August 2025 and placed under the Linux Foundation’s new Agentic AI Foundation that December, alongside the Model Context Protocol and goose – which is when it became genuinely vendor-neutral. It is now read by Copilot, Cursor, Codex, VS Code and others (Gemini CLI needs one setting, Claude Code one line: @AGENTS.md in CLAUDE.md), and the site itself counted more than 60,000 open-source projects in December 2025. The practical advice is therefore:

• Write one AGENTS.md at the root. That is where the architectural principles, the conventions, and the prohibitions live.
• Add a tool-specific file only when you actually need something that format can do and AGENTS.md can’t.
• And let the file be reviewed like any other code. It describes your standards; it deserves the same bar as the code that follows them.

Then everyone on the team – and all their assistants – starts from the same place, from a single source. Thoughtworks put “curated shared instructions for software teams” at Adopt in Technology Radar vol. 34 from April 2026, with AGENTS.md as one of the formats: relying on each developer to write prompts from scratch is, in their words, an emerging anti-pattern. The same edition warns against “agent instruction bloat”, context files that grow until instructions start to conflict.

What goes in it – and what the measurements say

It is tempting to assume that more context gives better answers. The measurements say otherwise. Gloaguen and colleagues at ETH Zurich tested coding agents with and without a context file on real tasks in February 2026: on average the files gave no higher success rate, but over 20 percent higher cost, and the authors’ advice is that a hand-written context file should hold only what the README does not already say – specific conventions, non-functional requirements – and be tested before it is adopted. A follow-up in July 2026 found the same for Claude Code and Codex across 288 runs: the agents fail on implementation choices, not on missing knowledge of the repo.

That is not an argument against the file. It is an argument about what the file is for. It doesn’t make the agent better; it makes the answers yours, and divergence is what it removes. It also explains what belongs in it. Anthropic’s own guidance for CLAUDE.md says under 200 lines, because longer files are followed less reliably, and cut everything the model can read out of the code itself – directory layout, dependencies, architecture overview. Keep the pitfalls, the reasoning and the conventions that differ from the tool’s defaults. That is the list from the previous section: the principles, the conventions and the prohibitions. Not a copy of the README.

2. Shared prompts for recurring tasks

Some tasks repeat: generating tests, writing migrations, building API clients. Put the good prompts in the repo and treat them as tooling. docs/prompts/generate-integration-tests.md is the same thinking as templates and example code, not bureaucracy.

3. Link, don’t copy

The principle from Standards that actually stick (in Norwegian) applies here too: one source of truth. The context file should point to the standards, not duplicate them.

This is not about control

It’s tempting to read this as yet another rulebook. The point is the opposite: making it easy to get answers that fit the system. A developer who asks without context gets generic answers and has to adapt them alone. That adaptation is friction. When the team’s context is already built into the question, the answers almost fit from the start, and that is support.

Standards work when they feel like help, not control. Prompts are no different.

The tech lead’s job

You should not write all the prompts yourself. The job is to make sure they exist, get shared, and stay maintained:

• bring prompt practice into retrospectives: what works, what produces poor answers?
• when someone gets an unusually good result, ask them to share the prompt, not just the code
• treat the context file as living documentation: outdated context gives outdated answers

Nobody decided you’d diverge

Your team has been handed a new tool that shapes the codebase every single day. The question is not whether to standardize its use. The question is whether the divergence will be deliberate or accidental.

Prompts have become part of the development practice. Then they belong in the repo, with a reviewer, like the rest of it.