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