Understanding the .claude Folder: Turning Claude from a Tool into a System

1. Claude Feels Inconsistent for a Reason

Most people use Claude Code the same way.

They open it, ask questions, generate code, and move on.

It works. But it also feels inconsistent.

Some days it follows patterns.
Some days it ignores them.
Sometimes it writes exactly what you expect.
Sometimes it drifts.

That inconsistency is not random.

It comes from how Claude actually works.

Claude is not just responding to your prompt.
It is operating inside a system.

That system includes:

Instructions it loads
Rules it follows
Permissions it respects
Context it carries across the session

And all of that is controlled by one place.

The .claude/ folder.

Most people never open it.
They treat it like a system folder. Something internal.

That assumption is wrong.

The .claude/ folder is the control layer.

It defines how Claude behaves inside your project.
What it follows. What it avoids. What it remembers.
And how consistent it stays over time.

If you ignore it, you get a helpful assistant.
If you understand it, you get a predictable system.

That shift matters more than any prompt you write.

2. Two Levels of Control Most People Miss

Before going deeper, there’s one detail most people don’t realize.

There isn’t just one .claude/ folder.

There are two.

One inside your project
One in your system (~/.claude/)

They serve different purposes.

The project-level .claude/ folder defines how Claude behaves for that codebase.

This is shared.

You commit it to git.
Your entire team gets the same:

instructions
rules
commands
permissions

This is what makes behavior consistent across developers.

Then there is the global ~/.claude/ folder.

This is personal.

It stores:

your preferences
your session memory
your reusable commands and workflows

This is not shared with your team.

A simple way to think about it:

Project .claude/ → how the system should behave
Global ~/.claude/ → how you prefer to work

This separation is important.

Without it, you either:

force personal preferences on the team
or lose consistency across projects

With it, you get both:

standardization at the project level
flexibility at the individual level

Once you understand this split, the rest of the structure becomes easier to reason about.

3. CLAUDE.md: The Instruction Layer That Actually Matters

At this point, it’s easy to get distracted by all the folders inside .claude/.

Ignore them for now.

If there is one file that actually matters early on, it is CLAUDE.md.

This is the first file Claude reads when a session starts. It gets loaded directly into its working context and stays there for the entire interaction.

Which means one simple thing.

Whatever you write here, Claude will follow.

If you define clear rules, it behaves consistently. If you leave it empty, you keep repeating yourself in prompts.

What CLAUDE.md is actually doing

It is not documentation.

It is not notes.

It is the instruction layer for how Claude should behave inside your project.

Instead of saying:

"use this pattern"
"don’t do this"
"follow this structure"

You define it once here, and Claude applies it every time.

What actually belongs in CLAUDE.md

Most people either overcomplicate this or leave it too vague.

The goal is simple.

Capture how your codebase works.

A practical CLAUDE.md usually includes:

1. Commands Claude should use


bash
npm run dev
npm run build
npm run test

2. Key architectural decisions

Monorepo setup using Turborepo
Shared utilities live in /packages
API layer is isolated from UI

3. Project structure


bash
src/
  api/         → backend logic
  components/  → UI components
  lib/         → shared utilities

4. Coding conventions

Use TypeScript strict mode
Prefer functional components
Use async/await for async flows

5. Non-obvious constraints

Unused variables are treated as errors
Do not modify .env files
Avoid direct DB access outside services

6. Patterns to follow

All API calls go through apiClient
Centralized error handling via logger
Keep business logic out of controllers

What does NOT belong here

This is where most people go wrong.

Do not include:

Long explanations
Full documentation
Generic best practices
Anything already enforced by tooling

If it doesn’t change how Claude behaves, it doesn’t belong here.

Keep it intentionally small

There is a trade-off most people miss.

More instructions do not improve behavior. They dilute it.

Once the file becomes too long:

context gets noisy
instruction adherence drops

A short, focused file works better than a detailed one.

In practice, most effective setups stay under ~200 lines.

The practical takeaway

CLAUDE.md is your highest leverage file.

It turns:

repeated prompting into defined behavior

Start with this.

