docs: split CLAUDE.md into per-directory guides#1846
Merged
Conversation
Add nested CLAUDE.md files that load automatically when working under each language directory, keeping the root file to cross-cutting rules. - rs/CLAUDE.md: crate map, Producer/Consumer model, poll_* plumbing, error handling, config/TOML merge, Version matching, testing. Folds in the root "Version Matching Convention" and "Rust Conventions" sections. - js/CLAUDE.md: package map, signals + Effect reactivity lifecycle, Web Components UI, bun/Biome tooling. Folds in the JS-specific Tooling bullets (TypeScript/bun, Biome, UI, JS async patterns). - py/CLAUDE.md: the moq-ffi vs moq-rs split and the moq public surface. Root CLAUDE.md gains a "Per-Directory Guides" section pointing at each nested file and now holds only universal rules. swift/kt/go are thin wrappers and defer to their READMEs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TSWQ8HdasmrvfCcR9P2QiA
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughThe root 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches✨ Simplify code
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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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 `@rs/CLAUDE.md`:
- Around line 72-79: The docstring comment containing "see `CLAUDE.md`" in
relation to TOML/CLI merge guidance needs to be updated after the documentation
reorganization. Find the comment that references CLAUDE.md for TOML merge/CLI
interaction rules and update it to reference rs/CLAUDE.md instead, ensuring the
external documentation link points to the correct location of the configuration
conventions.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: b7b598ac-a70e-40a6-b94c-ead8fbf097bf
📒 Files selected for processing (4)
CLAUDE.mdjs/CLAUDE.mdpy/CLAUDE.mdrs/CLAUDE.md
The "Config flags + TOML merge" guidance moved from the root CLAUDE.md into rs/CLAUDE.md, so update the three doc comments that reference it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TSWQ8HdasmrvfCcR9P2QiA
The previous run died on an sccache "Connection reset by peer" while compiling a third-party crate, unrelated to this docs-only change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TSWQ8HdasmrvfCcR9P2QiA
When CodeRabbit can't produce a review, the existing rule says to run /review locally. Spell out the follow-through: push high-confidence fixes directly and escalate ambiguous ones by asking first. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TSWQ8HdasmrvfCcR9P2QiA
kixelated
commented
Jun 22, 2026
|
|
||
| ## Workspace layout | ||
|
|
||
| Bun workspaces; members listed in the repo-root `package.json` (not in `js/`). Deps hoist to the repo root `node_modules`, not into `js/`. Run recipes via `just js <recipe>` (see `js/justfile`). The root `CLAUDE.md` lists only 8 packages; there are more. Full set, in dependency order: |
Collaborator
Author
There was a problem hiding this comment.
The root
CLAUDE.mdlists only 8 packages; there are more.
Don't have the root claude.md list them then.
|
|
||
| Reference for the `/rs` Cargo workspace. Universal rules (writing style, no em dashes, Branch Targeting, Cross-Package Sync, Public API Scrutiny, Refactor As You Go, AI Attribution) live in the root `/CLAUDE.md` and are not repeated here. | ||
|
|
||
| Workspace members live in the root `Cargo.toml` (`[workspace]`). `rust-version = "1.85"`, edition 2024 for most crates (moq-gst is 2021). Shared versions/paths are pinned under `[workspace.dependencies]`; new crates should add their dep there and reference it via `{ workspace = true }`. |
Collaborator
Author
There was a problem hiding this comment.
edition 2024 for most crates (moq-gst is 2021)
Can you fix that?
| Layered roughly transport -> container/format -> media -> apps/bindings. | ||
|
|
||
| **Transport / protocol** | ||
| - `moq-net` (lib): the core wire layer. Negotiates `moq-lite` or IETF `moq-transport`. Owns the Broadcast/Track/Group/Frame model and the Producer/Consumer split (see below). Generic over `web_transport_trait::Session` (no concrete QUIC dep). `lite/` and `ietf/` modules are private; `model/`, `error`, `version`, `coding`, `path`, `session`, `client`, `server` are public. |
Collaborator
Author
There was a problem hiding this comment.
Are all of those modules public? Is it even worth mentioning this?
|
|
||
| Bun workspaces; members listed in the repo-root `package.json` (not in `js/`). Deps hoist to the repo root `node_modules`, not into `js/`. Run recipes via `just js <recipe>` (see `js/justfile`). The root `CLAUDE.md` lists only 8 packages; there are more. Full set, in dependency order: | ||
|
|
||
| - `@moq/signals` (`signals/`): reactive core. `Signal`, `Computed`, `Effect`, plus framework adapters at subpaths `./solid`, `./react`, `./dom`. No deps on other workspace packages. Everything below uses it. |
Collaborator
Author
There was a problem hiding this comment.
Can you split these into categories like Rust?
| - **Errors**: `thiserror` with `#[from]` for libraries, `anyhow` (with `.context("...")`, not `.map_err(|_| anyhow!())`) for binaries. Always `#[non_exhaustive]` on public error enums (e.g. `moq-net/src/error.rs:6`, `moq-ffi/src/error.rs:4`, `moq-loc/src/lib.rs:55`). Use `#[error(transparent)]` + `#[from]` for wrapped foreign errors (see `moq-token/src/error.rs`). | ||
| - **Config + TOML merge**: any `#[arg]` field on a TOML-loadable config must be `Option<T>`, never a bare `bool`/`String`/etc. The TOML->CLI merge re-applies clap defaults and silently clobbers TOML values for bare fields. See `moq-relay/src/config.rs` and its regression tests (`cli_does_not_clobber_toml_*`, around line 126); add such a test for any new flag. | ||
| - **Config structs**: `#[derive(Parser, Serialize, Deserialize)]` with `#[serde(deny_unknown_fields, default)]`, clap `#[arg(long, env = "MOQ_...")]`, nested configs via `#[command(flatten)]`, and an `.init()`/`.load()` method that produces the live object. Add `#[non_exhaustive]` + `Default`/constructor to configs consumers build (per root Public API Scrutiny). | ||
| - **Unwrapping**: prefer `if let Some(v) = x { ... }` / `let Some(v) = x else { ... };` over a `match` whose only job is to bind the inner value. Keep `match` when both arms do real work. |
Collaborator
Author
There was a problem hiding this comment.
Add a note that match Option can usually be simpler as if let
|
|
||
| Key architectural rule: The CDN/relay does not know anything about media. Anything in the `moq` layer should be generic, using rules on the wire on how to deliver content. | ||
|
|
||
| ## Project Structure |
Collaborator
Author
There was a problem hiding this comment.
Is this worth having, especially if out of date?
Collaborator
Author
There was a problem hiding this comment.
I think a section about moq-ffi, and how it powers python/kotlin/go/swift, would be good?
Review-driven changes to the CLAUDE.md guides: - Trim the root Project Structure to a top-level map. Per-crate/package detail lives in the nested guides and was rotting in root. - Add a Language Bindings section: rs/moq-ffi is the single UniFFI core powering py/swift/kt/go, with libmoq exposing it as a C staticlib. - Move the py release/versioning detail into py/CLAUDE.md (root no longer carries it, and py/CLAUDE.md no longer points back at root for it). - Categorize the js/CLAUDE.md package list by role, mirroring rs. - Fix rs/CLAUDE.md: moq-net submodules are private and re-exported flat from the crate root, not public. - Add a Rust convention: prefer kio over tokio sync primitives; a channel or watch carrying a single value is a code smell. Also bump moq-gst from edition 2021 to 2024 (it was the only crate not on 2024) and drop the exception note in rs/CLAUDE.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TSWQ8HdasmrvfCcR9P2QiA
Collaborator
Author
|
Addressed the review in
(Written by Claude) Generated by Claude Code |
The edition 2024 bump changes rustfmt's import ordering (lowercase items sort after types), so cargo fmt rewrites this import group. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TSWQ8HdasmrvfCcR9P2QiA
The previous push did not fire a pull_request workflow run, so no required check was created and auto-merge is stuck. Nudge a fresh synchronize event. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TSWQ8HdasmrvfCcR9P2QiA
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.
Summary
Splits the monolithic root
CLAUDE.mdinto per-directory guides that load automatically when an agent works under each language directory. The root file now holds only cross-cutting rules; language-specific detail (and a richer module map than the root previously had) lives next to the code it describes.Why nested files, not
@imports or skills: nestedCLAUDE.mdis the only mechanism that loads conditionally by location, so a Rust-only session no longer carries JS reactivity rules and vice versa.@importwould load eagerly (no savings); skills are for actions (a pre-PR self-review skill is a sensible follow-up, but that is a separate concern from this reference knowledge).New nested guides
rs/CLAUDE.md- Cargo workspace: crate map (includingkio,moq-json,moq-loc,moq-msf,moq-videothat the root tree omitted), Producer/Consumer model,poll_*plumbing, error handling, config/TOML merge, Version matching, binary setup, testing.js/CLAUDE.md- bun workspace: package map grouped by role (Foundation / Transport / Container formats / Media / Apps), the signals + Effect reactivity model and its lifecycle/cleanup rules, the Web Components UI pattern, bun/Biome tooling.py/CLAUDE.md- themoq-ffi(generated bindings) vsmoq-rs(ergonomic wrapper) split, themoqpublic surface, and the release/versioning mechanics for both PyPI distributions.Root
CLAUDE.mdchangesrs/moq-ffiis the single UniFFI core powering py/swift/kt/go, withrs/libmoqexposing it as a C staticlib.rs/CLAUDE.md).js/CLAUDE.md); kept the cross-cutting ones (just, Nix, Local-first, CI)./reviewlocally and act on the findings (push the high-confidence fixes, escalate ambiguous ones by asking first).swift/,kt/,go/are thin wrappers mirrored to external repos, so they defer to their existingREADME.mds.Review-driven fixes
rs/CLAUDE.md: added a convention to preferkioovertokio::syncprimitives (a channel orwatchwith a single value is a code smell); corrected themoq-netnote (submodules are private and re-exported flat, not public).moq-relay/src/config.rs,moq-relay/src/stats.rs,moq-bench/src/config.rs) now referencers/CLAUDE.md, where the config/TOML-merge guidance moved.rs/moq-gstfrom edition 2021 to 2024 (it was the only crate not on 2024) with the rustfmt import reorder that edition 2024 requires.Public API changes
None. The only non-docs change is the
moq-gstedition bump (no behavioral or API change).Test plan
—is the literal one inside the "no em dashes" rule).cargo fmt -p moq-gstclean; CI buildsmoq-gston edition 2024 in Nix.Follow-ups (not in this PR)
pre-submit self-reviewskill that leans on the Cross-Package Sync table and public-API/breaking-change rules.justcommands and "use just" are repeated across Common Commands / Development Tips / Testing Approach / Workflow).(Written by Claude)
🤖 Generated with Claude Code
Generated by Claude Code