My CLAUDE.md is 582 lines. Six layers, and the failure behind each

Every new Claude Code chat starts from zero. It does not know the project, does not remember what we discussed an hour ago in the next window, and has no idea that one port on one server must not be touched. This post walks through the CLAUDE.md I built to deal with that: six layers, the incident that produced each of them, why a hook works where a written rule fails, the one setting that kept a compromised npm package off my machine, and which parts I would keep for an ordinary project. On 12 April 2026, when the Russian original came out, the config was 582 lines.

A CLAUDE.md is supposed to solve two problems at once: carry context between sessions and stop the agent from doing something irreversible. r/ClaudeAI has a new horror story every week. An agent dropped a production database. An agent pushed secrets to a public repository. An agent "optimised" a billing service until every customer got a zero invoice. The typical five-to-ten-line CLAUDE.md solves neither problem. I decided to treat it as an architecture task rather than a list of wishes, and every rule in it has a specific story behind it.

Three incidents behind the first rules

The agent "fixed" a working system. Sunday evening. The agent sees 127.0.0.1 in the config for an external storage service and decides a previous session left a mistake there. It puts in the real IP. Uploads break. Half an hour of debugging later it turns out the traffic went through an SNI proxy over a local tunnel, and 127.0.0.1 was the correct value. Without context, the obvious fix was the damage.

The rule that came out of it: do not change a config until you understand why the current values are what they are. If a value looks strange, understand it first and act second.

fail2ban took the agent for a brute-forcer. The agent was checking server state and opened a new SSH connection for every check. A dozen connections in a minute looked like an attack, and the IP was banned for half an hour. A training run was going on that box at the time, and I could no longer reach it.

Rule: one SSH bridge for everything, one client per session, and no separate scripts for check, fix and verify. Batch them into one call.

"Filter" turned out to mean "delete". I asked for a dataset to be filtered, meaning the unsuitable images taken out. The agent read it literally and deleted the files. Not moved, not marked. Deleted.

Rule: filtering means move or mark, never delete. Before any deletion, check that the user asked for deletion in those words.

Writing "be careful" does not work. It takes a system.

Six layers, none of them planned

Each layer appeared after a specific failure.

Rules, 9 files. Loaded by situation. When the agent writes an article it does not need the SSH rules; when it debugs code it does not need the rules about prose. Claude Code can pull in the rules file that matches the task.

Memory, 78 files. It appeared when the agent forgot a server's configuration for the third time. Between sessions it now keeps infrastructure settings, project decisions, my preferences and past mistakes. The files link to each other as [[filename]], 178 cross-links in all, so plain Markdown becomes a knowledge graph. Part of it always loads, the rest by topic.

Handoffs. They appeared when a new chat walked straight back into the previous chat's dead end. When a session closes, the agent writes a summary: what was done, what did NOT work (the valuable part), and one next action. A real one, translated from Russian:

## Session goal
Colour checker: CNN sweep + diffusion, first visual results.

## Done
- CNN baseline: median 1.99 deg (11M params, 21 MB)
- Sweep on 5 GPUs: crop128 (3.17), bs16 (2.04), lr3e-4 (NaN)
- Diffusion training started: epoch 5/50, loss 0.827

## Did NOT work
- EfficientNet-B0: hash mismatch in the Docker image
- lr=3e-4: NaN after epoch 10-13, no gradient clipping
- CNN, visually: three numbers give stray colour casts

## Next step
Inference script for diffusion + visual sheets with 24 patches

The next chat reads about 1,500 tokens instead of analysing the project from scratch. In four days 27 handoffs piled up, and not one dead end was repeated. It also works across accounts: I have three subscriptions, two for work and one personal, and a handoff lets me carry on in another one without explaining everything again. How this grew into a tool for several people working at once is in Several Claudes on one repo.

Chronicles. They appeared when, after twenty handoffs, it was no longer clear how the project had reached its current state. A handoff answers "what next"; a chronicle answers "how did we get here". Key decisions, turns and dead ends, three to seven lines per milestone.

Hooks. They appeared when the rule "check the links in CLAUDE.md" stopped being followed twenty minutes into a session. The next section is about them.

Skills, 16. Packaged knowledge for specific jobs. The description is written as a trigger for the model, "use when: GPU hung, server health check needed", not as "helps with servers".

A rule is a wish, a hook is a guarantee

This was the least obvious thing I learned in that month. A rule in CLAUDE.md is an instruction in a prompt. The model can forget it, reinterpret it, or drop it late in a long session when the context is full of other things. My "check the links before work" rule held for about ten minutes, and then the agent got absorbed in the task.