Everything else in the .claude/ folder is an extension of it.

4. When One File Stops Scaling: The `rules/` Folder

CLAUDE.md works well in the beginning.

Small project. Few conventions. Everything fits in one place.

Then the project grows.

More modules. More patterns. More edge cases. And slowly, CLAUDE.md turns into a 300-line file that nobody maintains.

At that point, the problem is not Claude.

It's structure.

The limitation of a single file

A single file forces everything into one place.

API rules
UI conventions
Testing standards
Data handling patterns

All mixed together.

Over time:

it becomes harder to read
harder to update
easier to ignore

And once people stop trusting it, it stops working.

The idea behind `rules/`

The rules/ folder solves this by splitting instructions by concern.

Instead of one large file, you create focused rule files:


bash
.claude/
  rules/
    api.md
    testing.md
    frontend.md

Each file handles one responsibility.

api.md → API design and patterns
testing.md → test structure and expectations
frontend.md → UI conventions

Claude loads these alongside CLAUDE.md.

So behavior stays consistent, but structure becomes manageable.

Why this works better

This is less about features and more about ownership.

Different parts of the system can evolve independently.

Backend rules can change without touching frontend
Testing standards can evolve without affecting API logic

And more importantly:

People actually update smaller files.

Path-based rules (where it gets useful)

You can scope rules to specific parts of the codebase.

For example:

Apply certain rules only to src/api/
Ignore them for UI components

This avoids overloading Claude with irrelevant instructions.

It only sees what matters for the current context.

When should you move to `rules/`

Not early.

Start with CLAUDE.md.

Move to rules/ when:

the file becomes hard to maintain
multiple concerns start mixing
different parts of the system need different rules

The practical takeaway

CLAUDE.md gives you control.

rules/ gives you scale.

If you skip this step, your setup will degrade over time. If you structure it properly, it stays usable even as the project grows.

5. Automating Repeated Work: The `commands/` Folder

So far, everything we've defined controls how Claude behaves.

Now we move to something different.

How Claude works.

There are tasks you repeat all the time:

reviewing code
fixing issues
generating commit messages
scanning for problems

You can keep typing the same prompt every time.

Or you can turn it into a command.

What the `commands/` folder does

The commands/ folder lets you create your own slash commands.

Each markdown file becomes a command.


bash
.claude/
  commands/
    review.md
    fix-issue.md

These show up inside Claude Code as:

/project:review
/project:fix-issue

The file name becomes the command.

What makes commands useful

This is not just saved text.

Commands can inject real context into the prompt.

For example:

git diff
file content
issue details

So instead of saying:

"Review this PR and tell me what's wrong"

You run:


bash
/project:review

And Claude already has the context it needs.

Passing arguments

Commands can take input.


bash
/project:fix-issue 123

This lets you dynamically pass:

issue IDs
file names
custom instructions

The command uses that input inside its logic.

Project vs personal commands

There are two places you can define commands:

.claude/commands/ → shared with your team
~/.claude/commands/ → personal

Use project commands for:

team workflows
standard processes

Use personal commands for:

your shortcuts
your preferences

When to create commands

Not for everything.

Only for workflows you repeat.

Good candidates:

code review
issue fixing
commit message generation
quick audits

If you've typed the same prompt more than 5 times, it should probably be a command.

The practical takeaway

CLAUDE.md defines behavior. rules/ organizes it. commands/ turns repeated work into reusable actions.

This is where Claude starts feeling less like a chat tool and more like a development system.

6. When Things Get Complex: `skills/` and `agents/`

Up to this point, everything is predictable.

CLAUDE.md defines behavior
rules/ organizes it
commands/ automate tasks

But some workflows don't fit into a single command.

They require multiple steps. More context. Sometimes even different ways of thinking.

That's where skills/ and agents/ come in.

Skills: workflows Claude can trigger on its own

Commands run when you call them.

Skills are different.

They activate automatically when the task matches.

Each skill lives in its own folder:


bash
.claude/
  skills/
    security-review/
      SKILL.md
      guide.md

The SKILL.md describes:

