docs(claude): slim root CLAUDE.md, relocate detail to sibling files - #2816
Merged
Conversation
The root CLAUDE.md loads into every conversation, so its ~510 lines were paid on every session. Cut it to ~190 lines: removed the derivable JSON Output Format pointer, tightened prose throughout, and pushed task-specific detail down to where the work happens, leaving terse pointers in the root. Relocations (substance preserved, root keeps a pointer): - Testing commands, mock-stub gotcha, web-env setup, shell/PTY nextest SIGTTOU, and codecov investigation -> tests/CLAUDE.md - Doc sync taxonomy, three-context help-text authoring, .gitattributes linguist exemption, config-TOML double-comment -> docs/CLAUDE.md - Plugin layout, Codex no-hooks re-enablement conditions, accepted wt-switch-create tradeoff -> plugins/worktrunk/CLAUDE.md (its back-pointers to the root made self-contained) - Add-a-CLI-command recipe -> src/commands/CLAUDE.md Governing invariants (Data Safety, Command Execution Principles, Project Commands Run Only After Approval, the codecov merge gate, Config Deprecation, accessor naming, Worktree Model) stay in the root, tightened but with their substance intact. Heading anchors referenced by code comments (Plugin Layout, Project Commands Run Only After Approval) are preserved. test_docs_are_in_sync passes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
worktrunk-bot
left a comment
Collaborator
There was a problem hiding this comment.
The PR description audits two preserved heading anchors (Plugin Layout, Project Commands Run Only After Approval) but the case-only changes to two H3 sub-headings turned four more code-comment breadcrumbs into non-verbatim references:
### Network Access→### Network access— quoted insrc/git/repository/config.rs:309("Network Access").### Signal Handling: Ctrl-C Cancels the Current Command→### Signal handling: Ctrl-C cancels the current command— quoted insrc/commands/command_executor.rs:636,src/commands/run_pipeline.rs:263, andsrc/git/error.rs:165(all"Signal Handling").
GitHub anchors are case-insensitive so any URL links still resolve, but the comments are plain-text quotes and a case-sensitive grep would miss. Either restore Title Case on these two headings (matches the stated "preserved anchors" intent) or downcase the quoted text in those four comments — your call. Inline suggestions cover the heading-restoration path; if you prefer the comment-update path, ignore them.
…ings The slimming pass downcased six H3 subheadings to sentence case, an unrequested style drift that also broke four code-comment breadcrumbs quoting the exact titles: "Network Access" (src/git/repository/config.rs) and "Signal Handling" (src/git/error.rs, src/commands/run_pipeline.rs, src/commands/command_executor.rs). Restore Title Case on all six to match the file's house style and the plain-text quotes a case-sensitive grep would otherwise miss. Caught by the automated reviewer on #2816. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
worktrunk-bot
approved these changes
May 19, 2026
The slimming pass added a "Doc sync taxonomy" section to docs/CLAUDE.md that overlapped with the file's existing "Command documentation" area: both said "edit src/cli/mod.rs, not the markdown" and both invoked test_docs_are_in_sync. writing-prose flags this as a patchy edit (same explanation at two detail levels). Consolidate: - Taxonomy stays as the single entry point. Category 1 grows the conceptual-vs-clap distinction (after_long_help carries prose; clap attrs carry usage/options) so it's stated once, here. - Drop "### Editing command docs" (its substance now lives in the taxonomy). - Rename "## Command documentation" -> "## Command page generation" so the section reads as the mechanism details (AUTO-GENERATED markers, non-greedy regex pairing, frontmatter preservation) for category 1 rather than restating the editing flow. - Trim the opener: drop the now-redundant first paragraph and the duplicate "wt <command> --help-page" code block. The taxonomy back-references "Command page generation" for mechanism details; the existing "see Command documentation structure" pointer from Help text authoring still resolves. test_docs_are_in_sync passes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
worktrunk-bot
approved these changes
May 19, 2026
max-sixty
added a commit
that referenced
this pull request
May 19, 2026
#2820) Two small CLAUDE.md follow-ups surfaced while surveying the tree during #2816. - `tests/CLAUDE.md`: one-line forward reference from "Coverage Investigation" to "Coverage in PTY Tests" — explains *why* the PTY section exists (the subprocess `env_clear()` is the link, so it reads as a real prerequisite rather than a generic "see also"). - `src/commands/list/CLAUDE.md` → "Adding New Features": three rhetorical questions all answering "defer to post-skeleton", then a restated "Default answer" line. Collapse to one declarative paragraph. Substance preserved (file I/O and template expansion wait; new columns render a placeholder until data arrives). Docs-only, `+5 / −12`. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
max-sixty
added a commit
that referenced
this pull request
May 20, 2026
… root CLAUDE.md (#2825) Continues the #2816 slimming pass on the root `CLAUDE.md` (which loads into every conversation). Two sections were deliberately left in the root last time as a judgment call; both are specialized — they only matter when touching log-path code or `Repository` git code — so they push down to their code homes, with the root keeping a one-line pointer. **Hook Output Logs → the `HookLog` type docstring in `src/commands/process.rs`.** That enum is already declared "the single source of truth for hook log file paths," and its `# Log file layout` docstring already carried the three path templates and the `sanitize_for_filename` rule. This folds in the three bits the docstring lacked: logs are centralized under the main worktree's `.git/wt/logs/`, rerunning the same op on the same branch overwrites its prior log, and `source` is `user` or `project`. The complementary file-vs-directory categorization stays in `commands::config::state` (its enforcer — `walk_hook_output_files`/`clear_logs` — lives there), now cross-referenced from `HookLog`. **Repository Caching → the `# Caching` module docstring in `src/git/repository/mod.rs`.** That docstring already contained 100% of the root section's substance, so this is a pure root reduction — nothing folded in. Neither heading (`Hook Output Logs`, `Repository Caching`) is quoted in any code comment, so no breadcrumbs dangle. No files under `docs/` or `skills/` are touched, so `test_docs_are_in_sync` is not in play; the `process.rs` change is comment-only and `cargo check` passes. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The root
CLAUDE.mdloads into every conversation, so its ~510 lines were paid on every session. This cuts it to ~190 lines without losing any documented behavior or invariant.Three things happened: derivable/stale content was removed (the JSON Output Format pointer, just a redirect to
wt list --help), prose was tightened throughout, and task-specific detail was pushed down to the siblingCLAUDE.mdthat loads where that work happens — the root keeps a one-line pointer.Relocations (substance preserved at the destination, root keeps a pointer):
mock-stubfiltered-run gotcha, Claude Code web setup, the shell/PTY nextest SIGTTOU suspension, and codecov investigation mechanics →tests/CLAUDE.md.gitattributeslinguist-generated=falseexemption, config-TOML double-comment rule →docs/CLAUDE.mdwt-switch-createtradeoff →plugins/worktrunk/CLAUDE.md(its back-pointers into the root were made self-contained so nothing dangles)src/commands/CLAUDE.mdKept in the root, tightened but substance intact: the governing invariants — Data Safety, the Command Execution Principles (
shell_exec::Cmd, structured output, network policy, signal handling), Project Commands Run Only After Approval (verbatim — the #2806 TOCTOU fix depends on its wording), the codecov merge gate, Config Deprecation, accessor naming, and the Worktree Model.A third commit consolidates the doc-sync explanation in
docs/CLAUDE.md: the new "Doc sync taxonomy" section was overlapping with the file's existing "Command documentation" area on "editsrc/cli/mod.rs" andtest_docs_are_in_sync. Now the taxonomy is the single entry point and "Command page generation" reads as the category-1 mechanism details.Every CLAUDE.md heading quoted in a code comment is preserved verbatim so the breadcrumbs still resolve under a case-sensitive grep:
Plugin Layout(src/commands/config/codex.rs),Project Commands Run Only After Approval(src/commands/hook_plan.rs,src/commands/picker/mod.rs),Network Access(src/git/repository/config.rs), andSignal Handling(src/git/error.rs,src/commands/run_pipeline.rs,src/commands/command_executor.rs). The first push downcased the latter two; the automated reviewer caught it and the second commit restored Title Case across all Command Execution Principles subheadings.test_docs_are_in_syncpasses (docs-only change; no code touched).