One Authoritative Source for Instructions

Since precedence isn't defined, don't create conflicts in the first place. The goal isn't designing "which one wins" correctly — that's impossible. What's possible is arranging things so no win-or-lose ever occurs.

Problem

The same content lives in multiple instruction files, and at some point they started disagreeing. One got fixed; the other got forgotten. So someone goes to find out "which one wins." But the official docs say different things depending on the surface — one surface defines a complete order of precedence, another also defines an order but the two orderings conflict, and yet another states plainly that it does not define a general order of precedence (Official, in Practice section). In other words, even a reader who goes looking for the right answer finds there isn't one. The conflict stays, and no one can say which instruction is actually taking effect.

Context

Applies when:

• Multiple instruction files exist — a personal layer, a repository layer, and an organization layer coexist. Or the same repository hosts differently-named instruction files side by side
• The same repository is used across multiple surfaces — written in an editor, run through the CLI, and read in a browser too, all under the same instructions
• After layering instructions — the moment layers are created, room opens up for the authoritative source to split

Does not apply when:

• Only one instruction file exists. No conflict can occur, so this pattern has nothing to do
• Deliberately wanting different instructions to take effect per surface. But confirm that this is actually intended — "allowed to differ by surface" and "ended up differing by surface" produce indistinguishable results

Boundary with neighboring patterns:

• Instruction Layering and Scoping — ⚠ that pattern works in the direction of creating conflicts. The more layers added, the easier it is for the authoritative source to split. This pattern handles that pattern's side effect. That pattern itself lists "no longer knowing what's taking effect" as one of its own costs, and this pattern is the form that prevents that state from arising. The two are used together, but they pull in opposite directions
• Rules Ranked by Binding Force — that pattern assigns weight within a single file. This pattern deals with across files. Resolving a conflict by binding force only works within the same file — cross a file boundary and it isn't even defined which one gets read at all
• Resident Context Inventory — having one authoritative source is also reducing duplicates. Counting and discarding is that pattern; not creating duplicates in the first place is this pattern

Solution

Laying the per-surface answers side by side gives this:

Surface	How precedence is handled	Result
Surface A	States it does not define a general order	Can't predict what happens on conflict
Surface B	Defines a complete order	But conflicts with Surface C's ordering
Surface C	Defines an order	But conflicts with Surface B's ordering

Why this works. This pattern's grounds differ in kind from other patterns. It isn't the general claim that "consolidating is good." The grounds sit instead in a verifiable fact: no rule for resolving conflict exists.

Normally, when precedence is defined, conflict can be designed. Put what matters in a higher layer, put what's fine to override in a lower one. Conflict stops being an accident and becomes a tool. But one surface states plainly that it does not define a general order of precedence (Official, in Practice section). Since it's undefined, what happens on conflict can't be predicted from this side. What can't be predicted can't be designed.

The substance of "unpredictable" gets one level clearer still. A conflict doesn't mean one side gets dropped. All three surfaces, together, state that instructions are handed over in full (Official, in Practice section) — not one surface drops anything. Which means two contradictory instructions arrive at the model simultaneously, still contradictory. What resolves the conflict isn't a documented rule — it's the model. Its output is written nowhere in any surface's docs.

So there's only one remaining move. Don't let conflict occur. Keep the content in one place, and have everywhere else reference it. Without duplication, there's nothing to disagree with.

This looks like a negative conclusion, but it's actually the strongest form of design. A design that doesn't depend on a resolution rule doesn't break even when the resolution rule changes. In a territory where the rule differs by surface, and that rule itself is subject to revision, not betting on the rule is the only stability there is. Stepping out of the race to pick the correct rule is exactly how much you stop being able to lose.

And — the official docs themselves reach the same conclusion. The surface that defines a complete order, on the very same page that defines that order, writes: "whenever possible, try to avoid providing conflicting sets of instructions" (Official, in Practice section). The very party that defined the order is telling readers not to rely on it. It doesn't fully trust the rule it wrote itself. This is strong circumstantial evidence — having a rule and being safe to bet on that rule are different things.

Trade-offs

Advantages

• The same instruction takes effect no matter which surface it's used on. With one authoritative source, the result doesn't change regardless of what the per-surface resolution rule is. The fact that the rule differs by surface stops mattering at all. Behavior confirmed on one surface no longer needs to be justified on another by cross-checking the docs.
• Sync maintenance disappears. Without duplication, there's no syncing to do, and no later discovery that a sync was missed. As many "places forgotten to fix" as there were duplicates — now zero.

