archy/.claude/plans/rosy-floating-lightning.md

# Plan: Optimize Claude Code Instructions for Maximum Coding Performance

## Context

### The Problem
Research across Anthropic's official docs, engineering blog, GitHub issues, and academic papers converges on one finding: **instruction overload degrades Claude's coding performance**. The more tokens consumed by rules/instructions, the less attention and context remain for actual code generation.

Key evidence:
- Anthropic official docs: *"Bloated CLAUDE.md files cause Claude to ignore your actual instructions!"*
- Boris Cherny (Claude Code creator) uses ~100 lines / ~2,500 tokens for his CLAUDE.md
- Research (Jaroslawicz et al., 2025): instruction compliance decreases linearly as count increases; frontier models plateau at ~150-200 instructions; Claude Code's system prompt already uses ~50
- "Lost in the Middle" (Stanford, 2024): LLMs exhibit U-shaped attention — middle content gets least attention
- Anthropic engineering blog: *"Find the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome"*
- Aggressive language (BANNED, NEVER, CRITICAL, Non-Negotiable) overtriggers on Claude 4.5/4.6 — Anthropic explicitly recommends dialing it back
- Multiple GitHub issues (15443, 28158, 16073, 34197) document systematic instruction ignoring with large CLAUDE.md files

### Current State (Archy Project)

**Always-loaded instruction payload:**
| Source | Lines | Chars | Est. Tokens |
|--------|-------|-------|-------------|
| Global CLAUDE.md | 97 | 5,624 | ~1,400 |
| Project CLAUDE.md | 130 | 5,270 | ~1,300 |
| 5 rules files | 119 | 5,123 | ~1,280 |
| MEMORY.md index | 16 | 1,099 | ~275 |
| 33 skill descriptions (system) | ~300 | ~13,200 | ~3,300 |
| **Total always-loaded** | **~662** | **~30,316** | **~7,555** |

Plus ~10 memory files (~290 lines, ~19K chars) loaded on relevance, and 33 skills totaling ~122K chars loaded on demand.

### Key Problems Identified

1. **Global CLAUDE.md is ~60% things Claude already knows** — "Comment WHY not WHAT," "Functions under 50 lines," "Zero compiler warnings" are standard practices Claude follows without being told
2. **Anti-Hallucination section (28 lines) restates built-in behavior** — package verification is in Claude's training
3. **Redundancy across files** — security rules appear in global CLAUDE.md + crypto.md + api.md + project CLAUDE.md (4x)
4. **Aggressive language throughout** — "BANNED," "Non-Negotiable," "MANDATORY," "NEVER" — Anthropic says this causes overtriggering on current models
5. **Project CLAUDE.md duplicates rules files** — Frontend section repeats frontend.md, Security section repeats crypto.md + api.md
6. **Philosophy section is ~30 lines that don't affect code generation** — Claude won't suggest altcoins or proprietary deps regardless

### What We Preserve (per user request)
- All deploy commands, build commands, SSH access, CI/CD info
- All infrastructure keys/addresses/IPs
- Security and quality architecture rules that prevent real mistakes
- All memory files and feedback (operational learnings)
- All skills (they already use progressive disclosure correctly)

---

## The Plan

### Principle: Every line must prevent a specific mistake Claude would otherwise make

If Claude would do the right thing without the instruction -> delete it.
If Claude does the wrong thing even with the instruction -> make it a hook.
If it only matters for specific files -> scope it with globs in rules/.

### Step 1: Rewrite Global CLAUDE.md (~97 -> ~35 lines)

**Remove (Claude already knows these):**
- "Comment WHY not WHAT" — standard practice
- "Functions under 50 lines, single responsibility" — standard practice
- "Zero compiler warnings, zero linter errors" — standard practice
- "Remove dead code entirely" — standard practice
- "Deploy and verify changes" — project-specific, belongs in project CLAUDE.md
- Entire "Core Principles" enumeration (5 items) — the one-line philosophy header covers it
- "Encryption first" details — covered by crypto.md rules file
- Most of "Anti-Hallucination" section (28 lines) — Claude already verifies packages; keep only "cross-reference existing deps" which is non-obvious
- "Code Sourcing: What to avoid" items 3-4 — too specific, rarely triggered

**Keep (prevents real mistakes):**
- Bitcoin-only stance (1 line) — prevents suggesting altcoin libs
- Open source preference (1 line)
- Code sourcing core rules (no vibe-code repos, no vendoring without approval)
- Dependency selection order (rustls > openssl, etc.) — non-obvious preferences
- Security standards not in rules files (never commit secrets, pin versions)
- Project ecosystem listing — useful cross-project context
- Atomic commit format

**Rewrite style:** Calm, direct. No MANDATORY, no bold on every line.

