/nest

Sharding Strategy

Reference for Nest's sharding recipe. Split large CLAUDE.md / reference docs via @import while preserving prompt cache prefixes and avoiding circular references.

Complements Hone (density audit). Hone identifies what to extract; Nest decides where to put it and in what order.

@import below is shorthand for Claude Code's bare @path directive — @.claude/rules/x.md, never @import <path>, which is not syntax and silently fails to load. These imports also resolve at load time: sharding buys deduplication, ownership, and cache-prefix stability, not a smaller startup context. Only paths:-scoped rules, skill bodies, and hooks defer or eliminate the recurring cost — hence the rule to measure the post-shard total, not per-file counts.

1. When to Shard

Trigger thresholds:

Don't shard prematurely. Below thresholds, monolithic is faster (fewer file reads, simpler grep).

2. Split Axis Selection

Choose one primary axis per shard layer. Mixing axes within a layer creates inconsistency.

Axis A: by domain (most common)

.claude/rules/
├── coding-standards.md
├── testing-policy.md
├── security-rules.md
├── git-conventions.md
└── deployment.md

Use when: rules cluster around well-defined topics.

Axis B: by lifecycle phase

.claude/rules/
├── design.md       # Pre-implementation rules
├── implement.md    # During-coding rules
├── review.md       # Pre-merge rules
└── deploy.md       # Post-merge / release rules

Use when: rules apply at distinct workflow stages.

Axis C: by change frequency (cache-optimal)

.claude/rules/
├── stable.md       # < 1 change / month (cache-friendly)
├── monthly.md      # 1-4 changes / month
└── volatile.md     # weekly+ changes (cache-unfriendly)

Use when: prompt cache hit rate is the dominant constraint.

Axis D: by audience

.claude/rules/
├── all-agents.md
├── code-agents.md   # builder, artisan, scout
├── review-agents.md # judge, zen
└── ops-agents.md    # gear, beacon

Use when: many agents share project but read different rule subsets.

3. Cache-Preserving Order

Prompt cache invalidates from the first changed byte forward. Order matters.

Stable-first principle

# CLAUDE.md

@.claude/rules/stable.md      ← rarely changes (cached for weeks)
@.claude/rules/monthly.md     ← occasionally changes
@.claude/rules/volatile.md    ← changes weekly (invalidates only itself + below)

## Project-specific (most volatile, last)
- Current sprint focus: ...
- Active branch: ...

Within a single file

# Stable preamble (license, identity)
# Boundaries (rare changes)
# Core rules (rare changes)
# Workflow (occasional changes)
# Recipes (occasional changes)
# Operational notes (frequent changes — bottom)

If a frequently-changed line appears in line 10, every line below 10 invalidates with each edit. Push volatile content to the bottom.

4. Include Manifest

Document the include graph in .claude/rules/INDEX.md:

# CLAUDE.md Include Manifest

## Cascade (root → leaf)
- `CLAUDE.md` (project root)
  - @.claude/rules/stable.md       (stability: high; lines: 80)
  - @.claude/rules/coding.md       (stability: medium; lines: 120)
  - @.claude/rules/security.md     (stability: high; lines: 60)
  - @.claude/rules/volatile.md     (stability: low; lines: 40)

## Total tokens: ~1,200 (within budget)

## Override hierarchy
- `packages/api/CLAUDE.md` overrides `coding.md` § 3 (Python-specific)
- `packages/web/CLAUDE.md` overrides `coding.md` § 3 (TypeScript-specific)

## Cycle check: ✓ no circular @import detected (run via scripts/check-cycles.sh)

Maintain alongside the actual rules. Stale INDEX.md is worse than no INDEX.md.

5. Cycle Prevention

@import graphs must be a DAG (Directed Acyclic Graph).

Allowed

A.md → B.md → C.md
A.md → C.md (diamond OK)

Forbidden

A.md → B.md → A.md  (cycle)
A.md → B.md → C.md → A.md  (cycle)

Detection script (bash, conceptual)

#!/bin/bash
# scripts/check-cycles.sh
declare -A graph
for f in $(find .claude -name '*.md'); do
  for ref in $(grep -oE '@\S+\.md' "$f" | tr -d '@'); do
    graph["$f"]+="$ref "
  done
done
# DFS cycle detection
# (full implementation: prefer madge or a Python/Node script)

Run on pre-commit if rule-file edits happen frequently.

6. Sharding Strategy Decision Matrix

7. Verification After Sharding

8. Common Pitfalls

9. Decision Walkthrough Template

Source file to shard: ____________
Current size: ____ lines / ~____ tokens
Trigger reason: □ size threshold  □ duplication  □ cache rot  □ audience mismatch

Split axis: □ A (domain)  □ B (lifecycle)  □ C (frequency)  □ D (audience)
Rationale: ____________

Planned shards (3-7 max):
  1. ____________  (~____ lines, stability: high/med/low)
  2. ____________  (~____ lines, stability: high/med/low)
  3. ____________  (~____ lines, stability: high/med/low)
  ...

Order in root CLAUDE.md (stable → volatile):
  1. @____
  2. @____
  3. @____

Override layers needed:
  □ Package-level overrides
  □ Module-level overrides
  □ None (single layer)

Cycle check: ✓ / pending

INDEX.md maintained: ✓ / ✗

Verification:
  □ Total tokens under budget
  □ Diff vs original = no content loss
  □ All @import paths resolve
  □ Cache prefix stable
  □ Discovery test passes

10. References

• Anthropic prompt cache documentation
• Claude Code @import syntax
• madge (cycle detection for JS/TS, adaptable concept)
• Hone skill (density audit complement)