WEB-META-1 CLAUDE.md Level-Up

Output of the dedicated Cowork session (24 Apr 2026) that rewrote pride-website/CLAUDE.md from a 29-line thin brief into a 154-line convention document. Executed after WEB-AG-5 shipped, drawing observations from seven execution sessions (S1–S7).

Decision: single file, keep AGENTS.md alongside

Rejected satellite files (SANITY.md, GIT.md, etc.). The project is small enough that indirection cost exceeds organisation benefit. Reassess if CLAUDE.md exceeds ~250 lines.

AGENTS.md already exists at the repo root — auto-generated by Next.js, warns that training data may be stale against this Next.js version. Left as-is. Claude Code treats CLAUDE.md as primary, AGENTS.md as fallback (precedence confirmed in Apr 2026 community guidance), so coexistence is non-conflicting.

What the level-up codifies

Twelve rules that weren’t in the previous CLAUDE.md, each traceable to an observed WEB-AG-5 drift:

Rule	Why it’s needed	Trace
Halt-by-default error handling	Claude Code soft-proceeded on remote ref does not exist because end-state looked correct	S1
Trust runtime over build-green	Four distinct bugs passed lint+build but broke on page-load	S1/S2/S4/S5/S6
Minimum verification (build + lint + tsc + dev + preview smoke)	No single check was sufficient in WEB-AG-5	All
Baseline-aware AC	”npm run lint passes” AC collided with 179 pre-existing errors	S2
Hygiene grep sweep	Prevents Unsplash residue, typo email, personal phones, invented env vars	S7
'use client' only at the leaf	Spec-level scatter suggested project convention wasn’t clear	S2
Primitives with sub-components export BOTH patterns	Reveal.Item broke twice across the server→client proxy boundary	S4, S6
Tailwind v4 @source scoping mandatory	Auto-scan of _specs/*.md generated broken bg-[url()] utility	S2
CSP directives must be set explicitly	Missing directives fall back to default-src and silently break features	S5 (style-src), S6 (img-src)
<Reveal immediate> for above-fold	SSR flash from async IntersectionObserver callback	S4
Scope discipline — halt on spec/repo conflict	Invented fetchers like getCachedReviews in specs	S4
Claude Preview viewport limitation → use Vercel preview	Headless browser reports window.innerWidth = 0	S4

Before/after validation

Taking WEB-AG-5 Session 2’s spec (_specs/WEB-AG-5-session-2.md) as the test case. Under the new CLAUDE.md, this section:

## Architectural rules
- Every file starts with `"use client"` — all primitives use `framer-motion`
  which is a client-only library.
- Named exports only (no default exports).
- Explicit TypeScript interfaces, no `any`.
- Respect `prefers-reduced-motion` via `useReducedMotion()` — when true,
  skip animation (render final state).
- Use the CSS variables (`var(--primary)`, `var(--accent)` etc.) from Session 1's
  globals.css — don't re-declare values.

Collapses to:

## Architectural rules
- Primitives use framer-motion, so every file in src/components/motion/ and
  animated primitives in src/components/ui/ start with `"use client"`.
- Use Session 1's CSS variables from globals.css — don't re-declare values.

The useReducedMotion rule, any-ban, and named-export convention are already in CLAUDE.md. Same logic applies to S2’s acceptance criteria — the following bullets are now implicit and can be removed:

• “No any types” (now in TypeScript section)
• “useReducedMotion() is read in every component that animates” (now in Animation + reduced motion)
• “npm run build passes with zero TypeScript errors” (now in Verification)
• “No references to window.Motion … Object.assign(window, ...)” (now in Hygiene greps)

Estimated spec-level shrink across S1–S7: ~15–25 lines per spec. Over 7 specs, ~100–175 lines of repeated convention statements removed, and the signal-to-noise on each spec improves.

Scope explicitly deferred

The spec listed 19 scope areas. Several were deferred deliberately:

• Testing expectations — project has no test infrastructure; rules without substrate are noise
• Sanity schema conventions at depth — project-specific, would benefit from a SANITY.md satellite if drift emerges
• Detailed component conventions — no evidence of drift beyond the server-vs-client and primitive-sub-component rules, which are covered

If any of these surfaces as a pattern in future sessions, add a rule then — not now.

How this changes Cowork’s spec-writing

Cowork writes thinner specs from this point. The “Architectural rules” and “Scope rule — read first” preambles in WEB-AG-5 specs were load-bearing then; now they’re redundant. Spec methodology going forward: spec states the goal, the specific constraints of the current task, and what verification is unusual for this task. Conventional rules stay in CLAUDE.md.

Related pages

• Cowork-Claude Code Workflow — supersedes the earlier process notes with the new CLAUDE.md as source of truth
• Tech Stack — informed by the conventions codified here
• WEB-AG-5 QA Findings — the execution-session observations feeding this level-up