Menú
Split oversized CLAUDE.md into subdirectory files. Trigger: CLAUDE.md too large, context window, documentation splitting.
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
| name | claude-md-context-management |
| description | Split oversized CLAUDE.md into subdirectory files. Trigger: CLAUDE.md too large, context window, documentation splitting. |
| author | KINTSUGI Team |
| date | "2026-02-21T00:00:00.000Z" |
| Item | Details |
|---|---|
| Date | 2026-02-21 |
| Goal | Keep root CLAUDE.md under 40k chars while preserving all documentation |
| Environment | Claude Code with auto-loaded CLAUDE.md files per subdirectory |
| Status | Success |
Root CLAUDE.md grew to 40,952 chars — just over the 40k limit. Claude Code auto-loads CLAUDE.md files when working on files in a directory, so feature-specific docs can live near the code they describe. The challenge is splitting without losing discoverability or creating broken cross-references.
Categorize each section as either "always needed" (keep in root) or "feature-specific" (move to subdirectory):
Keep in root (essential context for any task):
Move to subdirectory (only needed when working on that feature):
workflow/CLAUDE.mdsrc/kintsugi/signal/CLAUDE.mdsrc/kintsugi/CLAUDE.mdBefore creating new files, check if content already exists in subdirectory CLAUDE.md files. Avoid duplication — replace the root section with a pointer instead of creating a new file.
Each file should include:
Replace verbose sections with 2-line pointers:
## Registration
See `workflow/CLAUDE.md` for comprehensive registration documentation: ...
## Subdirectory Documentation
Feature-specific documentation lives in CLAUDE.md files near the code:
- `src/kintsugi/CLAUDE.md` — KRONOS, vessel3d, cleanup
- `src/kintsugi/signal/CLAUDE.md` — Weighted AF, batch signal isolation
- `workflow/CLAUDE.md` — Snakemake, registration, batch processing
- `notebooks/CLAUDE.md` — Jupyter autoreload, Notebook 4
wc -c CLAUDE.md # Should be well under 40k
wc -c src/kintsugi/CLAUDE.md # Each under 40k
wc -c src/kintsugi/signal/CLAUDE.md
Check cross-references with grep for any section names that were removed.
| Attempt | Why it Failed | Lesson Learned |
|---|---|---|
| Moving ALL feature docs out of root | Root became too sparse — no context for common tasks | Keep architecture overview, critical fixes, and build commands in root |
Creating one giant docs/CLAUDE.md | Claude Code only auto-loads CLAUDE.md in the directory you're working in | Files must be in the subdirectory where the code lives |
| Duplicating content in root + subdirectory | Stale content diverges over time | Root should have pointers only, never duplicated details |
| Moving content without back-references | Subdirectory files become orphaned — hard to discover | Every subdirectory CLAUDE.md needs a "See also" header |
| Parameter | Value | Rationale |
|---|---|---|
| Root CLAUDE.md target | < 25k chars | Well under 40k limit with room to grow |
| Pointer format | 2-line section (heading + "See X for Y") | Minimal but discoverable |
| Back-reference format | "See also:" header in each subdirectory file | Consistent navigation pattern |
| File placement | Same directory as the code it documents | Claude Code auto-loads based on working directory |
CLAUDE.md files from the directory tree you're working in — this is the key mechanism that makes splitting work../../workflow/CLAUDE.md) are for human readers; Claude Code finds CLAUDE.md files by directory traversalworkflow/CLAUDE.md — removing the root copy eliminated 65 lines of duplication with zero information loss| File | Before | After |
|---|---|---|
Root CLAUDE.md | 40,952 chars | 21,042 chars (49% reduction) |
src/kintsugi/CLAUDE.md | (new) | 8,265 chars |
src/kintsugi/signal/CLAUDE.md | (new) | 4,908 chars |
workflow/CLAUDE.md | 24,158 chars | unchanged |
notebooks/CLAUDE.md | 3,983 chars | unchanged |
9bc9e0f: "docs: split CLAUDE.md into subdirectory files to stay under 40k char limit"Normalize long-form CODEX cycle folders to short form before notebooks run. Trigger: cyc001_reg001_*, hard-coded cyc paths breaking, staged CODEX raw data failing in Notebooks 1/2.
v5.6.0 joint multi-TF model: single model per symbol with broadcast 1Hour context replaces dual 15Min/1Hour models. Trigger: (1) replacing weighted-voting model aggregation, (2) adding broadcast features to vectorized env, (3) limited training data + worried about overfitting from doubling obs_dim, (4) backtest builder mismatch with newer feature counts.
DEPRECATED in v5.6.0 — see joint-multi-tf-v560 skill. Documents the v5.2.0 dual-model approach (train separate 15Min/1Hour models, combine via weighted voting). Still relevant for: (1) loading legacy v5.5.0 dual models, (2) understanding the historical aggregation layer, (3) resampling pattern via origin='start'.
Surface a shipped-but-undocumented CLI feature in user-facing docs. Trigger: user reports a known feature missing from README/readthedocs even though the CLI command exists.
KINTSUGI Snakefile + CLI changes that route SLURM jobs around accounts saturated by OTHER users on the same QOS pool. Trigger: QOSGrpMemLimit, jobs stuck pending despite available GPU slots in config, noisy neighbor on shared QOS, multi-user investment pool exhaustion, _build_cycle_assignment static-vs-live.
KINTSUGI SLURM batch processing: Maximize throughput using multi-account resource calculation with GPU+CPU pools per account. Trigger: SLURM job submission, batch processing, resource maximization, GPU+CPU concurrent, headless processing, resource pool.