Mental Model

Project instructions are a context-routing system. Their job is to deliver the smallest relevant repository contract before the agent makes a consequential decision.

Four Properties

1. Scope — which repository, directory, file pattern, agent, or product surface receives the instruction.
2. Precedence — how organization, user, repository, and nested files combine when they disagree.
3. Persistence — when instructions load, reload, or survive context compaction.
4. Authority — whether the text advises the model or is backed by an independently enforced control.

The first three determine whether the agent sees the right context. The fourth determines whether noncompliance is merely unlikely or technically prevented.

Product Realizations

Do not infer a universal precedence algorithm from the shared use of Markdown. Each product decides discovery and merge behavior.

The Crux

If a rule must hold even when the model misunderstands, ignores, or never loads it, the rule does not belong only in an instruction file. Put the explanation in instructions and the enforcement in permissions, hooks, tests, CI, or release policy.