Claude Code doesn't need a better prompt. It needs a desk.

Claude Code is very good at the next twenty minutes. It is bad at the next three weeks.

That is not a model problem. Give it a real epic (one that spans three repos, has six known defects, a baseline someone measured on Tuesday and a handful of open decisions) and the code is rarely the hard part. The hard part is everything around the code: what we've already verified, which theory we ruled out and why, what's blocked on someone else, and which systems it may read but must never touch.

All of that lives in the conversation. And the conversation ends.

This is the first post in Claude Maxxing, a field journal of the systems I build around Claude Code on real client work rather than toy repos. It starts with the pattern I'd most want a teammate to steal: a dedicated folder for each epic, where the knowledge lives.

Where does epic knowledge go?

Think about what a two-week investigation actually produces. It isn't only diffs. It's findings, numbers, dead ends, and a growing list of things that look safe and aren't. Every obvious home for that knowledge is wrong:

• The repo's CLAUDE.md. Now every developer on that repo loads your epic's trivia in every session, forever. You have to commit it, and when the epic ships it becomes archaeology nobody dares delete.
• The ticket. Jira is not a working document. Nobody re-reads a forty-comment thread, and neither does the agent unless you make it.
• Your head. It survives until Friday.
• Nowhere. Then every session re-derives it, badly, and walks into the same traps. I have watched a session spend twenty minutes rediscovering something the previous session had already proved.

A better prompt doesn't fix any of these. The knowledge needs somewhere to live that outlasts the session, isn't the code, and that the agent reads before it does anything.

The pattern: a folder that isn't a repo

For each epic I create a folder that holds no code at all. The code stays in its repositories. This folder is the epic's desk: requirements, findings, decisions, traps and open work. Every session on the epic starts here.

SYNC-108/                  # named for the epic; it IS the epic's workspace
├── CLAUDE.md              # HOW to work: rules of engagement, traps, boundaries
├── SYNC-108.md            # WHAT is true: requirements, baselines, gates
├── reports/               # dated, immutable findings
│   ├── 2026-08-20_findings_lag-root-cause.md
│   ├── 2026-08-20_findings_duplicate-app-sweep.md
│   └── 2026-08-21_SYNC-112_comment-draft.md
├── .mcp.json              # read-only data access for this epic (gitignored)
├── .git/                  # yes, git init. More on that below.
└── .gitignore

It sits beside the repos it coordinates. Claude can read and change those repos, but whatever it learns comes back here.

Two documents, two jobs

This is the split people get wrong by merging. There are two questions a fresh session needs answered, and each gets its own document.

SYNC-108.md answers "what is true, and what must be true when we're done?" It's the requirements reference: closure conditions written so they can be tested, the canonical baseline numbers, open decisions and who owns them, what's explicitly out of scope, and code anchors verified against a specific commit.

# SYNC-108: Requirements reference
 
## 1. Identity (ticket keys, tree, status)
## 2. Outcome and closure conditions (what "done" means, testably)
## 3. Baseline numbers (CANONICAL: the only home for these)
## 4. Defects → ticket map
## 5. Gates, dependencies, open decisions (who owns each, what unblocks it)
## 6. Explicitly out of scope
## 7. Code-truth anchors (verified <date>, repo @ <commit sha>)
## 8. Ticket text vs. the code today
## 9. Leads (HYPOTHESES: verify, do not cite as fact)

CLAUDE.md answers "how do I not screw this up?" It's the operating manual: how to work here, which repo owns which fact, the traps, and the boundaries. Claude Code loads it automatically when a session starts in the folder, so its first line should stop the first mistake a fresh session makes, which is looking for source files.

# SYNC-108 coordinator: session brief
 
**You are in the coordinator folder, not a code repo.** Code lives in
the sibling repos listed in §3.
 
Read in this order:
1. `SYNC-108.md`: every requirement question is answered there.
   Do not re-derive it from Jira.
2. This file: how to work, the traps, what you may and may not touch.
3. The owning repo's own CLAUDE.md before you change anything in it.
 
## 1. What this epic is, in three lines
## 2. Rules of engagement
## 3. The repos, and which one owns which fact
## 4. Data access, and the read-only discipline
## 5. Standing traps        <- the most valuable section; add to it every session
## 6. Conventions for documents in this folder
## 7. Where the work stands (YYYY-MM-DD)

The rules that keep it honest

A folder full of markdown rots like any other documentation. These are the rules that have stopped mine from rotting, and each one was learned the hard way.

One canonical home per fact

A number lives in exactly one place. If you re-measure and get something different, you edit that table and note the date. You don't add a second table. Two numbers in circulation is how a wrong fix ships, and it usually starts with someone being too polite to overwrite.

Rewrite, don't layer

Corrections replace the wrong text in place. No "⚠️ the section below is outdated" banner above text that's still there. A reader who notices the banner is lucky; the next one skims past it. If it's wrong, delete it.

Findings are dated and immutable