when to use the skill
what it should do

For example:

If you say "review this PR for security issues"

Claude can detect that and trigger the skill automatically.

You can also call it manually if needed.

Why skills are different

A command is a single file.

A skill is a small system.

It can include:

instructions
supporting documents
detailed guides

This makes it suitable for:

structured reviews
audits
multi-step reasoning

Agents: specialized sub-workers

Sometimes even a skill is not enough.

You want a dedicated role.

That's what agents/ provides.

Each agent is a separate persona with:

its own instructions
limited tool access
optional model choice


bash
.claude/
  agents/
    code-reviewer.md
    security-auditor.md

When needed, Claude can spawn this agent, let it do the work, and return a summarized result.

Why agents exist

Two reasons:

1. Isolation

The agent works in its own context. It doesn't clutter your main session.

2. Specialization

You can restrict what it can do.

For example:

security agent → read-only
no file edits
no risky operations

When to use skills and agents

Not early.

Most setups don't need them.

Use them when:

workflows become complex
tasks require multiple steps
you want consistent, repeatable reasoning

The practical takeaway

Commands → you trigger
Skills → Claude triggers
Agents → Claude delegates

This is the advanced layer.

Useful when needed. Unnecessary if you don't have real complexity yet.

7. Control and Safety: `settings.json`

Up to this point, everything we've done is about behavior.

Now comes control.

Because giving Claude instructions is one thing. Letting it execute actions is another.

That's what settings.json handles.

What `settings.json` actually does

This file defines what Claude is allowed to do inside your project.

Not in theory.

In practice.

Which commands it can run
Which files it can access
When it should ask for permission

Without this, Claude operates with uncertainty.

With this, you define clear boundaries.

The two parts that matter

At a high level, everything comes down to two lists:

1. Allow list

Things Claude can do without asking.

Typical examples:

Run project commands
Read and edit files
Inspect the codebase

2. Deny list

Things Claude is never allowed to do.

Typical examples:

Destructive commands (rm -rf)
Direct network calls
Access to sensitive files like .env

Everything else sits in between.

If it's not explicitly allowed or denied, Claude will ask.

A simple example


json
{
  "allow": [
    "Bash(npm run *)",
    "Bash(git *)",
    "Read",
    "Write",
    "Edit"
  ],
  "deny": [
    "Bash(rm -rf *)",
    "Read(.env)",
    "Read(secrets/*)"
  ]
}

This setup does two things:

gives Claude enough freedom to work
prevents it from doing anything risky

Why this matters more than it looks

Without clear permissions:

Claude becomes overly cautious
or worse, overly permissive

Both are bad.

You either slow down your workflow or risk unintended actions.

This file balances both.

Personal overrides

Just like other parts of the system, you can override this locally.

Use:


bash
.claude/settings.local.json

This lets you:

experiment safely
keep personal preferences
avoid affecting the team

The practical takeaway

settings.json is not configuration noise.

It is the safety layer.

It defines:

what Claude can do
what it should never do
and where it needs your approval

Without it, you're guessing. With it, you're in control.

8. The Part That Feels "Magic": Memory and the Global Folder

At some point, you'll notice something strange.

Claude remembers things you never explicitly told it in the current session.

Patterns. Preferences. Even past decisions.

That behavior comes from the global folder.


bash
~/.claude/

What lives in the global folder

This is not project-specific.

This is your personal layer.

It stores:

your global CLAUDE.md (preferences across projects)
your personal commands and skills
session memory and learned patterns

Claude uses this to carry context forward.

Not just within a session. Across sessions.

Why this matters

This explains two common situations.

1. "Why is Claude behaving differently here?"

Because it's not just reading your project. It's also applying your personal context.

2. "Why does it remember something I didn't mention?"

Because it has seen it before. And stored it.

Where memory actually lives

Inside:


bash
~/.claude/projects/

Claude stores:

session summaries
patterns it has observed
useful context it wants to reuse

This builds up over time.

When this becomes a problem

Memory is useful.

Until it isn't.

Sometimes:

