Claude Code is very good at the next twenty minutes. It is bad at the next three weeks.
That isn't the model's fault. On a real epic that spans several repos, has open decisions and a baseline someone measured last Tuesday, the code is rarely the hard part. The hard part is everything around it: what's already been verified, which theory was ruled out, what's blocked, and what it must never touch.
All of that lives in the conversation. And the conversation ends.
The pattern: one folder per epic
I now give every epic its own folder that holds no code. The code stays in its repos. The folder is the epic's desk, and every session starts there:
SYNC-108/
├── CLAUDE.md # HOW to work: rules, traps, boundaries
├── SYNC-108.md # WHAT is true: requirements, baselines, gates
├── reports/ # dated findings that never get edited
└── .git/ # yes, git init
A few rules keep it from rotting:
- Two documents, two jobs. One says what's true. The other says how not to screw it up.
- One home per fact. If you re-measure, edit that number in place. Never keep two copies.
- Rewrite, don't layer. Delete wrong text instead of adding an "outdated" banner above it.
- Keep a trap register. It's a list of things that already burned someone, and it's the most valuable section in the folder.
- Mark hypotheses as hypotheses. A guess that gets promoted to fact by accident is how a wrong fix ships.
-
git initit. Corrections become diffs, and when the epic ships, the folder is the handover.
The test: start a fresh session in the folder and ask, "What are the closure conditions, what's blocked, and what must you not touch?" If it answers correctly without your help, the desk works.
This is part 1 of Claude Maxxing, a field journal of the systems I build around Claude Code on real work. The full post has both document skeletons, the real trap entries from my folder, and a 10-minute setup guide:
Top comments (2)
If you want to read the full article go here: hatimpatwa.dev/blog/orchestrator-f...
🔥🔥