One source of truth per role: the silent trap of agentic systems

In the previous article, I unpacked seven design principles from the Claude Code leak. The second principle, "the prompt is the architecture", is the one I see most often misapplied in practice. Not because people ignore it, but because they understand it partially, and that partial understanding creates a trap I want to describe here.

This trap has a name: the double source of truth. It shows up as soon as you start seriously structuring an agent system, and it produces disconcerting symptoms. The agent behaves correctly ninety percent of the time, then suddenly derails for no visible reason. Users then talk about hallucinations, instability, "the AI doing whatever it wants". In my experience, that's almost never the real cause. It's an internal contradiction the system loaded without knowing it.

The symptom

Here's a situation I've seen repeated several times. Someone asks me the following question:

I created a dedicated subfolder for my Code Reviewer agent, with a description file, examples and rules. But I just noticed that the same agent is already defined in my team manifest at the project root. Which one is Claude going to use?

The answer that feels obvious is "the most specific one" or "the most recent one". Both are wrong. The correct answer is: both.

When you interact with an agent like Claude Code, it explores your project folder, identifies relevant files (CLAUDE.md, markdown files related to the conversation topic, common entry points), and loads their content into its context. If your team manifest lists twenty roles including the Code Reviewer, it loads it. If your code-reviewer/ subfolder contains a description file, it loads that too. Both end up in the context, at the same time.

Why it breaks down

As long as the two definitions say the same thing, possibly at different levels of detail, everything is fine. The manifest introduces the role, the subfolder elaborates. That's actually healthy: a synthetic view and a detailed view, consistent with each other.

The problem starts as soon as the two diverge. And they always diverge, sooner or later, because you'll update one without thinking about the other. A tone that shifts in the subfolder, a rule that changes in the manifest, a mission rephrased in only one place. The divergence is often subtle, sometimes invisible to the naked eye.

From that point on, the model has two slightly different versions of the same role in its context. And its behavior depends on several unpredictable factors: the order in which files were loaded, their relative length, their position in context (recent tokens carry more weight than older ones), and the model's natural bias toward the most explicit formulations. The result is that you can no longer predict which version it will follow. Sometimes it's one, sometimes it's the other, and in the worst cases it tries to blend the two into something that matches neither.

Users then talk about model instability. In reality, the model is perfectly stable. It's the scaffold that handed it two competing truths to reconcile, without giving it any way to choose. This isn't an AI problem, it's a system design problem.

The rule to remember

One role, one single source of truth. Not two. Not "the manifest for the intro and the subfolder for the details" if you don't have a strict mechanism to prevent divergence.

This rule sounds obvious when stated like that. In practice, it's violated in almost every project I've seen, because people approach agentic systems with classical documentation reflexes, where duplicating information is considered normal (even helpful, for reading comfort).

In an agentic system, duplication is not normal, it's toxic. The model doesn't "skim" like a human who would skip the repetition. It loads everything, weights everything, and returns the weighting it produced, which depends on a thousand details you don't control.

Manifest or dedicated folder

Concretely, you have two options for each role:

Option 1: a card in the manifest, no dedicated folder.

If the role fits on a single page (mission, tone, main rules, concise examples), the manifest card is enough. No folder needed. You gain simplicity and consistency.

agents/
  MANIFEST.md         # 20 roles, one card per role, ~1 page each

Option 2: a dedicated folder, no card in the manifest.

If the role really warrants expansion (several documents, long examples, nuanced rules, playbooks), give it its own folder. But in that case, in the manifest, you only put a single line pointing to the folder, without redefining the role.

agents/
  MANIFEST.md         # 20 lines, one line per role
  code-reviewer/
    ROLE.md           # mission, tone, review criteria
    examples/
      style-violations.md
      common-smells.md
    playbooks/
      security-review.md
      performance-review.md

And in MANIFEST.md, the Code Reviewer entry looks like:

- **Code Reviewer**: see [code-reviewer/ROLE.md](code-reviewer/ROLE.md)

Nothing more. No repeated mission, no "just in case" summary. One line, one pointer, done.

How to decide which one to use

The next question is: "how do I know whether my agent deserves a folder or whether a card is enough?"

My personal rule is simple: if you can write everything on a single page without censoring yourself, the folder is over-engineering. You're going to create five files to store what fit on a single screen, and each of those files will be a potential source of future divergence.

Conversely, if your card is already three pages long, mixing general rules and specific playbooks, accumulating examples to the point of becoming hard to read, that's the signal it's time to split into a folder. But at that moment, the card disappears from the manifest entirely. It's not "summarized" at the root. It's replaced by a pointer.

This principle is exactly the same as in Claude Code with the distinction between MEMORY.md (the index, one line per entry, always in context) and the topic files (the detail, loaded on demand). The index points, it doesn't duplicate. This is an architectural convergence that's no accident: it's the only way to keep an agentic system predictable as it grows.

Connection to Principle 2

In the parent article, I wrote that "the prompt is the architecture". What I've just described is a direct consequence. If the prompt is the architecture, then good architecture rules apply to it, in particular the DRY principle (don't repeat yourself). In software architecture, everyone knows that duplicating information across two places in the code is a debt that will have to be paid. In an agent's prompt, it's exactly the same, except the cost is paid in unpredictable behavior rather than compiler bugs.

The difference with regular code is that you don't have a linter that flags duplication. There's no tool that tells you "watch out, the Code Reviewer role is defined in two files". You have to maintain this discipline yourself, by convention, when you design the tree structure and every time you modify it.

What Claude Code already does

The Claude Code leak confirms this approach. The three-layer memory system (index, topic files, transcripts) rests entirely on the rule "the index points, it doesn't duplicate". MEMORY.md is capped at 200 lines, and each entry must be about 150 characters maximum. That's not a cosmetic constraint, it's an architectural one: if the index starts containing actual content rather than pointers, it begins competing with the topic files, and the double source of truth problem reappears immediately.

The consolidation sub-agent autoDream explicitly has, in its prompt, a directive to "remove contradictions" when merging observations. Anthropic has clearly run into this problem and treated it at the system design level, not at the model level. This is consistent with Principle 1 from the parent article: the scaffold matters more than the model. No model resolves a contradiction in sources cleanly. You have to prevent it upstream.

What I apply in my own projects

In my own agent folders, I've ended up adopting three concrete rules that avoid the trap:

1. A single file has authority for a given role, and I know which one when I create the role. I don't leave myself the option of "I'll decide later whether to make a folder".

2. The manifest is an index, not documentation. If it contains anything other than pointers and summary lines without executable rules, I know I already have a latent problem.

3. When I migrate a role from a card to a folder, I immediately delete the card from the manifest at the moment the folder is created. In the same operation. Not later. Not "once I'm sure the folder is complete". The card and the folder never coexist, not even for five minutes.

These three rules are annoying to apply at first. They become natural after a few projects, and they eliminate a whole class of erratic behaviors that were previously blamed on "model instability".

Going further

The next article in this series tackles another direct consequence of Principle 2: how to structure the context so it stays efficient and economical. The architectural discipline I'm describing here extends naturally into fine-grained management of the files loaded at each session.

And if you want to see these principles applied to an inference engine rather than to an agent system, herbert-rs adopts the same philosophy: one source of truth per component, no hidden duplication, and an architecture where each piece knows exactly what it's responsible for. The domains change, the principles remain.

Questions about this article or your own project? Book a consultation