Folders Matter To Claude Code

So I made a mistake. When I first started using Claude Code, I didn’t think about the folder structures it might need.

I didn’t appreciate how much the folders mattered, nor the sheer number of .md files they would end up holding. That made for two errors straight away, and together those two errors added up to a much harder time using Claude.

I’m going to show you how to set up your folders so you don’t waste as much time as I did. At the end, there’s a printable guide that summarises what I did.

First, what is an .md file?

The two-letter extension .md stands for Markdown, which is a simple way to format plain text.

A hash sign at the start of a line makes a heading, a hyphen makes a bullet, and a link is created by placing the words you want to make into a link within square brackets, followed by the address in round brackets, resulting in a clickable link. You can write Markdown in any text editor.

The .md file that matters most is called CLAUDE.md. Claude Code reads it at the start of every session and uses it as the basis for instructions about the project and your working style. Where your CLAUDE.md files sit decides what Claude knows, which is why the folder structure is important.

Why I stopped sorting projects by type

Some articles, and indeed Claude himself, might advise you to set up a hierarchical folder structure: a folder for WordPress, with one inside it for websites and another for plugins, and so on down. That’s what Claude suggested I did. But in my case it turned out to be a disaster. Why?

When you start Claude Code in a folder for Project A, it reads the CLAUDE.md in that folder and every CLAUDE.md in the folders above it. So in a tree sorted by type, the only way to share a rule is to put it in a folder above every project that needs it. That works as long as every project is only one kind of thing.

OLL! (short for Ooh La Langue) is the project I’m working on at the time of writing. It centres on French lessons built around graded stories, from beginner to advanced. But it is also several things at once. It comprises two WordPress websites, ten WordPress plugins (and counting), plus a desktop app that runs on my Mac.

Sorted by type, it ends up scattered across three branches of the tree, and the rules its various parts share have no specific place to live. So you copy them into each branch, and the copies drift apart. If I fix a rule in one copy the others are out of sync.

A library, and imports

Another way is to forget the strict folder hierarchy and use a flatter folder structure that is easier to handle.

The import statement makes this approach possible. A line in a CLAUDE.md file made of @ followed by a file path pulls that file in. So rather than managing large CLAUDE.md files full of instructions, I write each rule once, in one file dedicated to that type of rule, and keep all those files in one folder I call the library.

Every CLAUDE.md file imports the rules it needs, one @ line per file. When you change a rule in the library, every project that imports it gets the new version the next time a session starts, because there is only one copy to change.

In fairness, imports would also work in a tree folder structure sorted by type. But once you decide to even have a library folder where all the rules live, the project folders no longer need to be hierarchical.

Every project then sits at the same depth, so their import lines are identical, and I never have to struggle with which category a project belongs in. So mostly, I lay my projects out flat, side by side.

But my layout isn’t completely flat. In two places, a folder above shares its rules with the projects inside it, and I’ll explain both of these cases later.

How I set it up

I keep a single folder called AI Developer, and in it go all my projects, whatever they are. In my case, they could be WordPress sites, WordPress plugins or desktop applications. Inside it sit one file and three subfolders.

The house rules file

The house rules file is the top-level CLAUDE.md. That means it includes anything that applies to every project I work on.

Every project sits inside AI Developer, so Claude reads this file regardless of which project I open. It sets out my general working style with rules like :

• use British English
• avoid hedging
• push back with evidence
• never invent anything
• never write code unless you have my explicit permission to do so

It also sets out how a session starts and ends, and it forbids Claude to change any .md file without showing me the exact change and getting my agreement. This is the first of the two places where a folder above shares its rules.

Note that you could keep house rules in a personal CLAUDE.md instead, in a hidden folder called .claude in your machine’s home folder, and they would apply to every project on your computer. But I dislike hidden files, so mine live in AI Developer.

The three folders

Inside each project

Every project gets the same five subfolders, plus any extra folders for the code itself.

My house rules list the five folders detailed above and what goes in each, so Claude knows where things belong. And loose in the project folder itself are these .md files.

The files work because CLAUDE.md tells Claude Code what to do with them. At the start of a session, Claude reads the project diary, the state and the lessons, then tells me what he thinks we should tackle and why.

When I say “close the session”, Claude proposes new updates for lessons.md and audit-trail.md plus a rewritten state.md file. He shows me everything and waits for me to agree before updating anything.

Funky specs

“Funky spec” is my name for a functional specification. I basically outline what to build so everything is thought out and agreed upon before a line of code is written.

For example, a WordPress plugin gets a funky spec map, which is the whole plugin in one document (what it is, its modules, its data and its build rules), and then one funky spec per module.

When testing finds a bug, the fix goes into the spec and the code, so they stay in sync.

Simple, clean CLAUDE.md files

Each project’s own CLAUDE.md now only has to say what the project is and anything specific to it. Then it lists the library files the project needs, one @ line for each. The CLAUDE.md for a small bakery website would read something like this :

# CLAUDE.md : bluebell-bakery.com

A small bakery website, built in Bricks with ACF.
One mega menu. No blog.

@../../library/wordpress-site-build-rules.md
@../../library/wordpress-css-rules.md
@../../library/wordpress-acf-rules.md
@../../library/wordpress-mega-menu-rules.md

Each ../ climbs one folder: from the bakery’s folder up to projects, then up to AI Developer, and from there down into the library. A plugin that needs only my CSS rules has one @ line. A desktop app has none, because nothing in my library currently addresses desktop apps, although that may change.

Bigger projects

OLL! comes in two halves: OLL! Tools, the public site where learners use the lessons, and OLL! Works, the private workshop where the lessons are made.

Breaking this down a bit, OLL! Works gets one folder, oll-works, with its four parts inside it: two plugins, the desktop app and the website. Each part is a full project, with its own CLAUDE.md, diary, state, lessons, audit trail and holes, plus its specs and folders.

The top-level project folder oll-works has its own CLAUDE.md that notes anything common to all the OLL! component sub-projects. Every sub-project reads it. That’s the second place where my layout is not completely flat.

The parts sit one folder deeper than an ordinary project, so their @ lines climb one folder more: @../../../library/ rather than @../../library/.

Before you copy this

The guide