ADR-012: In-repo instructions are the source of truth - never personal memory or config


Status	Accepted
Date	2026-07-22
Author	Łukasz Bodurka
Tags	consistency, agents, conventions, onboarding

Context

The "how to work here" knowledge - agent rules, repo-specific gotchas, tool settings, "always pass the full tenant id when editing its template" - tends to accumulate in the places closest to whoever learned it: a personal ~/.claude config, an agent's memory, a head. The repo then splits into invisible variants: each contributor (and each contributor's agent) works under different rules, and the difference is undiscoverable by construction. For a standard whose premise is "the repo is the context", this is the quietest possible failure.

Options considered

A - Tolerate personal stores, document the important bits sometimes. Status quo everywhere; guarantees divergence and makes review impossible ("works under my rules").
B - In-repo instructions are the single source of truth (chosen). Every rule about working in the repo lives in the repo, at its taxonomy-assigned home. Personal memory and global configs may point at repo rules, never hold them. "It's in my memory / my dotfiles" is rejected in review as a location for a repo rule.
C - Central org-wide rulebook outside any repo. Solves per-person divergence but reintroduces the wiki-drift failure and breaks the self-contained-repo premise.

Decision

Option B, with the two operational halves:

Location discipline (CONS-2): every rule kind has a named home - conventions in AGENTS.md/docs/conventions, process in ways-of-working, contribution mechanics in CONTRIBUTING, behavior in specs, decisions in records. A rule that exists only outside the repo (memory, personal config, chat) is treated as missing, and finding one is a defect to fix by landing it in its home.
Elicitation on entry (CONS-3): align-to-standards and onboard-repo explicitly ask for the unwritten rules - tribal knowledge, personal-config instructions, "everyone knows" gotchas - and land them in-repo at the right home, so a brownfield repo becomes self-describing instead of self-describing-except- for-the-important-parts.

Consequences

Positive: any agent or human, fresh, works under the same rules; review can check rule changes like code changes; the repo survives personnel and tool churn.
Negative: personal convenience configs must be split (pointer vs content); the elicitation step adds questions to onboarding - deliberately.

Confirmation

Conventions state the discipline; align/onboard skills carry the elicitation step; review culture rejects "it's in my memory" as a rule location.

Revisit when

Agent platforms ship portable, repo-scoped memory that is itself versioned in the repo, at which point it is an in-repo instruction and the distinction dissolves.

The CONS-1..3 epic in backlog.md; ADR-004 (decisions by reference); the coding-agent persona's pains in docs/personas.md.