docs: cut CLAUDE.md to the rules it is for (#256) #262

2026-09-26T19:48:44Z

yonlu commented

2026-09-26 19:48:44 +00:00

CLAUDE.md had grown to 4,046 lines, ~3,300 of them per-component write-ups (why a breakpoint is 500px, why a cap is a quarter, what a spec once missed). Every agent session loaded all of it, and the rules that apply to every change were buried among decisions that apply to one.

Those write-ups were already duplicated as comments beside the code they describe — every issue number they cite also appears in a code comment — so they are deleted rather than moved. CLAUDE.md is now ~375 lines: the tracker workflow, the commands, the verification tiers, and a set of broad engineering rules (one definition/many readers, data, work and persistence, events, platform tags, frontend structure, layout and input, accessibility, CI and release), each pointing at where its example lives.

What is in it

Commit	Issue
docs: cut CLAUDE.md to the rules it is for	#256

docs: only, so semantic-release will cut nothing.

Also in the commit:

.planning/NOTES.md gains three declined decisions that were recorded nowhere else (touch-action: manipulation, no "Go to Genre", no phone scrim gutter).
main.go, e2e/specs/phone-search.spec.ts and frontend/test/components/progress-line.test.ts no longer cite CLAUDE.md sections by name — comment-only changes.
The #258 lesson (a bound parameter against a BLOB column; a batch walk that must prove it advanced) is folded into the new rules, so this conflicts with fix/258-artifact-blob-cursor on CLAUDE.md — resolve by keeping this branch's CLAUDE.md.

Found along the way and filed rather than fixed: #257 (NOTES.md entries the code has since contradicted).

Verified locally

Every file, symbol and test name the new CLAUDE.md cites exists in the tree (scripted check).
make skill-check — 48 documented make targets, all present (also passes under #228's newer script).
scripts/commit-check.sh — well-formed.
gofmt -l main.go — clean.
Not run: make lint, make test, make ui-test, make e2e. The only code changes are three comments; CI runs the rest.

Closes #256.

🤖 Generated with Claude Code

CLAUDE.md had grown to 4,046 lines, ~3,300 of them per-component write-ups (why a breakpoint is 500px, why a cap is a quarter, what a spec once missed). Every agent session loaded all of it, and the rules that apply to every change were buried among decisions that apply to one. Those write-ups were already duplicated as comments beside the code they describe — every issue number they cite also appears in a code comment — so they are deleted rather than moved. CLAUDE.md is now ~375 lines: the tracker workflow, the commands, the verification tiers, and a set of broad engineering rules (one definition/many readers, data, work and persistence, events, platform tags, frontend structure, layout and input, accessibility, CI and release), each pointing at where its example lives. **What is in it** | Commit | Issue | |---|---| | docs: cut CLAUDE.md to the rules it is for | #256 | `docs:` only, so semantic-release will cut **nothing**. Also in the commit: - `.planning/NOTES.md` gains three declined decisions that were recorded nowhere else (`touch-action: manipulation`, no "Go to Genre", no phone scrim gutter). - `main.go`, `e2e/specs/phone-search.spec.ts` and `frontend/test/components/progress-line.test.ts` no longer cite CLAUDE.md sections by name — comment-only changes. - The #258 lesson (a bound parameter against a BLOB column; a batch walk that must prove it advanced) is folded into the new rules, so **this conflicts with `fix/258-artifact-blob-cursor` on CLAUDE.md** — resolve by keeping this branch's CLAUDE.md. Found along the way and filed rather than fixed: #257 (NOTES.md entries the code has since contradicted). **Verified locally** - Every file, symbol and test name the new CLAUDE.md cites exists in the tree (scripted check). - `make skill-check` — 48 documented make targets, all present (also passes under #228's newer script). - `scripts/commit-check.sh` — well-formed. - `gofmt -l main.go` — clean. - **Not run**: `make lint`, `make test`, `make ui-test`, `make e2e`. The only code changes are three comments; CI runs the rest. **Closes** #256. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

yonlu added 1 commit 2026-09-26 19:48:45 +00:00

docs: cut CLAUDE.md to the rules it is for

CI / check (push) Skipped

CI / e2e (push) Skipped

CI / check (pull_request) Successful in 4m22s

Details

CI / e2e (pull_request) Successful in 14m24s

Details

1997276def

CLAUDE.md had grown to 4,046 lines, ~3,300 of them per-component
write-ups: why a breakpoint is 500px, why a cap is a quarter, what a
spec once missed. Every session loaded all of it, and the rules that
apply to every change were buried among decisions that apply to one.

Those write-ups were already duplicated as comments beside the code
they describe -- every issue number they cite also appears in a code
comment -- so they are deleted rather than moved. What is left is the
tracker workflow, the commands, the verification tiers and a set of
broad engineering rules distilled from them, each pointing at where
its example lives. Three declined decisions recorded nowhere else go
to NOTES.md, and three code comments that cited CLAUDE.md sections by
name no longer do.

Closes #256

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

yonlu referenced this pull request

2026-09-26 20:02:36 +00:00

fix(explore): merge the catalog artifact in its own mbid encoding (#258) #259

yonlu referenced this pull request

2026-09-27 01:03:07 +00:00

Batch: explore catalog + UI, Go 1.26, Soulseek downloads, CI fixes #273

yonlu closed this pull request

2026-09-27 01:44:01 +00:00