Skip to content
Verbara Knowledge Base

ADR-0002 — Context Hygiene Standard

ADR-0002 — Context Hygiene Standard

Section titled “ADR-0002 — Context Hygiene Standard”

Status: Accepted — 2026-06-13 Supersedes/extends: the P1 context-hygiene work (docs/plans/completed/2026-06-13-context-hygiene.md, spec docs/specs/2026-06-13-context-hygiene-design.md).

Context

Section titled “Context”

Per-session context had bloated against Anthropic’s context-engineering doctrine (“find the smallest set of high-signal tokens”; anti-patterns = context bloat + rot). P1 fixed it (global CLAUDE.md 16.7KB→2.4KB; repo CLAUDE.mds trimmed; memory indexes cut — Pro MEMORY.md 362→153L, Platform 143→80L). This ADR is the durable guardrail so it does not re-bloat.

Decision — the standard

Section titled “Decision — the standard”

1. Where each kind of knowledge lives (“right altitude”)

Section titled “1. Where each kind of knowledge lives (“right altitude”)”
  • CLAUDE.md (repo + global) = standing CONSTRAINTS + POINTERS only. Hard rules (AOT/Npgsql/TreatWarningsAsErrors/test-naming/commit/@base-ui/i18n…), build-test commands, architecture quick-reference, and pointers to where detail lives. Never a changelog. A line that narrates “shipped vX on date Y” belongs in docs/, not here.
  • docs/ = history and decisions: decisions/ (ADRs), plans/completed/ (shipped plans), CHANGELOG.md, research/. This is the home for milestone/release narrative.
  • .project-memory/ (auto-memory) = session-spanning LIVE facts: feedback/user/ reference (durable) + genuinely live project (current position, active roadmap, in-flight work). Closed-milestone narrative does NOT belong here once it is in docs/.

2. Size budget (guideline, not a hard gate)

Section titled “2. Size budget (guideline, not a hard gate)”
  • Repo CLAUDE.md ≈ ≤ 90 lines. Global CLAUDE.md ≈ ≤ 40 lines.
  • MEMORY.md = one line per LIVE memory; no orphans (every on-disk file indexed or archived), no broken links.

3. .project-memory/ contract

Section titled “3. .project-memory/ contract”
  • Always gitignored, never committed (it is personal/local). Enforced in every repo’s .gitignore. (Pre-2026-06-13 Pro committed it — corrected in P1.)

4. Memory disposition rule (when compacting)

Section titled “4. Memory disposition rule (when compacting)”
  • KEEP durable feedback/reference/user + live project. MERGE near-duplicates.
  • ARCHIVE (.project-memory/archive/) closed narrative — de-index it (the per-session cost is the loaded MEMORY.md index, not files on disk). Archive-dominant: prefer ARCHIVE over hard-DELETE, because .project-memory/ is gitignored so a hard delete is NOT git-recoverable.
  • DELETE only genuinely worthless files (never-released drafts, exact duplicates).

5. Cross-repo shared feedback

Section titled “5. Cross-repo shared feedback”
  • Some feedback_* files are byte-identical across repos (e.g. feedback_commit_rules, feedback_no_company_references, feedback_subagent_*, feedback_update_plan). For now each repo keeps its own copy. Canonical source = whichever repo authored it; when one changes, propagate by hand. (A future Claude Code plugin could distribute these — see ADR-0001 graduation triggers; not worth it at solo scale today.)

6. Periodic re-check

Section titled “6. Periodic re-check”
  • When a CLAUDE.md drifts past budget or a MEMORY.md index grows unwieldy, re-trim: move closed narrative to docs//archive/, rewrite the lean index, fix broken links.

Consequences

Section titled “Consequences”
  • Lean, trustworthy context every session. New milestone notes land in docs/, not CLAUDE.md. Memory stays a live working set, not an archive.
  • One-time judgment cost when compacting; mitigated by the archive-dominant (reversible) rule and a pre-flight backup.