# .claude Folder Anatomy: Control Center for AI Coding

Author: Alex Chen
Published: 
URL: https://workless.build/posts/2026-03-29-claude-folder-anatomy-control-center-for-ai-coding.html

---

{{EXCERPT}}

---

March 29, 2026 • 9 min read • 569 HN points
.claude Folder Anatomy: Control Center for AI Coding
🧑‍💻
Alex Chen
AI Engineer @ workless.build
Most Claude Code users treat the
.claude
folder like a black box. They know it exists. They've seen it appear in their project root. But they've never opened it, let alone understood what every file does.
That's leaving 80% of Claude's power on the table.
The
.claude
folder is your control center. It holds your instructions, your custom commands, your permission rules, and Claude's memory across sessions. Once you understand what lives where, you can configure Claude to behave exactly how your workflow needs it to.
Two .claude Directories, Not One
Before we dive in, here's something that trips everyone up:
there are actually two .claude directories.
/your-project/.claude/
← Team config (committed to git)
~/.claude/
← Personal config (machine-local)
Project-level config is shared. Everyone on your team gets the same rules, same commands, same conventions.
Global
~/.claude/
holds your personal preferences and machine state — session history, auto-memory, your own custom commands.
Claude reads both and merges them. Project rules take precedence.
CLAUDE.md: The Most Important File
When you start a Claude Code session, the first thing it reads is
CLAUDE.md
. This file loads straight into the system prompt and stays in context for the entire conversation.
Whatever you write in CLAUDE.md, Claude will follow.
Tell Claude to always write tests before implementation? It will.
Say "never use
console.log
for errors, always use our custom logger"? It will respect that every time.
Most people either write too much or too little. Here's what actually works:
Write:
Build, test, and lint commands (
npm run test
,
make build
)
Key architectural decisions ("monorepo with Turborepo")
Non-obvious gotchas ("TypeScript strict mode, unused vars are errors")
Import conventions, naming patterns, error handling style
File and folder structure for main modules
Don't write:
Anything that belongs in a linter config
Full documentation you can already link to
Long theoretical explanations
Keep CLAUDE.md under 200 lines.
Files longer than that eat too much context, and Claude's instruction adherence actually drops.
Example: Minimal but effective CLAUDE.md
# Project Setup

## Tech Stack
- Next.js 14 (App Router)
- TypeScript strict mode
- Tailwind CSS
- Prisma ORM

## Commands
- `npm run dev` — Start dev server
- `npm run build` — Production build
- `npm test` — Run tests (Vitest)
- `npm run lint` — ESLint + Prettier

## Code Conventions
- Use named exports, not default
- Error handling: throw custom AppError, never raw Error
- Database queries: always use Prisma, never raw SQL
- API routes: /app/api/[resource]/route.ts

## Project Structure
- /app — Next.js pages and API routes
- /components — React components (client + server)
- /lib — Utilities and shared logic
- /prisma — Database schema and migrations
That's ~20 lines. It gives Claude everything it needs without constant clarification.
CLAUDE.local.md: Your Personal Overrides
Sometimes you have preferences specific to you. Maybe you prefer a different test runner, or you want Claude to open files differently.
Create
CLAUDE.local.md
in your project root. Claude reads it alongside the main
CLAUDE.md
, and it's automatically gitignored so your personal tweaks never land in the repo.
Pro tip:
Use
CLAUDE.local.md
for debugging preferences. Tell Claude to always log intermediate steps, or to prefer verbose error messages. When you push to production, your teammates don't inherit your debug mode.
rules/: Split Instructions by Concern
CLAUDE.md
works great for a single project. But once your team grows, you end up with a 300-line file that nobody maintains.
The
rules/
folder solves that.
Every markdown file inside
.claude/rules/
gets loaded alongside
CLAUDE.md
automatically. Instead of one giant file, you split instructions by domain:
.claude/rules/
├── api-conventions.md
├── testing.md
├── database.md
└── deployment.md
Each file stays focused. The team member who owns API conventions edits
api-conventions.md
. The person who owns testing edits
testing.md
. Nobody stomps on each other.
Path-Scoped Rules
The real power:
rules that only load for specific files.
Add YAML frontmatter to a rule file and it only activates when Claude is working with matching paths:
---
paths:
  - "src/api/**"
  - "src/handlers/**"
---

# API Handler Rules

All API handlers must:
- Validate input with Zod schemas
- Return standardized error responses
- Log requests to our observability stack
Claude won't load this when editing a React component. It only loads when working inside
src/api/
or
src/handlers/
.
Rules without a
paths
field load unconditionally.
This is the right pattern once your
CLAUDE.md
starts feeling crowded.
commands/: Custom Slash Commands
Out of the box, Claude Code has built-in commands like
/help
and
/compact
. The
commands/
folder lets you add your own.
Every markdown file you drop into
.claude/commands/
becomes a slash command.
A file named
review.md
creates
/project:review
. A file named
fix-issue.md
creates
/project:fix-issue
.
Here's a simple example:
# .claude/commands/review.md

