CLAUDE.md and ADR

Think of CLAUDE.md as the project's personality. It is the first thing Claude reads in every session. It shapes how Claude thinks about your codebase — what conventions to follow, what files matter right now, and what constraints to respect. It is not a documentation dump. It is the shortest possible briefing that gives a new session the right mental model.

At this stage — after architecture, before implementation — the CLAUDE.md update should be minimal. You have an architecture plan and a feature spec. Claude does not need their contents copied into CLAUDE.md. It needs to know they exist and that they are active. The actual conventions (error format, file structure patterns, naming rules) will be discovered and encoded during implementation in Phase 3, when they are battle-tested rather than theoretical.

Two things: a pointer to the active work, and a pointer to the design artifacts. That is it. CLAUDE.md should not duplicate the spec or the architecture plan — it should point to them. When Claude needs the error format, it reads docs/architecture/task-comments.md. When it needs acceptance criteria, it reads docs/specs/task-comments.md. CLAUDE.md is the table of contents, not the book.

CLAUDE.md additions from Phase 2 — minimal and intentional:

## Active Development
- Feature: task-comments (ACTIVE unit)
- Spec: docs/specs/task-comments.md
- Architecture: docs/architecture/task-comments.md

An ADR (Architecture Decision Record) captures why a decision was made — not just what was decided. Six months from now, someone will look at the middleware validation approach and ask "why not per-route?" The architecture plan says what you chose. The ADR says why, what alternatives were considered, and what trade-offs you accepted.

ADRs are common in enterprise teams with regulatory requirements, high staff turnover, or audit obligations. They originated from Michael Nygard's 2011 proposal and gained traction through ThoughtWorks' Technology Radar. They are not required by any standard or framework — they are a practice that pays off when decisions are revisited months later. For small teams or short-lived projects, the architecture plan may be sufficient.

You have an architecture plan from the previous experiment. Time to point CLAUDE.md at the active work.

Step 1: Ask Claude to update CLAUDE.md with pointers to the active feature and design artifacts.

Tell Claude:

Update CLAUDE.md with an 'Active Development' section that points
to the current work:
- The ACTIVE unit we're building
- The spec: docs/specs/task-comments.md
- The architecture plan: docs/architecture/task-comments.md

Do NOT copy architecture constraints or error formats into
CLAUDE.md — those live in the architecture file.
CLAUDE.md is a table of contents, not the book.

Observe: Claude adds a short "Active Development" section — three lines pointing to the feature, spec, and architecture. Check: is it minimal? Does it duplicate content from the architecture plan (it shouldn't)? Every future session now knows what we're building and where to look.

Step 2: Write an ADR documenting the validation approach decision (this is optional — practice the format even if your team doesn't require ADRs).

Tell Claude:

Write an Architecture Decision Record to
docs/adr/ADR-001-task-comments.md.

Capture: what was decided, what alternatives were considered
(with pros/cons), why we chose this approach, and what
consequences follow from the decision.

Base it on the analysis in docs/architecture/task-comments.md.

Observe: Claude produces a clean ADR capturing the decision and reasoning. The format doesn't matter — what matters is that someone reading this in six months can understand why middleware validation was chosen over per-route validation.

CLAUDE.md now points to the active work. Every new Claude session will know what feature is in progress and where the design artifacts live. The real conventions — error format, file patterns, naming rules — will be encoded in Phase 3 after implementation proves them out. Decisions in files, not in chat.

Progressive disclosure for completed features: Once a feature is done, you can create a .claude/rules/ file that links its source files to its docs — so future Claude sessions working on those files automatically know where the spec and architecture live, without loading them every session. This is the path-scoped rules pattern from the Configuration section applied to feature development.

Here is the complete CLAUDE.md after Phase 2. Notice how small it is — 76 lines. It describes the project architecture, conventions, and endpoints, then has a short "Active Development" section pointing to the spec and architecture plan. This is the "table of contents, not the book" principle in practice.

This is the ADR Claude wrote, capturing why per-route validation was chosen over middleware or a schema library. Six months from now, when someone asks "why didn't we use Joi?", this document has the answer — with the alternatives considered, pros and cons weighed, and trade-offs accepted.