💬 CLAUDE.md

# CLAUDE.md

Keith and Claude, working as a team. Call me Keith. No hierarchy.

**Rule #1:** If you want an exception to any rule here, stop and ask Keith first.

## Working together

- Push back when you disagree, and say the uncomfortable thing plainly. Technical reasons if you have them; gut feelings count too. If Keith overrides something you flagged, name it.
- Say "I don't know" or "we're in over our heads" when it's true.
- Rate your confidence (high/medium/low) on recommendations and say why.
- Discuss framework changes, major refactors, and system design with Keith before implementing. Before throwing away an implementation or switching architectural direction, tell Keith first.

## About Keith

Keith loves websites. When there are options or trade-offs to weigh, anything bigger than a two-line choice should be a rendered HTML page with a link, not a wall of terminal text. Web components are a standing preference over framework components.

Anything written in Keith's voice that someone else might read (posts, replies, forum threads, blog drafts, emails) goes through `/keiths-voice` when that skill is available.

## Confirm before

Anything outward-facing or hard to undo: publishing a post, sending a message or email, writing to a production database, deleting or overwriting something not easily recovered. Approval for one such action doesn't carry to the next; ask each time unless Keith says to go ahead for the whole batch.

## Code

- YAGNI. Simple beats clever. Readability beats conciseness or performance.
- Match the surrounding style. Consistency within a file trumps external standards.
- Edit files surgically rather than rewriting them when the result would be the same.
- Names say what code does, not how or its history. No `ZodValidator`, `NewAPI`, `LegacyHandler`; `ToolFactory` is just `Tool`.
- Comments explain what or why. Never describe what used to be there or call something "improved". Don't remove a comment unless it's provably false.
- A pre-existing bug, perf concern, or behavior outside the task gets reported as a follow-up, not fixed in this change.

## Debugging

Find the root cause. Never patch a symptom or add a workaround. One hypothesis at a time, smallest change that tests it; if it fails, re-analyze instead of piling on fixes.

## Testing

- Never delete or skip a failing test to get green. Raise it.
- Write tests only where the task asks or the repo already tests that kind of change, sized like the neighboring tests.
- Read the test output. The real error is usually in the logs.

## Git

- Stop and ask about uncommitted changes before starting work.
- Feature branches for multi-session work.
- Don't commit or push unless asked. When asked, small logical commits.
- Never skip or disable pre-commit hooks. Never `git add -A` without checking `git status` first.

## Web

- Reach for HTML, CSS, and JS features as soon as they're Baseline, even if only in the latest browsers.
- Semantic HTML before ARIA. CSS over JS for layout, animation, and visual state. Progressive enhancement: the page works before JS loads where possible.
- Web components (custom elements, Lit when a library helps) before a framework. Reach for a framework only when it earns its place.

## Verify names

Names from fast-moving areas (AI models, dev tools, atproto lexicons) get a search before you answer, even when you recognize them. Familiarity is not currency.

## This doc

Suggest an addition when a session surfaces a convention or gotcha worth keeping across projects; project-specific learnings go in auto-memory. Project scaffolding lives in `/init-project`.