The first thing I do when setting up a new Claude Code workspace, before writing a single prompt, before connecting any tools, is sort out the file system. I've watched enough people skip this step to know what happens: three weeks in, Claude's putting files in random places, forgetting conventions you've told it five times, and producing output that sounds different every session. The workspace becomes a mess, and people blame the AI.
It's not the AI. It's the structure. Or rather, the lack of it.
Claude Code doesn't just respond to what you type. It reads your file system. It scans folder names, opens files, checks how things are organised. Your folder structure is, in a very real sense, a form of prompting. Get it right and Claude figures out where things belong, what conventions to follow, and how your business works, all without you saying a word. Get it wrong and you'll spend half your time re-explaining context that should have been obvious from the environment.
This is the part most guides skip. They jump straight to prompt techniques and automation recipes, assuming you'll work out the foundation yourself. I'd rather start here, because everything else in this series depends on it.
What a Claude Code workspace actually is
A workspace is a folder on your computer, opened in VS Code, with Claude Code running inside it. That's the whole thing. It's not a chat window or a conversation thread. It's a persistent working environment where your files live and Claude can read, write, edit, and organise them.
When you close VS Code and come back tomorrow, everything's still there. Your files, your folder structure, your instruction files. Nothing disappears between sessions. This is a fundamentally different experience from using Claude through the web interface, where each conversation exists in isolation with no file system and no persistence beyond the chat itself.
I use this analogy with clients: the web interface is like ringing a colleague and explaining what you need over the phone. A workspace is like sitting that colleague at a desk in your office, handing them the keys to the filing cabinet, and letting them get on with it. The colleague has the same skills in both scenarios, but in one of them they can actually find things without asking you every thirty seconds.
Most workspaces are backed by a Git repository, which just means every change is tracked and you can roll back if something goes wrong. You don't need to understand Git in detail to benefit from it. Think of it as an automatic safety net that records every edit, every new file, every deletion. If Claude makes a change you don't like, you can undo it with a single command. That matters when you're giving an AI agent genuine access to your files.
The combination of a persistent file system and version control is what makes Claude Code workspaces qualitatively different from chat-based AI. You're not having a conversation that vanishes when you close the tab. You're building a working environment that accumulates knowledge, structure, and convention over time. The workspace gets better the longer you use it, which is the opposite of what happens with a stateless chat interface.
Why folder conventions matter for Claude Code workspace setup
Claude reads folder names and file names to build its understanding of your workspace. When it sees Client-Projects/Acme-Corp/Proposals/, it knows exactly what those files are, who they relate to, and what category of work they belong to. When it sees stuff/misc2/old/, it knows nothing. It has to guess. And its guesses aren't always good.
I've seen this play out across dozens of setups. Consistent naming means Claude can locate any file without you pointing at it. If all your client work lives under Projects/ with one subfolder per client, Claude can find any client's documents immediately. If your proposals are scattered between Documents/, the Desktop, and something called new stuff/, you're going to spend time giving directions that should be unnecessary. Worse, when Claude can't find what it needs, it sometimes proceeds with assumptions rather than asking, and those assumptions lead to output that's off-target or inconsistent with your earlier work.
Structure also determines defaults. When Claude creates a new file, it needs to know where to put it. A clear convention means it follows the pattern automatically. No convention means it either asks (slowing you down) or guesses (creating mess).
What good structure looks like
For a small business, something like this works well:
Documentation/
Projects/
Client-A/
Client-B/
Templates/
Scripts/Each folder has a clear purpose. Documentation/ holds internal guides, policies, and reference material. Projects/ contains one subfolder per client or engagement. Templates/ stores reusable document templates. Scripts/ holds automation scripts as they develop over time.
A consultancy might extend this:
Documentation/
SOPs/
Policies/
Projects/
Active/
Client-A/
Client-B/
Archive/
Templates/
Proposals/
Reports/
Scripts/The specifics matter less than the consistency. Pick a structure that reflects how your business actually works, document it, and stick with it. Claude will learn it immediately.
Naming conventions
A few simple rules make a significant difference:
- Use descriptive names.
Q1-2026-Marketing-Report.docxtells Claude what it's looking at;report-final-v3.docxtells it almost nothing. - Date-prefix files with
YYYY-MM-DD. They'll sort chronologically by default, and Claude can reason about recency. - Avoid spaces in folder names where possible. Hyphens or underscores work better:
Client-Projects/rather thanClient Projects/. Spaces aren't fatal, but they create friction with command-line tools. - Spell things out.
Business-Development/is obvious to everyone, including Claude.BizDev/is obvious only to you. - Keep nesting shallow. Three levels deep is usually enough. Deeply nested folders are harder to work with for both humans and AI.
CLAUDE.md files: the core of your workspace structure
If you take one thing from this article, let it be this. A CLAUDE.md file is a markdown file that sits in your workspace and Claude reads at the start of every conversation. It contains your instructions: who you are, what the workspace is for, what conventions to follow, what to avoid.
Without one, every conversation starts from zero. You have to re-explain your preferences, your tone, your rules, your file structure, every single time. With a CLAUDE.md, Claude already knows all of this before you type a word. The prompting is embedded in the structure. You define it once, and it persists across every session indefinitely.
This is the mechanism that transforms Claude from a general-purpose AI into your AI, configured for your business, your conventions, and your way of working. I can't overstate how much difference this makes in practice. The people I work with who set up a solid CLAUDE.md on day one are the same people who, a month later, have Claude producing output in their voice without any per-session instruction at all. Those who skip it, or put in a couple of vague lines and call it done, end up frustrated and assume the tool is the problem. It isn't. The tool just needs to know what you need from it.
Where CLAUDE.md files live
A workspace can have multiple CLAUDE.md files at different levels:
- Master CLAUDE.md at the workspace root (or in
.claude/CLAUDE.md). This contains global rules: writing style, date format, terminology, branding, file organisation, and any preferences that apply everywhere. - Project-level CLAUDE.md inside subfolders. These add context specific to a particular client or project: the client's brand preferences, the project scope, relevant deadlines, instructions that apply only within that folder.
Project-level files inherit the master rules and extend them. If your master says "always use UK English" and a project file says "this client's brand is always capitalised as TechFlow", both apply when Claude's working in that folder.
You don't need project-level files on day one. Start with a single master CLAUDE.md. Add project-level files as your workspace grows. For detailed guidance and templates you can adapt, see the hub article on CLAUDE.md files.
What goes in a CLAUDE.md
Anything you want Claude to know at the start of every session. In practice, most people cover these categories:
Identity and purpose. Your business name, what you do, who your clients are. Two sentences is enough. Without this, Claude treats your workspace as generic. With it, every response is tailored to your domain from the first message.
Writing style. UK or US English. Formal or conversational. Whether you use Oxford commas, avoid certain phrases, or have strong preferences about sentence length. Once defined, Claude follows these consistently across every document, email, and report it produces.
File organisation rules. Where different file types should be saved. Be specific: "Client proposals go in Projects/[Client-Name]/Proposals/" is far more useful than "put things in the right place." Concrete rules mean fewer questions from Claude.
Terminology and branding. Product names with specific capitalisation, brand colours with hex codes, terms that carry particular meaning in your business. If your company name has a specific format, state it. Claude will use the exact form you specify, every time.
Constraints. Actions Claude should never take without asking. Files it shouldn't delete. Operations requiring explicit approval. Constraints matter as much as instructions. If there are sensitive folders or restricted operations, define them clearly.
Reference pointers. Paths to style guides, client briefs, templates, or process documentation. Claude can then read those files when needed rather than relying on your summary of their contents.
A working example
Here's what a minimal but effective CLAUDE.md looks like for a small consultancy:
# CLAUDE.md
## Workspace
This workspace belongs to Oakwood Consulting. We provide HR advisory
services to SMBs in Ireland and the UK.
## Writing Style
- UK English (organise, colour, behaviour)
- Professional but not stuffy. Write as if advising a peer.
- No jargon unless the audience is HR professionals.
## File Organisation
- Client work goes in Projects/[Client-Name]/
- Templates are in Templates/
- Internal docs are in Documentation/
- Never create files in the workspace root.
## Branding
- Company name is always "Oakwood Consulting" in full. Never abbreviate.
- Primary colour: #2B5F83
## Rules
- Never delete client files without explicit confirmation.
- Always use the letterhead template for client-facing documents.Twenty lines. Five minutes to write. And it means every conversation Claude has in this workspace starts with the right context, conventions, and constraints. No repeated instructions. No drift between sessions. If you'd asked me two years ago whether twenty lines of markdown could fundamentally change how a business uses AI, I'd have been sceptical myself. But I've watched it happen enough times now to know that this is where the real leverage sits, not in prompt engineering tricks or automation libraries, but in telling Claude who you are and how you work.
Rules files: when your CLAUDE.md outgrows itself
As your workspace matures, your CLAUDE.md will grow. You'll accumulate detailed instructions about citation formatting, blocked operations, content type guidelines, communication standards. At some point it becomes unwieldy in a single file.
That's where rules files come in. They're separate markdown files, typically stored in a .claude/rules/ folder, each covering a specific behaviour or domain. Claude loads them automatically alongside your CLAUDE.md.
.claude/rules/communication.mdfor UK English, tone, and formatting defaults.claude/rules/blocked-commands.mdfor operations requiring explicit confirmation.claude/rules/research-standards.mdfor citation format and source verification.claude/rules/file-organisation.mdfor detailed file placement rules
The split is intuitive: broad context and identity go in CLAUDE.md, specific behavioural rules go in rules files. You can update one rule without touching the others, share individual rules files across workspaces, and keep your master file concise while the detail lives in purpose-built, automatically loaded files.
You don't need rules files to get started. They become valuable as your instruction set grows beyond what fits comfortably in a single document. In my own workspace, I've got rules files for communication standards, research citation formats, blocked commands, content type formatting defaults, and several more. That level of granularity took months to accumulate. On day one, you need a CLAUDE.md and nothing else. The rules files will come naturally as your requirements become clearer.
Structure is the prompting
Once your workspace has a clear folder convention and a solid CLAUDE.md, something shifts. You stop repeating yourself. Every conversation starts with Claude already knowing your preferences, your conventions, and your expectations. You don't say "use UK English" because it's in the file. You don't say "put client files in the Projects folder" because it's in the file. You don't explain your branding, your tone, or your terminology. It's all loaded automatically, every time, before you've said anything at all.
The compound effect is real. On day one you save a few minutes of repeated context-setting. By week four, Claude's producing output in your voice without any per-session instruction. By month three, you're building automations on top of a stable, documented foundation, and they work because Claude already understands the environment it's operating in.
I've watched people skip this step and jump straight to the advanced features. They always hit the same wall. Automations break because files end up in unexpected places. Outputs are inconsistent because there's no defined style. Workflows fail because Claude doesn't know the conventions. They spend more time fixing problems than they saved by automating.
Structure is the prerequisite. It's not the exciting part, and nobody's going to make a viral post about folder naming conventions. But it's the thing that makes everything else work. If you take nothing else from this guide, take this: the quality of Claude's output is directly proportional to the quality of the environment you give it. A well-structured workspace with a thoughtful CLAUDE.md produces better results than any prompt engineering course will teach you, because you're not writing prompts any more. You're defining an operating environment.
Getting started: five practical steps
None of this requires technical expertise. If you can create folders on your computer, you can do this.
1. Create your workspace folder. Give it a clear, descriptive name. Inside it, create the basics: Documentation/, Projects/, Templates/. Three folders is enough to start.
2. Write your first CLAUDE.md. Create the file in your workspace root and write the essentials: your name, your business, your language preference, your basic file structure. Ten lines is enough to make a meaningful difference. Don't overthink it; you'll refine it over time.
3. Open it in VS Code with Claude Code. With Claude Code installed, open your workspace folder and start a conversation. Claude reads your CLAUDE.md automatically.
4. Test it. Ask Claude "What workspace is this?" or "Where should I save a client proposal?" If your CLAUDE.md is set up properly, Claude answers using the information you provided. It knows your context without you explaining it.
5. Build from there. As you work, you'll notice conventions you keep repeating, preferences Claude keeps getting wrong, rules you want enforced. Add them. The file grows organically as your workspace matures. For a complete setup checklist, see the new workspace checklist.
What comes next
With your workspace structured and your CLAUDE.md in place, you have the foundation for everything that follows in this series. The next article, How Claude Remembers (and Forgets), covers what Claude retains between sessions, what it loses, and how the available tools address the gap. Understanding how memory works is the second structural concept you need before moving into skills and automation.
Structure and memory. Get those two right and you're building on solid ground.