reports/YYYY-MM-DD_<kind>_<topic>.md records what we knew and when. The living conclusions get rewritten in the two main documents, which link down to the dated findings as evidence. Never edit a dated finding so it looks right in hindsight, and never treat an old handoff note as current state.

Keep a trap register

The most valuable section in the whole folder is the list of things that have already burned someone. A few real entries from mine:

• Docs that lie about the code. Every file-and-line reference in the tickets was stale. Locate by symbol, never by line number.
• Code that shadows other code. Two apps in the monorepo hold parallel copies of the same filters and views, so a change made in only one is invisible on half the screens. An earlier version of this entry said the opposite and cost a full session. It's now corrected in place, with the routing chain spelled out so the next reader can check it in thirty seconds instead of trusting me.
• A deliberate misspelling. A directory named assests/ matches a framework scaffold and downstream imports. Do not "fix" it. It's exactly the tidy-up an eager agent does unprompted.
• A bug that heals itself. Any upstream edit forces a re-sync, so stale records fix themselves the moment someone looks. Reproduce by measuring a cohort, never by chasing one record.

None of these is in any ticket, and every one of them would have been rediscovered the expensive way.

Label hypotheses as hypotheses

Leads that aren't verified yet get their own section, each with what would confirm it. One of mine explains a 19-day median lag perfectly on paper, but the config it assumes has never been checked on the running instance. Until someone checks, it stays a hypothesis. A lead that gets promoted to fact by accident is another way a wrong fix ships.

Write the boundaries down, including the human ones

An agent has no way of knowing that another engineer owns a change unless you tell it.

**Do not, without asking:**
- Write to any production database. SELECT only.
- Edit, transition or comment on Jira. To comment, write a draft to
  reports/YYYY-MM-DD_<KEY>_comment-draft.md and tell me.
- Commit or push in any repo. Report the changed files and the
  commands you'd run, then wait.
- Touch the firewall rule on the shared subnet. Another engineer
  owns that change.

Why git init a folder with no code

Corrections become diffs. "When did we learn the shadow-app thing?" is answered by git log, not by memory. My last commit in that folder reads docs(sync-108): correct the shadow-app trap and the lag baseline. That's a changelog of the team's knowledge, and you can bisect it.

It scopes your tooling. Tools that resolve their state from the nearest git root (Claude Code's project settings, .mcp.json, the local issue tracker I'll cover next time) now treat the epic as its own project, rather than falling back to something shared across everything in your home directory.

It is the handover. When the epic ships, the folder is the handover. You don't need a meeting. The requirements doc says what "done" meant, the dated findings show the evidence, the trap register says what nearly went wrong, and the git log says when each thing was learned. Archive it, and the next person on that subsystem starts a week ahead.

Commit everything except secrets and client data. The conclusions travel; the raw exports don't.

Build one in ten minutes

1. Scaffold it beside the repos it coordinates.

EPIC=SYNC-108
mkdir -p ~/work/$EPIC/reports && cd ~/work/$EPIC
git init
printf '.mcp.json\nreports/*.xlsx\n*.db\n' > .gitignore

2. Write the two documents. Use the skeletons above. Don't try to fill every section on day one. Get the closure conditions, the repo-ownership table and the boundaries right, and let the rest grow as you learn.

3. Tell Claude what the folder is, once. From then on, the folder tells it.

This folder is the orchestrator for this epic. Keep every finding,
decision and open question here. Code changes go in the sibling repos;
knowledge comes back here. Read CLAUDE.md and SYNC-108.md first.

4. Commit, then test it cold. Start a brand-new session in the folder and ask:

What are the closure conditions, what's blocked, and what must you not touch?

If it answers correctly with no help from you, the desk works. If it improvises, your two documents aren't doing their job yet, and that's worth fixing before you write another line of code.

5. End every session by writing back. New trap? Add it to the register. Corrected a baseline? Edit the canonical table. Proved something? Write a dated finding and update the living doc. That last step is the habit that makes the folder worth having, and it's the one people skip.

What it doesn't fix

The folder makes knowledge durable. It doesn't make it true. An agent with a well-kept desk can still write a beautifully cited wrong answer, faster than before. A ticket marked Done whose fix was never merged, or a green CI run that collected zero tests, will be recorded in your folder just as faithfully as the truth. Verification is its own discipline, and it gets its own post.

It's also overkill for a one-ticket bug fix. Use it when the work outlives a session: anything that spans repos, needs investigation before implementation, or has more open questions than you can hold in your head.

Next in Claude Maxxing

The orchestrator folder is the desk. Next comes the memory that loads onto it automatically: a local issue tracker and a durable memory store, primed into every session by a hook, so a new session starts already knowing what's open and what's been learned. After that I'll cover giving it eyes (language servers and read-only MCP access to the systems you'd otherwise copy and paste from), and then the part that decides whether any of it pays off: making it prove things.

If you build one of these folders, I'd like to hear what ended up in your trap register. Get in touch.