Inside the Claude Code .claude Folder: How to Design Your Project's AI Brain

I'm Ryuta Hamamoto from TIMEWELL.

Have you ever opened the .claude folder in Claude Code? This folder is the "control center" that determines the quality of your collaboration with AI. In this article, I'll walk through every component — CLAUDE.md, rules, skills, subagents, settings.json, and auto-memory — in a way that's accessible even if you're new to the tooling.

---

Claude Code Has No Memory by Default — That's Exactly Why .claude Matters

One of the first things that trips people up when starting with Claude Code is the fact that nothing persists between sessions. You told it yesterday that your project uses TypeScript and Vitest for testing, but today it starts fresh with zero knowledge of that. It's like working with a colleague who wakes up with amnesia every morning.

The .claude folder and its centerpiece — the CLAUDE.md file — were designed to solve this problem. Every time Claude Code starts a new session, it reads the contents of this folder first. In other words, what you write here becomes Claude's "long-term memory."

To be precise, Claude Code has two memory systems. The first is CLAUDE.md, which you write yourself. The second is the "auto-memory" feature, where Claude writes its own notes based on what it learns during your sessions. The former is for intentionally guiding Claude's behavior; the latter lets Claude automatically pick up on your corrections and preferences. Together, they create a consistent development experience across sessions.

What matters here is that how well you design the .claude folder directly affects the quality of your project. A poorly configured folder produces vague, unreliable responses. A well-designed one produces surprisingly accurate ones. From our experience running this at TIMEWELL, optimizing the .claude folder alone reduced back-and-forth with Claude by roughly 40%.

---

The .claude Folder at a Glance — What Lives Where

Let's start with a bird's-eye view of a typical .claude directory structure.

.claude/
├── CLAUDE.md              # Project-wide instruction file (most important)
├── settings.json          # Shared team settings (permissions, model selection, etc.)
├── settings.local.json    # Personal settings (gitignored)
├── rules/                 # Topic-specific instruction files
│   ├── code-style.md
│   ├── testing.md
│   └── security.md
├── skills/                # Reusable workflow definitions
│   └── deploy/
│       └── SKILL.md
├── agents/                # Specialized subagents
│   └── code-reviewer.md
├── commands/              # Custom slash commands (legacy, now merged into skills)
│   └── fix-issue.md
└── .mcp.json              # External tool integrations (MCP Server configuration)

You can also place a CLAUDE.md at your project root (both .claude/CLAUDE.md and ./CLAUDE.md work). Additionally, ~/.claude/ in your home directory stores personal settings that apply across all projects.

One thing beginners often miss: the .claude folder can exist in two places — inside your project directory and in your home directory. The project-level folder affects everyone on the team; the home directory version affects only you.

---

CLAUDE.md — The Art of Writing Instructions for Claude

CLAUDE.md is the most important file in the .claude folder. Its contents are loaded into Claude's context window at the start of every session, influencing every response that follows.

Scope Depends on Where You Put It

Scope	Location	Reach	Who manages it
Managed Policy	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS)	Entire organization	IT administrators
Project	./CLAUDE.md or ./.claude/CLAUDE.md	Entire project	Shared via Git
User	~/.claude/CLAUDE.md	All projects (personal)	You only

Three Principles for Writing It Well

The official documentation recommends keeping CLAUDE.md under 200 lines. Because the file's content consumes tokens in the context window, an overly long file squeezes out the "thinking space" Claude needs. Files exceeding 3,000 tokens are known to cause a noticeable drop in how reliably Claude follows instructions [1].

Here are three principles for writing it effectively.

First, be specific. Instead of "please format the code properly," write "indent with 2 spaces, omit semicolons, use single quotes." The more verifiable an instruction, the more consistently it's followed.

Second, structure your content. Use Markdown headings and bullet points to group related instructions together.

Third, eliminate contradictions. If multiple CLAUDE.md files or rules files contain conflicting instructions, Claude will pick one arbitrarily.

Importing External Files with @ Syntax

You can import external files into CLAUDE.md using the @path/to/file syntax.

For project overview, see @README.md.
For available npm scripts, check @package.json.
For Git workflow details, follow @docs/git-instructions.md.

---

The rules Directory — Managing Instructions at Scale

As a project grows, stuffing all your instructions into a single CLAUDE.md becomes impractical. That's where the .claude/rules/ directory comes in.

Markdown files placed in this directory are loaded with the same priority as CLAUDE.md.

.claude/rules/
├── code-style.md     # Coding conventions
├── testing.md        # Testing guidelines
├── security.md       # Security requirements
└── api-design.md     # API design guidelines

Particularly powerful is the ability to apply rules conditionally based on file path. By specifying a paths field in the YAML front matter, you can make a rule activate only when Claude is working with specific files.

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- Implement input validation on all API endpoints
- Use the standard error response format
- Always include OpenAPI documentation comments

---

Skills — Packaging Reusable Workflows

