Skip to content

Split CLAUDE.md into agent rules and a CONTRIBUTING guide - #42

Open
Travus wants to merge 1 commit into
mainfrom
feat/36-docs-split
Open

Split CLAUDE.md into agent rules and a CONTRIBUTING guide#42
Travus wants to merge 1 commit into
mainfrom
feat/36-docs-split

Conversation

@Travus

@Travus Travus commented Aug 9, 2026

Copy link
Copy Markdown
Owner

Closes #36.

CLAUDE.md was 663 lines and mixed rules an agent must obey with the arguments behind
them. It is now 441 lines / 3,626 words, down from 663 / 5,967 — about 40% smaller.

Three audiences, three files

  • CLAUDE.md — agent rules. States the rule; the argument lives in the code comment
    next to what it governs.
  • CONTRIBUTING.md — new. Setup, building, testing, adding a module, PR expectations,
    and the by-hand deb/AppStream verification.
  • README.md — unchanged in purpose, but its CI section was stale.

Deleted from CLAUDE.md, already documented next to the code

Rule Now sole copy at
2-second chord timeout chords.ts:61-70
900ms recording wait ShortcutsDialog.tsx:24-30
Typo-tolerance gating, best-window distance search.ts:1-16
Palette remembers query, not row ActionPalette.tsx:14-19
· meta separator abilities.ts:15-19

Deleted outright: the "cite the book you are most likely to own" convention, which
governs data packs rather than anything shipped from this repo. The rule survives in
abilities.ts, where pack authors writing against this shape will actually see it.

Kept as one line each: Ctrl+X reserved on macOS, reference lists searching names only,
sequences left out of the native accelerator column, presets replacing wholesale.

Refiling

~150 lines of packaging documentation — the portable exe lock, Linux icons, deb
descriptions, AppStream metainfo, macOS cross-build — sat under ### The action palette, a third-level heading inside ## Keybindings. It now has its own
## Packaging and distribution section. The panel-clipping rule moved to
## Rendering, and search to ## Search.

The comment pass found little to cut

chords.ts 48%, shortcuts.ts 40%, search.ts 39%, palette.ts 35% — essentially
unchanged. The duplication was real but it was resolved by deleting CLAUDE.md's side;
those comments are now the only copy of that reasoning, and cutting them to hit a
percentage would delete what this PR deliberately preserved. Two genuine edits:
shortcuts.ts lost a paragraph of history about a table that no longer exists, and
abilities.ts lost a See CLAUDE.md pointer that this PR made dangle.

README fixes that belonged to #35

Found while checking for dangling references — the CI section still documented
package.yml, deleted in #35, and the --audit-level=critical gate, changed in #35. My
miss there; corrected here along with a pointer to CONTRIBUTING.md.

Verification

npm run check clean — format, lint, typecheck, 125 tests. No remaining references to
package.yml, audit-level=critical, or CLAUDE.md sections that no longer exist.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Split CLAUDE.md into agent rules and CONTRIBUTING

1 participant