Workspace Architecture: 7 Folders and CLAUDE.md That Keep Your Agent on Track
Without structure, Claude — and every other AI coding agent — loses context after roughly 25 messages. With the system in this guide, the agent remembers who you are, what the project is, and how to work, across the entire life of the project.
1. The Problem: Your Agent Forgets What You Discussed Yesterday
You start a project with Claude. You explain the audience, the visual style, the files that must not be touched. Claude picks it up immediately and works well through the first stretch of the conversation.
Around message 20–25, things start drifting. Claude proposes a change you already rejected. It forgets the color palette you defined. It adds code that breaks a constraint you set explicitly. This isn't a bug or a capability failure — it's how context windows work. Every model has a finite window of active memory, and as the conversation grows, older turns get pushed out. The agent isn't ignoring you; it genuinely can no longer see what you said early on.
This affects every AI coding agent: Claude, Codex (which runs GPT-5.5 and is on par with Claude Code today), Cursor, Copilot Workspace. The 7-folder structure and CLAUDE.md described here are not Claude-specific. They are a general workspace convention that works with any agent.
Message 5: Claude understands the project.
Message 15: All decisions are still in scope.
Message 25: It no longer knows there is a separate CSS file, that button styles are locked, or that it may only edit files under components/.
It starts reinventing — and sometimes breaking things that worked.
At the start of every conversation, Claude Code automatically loads CLAUDE.md from the project root. It immediately knows: who you are, what the project does, which tools are in use, what has already been decided, and what it must never touch — no re-explaining required.
/agent-onboarding-wizard.
2. The 7-Folder System — Your Project as a Well-Organised Office
A physical office has clear drawers: one for contracts, one for budgets, one for marketing materials. An AI agent needs the same thing — a structure that tells it where to look and where to write.
These seven folders are a convention, not an official spec. The key is consistency: once you and Claude agree that specs always live in 02-specs/ and decisions always go in 05-decisions/, the agent stops asking and starts knowing.
| Folder | Purpose | Who writes here | When to add files |
|---|---|---|---|
| 01-context/ | Project identity: who it is for, what problem it solves, the vision. Claude reads this at the start of every conversation. | You (once, at kick-off) | Before you start building. Update if direction changes. |
| 02-specs/ | PRD, technical SPEC, design decisions. Claude treats this folder as "what was agreed". | You + Claude | When you decide what to build and how — before implementation begins. |
| 03-src/ | Source code. Everything Claude writes and modifies. | Claude (primarily) | Always — this is the working heart of the project. |
| 04-tasks/ | Task lists, sprint plans, status of what is active vs. done. | You + Claude | At the start of each sprint. Claude updates it as it works. |
| 05-decisions/ | Decision log: what was decided, why, and what was deferred. Claude does not re-ask questions that have already been resolved. | You + Claude | Every time a significant decision is made — not just technical ones. |
| 06-assets/ | Images, fonts, sample data, reference documents. Claude knows where to look for source materials. | You | When importing design materials or background documents. |
| 07-output/ | Finished outputs: files ready for deployment, generated reports, data exports. Clearly separates "done" from "in progress". | Claude (primarily) | When something reaches completion. Do not store drafts here. |
Which folders to commit to version control
Not every folder needs to live in your repository. General guidance:
- Commit:
01-context/,02-specs/,03-src/,04-tasks/,05-decisions/ - Consider carefully:
06-assets/— depends on file size. Large binaries belong in Git LFS or cloud storage, not in the repo itself. - Usually skip:
07-output/— generated artifacts are typically reproduced on each deployment run.
Add to your root .gitignore:
07-output/ 06-assets/large-files/ .env .env.local
3. CLAUDE.md — The Briefing Your Agent Reads Every Morning
CLAUDE.md is a plain Markdown file that sits at the root of your project. Claude Code loads it automatically at the start of every conversation — you do not have to ask. Think of it as handing the agent a full project brief before every working session.
Without CLAUDE.md, every new conversation is like onboarding a contractor from scratch: re-explaining the audience, the style, the files that cannot be touched. With CLAUDE.md, the contractor read the brief before they arrived.
What goes in CLAUDE.md
A good CLAUDE.md covers five topics:
- Project identity — who is building this, for whom, and what it does
- Tools and environment — languages, frameworks, external services
- Working rules — common commands, code style, naming conventions
- Constraints — what must not change without explicit approval
- Voice and tone — if the project produces content (copy, UI text), what style is expected
CLAUDE.md for a course landing page project
# Project Context ## Who I am Solo founder, non-developer. Running online courses on Teachable. ## What this project is Landing page for an AI course aimed at startup founders. Built on Next.js 15. Audience: non-technical founders, ages 28-45, primarily English-speaking. ## Tools and environment - GitHub repo: my-org/landing-ai (default branch: main) - Supabase: storing lead records - Netlify: auto-deploy from main branch - TypeScript, Tailwind CSS ## Common commands - npm run dev — local dev server - npm run build — production build - npm run lint — lint check ## Hard rules - Do not modify globals.css without asking first - For every new file you create, tell me what you made and why - File names always in English, kebab-case (e.g. hero-section.tsx) - Do not alter the Supabase schema without explicit approval ## Voice and tone When writing UI copy: direct, warm, no technical jargon. The audience does not know programming terminology.
How to create CLAUDE.md
- Open your project folder in VS Code (or Cursor)
- In the sidebar, right-click the project name → New File
- Type
CLAUDE.mdand press Enter - Paste the template above, adapt it to your project, and save (
Ctrl+S)
Important: the file must be at the project root — directly alongside the 01–07 folders, not inside any of them.
You can also maintain a global ~/.claude/CLAUDE.md for org-wide rules that apply to every project. Claude loads both — the global file first, the project file on top. This is useful for cross-project conventions like commit message format or code review expectations.
planning.md, tasks.md, and decisions.md files. Run it with /new-project-from-prd inside Claude Code. Reading this guide first is still worthwhile — you will understand what the skill produced and know what to change.
4. Slash Commands — Encoding Team Patterns Once, Running Them Forever
A slash command is a small Markdown file you write once and invoke with /command-name. Claude substitutes the invocation with the full file content and acts on it. The filename (without the .md extension) becomes the command name.
The value is that large parts of working with an AI agent are recurring instructions. "Review the code you just wrote. Check edge cases. Look for duplication. Report by severity." If you type that from memory every time, you will eventually miss something — or drift from your own standard. If it is a slash command, your protocol is a file under version control.
Project-level vs. global commands
Commands in .claude/commands/ inside your project folder are scoped to that project. Commands in ~/.claude/commands/ in your home directory are available in every project — useful for general workflows like commit message generation or PR description formatting.
Creating a slash command: step by step
- In the VS Code sidebar, right-click the project name → New Folder → type
.claude→ Enter - Right-click
.claude→ New Folder → typecommands→ Enter - Right-click
commands→ New File → typereview.md→ Enter
Note: folders starting with a dot (.claude) are hidden in most OS file browsers. VS Code always shows them.
Contents of .claude/commands/review.md
This is the protocol that runs every time you type /review:
Review the code you wrote in this conversation. Work through these checks in order: 1. Logical correctness — does the code do what was asked? 2. Error handling — are edge cases covered? 3. Duplication — is there repeated logic that could be consolidated? 4. Style consistency — does it match the rest of the codebase? Output: a list sorted by severity. Critical → High → Medium → Low. If a category is clean, write "clean".
From now on, /review runs this full protocol — no retyping, no drift from the standard.
/plan — before starting a task, ask Claude to decompose it into steps and write them to 04-tasks/. /commit — generate a structured commit message from the changes made. /decision — log a new decision to 05-decisions/ in a consistent format.
5. Common Patterns and Conflict Resolution
What belongs in CLAUDE.md vs. in 05-decisions?
CLAUDE.md is for things that are always true — project identity, style, standing constraints. If something should not change between conversations, it belongs in CLAUDE.md.
05-decisions/ is for things that had context at a moment in time — "on date X we chose Y because Z". This is useful when you want to understand in six months why the project is built the way it is. Claude can read from there, but it does not auto-load the full directory the way it does CLAUDE.md.
What happens when a slash command and a decision file contradict each other?
Claude prioritises the most immediate, explicit instruction — meaning the content of the command that just ran — over background files it reads at session start. If there is a contradiction, resolve it in the source: update the command, or add a clarifying line to CLAUDE.md. Do not rely on Claude to resolve logical conflicts between two authoritative sources on its own.
Does the 7-folder model work with multiple repositories?
Yes, with one rule: one CLAUDE.md per repository. If you have a frontend repo and a backend repo, each gets its own CLAUDE.md describing its specific context. Rules shared across both repos belong in the global ~/.claude/CLAUDE.md.
Does this work with Codex and Cursor?
Yes. Codex reads AGENTS.md — the direct equivalent of CLAUDE.md. Cursor reads .cursorrules. The logical structure — 7 folders plus a session-loaded briefing file — transfers to any agent. Only the filename changes.
6. Troubleshooting
Claude is not following my CLAUDE.md
First check: is the file at the project root? Open a terminal and run ls -la (macOS/Linux) or dir (Windows) — CLAUDE.md must appear directly, not inside a subfolder.
Second check: did you open Claude Code from the right directory? Claude Code picks up the CLAUDE.md of the current working directory. If you launched it from a parent directory, it will not find your project's file.
Third check: did you save the file? Ctrl+S (or Cmd+S on Mac). Unsaved edits are invisible to Claude.
My /review command does not run
Check the path: the file must be at .claude/commands/review.md — yes with the leading dot, yes inside commands/.
Check the filename: the filename without .md is the command name. review.md → /review. If you named it differently, the command name will differ.
Try a fresh conversation: if you created or edited the command file while a conversation was already open, Claude may not pick up the change. Open a new conversation.
I edited CLAUDE.md mid-conversation and Claude did not notice
Claude loads CLAUDE.md once — at the start of the conversation. Changes made after the conversation is already open are not reloaded.
Solution: open a new conversation. If you have just made an important edit to CLAUDE.md and need it to take effect immediately, close the current conversation (Ctrl+W) and start a fresh one.
7. Where to Next
You now have a workspace structure and a CLAUDE.md — the agent knows who you are and what the project is. The next step is giving it hands: access to the external tools you already work in, so it can take action beyond the code editor.
That is what Guide 4 covers: Composio MCP — a connection layer that lets Claude operate inside GitHub, Notion, Gmail, and dozens of other services. Setup happens via a single claude mcp add command in your terminal, which we will walk through step by step.
Guide 5 closes the loop: how to turn your repository into an autonomous advisor — an agent that scans your codebase on a rolling basis and surfaces improvements before problems become incidents.