Skills are "reusable workflow definitions" stored in the .claude/skills/ directory. While CLAUDE.md and rules are instructions that are always loaded into Claude's context, skills are invoked only when explicitly called.

---
name: deploy
description: Execute a production deployment
disable-model-invocation: true
allowed-tools: Bash(npm *), Bash(git *)
---

Production deployment steps:
1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded

Setting disable-model-invocation: true prevents Claude from automatically triggering this skill — it only runs when the developer explicitly types /deploy [2].

Custom slash commands that used to live in .claude/commands/ have been merged into skills. Skills are more expressive because they can bundle supporting files (templates, scripts, examples, etc.) alongside the workflow definition.

---

Subagents — Building a Specialized AI Team

Subagents are a mechanism for spinning up a separate AI instance — independent of the main Claude session — and delegating specific tasks to it.

For example, a test suite run might produce hundreds of lines of output. Loading all of that into the main context window would crowd out other important context. By delegating to a subagent, only a summary is returned to the main session.

---
name: code-reviewer
description: Expert in reviewing code quality and security
tools: Read, Grep, Glob, Bash
model: sonnet
memory: project
---

You are a senior code reviewer. When called, check recent changes
using git diff and provide feedback on quality, security, and
maintainability.

Built-in subagents include Explore (codebase exploration, uses Haiku model), Plan (research during plan mode), and general-purpose (versatile multi-step tasks) [3].

Setting the memory field enables a subagent to accumulate persistent knowledge across sessions.

---

settings.json and Permissions — Defining Claude's Boundaries

.claude/settings.json defines what Claude is allowed and not allowed to do. If CLAUDE.md is "behavioral guidance," settings.json is "legally binding rules."

Scope	File Path	Reach	Shared with Team
User	~/.claude/settings.json	All your projects	No
Project	.claude/settings.json	Everyone in this repo	Yes (Git-managed)
Local	.claude/settings.local.json	You only	No (gitignored)

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run build)",
      "Read",
      "Grep"
    ],
    "deny": [
      "Bash(rm *)",
      "Agent(Explore)"
    ]
  }
}

Since settings.local.json is excluded from Git, it's the right place for personal preferences [4].

---

Auto-Memory — How Claude Builds Its Own Knowledge Base

Auto-memory is a feature that lets Claude save its own notes automatically, without any input from the developer.

Notes are stored in the ~/.claude/projects/<project>/memory/ directory, with a MEMORY.md entry point file and separate files for topic-specific details.

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Index (loaded at the start of every session)
├── debugging.md       # Notes on debugging patterns
└── api-conventions.md # Notes on API design decisions

The first 200 lines of MEMORY.md are loaded at the start of each session. Content beyond 200 lines is not read at startup, so Claude is designed to keep MEMORY.md concise and offload detailed notes into separate files automatically.

Auto-memory content is stored as plain Markdown files, so you can read, edit, or delete them anytime. Run the /memory command during a Claude Code session to see a list of all files currently loaded.

---

Practical Getting Started — Steps to Take Tomorrow

Here's a recommended path for anyone setting up the .claude folder for the first time.

Start by running the /init command inside a Claude Code session. That alone will have Claude analyze your codebase and automatically generate an initial CLAUDE.md that reflects your build commands, test procedures, and project conventions.

Next, review the auto-generated content and add any information Claude couldn't discover on its own — the reasoning behind architectural decisions, team-specific workflows, and integration rules for external services.

After that, identify tasks you repeat frequently and define them as skills. Processes with fixed steps — like "PR review," "deployment," or "database migration" — are strong candidates for skill-ification.

Finally, configure settings.json to set permissions and restrict dangerous commands. For team projects especially, I strongly recommend adding destructive operations like rm -rf to the deny list.

The .claude folder is not a "set it and forget it" configuration — it should evolve alongside your project. Even once a month, take a few minutes to review your CLAUDE.md and rules files. What ultimately determines the quality of your AI collaboration isn't cutting-edge prompt engineering; it's the steady, unglamorous work of keeping your environment well-configured [5] [6].

---

References

[1] Claude Code Official Documentation. "Store instructions and memories." https://code.claude.com/docs/en/memory (2026-03-23)

[2] Claude Code Official Documentation. "Extend Claude with skills." https://code.claude.com/docs/en/skills (2026-03-23)

[3] Claude Code Official Documentation. "Create custom subagents." https://code.claude.com/docs/en/sub-agents (2026-03-23)

[4] Claude Code Official Documentation. "Claude Code settings." https://code.claude.com/docs/en/settings (2026-03-23)

[5] Akshay Pachaar. "Anatomy of the .claude/ folder." https://x.com/akshay_pachaar/status/2035706568142893229 (2026-03-21)

[6] alexop.dev. "Claude Code Customization Guide." https://alexop.dev/posts/claude-code-customization-guide-claudemd-skills-subagents/ (2026-03-23)