A hook is a Python script that Claude Code runs on an event: SessionStart, Stop, PreToolUse. It does not forget and does not reinterpret. It runs every time. Here is the one that asks for a handoff before a long session closes:

# remind_handoff.py  (Stop hook, simplified)
age = session_age_minutes()
if age < 15:
    return                      # short session, nothing to hand off

if fresh_handoff_exists():
    return                      # already written

print(json.dumps({              # block the close, ask for the handoff
    "decision": "block",
    "reason": f"Session ran {int(age)} min with no handoff. "
              f"Write one into .claude/handoffs/ before exiting."
}))

The model usually knows when it is time on its own, when a task is finished or the context is filling up. The hook covers the times it forgets.

If something has to happen every time, it is a hook, not a rule.

One config line against a supply-chain attack

On 31 March 2026 the official npm package axios, about 100 million downloads a week, was compromised through a maintainer's account (Elastic Security Labs). A malicious 1.14.1 went out at 00:21 UTC, and the bad versions stayed on npm until 03:15 UTC, about three hours (the axios post-mortem). Microsoft attributes the attack to Sapphire Sleet, a North Korean state actor (Microsoft Security Blog).

My .npmrc had one line in it:

min-release-age=7

Packages published less than seven days ago do not install. Most malicious packages are caught within one to three days, so seven is a comfortable margin. I was not affected, and it cost one line. The Python equivalent goes in uv.toml:

exclude-newer = "7 days"

The research behind it: 37 papers

A good share of the rules came not from my own mistakes but from academic work: 37 arXiv papers reworked into principles. Four of them changed my workflow the most.

• Proof loop. The agent says the tests pass; you check, and they do not. The proof loop forbids the agent from signing off its own work. It needs artefacts: test output, and a verdict from a verifier in a fresh session that never saw the work being done. Source: arXiv 2603.10165.
• Structured reasoning. Instead of a free-form "maybe this, maybe that": what we know for certain from code and logs, a step-by-step trace, what follows from it, and which hypotheses were tested and dropped. In Ugare and Chandra's experiments this kind of semi-formal reasoning raised accuracy on patch equivalence from 78% to 88% on curated examples, and to 93% on real agent-generated patches (arXiv 2603.01896).
• Deterministic orchestration. Anything deterministic, such as tests, linters and formatting, runs through a shell script. A model loses count in loops and mixes up branch conditions. A script does not.
• Red lines. Ordinary rules get interpreted creatively. Red lines are absolute prohibitions with no exceptions, each tied to an incident: do not delete without confirmation, do not change production configs without understanding them. The pattern comes from Chinese engineering teams, 红线, literally "red line".

The rest, from generator-evaluator and autoresearch to multi-agent decomposition, codified context, agent security and documentation integrity, are written up in the repository.

Numbers, and the place it failed

78 memory files. 178 cross-links. 27 handoffs in four days. A 96.9% KV-cache hit rate across 83 sessions in one week. The config maintains itself: after every change the agent checks whether any links went stale, and a SessionStart hook validates them automatically.

Does it work perfectly? No. An audit found four memory files that had dropped out of the index. Documentation drift, inside the system built to prevent documentation drift. Without the system it would have been worse.

What I am not sure about

I am not convinced everyone needs all of it. For most projects five principles would probably do: deterministic orchestration, structured reasoning, supply-chain defence, codified context and handoffs.

I am not convinced six layers is the minimum either. I may have over-built it. But in that month no context was lost and no dead end came back.

One of the principles, assumption testing, says it plainly. Every component of the setup encodes an assumption about what the model cannot do on its own, and models improve. Remove components and measure. Some layer here is probably unnecessary already.

What changed after April

Update, September 2026. The repository was renamed from claude-code-config to codex-claude-code-config, because the same principles, hooks and skills now drive Codex and mixed Claude and Codex sessions too, and the old name no longer described it. The old URL still redirects. On 23 September 2026 it held 30 principles, 58 skills, 35 rule files and 73 scripts in hooks/, with 150 stars and 24 forks on GitHub.

The figures in the sections above (9 rule files, 78 memory files, 16 skills, 37 papers, 582 lines) describe my setup on 12 April. They were true on that day, and I have left them as they were.

Where to start

Paste this into a Claude Code chat:

https://github.com/AnastasiyaW/codex-claude-code-config - study it, pick what fits my work and set up my Claude Code

Start small: supply-chain defence (one line in .npmrc), deterministic orchestration (tests through scripts) and structured reasoning (a format for debugging). Add the rest when a failure asks for it. Everything is under the MIT licence.

The project page on this site is codex-claude-code-config. The reference library that grew next to it is described in 785 articles for agents, not humans, and why I trust handoffs more than the desktop app's own session history is in 45 MB of Claude Code sessions you never look at.