Review the changes in the current branch:

```
!git diff main...HEAD
```

Look for:
- Breaking changes
- Missing tests
- Performance issues
- Security vulnerabilities
Now run
/project:review
and Claude automatically injects the real git diff into the prompt before processing it.
The
!
backtick syntax runs shell commands and embeds the output. That's what makes custom commands genuinely useful instead of just saved text.
Commands with Arguments
Use
$ARGUMENTS
to pass text after the command name:
# .claude/commands/fix-issue.md

Analyze GitHub issue and propose a fix:

```
!gh issue view $ARGUMENTS --json title,body,comments
```

Based on the issue above, suggest:
1. Root cause
2. Implementation approach
3. Test cases needed
Running
/project:fix-issue 234
fetches issue #234 and feeds it to Claude.
Personal Commands
Project commands in
.claude/commands/
are committed and shared. For commands you want everywhere regardless of project, put them in
~/.claude/commands/
.
Those show up as
/user:command-name
instead of
/project:command-name
.
Useful personal commands:
Daily standup helper
Commit message generator following your style
Quick security scan
Explain this codebase (for jumping into new projects)
skills/: Automatically Triggered Workflows
Commands are
explicit
— you type
/project:review
to trigger them.
Skills are
automatic
— Claude decides when to use them based on your request.
Example: You have a skill for "deploy to staging." When you say "push this to staging," Claude sees the skill, realizes it matches, and executes it without you typing a slash command.
Skills are more complex than commands because they include:
Trigger conditions (when to activate)
Multi-step workflows
Error handling
Most solo builders don't need skills. Commands are simpler and cover 90% of use cases. But if you're building repeated multi-step processes, skills are worth learning.
Practical Workflow for Solo Builders
Here's my current setup after two months of heavy Claude Code usage:
Project-Level (.claude/ in repo)
CLAUDE.md:
Tech stack, key commands, 15-20 lines
commands/review.md:
Git diff analysis
commands/deploy-staging.md:
Deploy script with safety checks
rules/api.md:
API conventions (path-scoped to
src/api/
)
Global (~/.claude/)
CLAUDE.md:
My personal coding preferences
commands/standup.md:
Generate standup based on recent commits
commands/commit.md:
Generate commit message from staged changes
Typical Session
Open Claude Code in project
Claude auto-loads project CLAUDE.md + my global preferences
I ask "refactor the auth system to use middleware"
Claude knows our auth conventions from
rules/api.md
It refactors, I review with
/project:review
I deploy with
/project:deploy-staging
Total time: 10 minutes. Without the custom setup, this would take 30+ minutes of back-and-forth clarifications.
Common Mistakes to Avoid
1. Writing a Novel in CLAUDE.md
I see projects with 500-line CLAUDE.md files. Claude can't keep that in context. It starts ignoring instructions halfway through.
Keep it under 200 lines. Move specialized rules to
rules/
with path scoping.
2. Not Using CLAUDE.local.md
Don't pollute the team's CLAUDE.md with your personal preferences. Use CLAUDE.local.md for debugging modes, verbose logging, or alternative workflows.
3. Creating Commands for Everything
Commands are great for repeated tasks. They're overkill for one-off actions.
Ask yourself: "Will I use this 5+ times?" If no, just type the prompt directly.
4. Forgetting to Test Commands
Commands that run shell scripts can break your environment if they fail. Always test in a safe branch before committing.
Advanced: Memory and Session State
Claude Code stores session state in
~/.claude/.state/
. This includes:
Conversation history
Auto-memory (facts Claude learns about your project)
File context from previous sessions
You generally don't touch this manually. But if Claude starts "remembering" wrong information, you can clear state:
rm -rf ~/.claude/.state/
This resets Claude to a fresh session.
What to Do Next
Open your project's
.claude/
folder (or create it)
Create a minimal
CLAUDE.md
— 20 lines covering your tech stack and build commands
Add one custom command for your most repeated task
Use Claude Code for a week
Iterate: add rules and commands as you notice repeated clarifications
Starter template:
Copy the example CLAUDE.md from this post, replace the tech stack with yours, and commit it. You'll immediately notice Claude asking fewer questions.
The
.claude
folder is how you stop treating Claude like a chatbot and start treating it like a team member who knows your project.
Once you have this configured, you'll wonder how you ever coded without it.
Further reading:
Full .claude folder guide
|
Official Claude Code docs

---

Topics: {{KEYWORDS}}

© 2026 Work Less, Build. All rights reserved.