Skip to content

docs: split CLAUDE.md, keep a short must-not-regress list - #142

Merged
Maxaubert merged 2 commits into
mainfrom
docs/claude-md-split
Oct 9, 2026
Merged

Maxaubert merged 2 commits into
mainfrom
docs/claude-md-split

Conversation

@Maxaubert

Copy link
Copy Markdown
Owner

What

Owner decision: "Split, keep a short rules list".

  • docs/regression-rules.md: the "Rules that must not regress" section, moved verbatim (an <a id> anchor added to each top-level rule; "see THE MENU FITS" now links to its new home).
  • docs/two-apps.md: the "This repo is the terminal of TWO apps" section, moved verbatim (anchors added on the rules CLAUDE.md links; the core/README.md link made relative to docs/).
  • CLAUDE.md: 916 -> 167 lines. What the repo is, a six-line two-apps summary linking into docs/two-apps.md, Scope (unchanged), the 15 most important rules as one-liners each linking to its full entry, Layout, Build/test/release and Style (unchanged), and a new Docs section.
  • src/renderer/src/termHost.ts: a comment that pointed at CLAUDE.md for the theme/ground/indicator decisions now points at docs/regression-rules.md (comment only).

Rules kept as one-liners (most important first)

  1. What reaches a shell is inert until the user acts
  2. The only command the app writes into a shell is the agent resume
  3. Main installs only what main offered
  4. Renderer is sandboxed
  5. Bundled ConPTY
  6. The quit waits for every shell to be gone
  7. Closing the window quits; closing the last tab does not
  8. The indicator is the agent's own word
  9. Claude Code's hooks are its word, above the title
  10. Typing is heard on onKey, never onData
  11. Cells are not characters, and a key is its physical key
  12. titleBarStyle: 'hidden', never frame: false; material before colour
  13. ConPTY sends nothing on a resize
  14. The terminal panel paints the ground; xterm's canvas is clear
  15. The theme drives the chrome

Verification

  • Script check: stripping the added anchors from the two new docs reproduces the original sections byte for byte.
  • Every relative link and #anchor in the three files resolves.
  • No em-dashes. prettier --check passes on CLAUDE.md and termHost.ts; the two moved docs are left exactly as the original text was formatted (the original CLAUDE.md did not pass prettier either).
  • Docs and a comment only: no version bump, no core change.

🤖 Generated with Claude Code

Maxaubert and others added 2 commits October 9, 2026 22:43
Move the measured rules verbatim to docs/regression-rules.md and the
two-apps background verbatim to docs/two-apps.md, each top-level rule
with an anchor. CLAUDE.md (916 -> 167 lines) keeps the repo summary,
scope, the 15 most important rules as linked one-liners, layout,
build/test/release, style and a Docs section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Maxaubert
Maxaubert merged commit 251b23e into main Oct 9, 2026
2 checks passed
@Maxaubert
Maxaubert deleted the docs/claude-md-split branch October 9, 2026 21:42
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.

1 participant