map-project-monorepo
Skill15 starsChanged 8 months agoApache-2.0View on GitHub
Scan a Cargo workspace or package monorepo and generate/update per-member CLAUDE.md files. Each member directory gets a focused, self-contained CLAUDE.md with real exported surface, key files, dependencies, wiring points, and conventions. Run after coding sessions, refactors, or crate/package additions to keep the AI context map current.
In this repository63 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-browserSkill
- ast-grepSkill
- branch-review-before-prSkill
- browse-qaSkill
- browser-useSkill
- browseSkill
- bugfixSkill
- build-dmgSkill
- claude-reviewSkill
- codemapSkill
- code-simplifySkill
- codex-reviewSkill
- commitSkill
- cost-estimateSkill
- create-prSkill
- find-agentsSkill
- find-bugsSkill
- frontend-design-ui-uxSkill
- git-merge-expertSkill
- git-merge-expert-worktreeSkill
- kiro-reviewSkill
- laravel-filamentSkill
- laravelSkill
- lokeiSkill
- map-projectSkill
- nextjsSkill
- plan-founder-reviewSkill
- plan-to-task-list-with-dagSkill
- pr-retroSkill
- run-parallel-agents-feature-buildSkill
- run-parallel-agents-feature-debugSkill
- rustSkill
- secretsSkill
- startSkill
- update-agent-learningsSkill
- update-claude-learningsSkill
- update-claude-settingsSkill
- update-skill-learningsSkill
- ast-grepSkill
- branch-review-before-prSkill
- codemapSkill
- code-simplifySkill
- commitSkill
- cost-estimateSkill
- create-prSkill
- find-bugsSkill
- frontend-design-ui-uxSkill
- git-merge-expertSkill
- git-merge-expert-worktreeSkill
- map-project-monorepoSkill
- map-projectSkill
- plan-founder-reviewSkill
- plan-to-task-list-with-dagSkill
- pr-retroSkill
- run-parallel-agents-feature-buildSkill
- run-parallel-agents-feature-debugSkill
- startSkill
- update-agent-learningsSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 9 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Before writing ANY per-crate CLAUDE.md, you ABSOLUTELY MUST complete Phase 1 discovery.
- Distinctive: line 14
If the CLAUDE.md is incomplete, Claude has NO context for that crate.
- Distinctive: line 21
Before writing ANY documentation:
- Very specific: line 151
Document the surface that consumers actually reach first.
- Distinctive: line 173
Create a wiring inventory:
- Distinctive: line 180
Rule: if a future code change would require touching a file to make new functionality reachable, that file belongs in the member CLAUDE.md.
- Distinctive: line 203
Do not invent usage snippets.
- Distinctive: line 207
Use the same phases but with Node tooling:
- Distinctive: line 223
Before proceeding, you MUST have:
- Distinctive: line 241
Every per-crate CLAUDE.md MUST have:
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<EXTREMELY-IMPORTANT>
Before writing ANY per-crate CLAUDE.md, you **ABSOLUTELY MUST** complete Phase 1 discovery.SKIPPING DISCOVERY = INCOMPLETE PER-CRATE DOCS = CLAUDE SEARCHING BLINDLY
This is not optional. Each sub-directory CLAUDE.md must be self-contained.
Claude lazy-loads these files — they ONLY load when Claude touches files in that directory.
If the CLAUDE.md is incomplete, Claude has NO context for that crate.
</EXTREMELY-IMPORTANT>
Update CLAUDE.md for Workspace
MANDATORY FIRST RESPONSE PROTOCOL
Before writing ANY documentation:
- ☐ Detect project type: Cargo workspace (
Cargo.tomlwith[workspace]) or Node monorepo (package.jsonwithworkspaces) - ☐ Discover all member crates/packages
- ☐ For each, identify actual exported/public surface, not just raw
puborexport - ☐ Map inter-member dependencies
- ☐ Identify key files AND hidden wiring points (crate roots, barrels, manifests, startup hooks, registries, routers)
- ☐ Identify which members have tests, benchmarks, and runtime entry points
- ☐ Announce: "Generating CLAUDE.md for X crates/packages, targeting 10/10"
Writing per-crate docs without discovery = guaranteed gaps. Phase 1 is NON-NEGOTIABLE.
Overview
In a monorepo/workspace, Claude Code lazy-loads subdirectory CLAUDE.md files — they only load when Claude touches files in that directory. Sibling crates never see each other's CLAUDE.md. This means each per-crate CLAUDE.md must be self-contained: everything Claude needs to work effectively in that crate, right there.
This skill generates a focused CLAUDE.md for every workspace member directory, then simplifies the root CLAUDE.md by pushing per-crate detail down to where Claude actually needs it.
Core principle: Detail lives where it's used. Root stays lean. Crates are self-contained.
Quality target: 10/10 — Claude should implement features correctly on first attempt in ANY crate.
Critical refinement: map the real public surface and the hidden wiring surface. A member can look "documented" while still being incomplete if the docs miss:
- root export files (
src/lib.rs,mod.rs,src/index.ts, barrel files) - package or crate manifests (
Cargo.toml,package.json, exports maps, feature flags) - startup/bootstrap files
- router/registry/plugin registration points
- feature-gated modules that affect what is actually reachable
How Claude Code Loads Subdirectory CLAUDE.md
| Behavior | Detail |
| Lazy loading | crates/hgdb-storage/CLAUDE.md loads ONLY when Claude reads/writes files under crates/hgdb-storage/ |
| No cross-loading | Working in crates/hgdb-storage/ does NOT load crates/hgdb-sql/CLAUDE.md |
| Root always loads | Root CLAUDE.md loads at startup for every session |
| Hierarchy | Instructions from parent CLAUDE.md are inherited (root applies everywhere) |
Implication: Per-crate CLAUDE.md must include everything Claude needs for that crate. Don't assume root-level detail will be available — keep root lean, push detail down.
Context Budget
| Component | Max Lines | Rationale |
| Root CLAUDE.md | 300 | Always loaded — keep it to project-wide info only |
| Per-crate CLAUDE.md | 50-200 | Lazy-loaded per directory, focused on that crate |
When to Use
- After workspace refactor: Crates added, removed, or responsibilities shifted
- After coding session: New public API, changed dependencies
- Claude searches blindly: Reading 10 files across 5 crates to find one function
- Periodic refresh: User asks to update workspace docs or sync CLAUDE.md files
Phase 1: Workspace Discovery (MANDATORY)
Gate: Complete inventory before writing ANY per-crate CLAUDE.md.
For Rust Cargo Workspaces
Step 1: Find All Crates
# List all workspace members
grep -A 100 '^\[workspace\]' Cargo.toml | grep 'members' -A 50 | head -20
# Or list all Cargo.toml files
find crates/ -name "Cargo.toml" -maxdepth 2 | sortStep 2: Build Crate Inventory
For EACH crate, collect:
# Crate name and dependencies
for crate_dir in crates/*/; do
name=$(grep '^name' "$crate_dir/Cargo.toml" | head -1 | sed 's/.*= *"\(.*\)"/\1/')
echo "=== $name ==="
# Count public items
grep -rh "^pub " "$crate_dir/src/" --include="*.rs" 2>/dev/null | wc -l
echo ""
doneCreate inventory table:
| Crate | Public Items | Export Surface | Has Tests | Has Benches | Key Role |
| hgdb-common | ? | ? | ? | Shared types, errors | |
| hgdb-storage | ? | ? | ? | WAL, segments, MVCC | |
| ... | ... | ... | ... | ... |
Step 3: Map Inter-Crate Dependencies
# For each crate, find workspace dependencies
for crate_dir in crates/*/; do
name=$(grep '^name' "$crate_dir/Cargo.toml" | head -1 | sed 's/.*= *"\(.*\)"/\1/')
deps=$(grep 'path = ' "$crate_dir/Cargo.toml" 2>/dev/null | sed 's/.*"\(.*\)".*/\1/' | tr '\n' ', ')
echo "$name → $deps"
doneStep 4: Extract Public API Per Crate
For each crate, identify the actual export surface:
for crate_dir in crates/*/; do
name=$(grep '^name' "$crate_dir/Cargo.toml" | head -1 | sed 's/.*= *"\(.*\)"/\1/')
echo "=== $name ==="
echo "-- crate root exports --"
sed -n '1,200p' "$crate_dir/src/lib.rs" 2>/dev/null | grep -E '^(pub use|pub mod|mod |use )'
echo "-- public items --"
grep -rh "^pub " "$crate_dir/src/" --include="*.rs" 2>/dev/null | head -30
echo ""
doneImportant: raw pub count is not the same as exported API.
- Some
pubitems are internal to the crate and never re-exported. - Some crates export through
pub usefrom submodules. - Some functionality is reachable only via feature flags.
- Some packages export through
package.jsonexportsorsrc/index.ts, not by scanning every file.
Document the surface that consumers actually reach first; treat raw pub / export counts as a discovery aid, not the source of truth.
Step 5: Identify Key Files Per Crate
for crate_dir in crates/*/; do
name=$(grep '^name' "$crate_dir/Cargo.toml" | head -1 | sed 's/.*= *"\(.*\)"/\1/')
echo "=== $name ==="
find "$crate_dir/src" -name "*.rs" | sort
echo ""
doneStep 5a: Identify Hidden Wiring Files
For each member, identify files that make the module/package actually usable:
- crate/package roots:
src/lib.rs,src/main.rs,src/index.ts, barrel files - manifests:
Cargo.toml,package.json, exports maps, feature flags - registration points: routers, plugin registries, startup/bootstrap files, DI containers
- generated or feature-gated entry points that shape the public surface
Create a wiring inventory:
| Member | Wiring Files | Why They Matter |
| hgdb-storage | src/lib.rs, Cargo.toml | exports modules, feature flags |
| api-server | src/index.ts, src/app.ts | route registration, app bootstrap |
Rule: if a future code change would require touching a file to make new functionality reachable, that file belongs in the member CLAUDE.md.
Step 6: Check for Tests and Benchmarks
for crate_dir in crates/*/; do
name=$(grep '^name' "$crate_dir/Cargo.toml" | head -1 | sed 's/.*= *"\(.*\)"/\1/')
tests=$(find "$crate_dir" -name "*.rs" -path "*/tests/*" 2>/dev/null | wc -l)
benches=$(find "$crate_dir" -name "*.rs" -path "*/benches/*" 2>/dev/null | wc -l)
cfg_tests=$(grep -rl "#\[cfg(test)\]" "$crate_dir/src/" --include="*.rs" 2>/dev/null | wc -l)
echo "$name: $tests integration tests, $cfg_tests files with unit tests, $benches benchmarks"
doneStep 6a: Identify Runtime Entry Points and Cross-Member Consumers
For each member, answer:
- Who calls this member?
- How is it reached at runtime?
- Which files import it or register it?
- Which examples or tests exercise its real public surface?
Do not invent usage snippets. Prefer real consumers from the workspace.
For Node.js/TypeScript Monorepos
Use the same phases but with Node tooling:
# Find packages
ls -d packages/*/package.json apps/*/package.json 2>/dev/null
# Count exports
for pkg in packages/*/; do
name=$(jq -r '.name' "$pkg/package.json" 2>/dev/null)
count=$(grep -c "^export" "$pkg/src/index.ts" 2>/dev/null || echo 0)
echo "$name: $count exports"
donePhase 1 Gate
Before proceeding, you MUST have:
- List of ALL crates/packages with public API counts
- Actual exported/public surface for each member
- Inter-crate dependency map
- Key files per crate
- Wiring/registration file inventory
- Test and benchmark inventory
- Role description for each crate (1-line purpose)
Phase 2: Per-Crate CLAUDE.md Generation
Gate: EVERY crate has a CLAUDE.md.
Required Sections Per Crate (Rust)
Every per-crate CLAUDE.md MUST have:
| Section | Purpose | Format |
| Header | Crate name + 1-line purpose | # hgdb-storage + paragraph |
| Public API | Actual exported surface | Table: Item, Kind, Purpose, Source |
| Key Files | Source files with descriptions | Table: File, Purpose |
| Dependencies | Which workspace crates are imported | Bullet list with what's used |
| Wiring & Entry Points | Hidden files that expose/register behavior | Table: File, Role |
| Usage Pattern | How other crates use this one | Code block with use statements |
| Architecture | Key design decisions for THIS crate | Bullet list |
| Testing | How to test, what test types exist | Commands + patterns |
Required Sections Per Package (Node.js)
| Section | Purpose | Format |
| Header | Package name + 1-line purpose | # @scope/name + paragraph |
| Exports | Actual exported surface | Table: Export, Kind, Purpose, Source |
| Key Files | Source files with descriptions | Table: File, Purpose |
| Dependencies | Which @scope/* packages are imported | Bullet list |
| Wiring & Entry Points | Barrels, app bootstrap, route/plugin registration | Table: File, Role |
| Import Pattern | How consumers import from this package | Code block |
| Conventions | Package-specific rules | Bullet list |
| Testing | How to test (if tests exist) | Command + pattern |
Per-Crate Template (Rust)
# hgdb-<name>
[1-2 sentence purpose. What does this crate do? What problem does it solve?]
## Public API
| Item | Kind | Purpose | Source |
|------|------|---------|--------|
| `StructName` | struct | What it represents | `src/lib.rs` re-export |
| `TraitName` | trait | What contract it defines | `src/trait_mod.rs` |
| `function_name` | fn | What it does | `src/lib.rs` |
| `ErrorType` | enum | Error variants for this crate | `src/error.rs` |
## Key Files
| File | Purpose |
|------|---------|
| `src/lib.rs` | Crate root, re-exports public API |
| `src/wal/mod.rs` | WAL writer, group commit, crash recovery |
| ... | ... |
## Dependencies
Imports from these workspace crates:
- `hgdb-common` — types: `RowId`, `TxnId`, errors: `HgdbError`
- `hgdb-types` — formats: `Bmap`, `Barr`, type coercion
## Wiring & Entry Points
| File | Role |
|------|------|
| `src/lib.rs` | Public export surface |
| `Cargo.toml` | Features, optional deps, crate metadata |
| `src/startup.rs` | Runtime registration/bootstrap (if applicable) |
## Usage Pattern
```rust
use hgdb_storage::{Wal, Memtable, SegmentWriter, Reader};
use hgdb_storage::btree::BTreeIndex;
```
## Architecture
- [Key design decisions specific to THIS crate]
- [What's locked in CLAUDE.md that affects this crate]
- [What is NOT in this crate (common confusion points)]
## Testing
```bash
cargo test -p hgdb-<name>
cargo test -p hgdb-<name> -- --ignored # slow/integration tests
```
- Unit tests: `#[cfg(test)]` modules in source files
- Integration tests: `tests/` directory
- Proptest: `proptest!` blocks for invariant checking
- Benchmarks: `benches/` directory (if applicable)Content Quality Rules
- Public API table must describe the actual exported surface — not just raw
pubitems - If a member exports via barrel/root files, document the barrel/root first
- Key files must list all source files that matter plus all hidden wiring files
- Dependencies must be actual imports — grep the source, don't guess
- Usage patterns must show real examples — from actual consumers in the workspace
- Architecture must reference root CLAUDE.md decisions — if the root locks a decision that affects this member, say so
- Call out what is not owned here — common confusion points, delegated responsibility, upstream/downstream owners
- Run a drift check — if docs say "not implemented" but code exists, or docs imply exported surface that is unreachable, fix the docs
- No prose paragraphs — tables and bullet lists only. Save tokens.
Size Guide
| Crate Complexity | Target Lines | Example |
| Foundation (types, errors) | 50-80 | hgdb-common, hgdb-types |
| Engine (moderate API) | 80-150 | hgdb-doc, hgdb-sql |
| Core (large API) | 150-200 | hgdb-storage |
| Binary (entry point) | 50-80 | hgdb |
Phase 3: Root Simplification
Gate: Root CLAUDE.md simplified. No per-crate detail in root.
CRITICAL: NEVER remove or modify locked architectural decisions in root CLAUDE.md. The root CLAUDE.md may contain steering decisions, locked architecture, testing requirements, competitive positioning, and other project-level constraints that are NOT per-crate detail. These MUST be preserved exactly as-is. Only move per-crate detail (public API tables, file listings, crate-specific patterns) to per-crate files. When in doubt, leave it in root.
What STAYS in Root CLAUDE.md (DO NOT TOUCH)
- Project name + core principle
- ALL locked architectural decisions (even if they mention specific crates — they are project-wide constraints)
- Workspace layout table (crate name + 1-line purpose)
- Global conventions (Rust edition, clippy config, testing policy)
- Testing requirements section
- Competitive positioning, branding
- Reference to docs/ for detailed specs
What MOVES to Per-Crate CLAUDE.md
- Per-crate public API listings (if any exist in root — unlikely for a well-structured root)
- Per-crate file descriptions
- Per-crate wiring/registration notes
- Crate-specific testing instructions (not the global testing policy)
Root Simplification Checklist
- Root CLAUDE.md architectural decisions are UNCHANGED (diff check — no deletions in architecture sections)
- Root CLAUDE.md is ≤ 300 lines (if already under, no simplification needed)
- No per-crate public API detail in root
- Per-crate CLAUDE.md does not repeat root conventions verbatim
Phase 4: Verification (MANDATORY)
Gate: ALL checks pass before marking complete.
Check 1: Coverage
# Count crates that need CLAUDE.md
TOTAL=$(find crates/ -name "Cargo.toml" -maxdepth 2 | wc -l)
GENERATED=$(find crates/ -name "CLAUDE.md" -maxdepth 2 | wc -l)
echo "Coverage: $GENERATED / $TOTAL"FAIL if: Any crate is missing CLAUDE.md
Check 2: Public API Completeness
For each crate, verify public API coverage:
for crate_dir in crates/*/; do
actual=$(grep -rh "^pub " "$crate_dir/src/" --include="*.rs" 2>/dev/null | wc -l)
documented=$(grep -c "^|" "$crate_dir/CLAUDE.md" 2>/dev/null || echo 0)
name=$(basename "$crate_dir")
echo "$name: $documented documented / $actual pub items"
doneBut do not stop there. This check is only a coarse signal.
Also verify:
lib.rs/ barrel exports are represented in the docs- feature-gated exports are called out when relevant
- documented API is reachable from the consumer surface, not just
pubinternally
Check 3: Context Budget
wc -l CLAUDE.md
for f in crates/*/CLAUDE.md; do wc -l "$f"; doneFAIL if:
- Root CLAUDE.md > 300 lines
- Any per-crate CLAUDE.md > 200 lines
Check 4: Self-Containment
For each per-crate CLAUDE.md, verify it answers:
- What does this crate do? (header)
- What does it export? (public API table)
- What files does it contain? (key files)
- What does it depend on? (dependencies)
- What files expose or register it? (wiring/entry points)
- How do I use it? (usage pattern)
- How do I test it? (testing section)
Check 5: No Duplication
- Root CLAUDE.md has no per-crate public API listings
- Per-crate CLAUDE.md does not repeat root architectural decisions verbatim
Check 6: Wiring and Drift
For each member, verify:
- hidden wiring files are documented
- startup/bootstrap/registration points are called out when applicable
- manifests that shape exports/features are documented when relevant
- no stale claims like "not implemented yet" when the code exists
- no stale claims that something is exported/registered when it is not actually reachable
Quality Checklist (Must Score 10/10)
| Category | 0 | 1 | 2 |
| Coverage | Some members missing | All have CLAUDE.md but incomplete | Every member complete |
| API Surface Accuracy | Raw visibility only | Mostly accurate | Real exported surface documented |
| Self-Containment + Wiring | Missing key basics | Mostly standalone | Fully standalone with wiring points |
| Root Simplification | Root has per-member detail | Some moved | Root ≤300 lines, clean |
| Drift + Efficiency | Stale or duplicated | Minor drift/duplication | No stale claims, efficient context |
Total: 10/10 required to complete this skill
Quick Workflow Summary
PHASE 1: DISCOVERY (Do not skip)
├── Detect project type (Cargo workspace or Node monorepo)
├── Find all crates/packages
├── Count visible public items per member
├── Identify actual exported/public surface
├── Map inter-crate dependencies
├── List key files per crate
├── Identify wiring files and runtime entry points
├── Check for tests and benchmarks
└── Gate: Complete inventory
PHASE 2: PER-CRATE CLAUDE.md (Every crate)
├── Header + purpose
├── Public API table (actual exported surface)
├── Key files table
├── Dependencies list
├── Wiring & entry points
├── Usage patterns
├── Architecture notes (reference root decisions)
├── Testing instructions
└── Gate: Every crate has CLAUDE.md
PHASE 3: ROOT SIMPLIFICATION
├── Push per-crate detail to crate CLAUDE.md
├── Slim root to ≤300 lines
├── Keep only project-wide info in root
└── Gate: Root simplified, no duplication
PHASE 4: VERIFICATION (All must pass)
├── Check 1: Every crate has CLAUDE.md
├── Check 2: API surface documented accurately
├── Check 3: Context budget met
├── Check 4: Self-containment verified
├── Check 5: No duplication
├── Check 6: Wiring and drift verified
└── Gate: All checks pass
COMPLETE: Announce final quality score (must be 10/10)Integration with Other Skills
map-project— Use for single-crate projects or root-only updatesstart— Start skill identifies if workspace docs are neededcommit— After generating CLAUDE.md files, commit them
This skill ensures every crate in a workspace has focused, self-contained documentation that loads exactly when Claude needs it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

