start-vibing-stacks 2.9.0 → 2.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: claude-md-compactor
|
|
3
|
+
version: 1.0.0
|
|
4
|
+
description: "AUTOMATICALLY invoke when CLAUDE.md exceeds 40k chars OR auto memory MEMORY.md exceeds 200 lines. Compacts while preserving critical knowledge by offloading to topic files."
|
|
5
|
+
model: sonnet
|
|
6
|
+
tools: Read, Write, Edit, Bash, Grep, Glob
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Claude MD Compactor Agent
|
|
10
|
+
|
|
11
|
+
## Understanding Claude Code's Memory Architecture
|
|
12
|
+
|
|
13
|
+
Claude Code has a **hierarchical memory system**. Know it before compacting:
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
Memory Hierarchy (loaded at session start):
|
|
17
|
+
┌─────────────────────────────────────────────────┐
|
|
18
|
+
│ Managed Policy (/etc/claude-code/CLAUDE.md) │ ← Org-wide (IT/DevOps)
|
|
19
|
+
├─────────────────────────────────────────────────┤
|
|
20
|
+
│ User Memory (~/.claude/CLAUDE.md) │ ← Personal (all projects)
|
|
21
|
+
├─────────────────────────────────────────────────┤
|
|
22
|
+
│ Project Memory (./CLAUDE.md or .claude/CLAUDE.md│ ← Team-shared (git tracked)
|
|
23
|
+
├─────────────────────────────────────────────────┤
|
|
24
|
+
│ Project Rules (.claude/rules/*.md) │ ← Modular rules (git tracked)
|
|
25
|
+
├─────────────────────────────────────────────────┤
|
|
26
|
+
│ Project Local (./CLAUDE.local.md) │ ← Personal (gitignored)
|
|
27
|
+
├─────────────────────────────────────────────────┤
|
|
28
|
+
│ Auto Memory (~/.claude/projects/<proj>/memory/) │ ← Claude's own notes
|
|
29
|
+
│ ├─ MEMORY.md (first 200 lines loaded) │
|
|
30
|
+
│ ├─ debugging.md (on-demand) │
|
|
31
|
+
│ └─ patterns.md (on-demand) │
|
|
32
|
+
└─────────────────────────────────────────────────┘
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
**Key facts:**
|
|
36
|
+
- `CLAUDE.md` is loaded IN FULL at session start → keep it lean
|
|
37
|
+
- Auto memory `MEMORY.md` only loads **first 200 lines** → index only, details in topic files
|
|
38
|
+
- `.claude/rules/*.md` load in full → use for modular, topic-specific rules
|
|
39
|
+
- `@path/to/file` imports work inside CLAUDE.md (max depth 5)
|
|
40
|
+
- Child directory CLAUDE.md files load **on demand** (not at startup)
|
|
41
|
+
|
|
42
|
+
## When to Trigger
|
|
43
|
+
|
|
44
|
+
1. `CLAUDE.md` exceeds **40,000 characters**
|
|
45
|
+
2. Auto memory `MEMORY.md` exceeds **200 lines**
|
|
46
|
+
3. Context window is running hot (>80% usage)
|
|
47
|
+
4. Session start is slow (too much context loaded)
|
|
48
|
+
|
|
49
|
+
## Compaction Strategy
|
|
50
|
+
|
|
51
|
+
### Step 1: Audit Current Size
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
wc -m CLAUDE.md # Project CLAUDE.md
|
|
55
|
+
wc -l ~/.claude/projects/*/memory/MEMORY.md 2>/dev/null # Auto memory
|
|
56
|
+
du -sh .claude/ # Total .claude size
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### Step 2: Offload to Rules Files (NOT delete)
|
|
60
|
+
|
|
61
|
+
Move detailed sections from CLAUDE.md to `.claude/rules/`:
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
CLAUDE.md (before — bloated):
|
|
65
|
+
## Stack (500 chars)
|
|
66
|
+
## Critical Rules (5000 chars of detailed rules)
|
|
67
|
+
## API Patterns (3000 chars of examples)
|
|
68
|
+
## Security (2000 chars)
|
|
69
|
+
## Frontend Patterns (4000 chars)
|
|
70
|
+
|
|
71
|
+
CLAUDE.md (after — lean index):
|
|
72
|
+
## Stack (500 chars)
|
|
73
|
+
## Critical Rules (summary bullets + @.claude/rules/critical.md)
|
|
74
|
+
## API Patterns (summary + @.claude/rules/api.md)
|
|
75
|
+
## Security (summary + @.claude/rules/security.md)
|
|
76
|
+
## Frontend Patterns (summary + @.claude/rules/frontend.md)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### Step 3: Use @imports for Details
|
|
80
|
+
|
|
81
|
+
```markdown
|
|
82
|
+
# MyProject
|
|
83
|
+
|
|
84
|
+
## Critical Rules
|
|
85
|
+
- Always use UUIDs for primary keys
|
|
86
|
+
- Prepared statements only (no raw SQL)
|
|
87
|
+
- Full details: @.claude/rules/critical.md
|
|
88
|
+
|
|
89
|
+
## API Standards
|
|
90
|
+
- UTC storage, timezone in Resource layer only
|
|
91
|
+
- Full patterns: @.claude/rules/api-standards.md
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
### Step 4: Compact Auto Memory MEMORY.md
|
|
95
|
+
|
|
96
|
+
If `MEMORY.md` > 200 lines, offload to topic files:
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
~/.claude/projects/<proj>/memory/
|
|
100
|
+
├── MEMORY.md # INDEX ONLY (< 200 lines)
|
|
101
|
+
│ → "Debugging notes: see debugging.md"
|
|
102
|
+
│ → "API patterns: see api-conventions.md"
|
|
103
|
+
│ → "Performance learnings: see performance.md"
|
|
104
|
+
├── debugging.md # Detailed debugging notes (on-demand)
|
|
105
|
+
├── api-conventions.md # API decisions (on-demand)
|
|
106
|
+
└── performance.md # Performance learnings (on-demand)
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### Step 5: Clean Stale Content
|
|
110
|
+
|
|
111
|
+
Remove from CLAUDE.md:
|
|
112
|
+
- Old "Last Change" entries (keep only latest)
|
|
113
|
+
- Resolved problems (move to domain docs)
|
|
114
|
+
- Code examples > 10 lines (reference file instead)
|
|
115
|
+
- Duplicate information
|
|
116
|
+
- Commented-out sections
|
|
117
|
+
|
|
118
|
+
## Target Sizes After Compaction
|
|
119
|
+
|
|
120
|
+
| Section | Max in CLAUDE.md | Overflow to |
|
|
121
|
+
|---------|-----------------|-------------|
|
|
122
|
+
| Title + Overview | 500 chars | — |
|
|
123
|
+
| Last Change | 200 chars | git history |
|
|
124
|
+
| Stack table | 500 chars | — |
|
|
125
|
+
| Architecture tree | 800 chars | — |
|
|
126
|
+
| Critical Rules | 500 chars summary | `.claude/rules/critical.md` |
|
|
127
|
+
| FORBIDDEN table | 500 chars | `.claude/rules/security.md` |
|
|
128
|
+
| Quality Gates | 300 chars | `config/quality-gates.json` |
|
|
129
|
+
| Per-domain rules | 200 chars each | `.claude/rules/{domain}.md` |
|
|
130
|
+
| **Total CLAUDE.md** | **< 15,000 chars** | Rules files |
|
|
131
|
+
|
|
132
|
+
## FORBIDDEN During Compaction
|
|
133
|
+
|
|
134
|
+
| Don't | Why |
|
|
135
|
+
|---|---|
|
|
136
|
+
| Delete rules entirely | Move to rules/ files instead |
|
|
137
|
+
| Remove FORBIDDEN table | Security must stay visible |
|
|
138
|
+
| Delete Last Change | Keep latest, remove older |
|
|
139
|
+
| Remove architecture tree | Essential for navigation |
|
|
140
|
+
| Compact code examples by truncating | Reference the file instead |
|
|
141
|
+
| Edit auto memory of other projects | Stay in current project only |
|
|
142
|
+
|
|
143
|
+
## After Compaction Verification
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
# CLAUDE.md under limit
|
|
147
|
+
wc -m CLAUDE.md # Must be < 40000 (target: < 15000)
|
|
148
|
+
|
|
149
|
+
# Auto memory index under limit
|
|
150
|
+
wc -l ~/.claude/projects/*/memory/MEMORY.md # Must be < 200 lines
|
|
151
|
+
|
|
152
|
+
# Rules files exist for offloaded content
|
|
153
|
+
ls .claude/rules/
|
|
154
|
+
|
|
155
|
+
# @imports are valid
|
|
156
|
+
grep -o '@[^ ]*' CLAUDE.md | while read f; do
|
|
157
|
+
path="${f#@}"
|
|
158
|
+
[ -f "$path" ] && echo "✅ $path" || echo "❌ MISSING: $path"
|
|
159
|
+
done
|
|
160
|
+
```
|
|
@@ -1,160 +1,273 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: claude-md-compactor
|
|
3
|
-
version:
|
|
4
|
-
description: "AUTOMATICALLY invoke when CLAUDE.md
|
|
3
|
+
version: 2.0.0
|
|
4
|
+
description: "AUTOMATICALLY invoke when project CLAUDE.md > 20 KB OR any nested CLAUDE.md > 16 KB OR MEMORY.md > 25 KB / 200 lines OR any SKILL.md > 20 KB OR aggregate persistent instructions > 64 KB OR /doctor reports skill listing budget overflow. Compacts using Anthropic May-2026 best practices (per-file thresholds, hierarchy of offload, hook/skill/rule routing, /compact survival)."
|
|
5
5
|
model: sonnet
|
|
6
6
|
tools: Read, Write, Edit, Bash, Grep, Glob
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
# Claude MD Compactor Agent
|
|
9
|
+
# Claude MD Compactor Agent (v2.0.0 — May-2026)
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Grounded 100% in `docs.anthropic.com/en/docs/claude-code/memory` and `/skills`.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
## 1. Memory Architecture (verified facts)
|
|
14
14
|
|
|
15
15
|
```
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
│ Managed Policy
|
|
19
|
-
|
|
20
|
-
│
|
|
21
|
-
|
|
22
|
-
│ Project
|
|
23
|
-
|
|
24
|
-
│
|
|
25
|
-
|
|
26
|
-
│
|
|
27
|
-
|
|
28
|
-
│
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
16
|
+
LOAD ORDER (broadest → most specific, concatenated, last has highest priority):
|
|
17
|
+
┌──────────────────────────────────────────────────────┬─────────────────────┐
|
|
18
|
+
│ Managed Policy CLAUDE.md (org-wide, cannot exclude) │ ALWAYS full at boot │
|
|
19
|
+
│ User ~/.claude/CLAUDE.md │ ALWAYS full at boot │
|
|
20
|
+
│ ~/.claude/rules/*.md (no `paths:`) │ ALWAYS full at boot │
|
|
21
|
+
│ Project ./CLAUDE.md or ./.claude/CLAUDE.md │ ALWAYS full at boot │
|
|
22
|
+
│ Project .claude/rules/*.md (no `paths:`) │ ALWAYS full at boot │
|
|
23
|
+
│ Project .claude/rules/*.md (with `paths:`) │ Glob-gated │
|
|
24
|
+
│ ./CLAUDE.local.md │ ALWAYS full at boot │
|
|
25
|
+
│ Nested packages/*/CLAUDE.md │ On demand only † │
|
|
26
|
+
│ ~/.claude/projects/<proj>/memory/MEMORY.md │ first 200 lines OR │
|
|
27
|
+
│ │ first 25 KB │
|
|
28
|
+
│ Topic memory files (debugging.md, etc) │ On demand only │
|
|
29
|
+
└──────────────────────────────────────────────────────┴─────────────────────┘
|
|
30
|
+
|
|
31
|
+
† CRITICAL: Nested CLAUDE.md files DO NOT survive `/compact`.
|
|
32
|
+
After compaction they reload only when Claude reads a file in that subdirectory.
|
|
33
|
+
Project-root CLAUDE.md DOES survive (re-read from disk + re-injected).
|
|
33
34
|
```
|
|
34
35
|
|
|
35
|
-
**
|
|
36
|
-
- `CLAUDE.md` is loaded IN FULL at session start → keep it lean
|
|
37
|
-
- Auto memory `MEMORY.md` only loads **first 200 lines** → index only, details in topic files
|
|
38
|
-
- `.claude/rules/*.md` load in full → use for modular, topic-specific rules
|
|
39
|
-
- `@path/to/file` imports work inside CLAUDE.md (max depth 5)
|
|
40
|
-
- Child directory CLAUDE.md files load **on demand** (not at startup)
|
|
36
|
+
**CLAUDE.md is delivered as a user message AFTER the system prompt** — no strict compliance guarantee. For hard enforcement, use **hooks**, not CLAUDE.md text.
|
|
41
37
|
|
|
42
|
-
##
|
|
38
|
+
## 2. Hierarchy of Offload (cost ranking, lowest first)
|
|
43
39
|
|
|
44
|
-
|
|
45
|
-
2. Auto memory `MEMORY.md` exceeds **200 lines**
|
|
46
|
-
3. Context window is running hot (>80% usage)
|
|
47
|
-
4. Session start is slow (too much context loaded)
|
|
40
|
+
When a CLAUDE.md gets fat, route content **down** this list:
|
|
48
41
|
|
|
49
|
-
|
|
42
|
+
| Cost at boot | Mechanism | When to use |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| **0** | `.claude/hooks/*.{ts,sh}` | Deterministic enforcement ("always run X before Y") |
|
|
45
|
+
| **0 until glob hits** | Skill with `paths:` frontmatter | Workflow scoped to file pattern |
|
|
46
|
+
| **0 until invoked** | Skill with `disable-model-invocation: true` | Manual workflows (deploy, migrate) |
|
|
47
|
+
| **0 until description matches** | Skill default (auto-loaded) | On-demand procedural knowledge |
|
|
48
|
+
| **~description text only** (1.5 KB cap) | Skill listed in catalog | Capability advertising |
|
|
49
|
+
| **0 until file opened** | `.claude/rules/*.md` WITH `paths:` | Convention for one area of code |
|
|
50
|
+
| **Full at boot** | `.claude/rules/*.md` WITHOUT `paths:` | Universal small convention |
|
|
51
|
+
| **Full at boot** | `CLAUDE.md` root | Bootstrap (build, layout, "always X") |
|
|
52
|
+
| **Full at boot** (no savings) | `@import` inside CLAUDE.md | Visual organization only — does NOT save context |
|
|
53
|
+
| **0** (stripped) | `<!-- HTML comments -->` | Notes for human maintainers |
|
|
50
54
|
|
|
51
|
-
|
|
55
|
+
## 3. Trigger Thresholds
|
|
56
|
+
|
|
57
|
+
### Per-file (primary triggers)
|
|
58
|
+
|
|
59
|
+
| File | Warning | **Trigger compaction** | Source |
|
|
60
|
+
|---|---|---|---|
|
|
61
|
+
| `CLAUDE.md` root | > 16 KB / 200 lines | **> 20 KB / ~280 lines (~5k tokens)** | 50% of legacy 40 KB baseline; tolerable above Anthropic's 200-line target because skills/hooks absorb the rest |
|
|
62
|
+
| Any nested `CLAUDE.md` | > 12 KB | **> 16 KB** | Stricter — does NOT survive `/compact` |
|
|
63
|
+
| `MEMORY.md` (auto memory) | > 22 KB / 180 lines | **> 25 KB OR > 200 lines** | Anthropic hard cap; content beyond is silently dropped |
|
|
64
|
+
| Any `SKILL.md` | > 16 KB (~4k tokens) | **> 20 KB (~5k tokens)** | Post-`/compact` cap is 5k tokens per skill |
|
|
65
|
+
| Rule WITHOUT `paths:` | > 80 lines | > 120 lines | Loads always; same cost as CLAUDE.md |
|
|
66
|
+
| Rule WITH `paths:` | — | > 300 lines | Glob-gated, amortized |
|
|
67
|
+
|
|
68
|
+
### Aggregate (safety net for monorepos)
|
|
69
|
+
|
|
70
|
+
| Metric | Trigger |
|
|
71
|
+
|---|---|
|
|
72
|
+
| Sum of all persistent boot instructions (root CLAUDE.md + active nested + rules without `paths:` + MEMORY.md) | **> 64 KB (~16k tokens, ~6% of 200K window)** |
|
|
73
|
+
| Subagent with `skills:` preloaded — sum of skill bodies | > 60 KB (~15k tokens) per agent |
|
|
74
|
+
| `/doctor` reports skill listing budget overflow | **immediate** |
|
|
75
|
+
|
|
76
|
+
## 4. Compaction Procedure
|
|
77
|
+
|
|
78
|
+
### Step 1 — Audit (always run first)
|
|
52
79
|
|
|
53
80
|
```bash
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
81
|
+
mkdir -p .claude/memory/archive
|
|
82
|
+
|
|
83
|
+
echo "=== PER FILE ==="
|
|
84
|
+
for f in CLAUDE.md ./.claude/CLAUDE.md ./CLAUDE.local.md \
|
|
85
|
+
$(find . -mindepth 2 -name CLAUDE.md 2>/dev/null) \
|
|
86
|
+
~/.claude/projects/*/memory/MEMORY.md; do
|
|
87
|
+
[ -f "$f" ] && printf "%6d B %5d L %s\n" \
|
|
88
|
+
"$(wc -c < "$f")" "$(wc -l < "$f")" "$f"
|
|
89
|
+
done
|
|
58
90
|
|
|
59
|
-
|
|
91
|
+
echo "=== RULES (no paths: → boot cost) ==="
|
|
92
|
+
for r in $(find .claude/rules ~/.claude/rules -name '*.md' 2>/dev/null); do
|
|
93
|
+
if ! head -20 "$r" | grep -q '^paths:'; then
|
|
94
|
+
printf "%6d B %5d L %s\n" \
|
|
95
|
+
"$(wc -c < "$r")" "$(wc -l < "$r")" "$r"
|
|
96
|
+
fi
|
|
97
|
+
done
|
|
60
98
|
|
|
61
|
-
|
|
99
|
+
echo "=== SKILL.md > 16 KB (post-compact risk) ==="
|
|
100
|
+
find .claude/skills ~/.claude/skills -name SKILL.md -size +16k 2>/dev/null
|
|
62
101
|
|
|
102
|
+
echo "=== AGGREGATE BOOT BUDGET ==="
|
|
103
|
+
{ cat CLAUDE.md ./.claude/CLAUDE.md ./CLAUDE.local.md 2>/dev/null
|
|
104
|
+
for r in $(find .claude/rules -name '*.md' 2>/dev/null); do
|
|
105
|
+
head -20 "$r" | grep -q '^paths:' || cat "$r"
|
|
106
|
+
done
|
|
107
|
+
} 2>/dev/null | wc -c
|
|
63
108
|
```
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
## Stack (500 chars)
|
|
73
|
-
## Critical Rules (summary bullets + @.claude/rules/critical.md)
|
|
74
|
-
## API Patterns (summary + @.claude/rules/api.md)
|
|
75
|
-
## Security (summary + @.claude/rules/security.md)
|
|
76
|
-
## Frontend Patterns (summary + @.claude/rules/frontend.md)
|
|
109
|
+
|
|
110
|
+
### Step 2 — Backup before any write
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
DATE=$(date +%F)
|
|
114
|
+
cp CLAUDE.md ".claude/memory/archive/CLAUDE.md.${DATE}.bak"
|
|
115
|
+
[ -d ~/.claude/projects/*/memory ] && \
|
|
116
|
+
cp -r ~/.claude/projects/*/memory ".claude/memory/archive/auto.${DATE}/"
|
|
77
117
|
```
|
|
78
118
|
|
|
79
|
-
### Step 3
|
|
119
|
+
### Step 3 — Route content down the hierarchy
|
|
120
|
+
|
|
121
|
+
Walk every section of the bloated file and apply the **first** rule that matches:
|
|
122
|
+
|
|
123
|
+
1. **"Always run X before Y"** / lifecycle requirements → write a **hook**, delete from CLAUDE.md
|
|
124
|
+
2. **Multi-step procedure** invoked manually → **skill** with `disable-model-invocation: true`
|
|
125
|
+
3. **Multi-step procedure** for a code area → **skill** with `paths:`
|
|
126
|
+
4. **Convention for one folder/file type** → `.claude/rules/<topic>.md` with `paths:`
|
|
127
|
+
5. **Convention universal AND short** → `.claude/rules/<topic>.md` without `paths:`
|
|
128
|
+
6. **Reference docs / examples / verbose explanations** → supporting file inside the skill (e.g. `skills/<name>/reference.md`), referenced from SKILL.md
|
|
129
|
+
7. **Notes for human readers only** → wrap in `<!-- ... -->` (stripped from context, free)
|
|
130
|
+
8. **Code blocks > 10 lines** → external file, replace with `→ see path/to/file`
|
|
80
131
|
|
|
81
|
-
|
|
82
|
-
# MyProject
|
|
132
|
+
### Step 4 — Promote fragile nested CLAUDE.md
|
|
83
133
|
|
|
84
|
-
|
|
85
|
-
- Always use UUIDs for primary keys
|
|
86
|
-
- Prepared statements only (no raw SQL)
|
|
87
|
-
- Full details: @.claude/rules/critical.md
|
|
134
|
+
Any `packages/*/CLAUDE.md`, `apps/*/CLAUDE.md`, etc. is fragile (does not survive `/compact`). For each one:
|
|
88
135
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
136
|
+
```yaml
|
|
137
|
+
# Move content into .claude/rules/<area>.md with paths frontmatter:
|
|
138
|
+
---
|
|
139
|
+
paths:
|
|
140
|
+
- "packages/<area>/**/*.{ts,tsx}"
|
|
141
|
+
---
|
|
142
|
+
# rules content (now /compact-safe)
|
|
92
143
|
```
|
|
93
144
|
|
|
94
|
-
|
|
145
|
+
Then delete the nested CLAUDE.md (or shrink to a one-line pointer).
|
|
146
|
+
|
|
147
|
+
### Step 5 — Compact MEMORY.md to an index
|
|
95
148
|
|
|
96
|
-
|
|
149
|
+
`MEMORY.md` cap is **200 lines OR 25 KB whichever first**. Above it is silently discarded. Move detail into topic files:
|
|
97
150
|
|
|
98
151
|
```
|
|
99
152
|
~/.claude/projects/<proj>/memory/
|
|
100
|
-
├── MEMORY.md # INDEX ONLY (< 200 lines)
|
|
101
|
-
│
|
|
102
|
-
│
|
|
103
|
-
│
|
|
104
|
-
├── debugging.md #
|
|
105
|
-
├── api-conventions.md
|
|
106
|
-
└── performance.md
|
|
153
|
+
├── MEMORY.md # INDEX ONLY (< 200 lines, < 25 KB)
|
|
154
|
+
│ - "Debugging notes → debugging.md"
|
|
155
|
+
│ - "API patterns → api-conventions.md"
|
|
156
|
+
│ - "Perf learnings → performance.md"
|
|
157
|
+
├── debugging.md # On-demand detail
|
|
158
|
+
├── api-conventions.md
|
|
159
|
+
└── performance.md
|
|
107
160
|
```
|
|
108
161
|
|
|
109
|
-
### Step
|
|
162
|
+
### Step 6 — Skill listing budget cleanup
|
|
110
163
|
|
|
111
|
-
|
|
112
|
-
- Old "Last Change" entries (keep only latest)
|
|
113
|
-
- Resolved problems (move to domain docs)
|
|
114
|
-
- Code examples > 10 lines (reference file instead)
|
|
115
|
-
- Duplicate information
|
|
116
|
-
- Commented-out sections
|
|
164
|
+
If `/doctor` reports overflow, in order:
|
|
117
165
|
|
|
118
|
-
|
|
166
|
+
1. Set low-priority skills to `"name-only"` in `.claude/settings.local.json` → `skillOverrides`
|
|
167
|
+
2. Add `disable-model-invocation: true` to skills that should NOT auto-trigger
|
|
168
|
+
3. Trim each skill `description` + `when_to_use` (combined cap = 1.536 chars; configurable via `maxSkillDescriptionChars`)
|
|
169
|
+
4. Raise budget: `skillListingBudgetFraction: 0.02` in settings (default 0.01) OR env `SLASH_COMMAND_TOOL_CHAR_BUDGET=<chars>`
|
|
119
170
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
171
|
+
### Step 7 — Monorepo: exclude irrelevant ancestor CLAUDE.md
|
|
172
|
+
|
|
173
|
+
```jsonc
|
|
174
|
+
// .claude/settings.local.json
|
|
175
|
+
{
|
|
176
|
+
"claudeMdExcludes": [
|
|
177
|
+
"**/monorepo/CLAUDE.md",
|
|
178
|
+
"/abs/path/other-team/.claude/rules/**"
|
|
179
|
+
]
|
|
180
|
+
}
|
|
181
|
+
```
|
|
131
182
|
|
|
132
|
-
|
|
183
|
+
Arrays merge across settings layers (user/project/local/managed). **Managed policy CLAUDE.md cannot be excluded.**
|
|
184
|
+
|
|
185
|
+
### Step 8 — Conflict scan
|
|
186
|
+
|
|
187
|
+
Two rules that contradict make Claude pick arbitrarily. Diff sources of truth:
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
diff <(grep -h '^- ' ~/.claude/CLAUDE.md 2>/dev/null) \
|
|
191
|
+
<(grep -h '^- ' CLAUDE.md ./.claude/CLAUDE.md 2>/dev/null) | head -40
|
|
192
|
+
grep -rh '^- ' .claude/rules/ ~/.claude/rules/ 2>/dev/null | sort | uniq -d
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
## 5. CLAUDE.md target shape after compaction (~ 20 KB / 280 lines)
|
|
196
|
+
|
|
197
|
+
| Section | Budget | Overflow target |
|
|
198
|
+
|---|---|---|
|
|
199
|
+
| Title + 1-paragraph overview | 500 chars | — |
|
|
200
|
+
| Last Change (latest only) | 250 chars | git history |
|
|
201
|
+
| Stack table | 600 chars | — |
|
|
202
|
+
| Architecture tree | 1.000 chars | — |
|
|
203
|
+
| Critical Rules (bullets) | 4.000 chars | `.claude/rules/<topic>.md` (with `paths:` when scoped) |
|
|
204
|
+
| FORBIDDEN table | 1.500 chars | — (must stay visible) |
|
|
205
|
+
| Quality Gates pointer | 200 chars | `config/quality-gates.json` |
|
|
206
|
+
| Per-domain summary bullets | 200 chars each | `.claude/rules/<domain>.md` |
|
|
207
|
+
| `<!-- maintainer notes -->` | 0 cost | inline |
|
|
208
|
+
| **Total** | **≤ 20 KB / ≤ 280 lines** | rules / skills / hooks |
|
|
209
|
+
|
|
210
|
+
## 6. FORBIDDEN During Compaction
|
|
133
211
|
|
|
134
212
|
| Don't | Why |
|
|
135
213
|
|---|---|
|
|
136
|
-
| Delete rules entirely | Move to rules
|
|
137
|
-
| Remove FORBIDDEN table | Security
|
|
138
|
-
| Delete Last Change | Keep latest,
|
|
214
|
+
| Delete rules entirely | Move to `.claude/rules/` or skill instead |
|
|
215
|
+
| Remove FORBIDDEN table | Security visibility is the point |
|
|
216
|
+
| Delete Last Change | Keep latest, drop older |
|
|
139
217
|
| Remove architecture tree | Essential for navigation |
|
|
140
|
-
|
|
|
141
|
-
| Edit auto memory of other projects | Stay in current
|
|
218
|
+
| Truncate code examples mid-block | Reference the file instead |
|
|
219
|
+
| Edit auto memory of other projects | Stay in current `~/.claude/projects/<proj>/` |
|
|
220
|
+
| Edit Managed Policy CLAUDE.md | Org-controlled, cannot be excluded |
|
|
221
|
+
| Touch a `CLAUDE.md` referenced by `claudeMdExcludes` | User intentionally hid it |
|
|
222
|
+
| Trust `@import` to save context | It does NOT — imports load full at launch |
|
|
223
|
+
| Keep nested CLAUDE.md content critical | Lost after `/compact` — promote to rule with `paths:` |
|
|
142
224
|
|
|
143
|
-
##
|
|
225
|
+
## 7. Verification (mandatory after compaction)
|
|
144
226
|
|
|
145
227
|
```bash
|
|
146
|
-
|
|
147
|
-
wc -
|
|
228
|
+
echo "1) Per-file size"
|
|
229
|
+
wc -c CLAUDE.md ./.claude/CLAUDE.md 2>/dev/null # target each ≤ 20 KB
|
|
230
|
+
wc -l ~/.claude/projects/*/memory/MEMORY.md # ≤ 200 lines
|
|
231
|
+
|
|
232
|
+
echo "2) Aggregate boot cost"
|
|
233
|
+
{ cat CLAUDE.md ./.claude/CLAUDE.md ./CLAUDE.local.md 2>/dev/null
|
|
234
|
+
for r in $(find .claude/rules -name '*.md' 2>/dev/null); do
|
|
235
|
+
head -20 "$r" | grep -q '^paths:' || cat "$r"
|
|
236
|
+
done
|
|
237
|
+
} 2>/dev/null | wc -c # target ≤ 64 KB
|
|
238
|
+
|
|
239
|
+
echo "3) @import targets exist"
|
|
240
|
+
grep -hoE '@[^ )]+' CLAUDE.md ./.claude/CLAUDE.md 2>/dev/null | while read f; do
|
|
241
|
+
p="${f#@}"; [ -f "$p" ] || echo "MISSING: $p"
|
|
242
|
+
done
|
|
148
243
|
|
|
149
|
-
|
|
150
|
-
|
|
244
|
+
echo "4) Rules well-formed"
|
|
245
|
+
for r in $(find .claude/rules -name '*.md' 2>/dev/null); do
|
|
246
|
+
head -20 "$r" | grep -q '^paths:' && echo "scoped: $r" || echo "boot: $r"
|
|
247
|
+
done
|
|
151
248
|
|
|
152
|
-
|
|
153
|
-
|
|
249
|
+
echo "5) Suggested in-session checks (run manually):"
|
|
250
|
+
echo " /memory → list of all loaded files"
|
|
251
|
+
echo " /doctor → skill listing budget overflow check"
|
|
252
|
+
```
|
|
154
253
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
254
|
+
### Optional — install `InstructionsLoaded` hook for permanent visibility
|
|
255
|
+
|
|
256
|
+
```jsonc
|
|
257
|
+
// .claude/hooks.json
|
|
258
|
+
{
|
|
259
|
+
"InstructionsLoaded": [
|
|
260
|
+
{ "command": "echo \"$INSTRUCTION_PATH ($INSTRUCTION_REASON)\" >> .claude/memory/load.log" }
|
|
261
|
+
]
|
|
262
|
+
}
|
|
160
263
|
```
|
|
264
|
+
|
|
265
|
+
## 8. When to bail out and rebootstrap
|
|
266
|
+
|
|
267
|
+
If after compaction the project still exceeds aggregate 64 KB AND has 50+ rule files AND `/doctor` keeps overflowing, suggest a clean restart:
|
|
268
|
+
|
|
269
|
+
```bash
|
|
270
|
+
CLAUDE_CODE_NEW_INIT=1 claude /init
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
This launches the multi-phase interactive `/init`: subagent explores the codebase, asks follow-up questions, and presents a reviewable proposal of CLAUDE.md + skills + hooks before writing.
|