knowledge-layerslisted

# Knowledge layers — authority order A project has three knowledge layers, and they rank in a fixed authority order. Most doc-trust bugs come from not knowing which one wins when they disagree. 1. **`.claude/` (or the project's guidance layer) is GUIDANCE.** Rules, skills, invariants, conventions — *how to build* this project. Intentional, hand-authored, prescriptive. It tells you what discipline to apply; it does not describe what the system currently does. 2. **Code is TRUTH.** It is what the system actually does, because it is the thing that runs. For any factual question about real behavior — the actual retry limit, the actual auth check, the actual schema — read code, not a description of code. 3. **`docs/` is a REFLECTION of code, plus transient intent.** *Reflection docs* (architecture overviews, flow docs, a capabilities index) are a downstream *description* of code — a navigable map to find the right code fast, not an authority on what it does. *Transient intent* (brainstorms, plans) is forward-looking exploration consumed when the work ships, then archived. Neither is authoritative about current behavior. ## The rule that follows from the ranking **Derive correctness from code plus the guidance layer.** Verify any load-bearing claim against code. **When a doc and the code disagree, the code wins — every time, no exceptions.** This is not "prefer code"; it is code wins. Hedged language invites you to trust the doc anyway. The reason: code is executed, so it ca