agentleFS
ulpi-ioulpi-io/browse/.agents/skills/map-project-monorepo/SKILL.md

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.

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
  1. Distinctive:

    Before writing ANY per-crate CLAUDE.md, you ABSOLUTELY MUST complete Phase 1 discovery.

    line 8
  2. Distinctive:

    If the CLAUDE.md is incomplete, Claude has NO context for that crate.

    line 14
  3. Distinctive:

    Before writing ANY documentation:

    line 21
  4. Very specific:

    Document the surface that consumers actually reach first.

    line 151
  5. Distinctive:

    Create a wiring inventory:

    line 173
  6. Distinctive:

    Rule: if a future code change would require touching a file to make new functionality reachable, that file belongs in the member CLAUDE.md.

    line 180
  7. Distinctive:

    Do not invent usage snippets.

    line 203
  8. Distinctive:

    Use the same phases but with Node tooling:

    line 207
  9. Distinctive:

    Before proceeding, you MUST have:

    line 223
  10. Distinctive:

    Every per-crate CLAUDE.md MUST have:

    line 241

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<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:

  1. ☐ Detect project type: Cargo workspace (Cargo.toml with [workspace]) or Node monorepo (package.json with workspaces)
  2. ☐ Discover all member crates/packages
  3. ☐ For each, identify actual exported/public surface, not just raw pub or export
  4. ☐ Map inter-member dependencies
  5. ☐ Identify key files AND hidden wiring points (crate roots, barrels, manifests, startup hooks, registries, routers)
  6. ☐ Identify which members have tests, benchmarks, and runtime entry points
  7. ☐ 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

BehaviorDetail
Lazy loadingcrates/hgdb-storage/CLAUDE.md loads ONLY when Claude reads/writes files under crates/hgdb-storage/
No cross-loadingWorking in crates/hgdb-storage/ does NOT load crates/hgdb-sql/CLAUDE.md
Root always loadsRoot CLAUDE.md loads at startup for every session
HierarchyInstructions 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

ComponentMax LinesRationale
Root CLAUDE.md300Always loaded — keep it to project-wide info only
Per-crate CLAUDE.md50-200Lazy-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 | sort

Step 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 ""
done

Create inventory table:

CratePublic ItemsExport SurfaceHas TestsHas BenchesKey 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"
done

Step 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 ""
done

Important: raw pub count is not the same as exported API.

  • Some pub items are internal to the crate and never re-exported.
  • Some crates export through pub use from submodules.
  • Some functionality is reachable only via feature flags.
  • Some packages export through package.json exports or src/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 ""
done

Step 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:

MemberWiring FilesWhy They Matter
hgdb-storagesrc/lib.rs, Cargo.tomlexports modules, feature flags
api-serversrc/index.ts, src/app.tsroute 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"
done

Step 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"
done

Phase 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:

SectionPurposeFormat
HeaderCrate name + 1-line purpose# hgdb-storage + paragraph
Public APIActual exported surfaceTable: Item, Kind, Purpose, Source
Key FilesSource files with descriptionsTable: File, Purpose
DependenciesWhich workspace crates are importedBullet list with what's used
Wiring & Entry PointsHidden files that expose/register behaviorTable: File, Role
Usage PatternHow other crates use this oneCode block with use statements
ArchitectureKey design decisions for THIS crateBullet list
TestingHow to test, what test types existCommands + patterns

Required Sections Per Package (Node.js)

SectionPurposeFormat
HeaderPackage name + 1-line purpose# @scope/name + paragraph
ExportsActual exported surfaceTable: Export, Kind, Purpose, Source
Key FilesSource files with descriptionsTable: File, Purpose
DependenciesWhich @scope/* packages are importedBullet list
Wiring & Entry PointsBarrels, app bootstrap, route/plugin registrationTable: File, Role
Import PatternHow consumers import from this packageCode block
ConventionsPackage-specific rulesBullet list
TestingHow 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

  1. Public API table must describe the actual exported surface — not just raw pub items
  2. If a member exports via barrel/root files, document the barrel/root first
  3. Key files must list all source files that matter plus all hidden wiring files
  4. Dependencies must be actual imports — grep the source, don't guess
  5. Usage patterns must show real examples — from actual consumers in the workspace
  6. Architecture must reference root CLAUDE.md decisions — if the root locks a decision that affects this member, say so
  7. Call out what is not owned here — common confusion points, delegated responsibility, upstream/downstream owners
  8. Run a drift check — if docs say "not implemented" but code exists, or docs imply exported surface that is unreachable, fix the docs
  9. No prose paragraphs — tables and bullet lists only. Save tokens.

Size Guide

Crate ComplexityTarget LinesExample
Foundation (types, errors)50-80hgdb-common, hgdb-types
Engine (moderate API)80-150hgdb-doc, hgdb-sql
Core (large API)150-200hgdb-storage
Binary (entry point)50-80hgdb

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"
done

But 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 pub internally

Check 3: Context Budget

wc -l CLAUDE.md
for f in crates/*/CLAUDE.md; do wc -l "$f"; done

FAIL 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)

Category012
CoverageSome members missingAll have CLAUDE.md but incompleteEvery member complete
API Surface AccuracyRaw visibility onlyMostly accurateReal exported surface documented
Self-Containment + WiringMissing key basicsMostly standaloneFully standalone with wiring points
Root SimplificationRoot has per-member detailSome movedRoot ≤300 lines, clean
Drift + EfficiencyStale or duplicatedMinor drift/duplicationNo 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 updates
  • start — Start skill identifies if workspace docs are needed
  • commit — 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.