Skip to content

CLAUDE.md

Latest commit

 

History

History
40 lines (27 loc) · 3.46 KB

CLAUDE.md

File metadata and controls

40 lines (27 loc) · 3.46 KB
Raw

Repo guidance

This file is read by Claude Code (and other agents that respect CLAUDE.md). Keep it as a pointer file, not a long doc; the real conventions live in docs/reference/.

Conventions

Hard rules carried into every change

  • No phase / iteration / audit tags (Phase 8f-d, Iter B-3, DLM-A, audit-2026-...) in source. Git log and project_phase_plan.md are the right home.
  • No emoji anywhere in source — comments, docstrings, log strings, error messages, Field(description=...).
  • No em dashes in user-facing prose; use commas, colons, or rephrase.
  • Default to no # comments. Add one only when the WHY is non-obvious.
  • Test names carry scenarios (test_<subject>_<scenario>_<expectation>); per-test docstrings stay rare.

Memory hygiene

Auto-memory grows monotonically without a forcing function. These rules curb drift between sessions. They apply to this repo's Claude auto-memory directory: ~/.claude/projects/<repo-path-slug>/memory/, where <repo-path-slug> is the repository's absolute path with / replaced by - (it differs per machine).

The index is split across three files because the always-loaded one has a fixed budget: MEMORY.md (auto-loaded each session) carries only the User, Feedback, and Durable shelves; the work-ledger shelves live in on-demand siblings, MEMORY_ACTIVE.md (in-flight designs, research, BC work, pilots, watch-items) and MEMORY_REFERENCE.md (superseded or 30d-shipped memos, kept for provenance). Keep MEMORY.md under ~17KB so it never truncates on load.

  • A new memo's one-line pointer goes in the shelf that fits: a durable convention, principle, or pattern, a user fact, or feedback goes in MEMORY.md; in-flight work goes in MEMORY_ACTIVE.md.
  • Before creating a new memo, grep all three index files for the topic; prefer edit-in-place over a new file.
  • When tagging a memo SUPERSEDED, move its pointer from MEMORY_ACTIVE.md to MEMORY_REFERENCE.md in the same edit.
  • After a memo's content reaches SHIPPED and the work has been on main for 30+ days, demote its pointer from MEMORY_ACTIVE.md to MEMORY_REFERENCE.md.
  • Any index description containing a count, phase tag, or date older than 7 days requires a Read of the underlying file before quoting in chat.
  • Mutable phase status does not belong in index descriptions; the index carries the durable claim, the file carries the status.
  • Memo files over ~300 lines: split into 2-3 sibling files linked from the first.

Commits

One-line subject, body explains WHY. Recent commits set the tone — git log --oneline -10.

Reviewer subagents

  • naming-r3-reviewer: auto-invoked on rename or new-name commits (aggregate fields, event/command classes, slice directories, aggregate types, agent types, procedure kinds). Checks R1-R6 with an explicit guard against the R3 noun-LAST trap; R6 (procedure-kind operation-noun-LAST) added 2026-06 alongside the set_energy to energy_setting normalization. Further axes added only after a rule-of-three trigger fires.