Costs

• A reference is less convenient than a duplicate. Consolidating into one place means it can't be tailored to each surface's needs. Duplicating lets each copy be shaped to fit, and that's exactly what this pattern forbids. Convenience is traded away for stability.
• There are legitimate cases for wanting different instructions per surface. A real need might be to suppress verbose output on an interactive surface, say. This pattern makes that harder. Having one authoritative source means every "I want it to differ by surface" has to be justified as an exception, every time.

GitHub Copilot in Practice

Copilot isn't a single product. For this pattern, that fact isn't a preamble — it's the subject itself. Three surfaces write different answers to the same question — what happens when instruction files conflict. What follows isn't speculation — it's a verbatim comparison of three Official sources.

Copilot CLI — states plainly it defines no general order

Source: Copilot CLI — Adding custom instructions (retrieved 2026-07-16) Official:

When multiple applicable user-level and repository instruction files exist, Copilot CLI combines their instructions. It removes duplicate copies of identical user-level copilot-instructions.md, repository-wide, and agent instructions, but does not define a general precedence order between these files. Avoid conflicting instructions.

When multiple instruction files exist, this surface combines them. Duplicate copies of identical content get removed, but it does not define a general precedence order between these files. Then, in one final sentence, comes the advice — Avoid conflicting instructions.

"Does not define" is Official — not Undocumented, not Absence Confirmed

Undocumented is a double claim — "the behavior was observed" plus "the official docs don't mention it" — and this catalogue hasn't observed conflict-time behavior, so it can't be attached here. Absence Confirmed claims "the primary source was checked, and the description is absent," but what's happening here is the opposite — the description exists. The content of that description just happens to be "not defined."

So this is a design fact the official docs state explicitly, and Official suffices. It isn't "not written in the official docs" — it's "the official docs write that it isn't defined." That difference matters — the former leaves open the possibility of a bad search; the latter doesn't.

The same surface also has a way for a human to see directly what's currently in effect Official:

Use the /instructions command to view the instruction files discovered for the current session and enable or disable individual files.

It lists the instruction files discovered for the current session and lets individual files be enabled or disabled. On this surface, whether the authoritative source has split can be checked in a list, rather than from memory or guesswork.

github.com — defines a complete order

Source: GitHub — Response customization (retrieved 2026-07-16) Official:

Multiple types of custom instructions can apply to a request sent to Copilot. Personal instructions take the highest priority. Repository instructions come next, and then organization instructions are prioritized last. However, all sets of relevant instructions are provided to Copilot.

The same page also lists the complete order of precedence Official:

The following list shows the complete order of precedence, with instructions higher in this list taking precedence over those lower in the list:

• Personal instructions
• Repository custom instructions:
  • Path-specific instructions in any applicable .github/instructions/**/*.instructions.md file
• Repository-wide instructions in the .github/copilot-instructions.md file
• Agent instructions (for example, in an AGENTS.md file)
• Organization custom instructions

The original rule is "what's higher takes precedence over what's lower." Personal is first, Organization is last. Between them, in this order, come repository custom instructions (path-specific), repo-wide .github/copilot-instructions.md, then agent instructions — the example the original text gives is AGENTS.md. AGENTS.md sits below repo-wide. What the CLI states it "does not define," this surface defines completely, in a list.

And having shown that order, it goes on to say Official:

Whenever possible, try to avoid providing conflicting sets of instructions.

The very surface that defines a complete order is telling readers not to rely on it. This is the circumstantial evidence noted in Solution. The one who wrote the order recommends not creating conflict in the first place.

VS Code — defines an order, but it conflicts with github.com

Source: VS Code — Custom instructions (retrieved 2026-07-16) Official:

When multiple types of custom instructions exist, they are all provided to the AI. Higher-priority instructions take precedence when conflicts occur:

1. Personal instructions (user-level, highest priority)
2. Repository instructions (.github/copilot-instructions.md or AGENTS.md)
3. Organization instructions (lowest priority)

Here too, Personal sits at the top and Organization at the bottom. Both ends match github.com. The middle is where they conflict — this surface writes .github/copilot-instructions.md or AGENTS.md, placing the two on the same rung. github.com put those same two on separate rungs, dropping AGENTS.md below repo-wide.

Cross-check — three answers to the same question

