The Claude Code Folder Structure That Survives Real Clients

By Lazar Milicevic · Published June 21, 2026 · 9 min read

Every Claude Code tutorial shows you the first hour. None of them show you month nine, when three paying clients depend on the same folder and one wrong CLAUDE.md line breaks an invoice run at 6 a.m. If you've opened your own Claude setup after two weeks away and thought what was I doing here — that's a folder structure problem, not a Claude problem.

I run three live products from one projects/ directory on a small home server. One human, roughly 45 minutes a day of maintenance. The four conventions below are the entire reason that number is 45 minutes and not five hours.

The directory you're actually going to live in

Before the conventions, the shape. This is the real top-level layout, simplified:

projects/
├── CLAUDE.md                 # root: identity + guardrails (~40 lines)
├── commands/                 # 6 slash commands shared across all projects
│   ├── triage.md
│   ├── deploy-check.md
│   ├── run.md
│   ├── sweep.md
│   ├── bug-repro.md
│   └── daily-log.md
├── invoicing/
│   ├── CLAUDE.md             # project-level: stack, clients, quirks
│   ├── skills/               # verbs: how to do things
│   ├── context/              # nouns: client profiles, pricing, glossaries
│   ├── handoff/              # session notes, newest first
│   └── src/
├── gmail-ops/
│   ├── CLAUDE.md
│   ├── skills/
│   ├── context/
│   ├── handoff/
│   └── src/
└── leadgen/
    ├── CLAUDE.md
    ├── skills/
    ├── context/
    ├── handoff/
    └── src/

Four moving parts: a cascading CLAUDE.md, shared commands/, the skills/context split, and a handoff/ folder per project. That's the whole structure. Everything else is just code.

Convention 1 — Two CLAUDE.md files, never one

There's exactly one root CLAUDE.md at the top of projects/. It is the operating manual for every session inside any subfolder. It does not contain code instructions. It contains identity, tone, and guardrails.

The root file is short. Around 40 lines. Something like:

# Root operating manual

You are working inside a production environment with paying clients.

## Hard rules
- Never run destructive commands (rm -rf, DROP, force push) without an
  explicit confirm step that quotes the exact command back to me.
- Prefer small reversible changes over large refactors.
- If you are unsure which project's conventions apply, stop and ask.

## Session hygiene
- At the start of a session, read the latest file in ./handoff/.
- Before ending a session, run /daily-log.
- Write commit messages in imperative mood, no emojis.

## Tone
- Direct. No hedging. If something is broken, say it's broken.

Then inside each project folder there's a second CLAUDE.md that overrides and extends. The project-level file is where the specific stack, clients, and quirks live:

# Invoicing project

Stack: Python 3.11, pdfplumber, FastAPI, Postgres on the same box.
Clients: 3 (see context/clients.md for IDs and contact rules).

## Quirks that have burned me before
- Table extraction uses HTML, not markdown. Markdown loses column alignment
  on multi-line cells and silently produces wrong VAT totals.
- Never trust OCR confidence above 90% without a second pass. The vendor
  returns 0.94 on garbage roughly 1 in 40 invoices.
- Client 002 sends scans rotated 180°. Auto-rotate before parsing.

## Do not touch without asking
- src/pipeline/vat_rules.py
- migrations/ (run by cron at 03:00 UTC)

Claude reads both files automatically because of how the working directory cascades. The root gives you a consistent personality across all your work. The project file gives you the surgical context for that one job.

Why people merge them and regret it

• One giant file feels easier on day one — there's only one thing to edit.
• By day 30, the guardrails are buried under stack notes and Claude starts ignoring both.
• By day 90, you can't reuse the personality across a new project without copy-pasting and pruning, which nobody actually does.

Two files. Always.

Convention 2 — Six slash commands, shared across every project

There's a commands/ directory at the root. Six files in it. That's it.

These six cover roughly 90% of what I do across three completely different products. The trick: the commands themselves are generic, the behavior is specific, because each command reads the project-level CLAUDE.md and adapts.

Here's the actual /triage command, trimmed:

---
name: triage
description: Scan the current project for broken, stale, or inconsistent state.
---

You are running inside a project directory. Do these steps in order:

1. Read ./CLAUDE.md to load project-specific quirks.
2. Read the most recent file in ./handoff/ to load yesterday's state.
3. Run: git status, git log --oneline -10, and check for any files
   modified more than 14 days ago in src/ that are not tests.
4. Check ./skills/ and ./context/ for files referenced in CLAUDE.md
   that no longer exist.
5. Produce a prioritized list: P0 (client-facing broken),
   P1 (will break soon), P2 (cleanup). No prose, just the list.

Do not modify any files. Read-only pass.

Same verb, different noun, every time. /triage in the invoicing project surfaces VAT edge cases. /triage in the Gmail bot surfaces stuck threads. I never have to remember a project-specific command name.

Convention 3 — Skills are verbs, context is nouns

This is the one that took me longest to figure out and the one that will save you the most pain.

Split your supporting files into two folders:

• skills/ — verbs. How to do something. How to extract a table from a PDF. How to format a daily summary. How to draft a follow-up email in a specific tone.
• context/ — nouns. What something is. A client profile. A pricing sheet. A list of known customers. A glossary of internal terms.

