Context architecture

Every contextual detail has exactly one authoritative home. Any other layer that needs the detail links to that home and never restates or redefines it. A restatement is a second source of truth from the moment it is written, and it drifts from the moment the original changes.

The principle governs every layer that carries written context: the architecture and its principle pages, each repository's README, documentation, and CLAUDE.md file, each project's working context, and each workflow skill's files. It applies the downward-dependency principle to prose: a detail is defined once, at the layer whose authority it is, and every other layer refers to that definition by link.

Where each kind of detail is defined

How another layer refers to a detail

A layer that needs a detail defined elsewhere cites the home. A repository README links the principles the repository follows. The architecture's catalog links the repository rather than describing its packages. A profile links the architecture. A summary that adds no information beyond the link is a restatement and is removed.

A narrowing is not a restatement. A profile that states less than the design supports, or a repository that declares a tighter dependency line than its standard, asserts something the home does not. The narrowing rule of the hierarchy permits that assertion, and the layer states it beside the link to the principle it tightens.

What each layer answers for a reader

The organization carries a large amount of technically dense information, and the layering is how a reader digests it. Each layer answers one question and links to the layer that answers the next one.

Layer The question the layer answers
The principle pages What does the organization believe?
The architecture's catalog Which repositories implement the architecture, and where is each?
A repository's README and documentation What does this repository do, and how is it used?
A repository's CLAUDE.md file How does a contributor work in this repository?
A repository's working context What is in flight?
The code and its API documentation What does the software do?

How a restatement is handled

A contributor who finds a restatement collapses it to a link in the same change, the way a contributor already fixes a stale claim. The organization adopted the principle after finding the same defect in three unrelated places. A role boundary restated in six repositories took a seven-file change to update. A rule restated without its protective qualifier authorized what the authoritative copy forbade. Package inventories restated in three places were two releases stale in two of them while the code was current.

Keyboard shortcuts

Settings