Surface	Defines a general order?	Position of AGENTS.md	Source
Copilot CLI	States it does not	—	add-custom-instructions, above
github.com	Defines a complete order	Below repo-wide .github/copilot-instructions.md	response-customization, above
VS Code	Defines an order (3 tiers)	Same tier as .github/copilot-instructions.md	custom-instructions, above

Two separate points are at issue here. They need to be read without mixing them up.

(1) The CLI versus the other two surfaces. One states plainly it "doesn't define" one; the others "define" one. The design itself differs between surfaces of the same product name. This isn't a difference in detail — it's a difference in whether the concept of precedence exists at all.

(2) github.com versus VS Code. Both define an order, yet they treat AGENTS.md differently. One places it on a rung below repo-wide; the other places it on the same rung as repo-wide. Both surfaces have an answer here, and the answers don't match.

This catalogue doesn't know which one is correct

What's been confirmed is only that the three original passages above said this, at this URL, as of this retrieval date. Behavior hasn't been observed. So this catalogue doesn't claim "AGENTS.md is actually handled this way," nor does it say "one of these docs is wrong."

What's handed to the reader isn't a verdict — it's material for a verdict. The fact that different things are written across surfaces is placed here verbatim, with URL and retrieval date. The reader decides the weight.

Where the three surfaces agree — instructions never get dropped

The disagreements stand out, but there's one thing all three surfaces state together. On conflict, nothing gets dropped.

• VS Code: "they are all provided to the AI"
• github.com: "However, all sets of relevant instructions are provided to Copilot."
• Copilot CLI: "Copilot CLI combines their instructions" — the only thing removed is duplicate copies of identical content

All three are the exact original text of each surface, quoted in full above. When two instructions contradict, no surface drops either one. Both reach the model. This is the substance of "unpredictable" from Solution. Precedence isn't a mechanism for dropping one side before delivery — it's merely a hint, after everything has been delivered, about which one to weigh more.

And two of the surfaces state advice for this exact situation — the CLI's "Avoid conflicting instructions." and github.com's "Whenever possible, try to avoid providing conflicting sets of instructions." (both quoted above). The very surfaces that define an order are telling readers not to rely on it.

Also Known As

Name	Source
Single source of truth / SSOT	Folklore — circulates in the community, but no primary source can be traced for this usage. And it collides with an existing, established term (below)
One Authoritative Source for Instructions	Descriptive — a descriptive name coined by this catalogue; no primary source uses it

SSOT is a name with prior occupants, not a borrowed one. In data design and configuration management, it's an established term for keeping a single authoritative copy of data in one place. What this pattern says is keeping a single authoritative source of instructions — the structure is close, but the object is different: that term is about data, this pattern is about instructions. That closeness causes real harm. Call it SSOT, and readers first picture the existing meaning, then pay the cost of reinterpreting it every time. A reader who fails that reinterpretation walks past this pattern as unrelated to them. The closer the name, the more quietly the misreading happens.

For that reason, this catalogue changed its former name, "single source of truth," because of this collision (a design decision internal to this catalogue, not an external renaming). SSOT is still kept as an alias — because readers come looking for it under that name. Rather than dropping the name, noting the collision and keeping it alongside lets readers actually arrive.

Related

• Instruction Layering and Scoping — creating layers makes the authoritative source easier to split. This pattern handles that pattern's side effect. That pattern lists "no longer knowing what's taking effect" as one of its own costs, and this pattern is the form that prevents that state from arising. Used together, but pulling in opposite directions — every layer added means checking whether the authoritative source stayed whole
• Rules Ranked by Binding Force — that pattern assigns weight within a single file. This pattern deals with across files. Resolving conflict by binding force only works within the same file — cross a file boundary and it isn't even defined which one gets read. The same word "precedence" loses its meaning the instant it crosses that boundary
• Resident Context Inventory — having one authoritative source is also reducing duplicates. Counting and discarding is that pattern; never creating duplicates in the first place is this pattern. Keeping one authoritative source doesn't stop that source itself from growing — having no duplicates and being lightweight are separate problems; read that pattern next if the latter is the concern
• Separating Mechanical Gates from Semantic Gates — whether two instructions conflict can't be judged by string matching. Since it can't be handed to a mechanical gate, design avoids it instead. What can't be detected can only be prevented from happening
• If reading just one more next: Failure as Institutional Memory — having settled on an authoritative source, it's next to put the record of incidents into that source