### Step 2: Rewrite Project CLAUDE.md (~130 -> ~75 lines)

**Remove (duplicated in scoped rules files):**
- Frontend section (lines 70-77) — exact duplicate of .claude/rules/frontend.md
- Security section (lines 87-94) — duplicates crypto.md + api.md + containers.md
- "See .claude/rules/ for detailed..." pointer — Claude loads them automatically

**Remove (Claude already knows):**
- "No unwrap()/expect() — use ? with .context()" — standard Rust practice
- "tracing for logging, never println!" — standard practice
- "tokio runtime" — obvious from the codebase

**Keep and tighten (all non-obvious, prevents real mistakes):**
- Overview + Stack (essential context)
- Beta freeze status (active project constraint)
- Quick Reference commands (frequently used, non-guessable)
- Infrastructure table (IPs, keys, remotes — user explicitly wants these)
- Architecture diagram (essential mental model)
- Critical Rules (5 items — all non-obvious)
- Backend: only non-obvious rules (bind 127.0.0.1, path validation, timeouts)
- ISO Build commands (operational knowledge)
- App Integration Checklist (prevents real mistakes)
- Git conventions (one line)

### Step 3: Tone Adjustment (all files)

Per Anthropic's explicit guidance for Claude 4.5/4.6:

| Before | After |
|--------|-------|
| `.gradient-button` is BANNED | Use `.glass-button` for all buttons, not `.gradient-button` |
| Non-Negotiable | _(remove header, rules speak for themselves)_ |
| MANDATORY checks | _(remove, rules are clear)_ |
| NEVER use floating point | Sats are always integers (`u64`/`BigInt`), not floats |
| NEVER build Rust on macOS | Do not build Rust on macOS — deploy script handles cross-compilation |

This is not cosmetic — Anthropic docs state aggressive language causes overtriggering.

### Step 4: Tighten Rules Files

- **frontend.md** — Tone adjustment only (already 8 good rules, glob-scoped)
- **containers.md** — Reorder critical rules to top, tone adjustment. Keep UID table and systemd requirements (genuine lookup references)
- **api.md, bitcoin.md, crypto.md** — Tone adjustment only (already concise and glob-scoped)

### Step 5: Clean Up Memory Index

- Fix duplicate Session 2026-03-28 entry in MEMORY.md
- Add missing entries for untracked files (feedback_asset_workflow.md, project_iso_size_reduction.md, etc.)
- All memory file content preserved as-is

### Step 6: No Changes To

- **Skills** — Load on demand (correct architecture). 33 skill descriptions at ~100 tokens each is the design intent.
- **Hooks** — Already well-structured.
- **Settings** — Good as-is.
- **Rules file glob scoping** — Already correct.

---

## Expected Impact

| Metric | Before | After | Reduction |
|--------|--------|-------|-----------|
| Global CLAUDE.md | 97 lines / 5,624 chars | ~35 lines / ~2,100 chars | 64% |
| Project CLAUDE.md | 130 lines / 5,270 chars | ~75 lines / ~3,200 chars | 42% |
| Rules files | 119 lines / 5,123 chars | ~115 lines / ~5,000 chars | 3% |
| **Total always-loaded** | **346 lines / 16,017 chars** | **~225 lines / ~10,300 chars** | **35%** |

Key outcomes:
- Every remaining line prevents a specific, real mistake
- No redundancy between files
- Calm, direct tone matched to current model behavior
- Critical rules at top/bottom of files (exploits primacy/recency attention bias)
- ~1,400 tokens freed for actual code context per session

## Files to Modify

1. `/Users/dorian/.claude/CLAUDE.md` — Rewrite (97 -> ~35 lines)
2. `/Users/dorian/Projects/archy/CLAUDE.md` — Rewrite (130 -> ~75 lines)
3. `/Users/dorian/Projects/archy/.claude/rules/frontend.md` — Tone adjustment (BANNED -> positive)
4. `/Users/dorian/Projects/archy/.claude/rules/containers.md` — Reorder + tone
5. `/Users/dorian/.claude/rules/bitcoin.md` — Tone adjustment
6. `/Users/dorian/.claude/rules/crypto.md` — Tone adjustment
7. `/Users/dorian/.claude/projects/-Users-dorian-Projects-archy/memory/MEMORY.md` — Fix index

## Verification

1. Start a new Claude Code session on archy
2. Check infrastructure IPs, SSH keys, deploy commands are all accessible
3. Ask Claude to write a Vue component — should follow glass-button, script setup, style.css
4. Ask Claude to write Rust backend code — should use ?, bind 127.0.0.1
5. Ask Claude about deploying — should know deploy-to-target.sh, .228, .198
6. Ask Claude to add a container — should follow rootless Podman, UID mapping
7. Observe: faster responses, less hedging, more focused output