1e283daf13
Container recovery: - Health monitor: MAX_RESTART_ATTEMPTS 3→10, interval 60s→120s - Dependency-aware restarts: won't restart services before their deps - Reset dependent counters when a dependency recovers - Handle "created" state containers (were invisible to health monitor) - Added IndeedHub, mempool-api, mysql to tier system - Crash recovery: podman start timeout 30s→120s with retry - Podman client: socket timeout 5s→30s, added restart policy UI state representation: - Exit code 0 shows "stopped" (gray), not "crashed" (red) - Exit code 137 shows "killed (OOM)" - Non-zero exit shows "crashed" (red) - Added exit_code field to PackageDataEntry Install/uninstall fixes: - Install returns error when container doesn't start (was silent success) - Post-install hooks awaited instead of fire-and-forget tokio::spawn - Uninstall: graceful rm before force, volume prune, network cleanup - Uninstall returns error on partial failure (was 200 OK) Config consistency: - DB passwords read from /var/lib/archipelago/secrets/ (was hardcoded) - Bitcoin: added ZMQ ports 28332/28333 for LND block notifications - IndeedHub port 7777→8190 (was conflicting with strfry) - Marketplace versions: LND 0.17.4→0.18.4, Mempool 2.5.0→3.0.0 Performance: - Metrics collector interval 60s→300s (was duplicating health monitor) - Podman client: proper error propagation instead of unwrap_or_default Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
175 lines
9.1 KiB
Markdown
175 lines
9.1 KiB
Markdown
# 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
|