Repository navigation
docs: compact CLAUDE.md/AGENTS.md to load-bearing rules - #5606
Closed
lawrencecchen wants to merge 2 commits into
Closed
lawrencecchen wants to merge 2 commits into
lawrencecchen wants to merge 2 commits into
Conversation
…E.md Move the verbatim Swift package/architecture conventions and the sidebar extension-point how-to into self-contained in-repo docs. CLAUDE.md will point to these and keep only the load-bearing summary, so the per-task agent context stops carrying ~180 lines that apply only to Packages/ work and are already enforced by the review bots. No content changed; this commit only relocates it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
533 -> 313 lines. CLAUDE.md (== AGENTS.md) is loaded into every agent's context on every task, so it should hold constraints agents would get wrong, not reference essays that apply to a minority of tasks. What moved (content preserved verbatim in docs/, summarized in-file): - Swift package/architecture, file-org, DocC, package-design, testability, modern-concurrency, and test-framework sections -> docs/swift-architecture.md (~160 lines). Replaced by a load-bearing summary + pointer. - Sidebar extension-point how-to -> docs/sidebar-extension-point.md. What was compressed in place (every command/fact kept): - Xcode toolchain: 3 paragraphs -> 1, same pin/objectVersion/CI facts. - Local dev: deduped the reload.sh explanation (repeated 4x) into one; kept every script (reload/reloadp/reloads/reload2), the compile-only xcodebuild, the cmux-debug-cli helper, and the file:// link block verbatim (correct for external contributors, who have no Tag Opener). - Debug event log: kept the impl/#if-DEBUG contract; replaced the exhaustive event-name catalog with a grep pointer. Nothing load-bearing dropped; the review bots still enforce the Swift rules. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThis PR consolidates and expands development guidance across CLAUDE.md and two new documentation files. Local build and debug instrumentation guidance in CLAUDE.md is refined, a new spec documents ExtensionKit sidebar extension point isolation for tagged builds, and a comprehensive Swift architecture conventions document is introduced. CLAUDE.md's architecture policies are condensed to reference external specs instead. ChangesDevelopment Documentation Consolidation
Estimated Code Review Effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly Related PRs
Poem
Important Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (2 errors, 1 inconclusive)
✅ Passed checks (16 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
Greptile SummaryThis PR compresses
Confidence Score: 5/5Safe to merge — documentation reorganization only, no runtime or app behavior touched. All three files are documentation. Content from CLAUDE.md is either preserved verbatim in the new docs/ files or kept in compressed form with accurate pointers. Every script command, build rule, and architecture constraint is reachable from CLAUDE.md. The review bots continue to enforce the full Swift rules via .github/review-bot-rules/ regardless of what is summarized in CLAUDE.md. No files require special attention. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Agent / CLAUDE.md loaded on every task] --> B{Task type?}
B -->|Swift/Package work| C[Read docs/swift-architecture.md\n164 lines — full rules]
B -->|Sidebar extension tagging| D[Read docs/sidebar-extension-point.md\n18 lines — full mechanics]
B -->|All other tasks ~95%| E[CLAUDE.md only\n313 lines — summaries + commands]
C --> F[Review bots enforce via\n.github/review-bot-rules/]
D --> F
E --> G[No wasted context window]
Reviews (1): Last reviewed commit: "docs: trim CLAUDE.md to load-bearing rul..." | Re-trigger Greptile |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Line 76: Update the GhosttyKit rebuild command to include the missing flag so
it reads the canonical form: add the -Demit-macos-app=false option to the
existing Zig build invocation (the command that currently contains "zig build
-Demit-xcframework=true -Dxcframework-target=universal -Doptimize=ReleaseFast")
to prevent unintentionally building/installing Ghostty.app as a side effect.
In `@docs/swift-architecture.md`:
- Line 161: The documentation line allowing "local runs" alongside CI filtering
conflicts with the repo policy; update the sentence that references test tagging
(e.g., `@Test`(.tags(.something)) and `@Suite`) to remove any mention of running
tests locally and explicitly state that tags are used for CI/VM-based selective
runs only (e.g., via GitHub Actions or the VM), ensuring the doc aligns with the
"Never run tests locally" guideline.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 15d36e9a-a4cb-4030-b9c2-a663f6605093
📒 Files selected for processing (3)
CLAUDE.mddocs/sidebar-extension-point.mddocs/swift-architecture.md
| When rebuilding GhosttyKit.xcframework or cmuxd for release/bundling, always use Release optimizations: | ||
|
|
||
| ```bash | ||
| cd ghostty && zig build -Demit-xcframework=true -Dxcframework-target=universal -Doptimize=ReleaseFast |
There was a problem hiding this comment.
Add -Demit-macos-app=false to the GhosttyKit rebuild command.
The documented command currently omits the required -Demit-macos-app=false flag, which can unintentionally build/install Ghostty.app as a side effect and add avoidable build time. Please update the command to the canonical form.
Suggested diff
-cd ghostty && zig build -Demit-xcframework=true -Dxcframework-target=universal -Doptimize=ReleaseFast
+cd ghostty && zig build -Demit-xcframework=true -Demit-macos-app=false -Dxcframework-target=universal -Doptimize=ReleaseFastBased on learnings, the canonical GhosttyKit command requires -Demit-macos-app=false to prevent unintended app build side effects.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` at line 76, Update the GhosttyKit rebuild command to include the
missing flag so it reads the canonical form: add the -Demit-macos-app=false
option to the existing Zig build invocation (the command that currently contains
"zig build -Demit-xcframework=true -Dxcframework-target=universal
-Doptimize=ReleaseFast") to prevent unintentionally building/installing
Ghostty.app as a side effect.
Source: Learnings
| - **Migration guide when touching an existing XCTest test.** Convert in place: `XCTestCase` subclass becomes a `@Suite struct` (or `final class` if you need a reference type); each `func testFoo()` becomes `@Test func foo()`; `XCTAssertEqual(a, b)` becomes `#expect(a == b)`; `XCTAssertTrue(cond)` becomes `#expect(cond)`; `XCTUnwrap(x)` becomes `try #require(x)`; `XCTFail("msg")` becomes `Issue.record("msg")`. `setUp()` becomes `init()` on the suite; `tearDown()` becomes `deinit`. Async setup is `async init()`. Do not bulk-rewrite untouched tests; migrate incrementally as a side effect of editing the file. | ||
| - **Parameterized tests** use `@Test(arguments: [...])`. Prefer this over duplicate test methods. | ||
| - **Parallelization and shared state.** Swift Testing runs tests in parallel by default, including across suites. If a suite genuinely needs ordering or guards shared mutable state, annotate it with `.serialized` instead of adding locks or sleeps. | ||
| - **Tags** with `@Test(.tags(.something))` (or on a `@Suite`) let CI and local runs filter selectively. |
There was a problem hiding this comment.
Remove the “local runs” guidance to avoid policy contradiction.
Line 161 conflicts with the repo policy that tests should not be run locally; keeping both instructions will cause operator confusion.
As per coding guidelines: “Never run tests locally. All tests (E2E, UI, python socket tests) run via GitHub Actions or on the VM.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/swift-architecture.md` at line 161, The documentation line allowing
"local runs" alongside CI filtering conflicts with the repo policy; update the
sentence that references test tagging (e.g., `@Test`(.tags(.something)) and
`@Suite`) to remove any mention of running tests locally and explicitly state that
tags are used for CI/VM-based selective runs only (e.g., via GitHub Actions or
the VM), ensuring the doc aligns with the "Never run tests locally" guideline.
Source: Coding guidelines
lawrencecchen
added
the
stale-revisit
This branch was successfully deployed
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.
What
Compacts
CLAUDE.md(the fileAGENTS.mdsymlinks to) from 533 → 313 lines by moving reference material into self-contained in-repo docs and deduplicating repeated prose. No load-bearing rule is dropped.The symlink
AGENTS.md -> CLAUDE.mdis unchanged.Why
CLAUDE.md/AGENTS.mdis pasted into every agent's context window on every task. It should carry constraints an agent would otherwise get wrong, not reference essays that apply to a minority of tasks. Today ~180 of the 533 lines are the Swift package/architecture guidance, which only matters when a task extracts aPackages/module and is already enforced by the review bots (Codex, CodeRabbit, Greptile). For the other ~95% of tasks (bug fixes, UI tweaks, CLI work) it is dead weight crowding out the rules that do apply.What moved (content preserved verbatim in
docs/, summarized in-file)docs/swift-architecture.md(~164 lines, verbatim).CLAUDE.mdkeeps a load-bearing summary + pointer. This also fixes a real gap: the old in-file pointer to hq'sdocs/cmux-refactor-audit/blueprint/is unfollowable for an external contributor; the new doc is the canonical in-repo copy.docs/sidebar-extension-point.md.What was compressed in place (every command/fact kept)
objectVersion = 60/ CI-enforcement facts.reload.shbehavior was explained four separate times; merged into one. Kept every script (reload/reloadp/reloads/reload2), the compile-onlyxcodebuildinvocation, thecmux-debug-clihelper, and thefile://link block verbatim (deliberately not redirected to hq's Tag Opener, which externalmanaflow-ai/cmuxcontributors do not have).#if DEBUGcontract; replaced the exhaustive event-name catalog with agrep cmuxDebugLogpointer (the catalog is regenerable from code, not a rule).Conservation
Every original
##section is either kept in-file or moved to a pointed-to in-repo doc:CLAUDE.mddocs/swift-architecture.md(summary + pointer in-file)docs/sidebar-extension-point.md(pointer in-file)Two commits so the move is reviewable: commit 1 adds the docs (verbatim relocation), commit 2 trims
CLAUDE.md.Meta-only change; no runtime/app behavior touched.
🤖 Generated with Claude Code
Need help on this PR? Tag
/codesmithwith what you need. Autofix is disabled.Note
Low Risk
Documentation-only reorganization; no application code, build scripts, or runtime behavior changes.
Overview
Shrinks
CLAUDE.md(and theAGENTS.mdsymlink) so agent context stays lean: long Swift/package guidance and sidebar extension mechanics move intodocs/swift-architecture.mdanddocs/sidebar-extension-point.md, whileCLAUDE.mdkeeps a short load-bearing summary plus links.In-file sections are tightened without dropping commands or constraints—Xcode toolchain, local dev (
reload.sh, tagged builds,file://app links,cmux-debug-cli), and debug event log (catalog replaced with agrep cmuxDebugLogpointer). The former multi-section Swift architecture, concurrency, testability, and test-framework essays are consolidated behinddocs/swift-architecture.mdso external contributors get an in-repo canonical copy instead of an unfollowable hq blueprint link.Reviewed by Cursor Bugbot for commit a375e5d. Bugbot is set up for automated code reviews on this repo. Configure here.
Summary by cubic
Compacted CLAUDE.md/AGENTS.md by moving long-form Swift architecture and sidebar extension docs into repo docs while keeping all load‑bearing rules; file size drops 533 → 313 lines. No runtime changes.
docs/swift-architecture.md(CLAUDE.md now has a short summary + pointer).docs/sidebar-extension-point.md.reload.shand helpers), and debug event log (kept implementation + grep pointer). SymlinkAGENTS.md -> CLAUDE.mdremains unchanged.Written for commit a375e5d. Summary will update on new commits.
Summary by CodeRabbit
Note: This release contains documentation-only updates with no visible changes to end-user functionality or features.