invoicing/
├── skills/
│   ├── extract-table-from-pdf.md
│   ├── classify-vat-rate.md
│   ├── draft-payment-reminder.md
│   └── format-daily-summary.md
└── context/
    ├── clients.md
    ├── pricing-tiers.md
    ├── known-vendors.md
    └── glossary.md

If you mix these, your setup rots. Claude starts treating reference data as instructions and instructions as reference data. You end up with a model that "remembers" a client's billing address as a procedure to run.

Keep them apart. When you write a new slash command, it pulls verbs from skills/ and nouns from context/. Behavior stays predictable for months instead of weeks.

A quick test for which folder a file belongs in

• Does the file describe how? → skills/
• Does the file describe what or who? → context/
• Does it do both? → split it into two files. Always.

Convention 4 — The handoff folder is your stateless colleague's inbox

Every project has a handoff/ folder. At the end of every session, /daily-log writes a short markdown file in there:

invoicing/handoff/
├── 2024-11-18.md
├── 2024-11-19.md
└── 2024-11-20.md   ← read this first tomorrow morning

The format is fixed:

# 2024-11-20

## What I worked on
- Fixed rotation bug for client 002 (src/pipeline/preprocess.py).
- Added retry on OCR confidence < 0.90.

## Unfinished
- Client 003 onboarding — context/clients.md updated, but
  pricing tier still TBD pending their response.

## Known broken
- Nightly cron at 03:00 UTC fails on empty input batch.
  Workaround: skip if batch_size == 0. Real fix needed.

## Do not touch tomorrow
- migrations/ — running a backfill, will be done by Thursday.

## Next session should
- Implement empty-batch skip in cron.
- Reply to client 003 if pricing tier confirmed.

The next morning, the first thing the root CLAUDE.md tells Claude to do is read the latest handoff file. That single habit is the difference between starting tomorrow's session in 30 seconds versus 30 minutes.

You're leaving notes for a colleague who happens to be a stateless model. Treat them like one.

Putting it all together: a 45-minute morning

Here's what an actual morning looks like with all four conventions in place:

cd ~/projects/invoicing
claude                    # reads root + project CLAUDE.md + latest handoff
/triage                   # 30 seconds: prioritized list of what needs attention
/run --since=yesterday    # process anything new
/deploy-check             # if shipping
/daily-log                # write tomorrow's starting point

Then I cd into the next project and repeat. Three projects, about 15 minutes each on a calm day. The reason it stays at 15 minutes per project — not 60 — is that nothing in my head has to hold the context. The folder holds it.

Why bizflowai.io helps with this

This is the layer I set up for every client engagement on bizflowai.io before writing a single line of business logic. Most of the automation systems I deliver — invoice processing, lead enrichment, email triage — only stay maintainable because the folder conventions above are in place from day one. When a client takes over the system or hands it to their own developer six months later, they inherit a directory that explains itself, not a pile of prompts nobody remembers writing.

Frequently asked questions

What is the root CLAUDE.md file used for in a Claude Code project setup?

The root CLAUDE.md sits at the top of your projects directory and acts as the operating manual for every session in any subfolder. It contains identity, tone, and guardrails rather than code instructions, such as warnings against destructive commands, requirements to write handoff notes, and preferences for small reversible changes. It is short, around forty lines, and provides consistent personality across all work.

Why do I need two CLAUDE.md files instead of one?

Two CLAUDE.md files separate global behavior from project-specific context. The root file defines identity, tone, and guardrails that apply everywhere. Each project folder has its own CLAUDE.md that overrides and extends with stack details, client quirks, and surgical context for that job. Claude reads both automatically through directory cascading. Mixing these layers into one giant file is the most common mistake and causes setups to degrade over time.

What slash commands should I create for managing Claude Code projects?

Six reusable slash commands cover roughly ninety percent of work across projects: a triage command to scan for broken or stale items, a deploy check to run a production checklist, a run command to execute the main pipeline, a sweep command to find new inputs, a bug repro command to deterministically reproduce failures, and a daily log command to summarize sessions into a handoff file.

What is the difference between skills and context folders in Claude Code?

Skills and context are two separate folders for supporting files. Skills are verbs that describe how to do something, like extracting a table from a PDF, formatting a daily summary, or drafting a follow-up email in a specific tone. Context is nouns that describe what something is, such as a client profile, a pricing sheet, or a list of known customers. Splitting them prevents long-term maintenance pain.

Why does folder structure matter more than prompts for Claude Code workflows?

Folder structure determines whether maintaining multiple Claude Code products takes forty-five minutes or five hours a day. When Claude contradicts itself between sessions, slash commands behave inconsistently, or you spend mornings re-explaining your project, the cause is directory conventions, not the model. Proper structure using a layered CLAUDE.md, reusable commands, and split skills/context folders lets one person maintain several live products efficiently.

Want more like this?

I publish practical AI automation, GenAI engineering, and faceless content workflows on YouTube every week.

Subscribe to bizflowai.io on YouTube — never miss a new tutorial.

Planning an AI automation project or need a second opinion on your architecture?

Connect with me on LinkedIn — Lazar Milicevic, GenAI Engineer & bizflowai.io Founder.

Visit bizflowai.io for our services, case studies, and AI consulting.