The .claude/ Folder Explained: How to Set Up Any Claude Code Project
Most developers skip the setup and just start prompting. They open Claude Code, type a request, and hope for the best. That is the mistake. A proper Claude Code project is not about the prompts you type in the moment. It is about the context you build before the first prompt ever fires.
I have been running my entire studio through Claude Code for weeks now. A Next.js SaaS app, a Shopify store with 42+ custom Liquid sections, an AI content pipeline, automation scripts, and more. My CLAUDE.md file alone is over 400 lines. And it is the single most important file in my repository.
Here is how the .claude/ folder system works, and how to set it up so Claude actually understands your project from the first message.
CLAUDE.md: The Project Brain
CLAUDE.md is the instruction manual for Claude Code. It gets loaded automatically at the start of every conversation. Not sometimes. Not when it feels relevant. Every single time. That makes it the most reliable way to give Claude persistent context about your project.
You can place a CLAUDE.md at the root of your repository, and Claude Code will read it before doing anything else. Think of it as a README, but written for an AI pair programmer instead of a human contributor.
What belongs in a CLAUDE.md:
- Project overview - what this project is, what it does, who it is for
- Project structure - directory layout with short descriptions of each folder
- Commands - how to run dev, build, test, lint, deploy
- Tech stack - frameworks, libraries, versions, and why they were chosen
- Architecture - data flow, auth flow, API routes, database schema
- Key conventions - naming patterns, color values, font sizes, brand rules
- Environment variables - what is needed (not the values, just the keys)
The key insight: be specific, not vague. Do not write "I use a glassmorphism design." Write the exact CSS class names, the exact hex colors, the exact font weights. Claude cannot guess your conventions. It can only follow what you document.
The .claude/ Folder Structure
Beyond the root CLAUDE.md, Claude Code uses a .claude/ directory for project-level configuration. Here is what lives inside:
.claude/
settings.json - Shared project settings (checked into git)
settings.local.json - Personal settings (gitignored)
CLAUDE.md - Alternative location for project instructionssettings.json is the project-wide configuration file. It handles things like enabled plugins and project-level tool permissions. Since it gets committed to git, your whole team shares the same Claude Code configuration.
settings.local.json is for personal overrides. This is where your individual tool permissions, MCP server configs, and local preferences live. It stays out of version control so each developer can customize their setup without affecting others.
You can also place a CLAUDE.md inside the .claude/ directory instead of the repo root - Claude Code checks both locations.
Three Levels of Configuration
Claude Code reads instructions from three levels, and they all stack:
- Project level - CLAUDE.md at your repo root (or inside .claude/). This is where 90% of your context should live.
- User level - ~/.claude/CLAUDE.md applies to every project on your machine. Good for personal preferences that span all your work.
- Enterprise/org level - Organization-wide settings that administrators can push to all team members. Useful for company-wide coding standards or security policies.
The project level is the one that matters most for day-to-day work. It is the file you will update the most, and the one that has the biggest impact on output quality.
The Memory System
Claude Code has a built-in memory system that persists across sessions. It lives at:
~/.claude/projects/<project-path>/memory/This is where Claude stores things it learns during conversations - behavioral corrections you give it, project-specific references, key decisions, and running notes. Unlike CLAUDE.md which you write manually, the memory directory is managed by Claude Code itself as you work together.
In my setup, the memory folder contains feedback rules (like "always use Phosphor icons, never emoji"), project references (API credentials locations, key IDs), and milestone tracking. Every new session, Claude picks up exactly where the last one left off.
The memory system is what turns Claude Code from a stateless tool into something that actually learns your preferences over time. If you correct Claude once - say, telling it to never use em dashes in your content - it stores that correction and applies it in every future session.
The /init Command
If you are starting from scratch, you do not have to write CLAUDE.md by hand. Claude Code has a built-in /init command that scans your repository and auto-generates a CLAUDE.md based on what it finds.
It will detect your package manager, test commands, build scripts, project structure, and common patterns. The generated file is a solid starting point, but treat it as a first draft. The real value comes when you customize it with the specific knowledge that only you have about your project.
Run /init, review what it generates, then start adding your architecture decisions, naming conventions, and the tribal knowledge that lives in your head but has never been documented.
What I Learned From 400+ Lines
My own CLAUDE.md covers a Next.js SaaS app, a Shopify store with dozens of custom Liquid sections, an AI content production pipeline, automation scripts, database schemas, deployment flows, and more. Here is what I have learned about writing effective project instructions:
Document your architecture, not just your stack. Saying "I use Next.js and Clerk" tells Claude almost nothing. Documenting the actual auth flow - from middleware check to database user creation to API route protection - tells Claude exactly how to work with your code. Include the data flow diagrams. Include the database schema. Include which API routes exist and what they do.
Be explicit about conventions. If your brand color is #e3fc02, write that down. If your text color must be #F5F5F7 and never plain white, write that down. If you use Phosphor Icons with bold weight and never Lucide, write that down. Claude will follow explicit rules reliably. It will guess at implicit ones poorly.
Include the "never do" list. Some of my most valuable CLAUDE.md lines are the negative rules: never use a specific word in prompts, never use em dashes, never mention refunds, never deploy to production without review. These constraints prevent mistakes that would be painful to catch after the fact.
Keep files focused. If your CLAUDE.md is growing past 200 lines for a single concern, consider splitting it up. You can use @imports to reference other markdown files, keeping your main instruction file clean while still giving Claude access to detailed documentation.
Add behavioral rules. Beyond code conventions, document how you want Claude to behave. Should it ask before making changes? Should it batch operations for efficiency? Should it always verify visually before confirming? These meta-rules shape the working relationship.
Tips for Your Own Setup
If you are setting up Claude Code for the first time, here is the path I would recommend:
- Run /init to generate a baseline CLAUDE.md
- Add your project structure with descriptions of what each directory contains
- Document your commands - dev, build, test, deploy, and any custom scripts
- Map your architecture - auth flow, data flow, API routes, database schema
- Write your conventions - colors, fonts, naming patterns, file organization rules
- Add your "never do" list - the guardrails that prevent costly mistakes
- Commit settings.json to git so your team shares the same config
- Keep settings.local.json gitignored for personal preferences
The investment pays off immediately. Instead of re-explaining your project every session, Claude arrives already knowing your stack, your patterns, your preferences, and your constraints. The conversations start at a higher level because the foundation is already there.
The Compound Effect
Here is the thing most people miss about CLAUDE.md: it is not just documentation. It is a compounding asset. Every convention you add, every behavioral rule you document, every architectural decision you record - they all stack. Session after session, Claude gets more effective because the instruction set gets more complete.
I started with maybe 50 lines covering basic project structure and commands. Now it is 400+ lines, and Claude can navigate my entire codebase - Next.js app, Shopify store, content pipeline, automation scripts - without me explaining anything. It knows the deployment flow. It knows the naming conventions. It knows the brand rules. It knows what not to do.
That is the difference between prompting and building a system. Prompts are ephemeral. A well-maintained CLAUDE.md is permanent context that makes every future interaction better.
If you are using Claude Code without a CLAUDE.md, you are leaving most of its capability on the table. Set up the folder. Write the instructions. Let it compound.
This article contains affiliate links. If you sign up through them, I earn a small commission at no extra cost to you.
This article contains affiliate links. If you sign up through them, I may earn a small commission at no extra cost to you. (Ad)
Back to all articles
