Rework agent context: gotcha-first CLAUDE.md, progressive disclosure via skills

[alexpricedev]

Applies Anthropic's context engineering guidance for Claude 5 generation models to this repo's agent context.

The post's CLAUDE.md guidance is specific: "Keep your CLAUDE.md lightweight and briefly describe what your repo is for, but spend most of the tokens on gotchas inside of the codebase. Avoid stating 'the obvious' things Claude should know by looking at your file system or your repo." Measured against that, the old file was mostly obvious-restating.

CLAUDE.md: 222 → 90 lines

Removed — the directory tree (duplicated README's, and stale: it listed pages that don't exist and omitted controllers/admin/, page-lifecycle.ts), the naming-conventions table, the step-by-step new-page walkthrough, the per-module testing strategies, and the architecture prose restating what the code already shows.

Also removed two claims that were false: --max-warnings 0 is an ESLint flag, not a Biome one, and "no unsafe writes" described nothing in biome.json.

Added — gotchas found by reading the source, each verified against it:

• Two JSX runtimes with no hydration: server templates render through react-dom/server, islands opt into Preact per-file, and the Preact version is pinned twice (package.json and the esm.sh import map in layouts.tsx).
• Service tests call mock.module before importing the service — the odd-looking import ordering is load-bearing, and tidying it silently breaks the mock.
• bun test ≠ bun run test: the script applies migrations, isolates per file, and pins SESSION_COOKIE_NAME because a custom value in a developer's .env otherwise breaks auth tests for unrelated-looking reasons.
• The CSP script allowlist — a new third-party script fails only in the browser and passes every test.
• APP_URL must include the port; CSRF origin comparison is exact.
• Production-only asset fingerprinting, the boot-order/env contract, and the tsconfig exclusion that puts resend.ts outside bun run check.

Rules → judgement — "use code comments sparingly" was close to the exact example the post calls out, so it now uses the post's replacement framing: match the surrounding code's comment density, naming, and idiom. The absolutes that encode real environment failures (dev server on port 3000, use the test scripts) stay, since those have documented failure modes.

Skills

Procedural detail moves into three progressively-disclosed skills, the long ones split across reference files so only the relevant layer loads:

Skill	References
adding-a-feature	page.md, api-endpoint.md
writing-tests	controllers.md, services.md, client.md
verifying-changes	—

Note on .gitignore

.claude was ignored wholesale, so the skills would never have been committed. It now tracks .claude/skills/ and keeps local settings ignored. Easy to revert if you'd rather keep skills local.

Verification

bun run check passes, and the pre-commit hook ran build + check clean. Tests were not run — no PostgreSQL in this environment. The changes are markdown-only plus one .gitignore line, so there's no code risk, but the suite hasn't been executed.

No application code was touched. The post's "examples → interface design" shift is about tool/API design for agent harnesses; applying it here would mean refactoring app code.

---

Generated by Claude Code