Stop Claude output drift with an 8-folder repo setup
Yuri VonchitzkiMost Claude Code setups start well. You create a clean CLAUDE.md file, write clear instructions, and the agent produces exactly what you need.
Then the project grows. Rules, domain knowledge, session state and agent definitions all go into that one file. Claude starts to behave inconsistently across sessions. When someone else on the team picks up the project, they must explain everything to the agent again from zero.
The cause of Claude output drift is file architecture, not prompt quality. Claude re-reads one mixed file every session and re-interprets it each time. The fix is to separate three types of information into folders: how Claude behaves (rules/), what Claude knows (context/) and where the workflow is (memory/). Commit rules/ and context/ to one shared GitHub repo, and keep memory/ gitignored.
How to fix Claude output drift: separate rules, context and memory
Output drift stops when you separate what Claude knows, how Claude behaves and where Claude is in a workflow. If state, context and rules share one file, the LLM re-interprets all of them in every session.
Claude Code is Anthropic's coding agent: it reads the project files at the start of a session and acts on them. CLAUDE.md is the instruction file that Claude Code loads at the start of every session, according to Anthropic's docs. The 8-folder setup that I use for every Claude project starts with three folders:
| Folder | Question it answers | What goes in it | How often it changes | Git |
|---|---|---|---|---|
rules/ | How should Claude behave? | Code style, brand voice, QA standards | Slowly | Commit it and apply it everywhere |
context/ | What should Claude know? | Audience definitions, topic taxonomies, approved data sources | When the facts change | Commit it |
memory/ | Where is the workflow now? | Runtime state only: where the pipeline is, what finished last | Every run | Keep it gitignored |
The context/ folder gives Claude facts about the world. It does not tell Claude how to act. The memory/ folder is the only folder that changes between runs.
The other five folders (schemas/, commands/, agents/, skills/, protocols/) sit on top of this foundation, depending on the build. But the separation of the first three folders resolves 90% of consistency issues. Naming the structure before you build is the same discipline I describe in the Automation Architecture Guide.
What the 8-folder setup looks like in practice
The .claude/ folder sits at the project root, next to CLAUDE.md. CLAUDE.md itself is only a routing board that points to the folders. If CLAUDE.md does not fit on one laptop screen without scrolling, it is too long.
Set up the shared workflow in four steps:
- Create a Claude Project. This is the workspace that each team member uses.
- Attach your GitHub repo in the file settings of the Claude Project. Anthropic's GitHub integration guide shows how to add a repo to the project knowledge. Claude Code updates the local repo during active sessions. Manual edits go to Git between sessions.
- Link every team member's Claude Project to the same repo. One committed folder structure becomes the shared brain. Behavior on day one matches behavior on day ninety.
- Add the settings files at the
.claude/root. Asettings.jsondefines which tools Claude can use and which paths Claude can write to, through theallowanddenyrules in Anthropic's settings docs. I recommend asettings.env.jsontoo, so that dev behavior does not leak into production.
Four places where teams break the setup
1. Putting context in the rules folder. People like to put audience personas into rules/ because a persona feels like an instruction. It is not an instruction. Before you put a file in rules/, ask one question: does this file tell the agent how to act, or what to know? If it is knowledge, move it to context/.
2. Using memory as a permanent database. In March 2026, I saw a state.json file grow out of control because an agent kept appending entire chat histories to it. The file was gitignored and was wiped during a commit, and weeks of refined project history went with it. Memory is for workflow position only. If information must survive a session reset, put it in context/.
3. Keeping everything in CLAUDE.md. Subfolders do not help if your root CLAUDE.md still holds 400 lines of instructions. You recreate the same problem in a different location. Use CLAUDE.md as an entry point, not a dumping ground.
4. Updating the repo but not syncing the Claude Project. Your team pushes an update to the repo, for example a new context file or a revised rule. Nobody clicks "Sync" in the Claude Project settings. The agent works on the old version, and you spend three hours debugging a prompt that is not broken. Make the project sync part of your commit habit.
Use my template repo
I packaged this architecture into a template repo. It contains the CLAUDE.md router, all eight subfolders, starter settings files and a SKILL.md that scaffolds the whole structure.
Clone it from GitHub. You can also import the SKILL.md file into Claude as a skill and use it in your next Claude Code build.
The bottom line
Three questions, eight folders, one structural separation. Stop mixing information types, and consistent output follows. If you still work with AI one chat at a time, read why I say you should stop chatting with AI and start building.
Build a calmer business,Yuri
Frequently asked questions
Why does Claude Code give inconsistent output across sessions?
Claude Code output drifts when rules, domain knowledge, session state and agent definitions all sit in one CLAUDE.md file. Claude re-interprets the whole mix in every session, so behavior changes from run to run. The cause is file architecture, not prompt quality. Separate how Claude behaves, what Claude knows and where the workflow is into different folders.
What goes in the rules, context and memory folders of a .claude setup?
In a .claude folder, rules/ holds how Claude behaves: code style, brand voice and QA standards, committed to Git. context/ holds what Claude knows: audience definitions, topic taxonomies and approved data sources. memory/ holds only runtime state, such as where the pipeline is and what finished last. memory/ is the only folder that changes between runs, and it stays gitignored.
How long should a CLAUDE.md file be?
A CLAUDE.md file should work as a routing board that points Claude to the folders in .claude/, not as a store for all instructions. A practical limit: if CLAUDE.md does not fit on one laptop screen without scrolling, it is too long. Keeping 400 lines of instructions in CLAUDE.md recreates the drift problem that subfolders are meant to fix.
How do I share one Claude Code setup across a team?
To share a Claude Code setup, create a Claude Project and attach the team's GitHub repo in the file settings. Each team member links their own Claude Project to the same repo, so one committed folder structure becomes the shared brain. After every push, sync the Claude Project, or the agent keeps working on the old version of the files.