it reinforces outdated patterns
it carries assumptions you don't want
it creates inconsistent behavior across projects

What to do when things feel off

You have two options:

1. Inspect memory

Understand what Claude has stored.

2. Reset it

Clear project memory and start fresh.

A simple mental model

Think of this as:

Project .claude/ → rules of the system
Global ~/.claude/ → habits of the user

Both influence behavior.

The practical takeaway

If Claude feels unpredictable, don't just look at your prompts.

Check:

your project configuration
your global memory

Most "weird behavior" comes from here.

Once you understand this layer, Claude becomes much easier to reason about.

9. A Practical Setup That Actually Works

At this point, it's easy to over-engineer this.

You don't need everything.

You don't need skills, agents, or complex setups on day one.

You need a simple progression that gives value immediately.

Step 1. Start with CLAUDE.md

Run:


bash
/init

Claude will generate a starter CLAUDE.md based on your project.

Don't accept it as is.

Edit it down.

Keep only:

commands
structure
conventions
constraints

This is your foundation.

Step 2. Add basic permissions

Create:


bash
.claude/settings.json

Start simple.

allow your project commands
allow basic file operations
deny sensitive files like .env

This removes friction and adds safety.

Step 3. Add 1–2 commands you actually use

Don't create 10 commands.

Start with what you repeat.

Good starting points:

code review
fix issue

If you're not using a command weekly, you don't need it.

Step 4. Split into rules when needed

Only do this when CLAUDE.md starts getting messy.

Move into:


bash
.claude/rules/

Split by concern:

API
frontend
testing

Keep files small and focused.

Step 5. Add personal preferences

Create:


bash
~/.claude/CLAUDE.md

This is where you define how you like to work.

Examples:

prefer functional patterns
always define types first
keep responses concise

This travels across all projects.

What this setup gives you

With just these steps, you get:

consistent behavior across sessions
less repetition in prompts
safer execution
reusable workflows
a system that scales with your project

Closing Thought

The .claude/ folder is not configuration.

It is a protocol.

A way to tell Claude:

how your project works
how you want it to behave
and what rules it should follow

If you treat it like a tool, you'll keep prompting.

If you treat it like infrastructure, it compounds.

Start small. Refine as you go.

That's where the real leverage is.

1. Claude Feels Inconsistent for a Reason

2. Two Levels of Control Most People Miss

3. CLAUDE.md: The Instruction Layer That Actually Matters

What CLAUDE.md is actually doing

What actually belongs in CLAUDE.md

What does NOT belong here

Keep it intentionally small

The practical takeaway

4. When One File Stops Scaling: The rules/ Folder

The limitation of a single file

The idea behind rules/

Why this works better

Path-based rules (where it gets useful)

When should you move to rules/

The practical takeaway

5. Automating Repeated Work: The commands/ Folder

What the commands/ folder does

What makes commands useful

Passing arguments

Project vs personal commands

When to create commands

The practical takeaway

6. When Things Get Complex: skills/ and agents/

Skills: workflows Claude can trigger on its own

Why skills are different

Agents: specialized sub-workers

Why agents exist

When to use skills and agents

The practical takeaway

7. Control and Safety: settings.json

What settings.json actually does

The two parts that matter

A simple example

Why this matters more than it looks

Personal overrides

The practical takeaway

8. The Part That Feels "Magic": Memory and the Global Folder

What lives in the global folder

Why this matters

Where memory actually lives

When this becomes a problem

What to do when things feel off

A simple mental model

The practical takeaway

9. A Practical Setup That Actually Works

Step 1. Start with CLAUDE.md

Step 2. Add basic permissions

Step 3. Add 1–2 commands you actually use

Step 4. Split into rules when needed

Step 5. Add personal preferences

What this setup gives you

Closing Thought

Discussion Log (0)

4. When One File Stops Scaling: The `rules/` Folder

The idea behind `rules/`

When should you move to `rules/`

5. Automating Repeated Work: The `commands/` Folder

What the `commands/` folder does

6. When Things Get Complex: `skills/` and `agents/`

7. Control and Safety: `settings.json`

What `settings.json` actually does