CLAUDE.md: 6 layers for Claude Code without losses

Claude.md System Config: 6 Layers for Rock-Solid Context in Claude Code

Claude Code starts every session from scratch: no project knowledge, no server details, no past fixes. This leads to repeated explanations and risks—from wiping production data to pushing secrets to the repo. The 582-line CLAUDE.md system solves this with 6 layers: from rules to automated hooks. Each layer evolved from real-world incidents.

Incidents That Shaped the Architecture

Three mishaps defined the approach:

• SNI-proxy via localhost. The agent swapped 127.0.0.1 for a real IP, breaking uploads. Root cause: no grasp of why that specific value mattered.
• Fail2ban lockdown. Multiple SSH logins in a minute got flagged as a brute-force attack, halting model training.
• Dataset wipeout. A "filter" command deleted files instead of just moving them.

Lessons learned: rules must analyze current values before changes, enforce a single SSH tunnel, and require explicit confirmation for deletions.

The 6-Layer Structure

Layer 1: Rules (9 files)

Loaded contextually: SSH rules don't clutter text tasks, debug rules skip style guides.

Layer 2: Memory (78 files)

Knowledge graph with 178 cross-references via [[filename]]. Core files always in context; topic-specific ones loaded on demand. Covers infrastructure, fixes, and pitfalls.

Layer 3: Handoffs

Session summaries: goal, achievements, failures, next steps. Example:

## Session Goal
Color checker: CNN sweep + diffusion.

## Done
- CNN baseline: median 1.99 deg (11M params)
- Sweep: crop128(3.17), bs16(2.04)
- Diffusion: epoch 5/50, loss 0.827

## What Flopped
- EfficientNet-B0: hash mismatch
- lr=3e-4: NaN without clipping

## Next Up
Inference for diffusion + visual sheets.

27 handoffs over 4 days prevent rehashing dead ends. Works across subscriptions.

Layer 4: Chronicles

Timeline of decisions: 3-7 lines per milestone. Complements handoffs with the full story.

Layer 5: Hooks

Automated Python scripts triggered by events (SessionStart, Stop, PreToolUse). Independent of model memory.

Example handoff hook:

# remind_handoff.py (Stop hook)
age = session_age_minutes()
if age < 15 or fresh_handoff_exists():
    return
print(json.dumps({
    "decision": "block",
    "reason": f"Session {int(age)} min, no handoff recorded."
}))

Layer 6: Skills (16 kits)

Trigger-based guides: "use this for stuck GPUs" instead of vague instructions.

Hooks vs Rules: Execution Guaranteed

Prompt rules get forgotten in long sessions. Hooks run mechanically. The startup hook validates CLAUDE.md links; the shutdown hook nudges for handoffs.

Supply Chain Defense: One-Line Config

In .npmrc:

min-release-age=7

Blocks packages younger than 7 days. Saved us from the axios 1.14.1 attack (Sapphire Sleet, March 31, 2026, 3-hour window). Python equivalent in uv.toml:

exclude-newer = "7 days"

Principles from 37 Research Papers

Distilled into rules:

• Proof Loop. No self-confirmation: demand external proof (tests from a fresh session).
• Structured Reasoning. Format: facts → trace → conclusions → verified hypotheses. Patch accuracy: 78% → 93%.
• Deterministic Orchestration. Fixed tasks (tests, linting) via shell scripts.
• Red Lines. Hard bans: "no deletes without confirmation," tied to specific incidents.

Others: generator-evaluator, multi-agent breakdown, agent security.

Metrics and Self-Updating

• 78 memory files, 178 links.
• 27 handoffs in 4 days.
• 96.9% KV-cache hit rate (83 sessions).

The config self-validates: SessionStart hook checks links after edits.

Key Takeaways:

• Handoffs and Memory prevent context loss across sessions.
• Hooks ensure critical actions happen.
• Supply chain shields: min-release-age=7 in .npmrc / uv.toml.
• Structured Reasoning boosts debug accuracy to 93%.
• Red Lines slash production risks.

Minimal stack: Deterministic Orchestration + Structured Reasoning + Supply Chain Defense + Handoffs.

Repo: github.com/AnastasiyaW/claude-code-config (MIT).

— Editorial Team