Tag: CLAUDE.md

  • What 3 months building a 99-agent Claude Code system taught me about context

    What 3 months building a 99-agent Claude Code system taught me about context

    I went quiet for seven weeks. I was building something called RennOS, a Claude Code setup with 99 specialized agents across 20 departments that runs my whole brand and a chunk of my personal life. For most of those seven weeks, it was broken in a specific, frustrating way: the agents would start sharp and get dumber the longer I used them.

    Then something clicked. I stopped writing CLAUDE.md for myself. I started writing it for a version of Claude that has zero memory of this project, zero knowledge of what I tried yesterday, zero sense of what the file it just opened is supposed to do. That one mindset shift is when 99 agents actually started cooperating.

    This is what I learned about context, and why the fix is almost never a better prompt.

    Why your sessions get dumber

    There’s a post on r/ClaudeAI from a couple of months ago that stuck with me: “You accidentally say ‘Hello’ to Claude and it consumes 4% of your session limit.” 6,200 upvotes. The replies were full of people describing the same thing, a session starts fine, then halfway through the model starts forgetting what you asked twenty messages ago, or blending two unrelated tasks together, or confidently hallucinating a file path that doesn’t exist.

    The instinct is to blame the prompt. Or blame the model. Or wait for a bigger context window. I did all three for about a month.

    What’s actually happening is simpler. Context inside a session is like a desk. Every message adds another sheet of paper. Eventually there’s no room left to think, and the model starts reaching for whatever’s on top. Joshua Chakmanho put it cleanly on Twitter recently: “the more the context accumulates, the more dumb the model is.” That matched my experience exactly.

    The fix isn’t a bigger desk. It’s a different workflow. Here are the four patterns that actually moved the needle for me.

    1. Treat every session like a cold start

    This is the mindset shift. Everything else follows from it.

    Clean wooden desk in warm morning light with a blank open notebook, sharpened pencil, and steaming tea, representing a fresh Claude Code session cold start.

    Stop thinking of your chat history as memory. It isn’t memory. It’s scratch paper that gets thrown away when the session ends, and it poisons the model’s attention long before that. If you’re relying on “I told Claude about this earlier in the conversation,” you’re building on sand.

    The first thing I did inside RennOS was make the CEO agent, the top-level orchestrator, explicitly state in its own instructions that every session is a cold start. Not as a reminder to me. As a reminder to itself. The CEO agent opens every session by reading a set of files in .claude/ceo-memory/, because it genuinely does not remember what it decided yesterday. It has to re-read.

    That sounds inefficient. It isn’t. A session that rebuilds its context from durable files is always sharper than a session that’s been stewing in its own output for two hours.

    2. Keep memory in markdown, not in the session

    Once you accept the cold start, the next question is obvious. Where does the state live?

    Wooden library card catalog with blank brass label holders and one drawer open revealing blank index cards, representing markdown memory files Claude Code agents read on demand.

    For me it lives in markdown files on disk. Nothing fancier than that. Andrej Karpathy has been talking about a pattern he calls WikiLLM. The idea is you give the model a wiki of text files and let it read what it needs instead of cramming everything into the prompt. Community implementations of the pattern have collectively pulled in thousands of GitHub stars over the past week, which suggests the rest of the ecosystem is landing on the same answer.

    RennOS uses this everywhere. The CEO agent has .claude/ceo-memory/ with files like org-chart.md, workflows.md, active_projects.md, and decisions.md. Each of the 99 specialized agents has its own .claude/agent-memory/<agent-name>/MEMORY.md, which gets loaded the moment that agent is spawned. Shared knowledge like brand identity and the content calendar lives in data/, where any agent can read or write it.

    The Twitter workflow alone has its own eight-file brain under data/social/twitter/brain/: voice, patterns, posts, viral, analytics, growth-strategy, daily-activity, and a MEMORY file. When the short-form writer gets spawned to draft a reply, it reads those files fresh. No session state required. No “remember what we talked about on Tuesday.” Just files.

    The payoff is that the system survives a cold start perfectly. Close the laptop, open it tomorrow, and every agent boots up with the same brain it had yesterday. Better, actually, because the files have been edited to be clearer.

    3. Split the roles

    This one took me the longest to accept, because it felt wasteful at first.

    Warmly lit workshop with three separate craft stations for writing, editing, and labeling, representing Claude Code's split-role multi-agent architecture.

    The instinct when you’re using Claude Code is to let one session do everything: research the problem, plan the approach, write the code, review the code, commit the code. It feels faster. It isn’t. By the time the model is reviewing its own code, its context is half-full of the exact reasoning it used to write it, which is the worst possible state for catching its own bugs.

    Inside RennOS, every agent has exactly one job. There is a long-form-writer for blog posts. There’s a content-editor that reviews drafts and never writes them from scratch. There’s an seo-specialist that adds metadata and never touches the prose. There’s a research agent that reads the web and dumps findings into data/, and a strategy agent that reads those findings and makes recommendations. They talk to each other through files, not through a shared session.

    You don’t need 99 agents to get this benefit. You can get most of it with two. Open one Claude Code session to research and plan. Close it. Open a fresh one to implement. Close it. Open a third to review. The review session has no attachment to the implementation because it genuinely didn’t write it. It’s the closest thing to a real second opinion you’ll get out of a single model.

    If you try only one thing from this post, try that.

    4. Write every file for a future amnesiac

    This is the pattern the thesis tweet is about, and it’s the one that changed the most things at once.

    For the first month of RennOS, I wrote CLAUDE.md the way I’d write a note to myself. Short, gestural, full of phrases like “the usual workflow” and “the main agents.” I knew what I meant. The problem is Claude didn’t. Every cold-start session would open that file, hit a phrase like “the usual workflow,” and just… guess. Sometimes it would guess well. Often it wouldn’t.

    The shift was writing every file for a hypothetical fresh session that has never seen this project. That means:

    • Name the specific thing, not the category. Not “the main agents,” but “the CEO agent at .claude/CLAUDE.md, which delegates to 99 specialists listed in ceo-memory/org-chart.md.”
    • State the assumptions. If a workflow expects Asana to be connected, say so in the file, not in your head.
    • Leave no implicit context. If a decision has a reason, write the reason down. A future session will not remember why.
    • Define acronyms the first time. My own ADHD brain was happy to write “UAT gate” without defining User Acceptance Testing. A cold-start Claude was not.

    This is also where the 230+ skill playbook files in .claude/skills/ stopped being a mess and started being useful. Each skill is a markdown recipe another agent can follow, written for a reader who has never done this task before. They work because they assume nothing.

    The rule is simple. If a file only makes sense to someone who already has the context in their head, it will fail every cold-start session that opens it. Which is all of them.

    What to do Monday morning

    You don’t need to build RennOS to get the benefit of any of this. Here’s the smallest useful thing you can do.

    Pick one project where your Claude Code sessions keep going sideways. Open the project folder and create a CLAUDE.md file. Write it for a version of Claude that has never seen this project before. Name the specific files that matter. State the assumptions. Write down the two or three decisions that have a reason you’d otherwise have to explain out loud. Keep it short, but keep it specific.

    Then next time you open a session, let it read that file first and nothing else. Ask your question. See what happens.

    That single file changed more for me than any prompt tweak I’ve ever made. It’s a small habit with a big shape, and once you feel the difference you start writing everything this way.

    I’m going to keep sharing what worked and what didn’t from the RennOS build in future posts. No hype. No fear. Just what I tested.