More specific always wins over more general — and a real conflict gets flagged, not silently resolved.
Why this exists
An AI agent dropped into a large, old codebase with no context will do exactly what a new hire does on day one: read the code and infer intent. That's slow, and worse, it's unreliable — inferred intent is a guess, and a codebase built up over twenty years has plenty of decisions that look arbitrary from the code alone but exist for real, non-obvious reasons. Re-deriving those reasons from scratch, every session, either by a human or an agent, wastes time and eventually reproduces a mistake someone already made and fixed once. The alternative is writing decisions down once, in a form that's actually consulted rather than filed away — and treating that as seriously for an AI collaborator as you would for a new hire's onboarding.
1. One canonical guide, read by every AI tool the same way
Three different AI coding tools touch this codebase — Claude Code, GitHub Copilot, and JetBrains Junie — each with its own configuration format. The obvious failure mode is writing separate instructions for each and watching them quietly drift apart. Instead there's one full guide — project structure, conventions, guardrails, where to look for what — and each tool's own config file (Claude Code's CLAUDE.md, GitHub Copilot's copilot-instructions.md) is a short pointer into it, not a parallel copy. A tool-specific file states the handful of things that tool needs immediately, then says "the full guide lives here, read it first." One source of truth, several thin adapters, so a correction made once actually applies to all three tools at once — and so the choice of which AI tool a developer happens to be using on a given day is genuinely irrelevant to the outcome, not something that quietly changes what the codebase expects of them.
2. A stated order to consult sources in — not an implicit one
The guide doesn't just list what documentation exists; it states the order to read it in when implementing or changing behavior: first the high-level context for why an initiative exists, then the specific requirements and acceptance criteria for what's being asked, then the durable architectural decisions that constrain how, then the delivery-level breakdown of this particular piece of work, then the baseline engineering conventions that apply by default absent a more specific rule. And it states what happens when two of those disagree: more specific wins over more general, and — critically — the agent is instructed to surface the conflict explicitly rather than silently pick a side. An agent that guesses which instruction takes precedence is making an undocumented judgment call on your behalf; one that's told the actual precedence order doesn't have to guess, and one that's told to flag conflicts doesn't get to quietly resolve them in whichever direction was easiest.
3. Decisions get written down with their reasoning attached, not just their conclusion
The architectural-decisions layer isn't a style guide — it's a record of durable, sometimes non-obvious technical constraints along with why they exist, specifically because the codebase has traps that don't announce themselves as bugs. A framework can be built such that a subtly wrong return type, or a mismatched field name, produces no error at all — just quietly wrong behavior nobody notices until much later. Reading the source code won't reliably reveal a trap like that; testing the surface behavior might not either, if the wrong path happens not to get exercised. So it gets written down explicitly, once: this exact shape of mistake, why the framework behaves that way, what it looks like when you hit it. An agent that's told about the trap avoids it on the first attempt. An agent — or a person — left to discover it by trial and error eventually will, but only after shipping the same silent failure everyone before them also shipped.
4. Requirements become something an agent can actually build from
A request that only exists as a conversation, a slide, or someone's memory of a meeting is not something an agent (or a new team member) can reliably work from — it has to be re-extracted and re-interpreted every time someone touches that area, and every re-interpretation is a new chance to get it slightly wrong. So incoming requests get converted into a structured, stable document: what's actually being requested, and what "done" concretely means, kept engineering-readable and kept in sync with the original ask rather than drifting from it. That document, not a person's recollection of a meeting, is what an agent should build against — and it's exactly as useful to a human picking up the same ticket six months later.
5. Explicit guardrails against the agent's own initiative
Separately from what to read, the guide states what an agent should never do on its own judgment: don't invent requirements that aren't documented, don't silently expand scope beyond what was actually asked, respect a documented non-goal, prefer the smallest change that satisfies the requirement over a broader redesign. This matters more with an agent than with most humans, because an agent that's asked to fix one thing will often — helpfully, and without any bad intent — notice three other things nearby it thinks should also change. A human colleague usually asks first. An agent needs to be told, explicitly, that noticing something out of scope is a thing to flag, not a thing to just also do. None of this is tool-specific — the guardrails live in the documentation, not in any one product's settings, so the same rule applies whichever of the three tools happens to be running.
What this actually buys
None of this makes an agent smarter, and none of it is about clever prompting. What it does is convert institutional knowledge that would otherwise live only in a few people's heads — or get silently relearned the expensive way, repeatedly — into something written down once and consulted by default. The same documents that stop an agent from re-deriving the codebase from first principles every session are, almost without modification, the best onboarding material a new human hire could get too — with one advantage most onboarding docs never have: they can't quietly go stale, because agents depend on them being accurate every single day, not just once during someone's first week. And because the guidance lives in the codebase rather than in any single tool's configuration or a person's memory, any agent working from it — Claude Code today, whichever tool replaces it in a few years — should land in roughly the same place.
If you're setting this up yourself: start with one canonical guide and keep every other AI tool's config file a thin pointer into it, not a copy. Give each document type exactly one job — context explains why, requirements define what, decisions capture why it has to be built that way, delivery docs scope this specific piece of work — and resist merging them, because a document trying to do two jobs at once ends up serving neither well. And write decisions down when they're made, not retroactively; a decision record written months later is really just an aging memory with better formatting.