While building Monafy with AI agents, I found different versions of the same instruction across repositories. A rule would change in one file while another copy continued to request the old behavior. Because an agent could read both as context, the conflict affected development decisions rather than just documentation quality.
I consolidated shared rules in one workspace-level file and kept repository files focused on local commands and boundaries. Other documents refer to the shared rule instead of carrying their own rewritten version.
When two files both claim authority
One repository contained a long copy of the root instructions. It described itself as the authority for the workspace, but some of its rules had already changed at the real root. An agent starting in that repository could encounter both versions without a clear reason to prefer the current one.
Related conflicts also appeared in design notes and persistent memory. A tool had recorded a preference from one session as a lasting rule. Elsewhere, two notes gave opposing advice on how parallel work should be isolated. These were different sources of the same problem: a decision had been copied without retaining a reliable owner.
Separating shared policy from local context
I put workspace-wide decisions at the root, including source priority, evidence requirements and context recovery. A service's test command or a repository-specific development constraint stays in that repository's own instructions.
This is not an attempt to put all knowledge in a single file. It gives each rule one authoritative home while leaving operational detail near the code it describes. I explain the writing approach in the article on CLAUDE.md and project context.
Searching for the superseded rule
Updating the authoritative file is only part of a rule change. I also search the relevant documentation for the previous wording and inspect the surrounding lines. A sentence can be split across lines or carried into a longer explanation, so a narrow exact-match search can miss a conflicting copy.
References need a separate check. A relative path that resolves from a normal checkout may point somewhere else from a worktree. Reviewing the destination from the actual working directory establishes whether an agent can find the intended instructions, rather than merely whether the link looks plausible.
Keeping repeated context useful
Every paragraph in the shared file is read repeatedly. I keep the actionable rule and its reason there, while incident histories and earlier debates remain in their own reports. This reduces the amount of historical interpretation an agent must perform before it can act on the current decision.
The remaining maintenance task is ongoing: a rule change needs both an updated source and a check for old copies. A single authoritative file provides the boundary; searches and review keep the rest of the workspace consistent with it.