Inside the Claude Code .claude Folder (Late-2026 Edition): Designing Your Project's Brain by Hand

I'm Ryuta Hamamoto from TIMEWELL.

Have you ever actually opened the .claude folder in Claude Code? The way you design this folder all but decides the quality of your collaboration with the AI.

The short version: put instructions in CLAUDE.md, put procedures you only need on demand in skills, and put role-specific helpers in agents. Anything you need to be enforced, rather than requested, goes into permissions or hooks in settings.json. Get those three things right and you have designed most of .claude.

This article is based on the official documentation as of November 6, 2026. It walks through the whole .claude ecosystem, from CLAUDE.md to subagents, hooks, auto-memory, MCP, and compatibility with other tools. Specs move from version to version, so check what I describe here against /context and the official docs for the version you run. This is not a recommendation to adopt any particular tool.

---

Claude Code Has No "Memory." That's Why You Design .claude

The first thing that trips people up when they start with Claude Code is that nothing carries over between sessions. You told it yesterday that "this project is TypeScript and the tests are Vitest," yet a fresh session the next morning remembers none of it. It's like pairing with a colleague whose memory resets every morning.

The .claude folder was designed to fill that gap, and CLAUDE.md sits at its core. Claude reads these files every time it starts a session. Whatever you write here effectively becomes Claude's "long-term memory."

The memory mechanism splits into two systems. One is the CLAUDE.md you write yourself, meant to deliberately guide Claude's behavior. The other is "auto-memory," where Claude records its own learnings, picking up patterns from your corrections and preferences automatically. The former is active instruction, the latter passive learning — their roles are cleanly divided. When the two mesh, you get a consistent development experience even as sessions turn over.

It's unglamorous work, but whether you do it carefully changes how much rework you face. My own view is that this "environment configuration" tends to matter more than clever prompting techniques.

---

The .claude Folder at a Glance — What Lives Where

Let's start with the overall map. There are two errors from the first edition I want to correct here: the location of the MCP configuration file, and the existence of the personal CLAUDE.local.md. I'll go through them in order.

project-root/
├── CLAUDE.md              # Instructions for the whole project (project root by default)
├── CLAUDE.local.md        # Your own project instructions (gitignored)
├── .mcp.json              # Project-scope MCP config (team-shared — this is the correct spot)
└── .claude/
    ├── settings.json          # Team-shared settings (Git-managed)
    ├── settings.local.json    # Personal settings (gitignored)
    ├── rules/                 # Topic-specific instruction files
    ├── skills/                # Reusable workflow definitions
    │   └── deploy/SKILL.md
    ├── agents/                # Specialized subagents
    ├── commands/              # Custom commands (merged into skills; existing ones still work)
    ├── output-styles/         # Instruction sets that adjust response format
    └── workflows/             # Dynamic Workflows scripts (*.js)

~/.claude/          # Per-user (shared across all projects)
├── CLAUDE.md
├── settings.json
└── keybindings.json
~/.claude.json      # local / user scope MCP config (NOT inside the .claude folder)

The official home for project-scope MCP configuration is not inside .claude/ but .mcp.json at the project root. MCP servers you want to share with your team go here. Meanwhile, local-scope config for yourself only and user-scope config for everything go in ~/.claude.json — and those, too, do not live inside the .claude/ folder. The first edition wrote this as .claude/.mcp.json, which was wrong. My apologies, and here's the correction.

The other file worth knowing is the project-personal ./CLAUDE.local.md. Separate from the team-shared CLAUDE.md, it's the place for your own notes or temporary instructions, and it's gitignored. Instructions you don't want to expose to the whole team but do want in force for yourself in this repository go here.

.claude can exist in two places — "inside the project" and "in your home directory (~/.claude/)." What's inside the project applies to the whole team; what's in your home directory applies only to you. Mix these up and you can change your team's behavior without meaning to, so be careful.

---

CLAUDE.md — Instruction Design, and What "200 Lines" Really Means

CLAUDE.md is the single most important file in the .claude ecosystem. What you write here is loaded into context at the top of every session and shapes every response that follows. Because its reach changes with where you place it, let's get that straight first.

Scope	Location	Reach	Sharing
Organization (managed)	Embedded directly in the claudeMd key of managed-settings.json	Entire organization	Distributed by IT admins
Project	./CLAUDE.md (.claude/CLAUDE.md also works)	Entire repository	Shared via Git
Personal (in-project)	./CLAUDE.local.md	You only, in this repo	gitignored
User	~/.claude/CLAUDE.md	All projects (personal)	You only

Now, the biggest error from the first edition. The first edition claimed that "once you exceed 3,000 tokens, instruction adherence drops." That figure appears nowhere in the official docs. Since I couldn't back it up, I'm removing it. What the docs actually say goes only as far as: "Target under 200 lines. The longer it is, the more context it consumes and the lower adherence becomes."

And another important fact. The thing you actually need to worry about a line limit for is not CLAUDE.md. CLAUDE.md is loaded in full regardless of length. The only place where parts go "unloaded" because of line count or size is the MEMORY.md of auto-memory, discussed later. In other words, 200 lines is purely a design guideline — "Claude works smarter when you keep it short" — not a case of "exceed it and it stops being read." This is easy to confuse, so keep the two clearly apart.

There are three points to writing it effectively. First, be specific. Not "format it properly," but "indent with two spaces, omit semicolons, use single quotes." The more verifiable the instruction, the better it's followed. Second, structure it. Group related instructions with headings and bullet points. Third, leave no contradictions. When conflicting instructions sit across multiple files, Claude will pick one on its own.

Being able to reference external files with @ imports is convenient, too.

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

A quietly effective technique: block HTML comments (<!-- ... -->) inside CLAUDE.md are stripped before the content is injected into context. You can leave notes for maintainers without consuming any tokens, so writing "why this rule exists" as a comment helps whoever comes after you.

In a monorepo where multiple teams' CLAUDE.md files get mixed together, the claudeMdExcludes setting lets you drop other teams' CLAUDE.md from what gets loaded. Conversely, when you want additional working directories' CLAUDE.md loaded too, use the environment variable CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. When CLAUDE.md starts to balloon, /doctor prompt-audit (v2.1.283 or later) helps. It looks for instructions written for older models, references to files or commands that don't exist, and files that contradict each other, then returns a report with proposed edits. Nothing in your files changes until you ask Claude to apply them. My own rule for trimming: cut anything derivable from the codebase, such as directory structure, dependency lists, and architecture overviews, and keep the pitfalls, the reasoning behind decisions, and the house rules that differ from a tool's defaults.

If you are migrating from other tools, here is what changed since the first edition. According to the official docs, Claude Code can now read AGENTS.md directly (v2.1.277 or later). By default it reads AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it. If both exist, CLAUDE.md wins and AGENTS.md is not read. To have Claude read both, switch "Project instructions" in /config to claude-md-and-agents-md. Importing it with @AGENTS.md from your CLAUDE.md still works too.

/init also pulls in existing settings from other tools. Per the docs, it picks up Cursor rules (.cursor/rules/ or .cursorrules) by default, and with the environment variable CLAUDE_CODE_NEW_INIT=1 it also covers AGENTS.md, .devin/rules/, .windsurf/rules/ or .windsurfrules, and .clinerules. Lumping .windsurfrules in with the default behavior, as the first edition did, was inaccurate.

---

Skills and Custom Commands — Instructions Called "Only When Needed"

Where CLAUDE.md and rules are "instructions that are always loaded," skills are instructions invoked only when needed. You package a workflow into .claude/skills/.

---
name: deploy
description: Run 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 stops Claude from invoking this skill on its own — it runs only when you explicitly type /deploy. Conversely, if you want it to auto-trigger, write the firing conditions in when_to_use (up to 1,536 characters). A skill's frontmatter also supports fields like argument-hint, user-invocable, allowed-tools, disallowed-tools, model, effort, context, agent, hooks, and paths (the range I could confirm in the official list).

Here's another spot that needs correcting from the first edition. The first edition described .claude/commands/ as "legacy," which wasn't accurate. The official phrasing is: "Custom commands have been merged into skills. Existing .claude/commands/ continue to work and support the same frontmatter." Not removed, not deprecated. When a skill and a command share the same name, the skill takes priority. There's no need to rush to throw away your existing commands/ — keep that in mind.

Skill priority goes: enterprise (organization) strongest, then personal, then project last. In a monorepo, skills in a subdirectory are loaded the first time Claude reads or edits a file there, so you can nest them.

Skills, fundamentally, aren't a Claude Code-only construct: they conform to Agent Skills, an open standard (agentskills.io). The aim of standardization is to let you reuse the same skill across multiple AI tools. Claude Code ships with bundled skills out of the box — /doctor, /code-review, /batch, /debug, /loop, /claude-api. If you don't need them, you can disable the whole set with disableBundledSkills.

Turning recurring work into skills is the customization I feel has the highest return on investment. For work with fixed steps — PR reviews, deployments, DB migrations — consider skill-ifying it first.

The next questions are usually how finely to slice a skill and how to grow it over time. I walk through building one step by step in how to build your own Claude Code skills.

---

Subagents — Recreating a Team of Specialists with AI

A subagent spins up a separate Claude instance, independent of your main session, and hands it a specific task. A test run's logs can be hundreds of lines, for instance; loading that into the main context crowds out everything else. Run it in a subagent and only a summary comes back to the main session.

---
name: code-reviewer
description: A specialist that reviews code quality and security
tools: Read, Grep, Glob, Bash
model: inherit
memory: project
---

You are a senior code reviewer. When called, review recent changes
with git diff and give feedback from the standpoint of quality,
security, and maintainability.

The first edition listed the built-in subagents as three — Explore, Plan, and general-purpose — but that too had gone stale. The official docs now list six. In addition to Explore for exploration, Plan which handles research during plan mode, and the versatile general-purpose, there is claude, a catch-all with every tool available to subagents, plus statusline-setup (Sonnet) for /statusline and claude-code-guide (Haiku), which answers questions about Claude Code's own features. Explore and Plan are read-only: Write and Edit are denied.

Another big correction. The first edition asserted that Explore was "the Haiku model," but the current docs say otherwise. With a Claude subscription, a Console account, or an LLM gateway via ANTHROPIC_BASE_URL, Explore runs on the Opus model that the opus alias resolves to. On Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, and Claude Platform on AWS, it stays on the main conversation's model. If you do want to keep exploration cheap, prepare your own subagent with model: haiku specified. Drop the assumption that "Explore is a light model, so it's cheap."

The values you can specify for model have broadened, too. You can use the aliases sonnet, opus, haiku, and fable, a full ID like claude-opus-5-5, or inherit (use the parent's model). If you omit model, Claude Code picks one by the subagent model order. Permissions are controlled by permissionMode, which takes default, acceptEdits, auto, dontAsk, bypassPermissions, and plan (manual works as an alias for default). The frontmatter also accepts fields such as maxTurns, skills, mcpServers, hooks, background, effort, and isolation. Tools can be allow-listed with tools and deny-listed with disallowedTools, and MCP control is possible at the mcp__<server-name> granularity. Write something like memory: project and you give the subagent persistent knowledge that carries across sessions (project is the officially recommended default, stored under .claude/agent-memory/<agent-name>/).

The range of use has widened as well. --agent <name> lets you launch an entire session as a specific subagent, and a fork branches off while inheriting the parent's conversation, system prompt, tools, and model. Because a fork can reuse the parent's prompt cache, it costs less than a fresh subagent when the task needs the same context. To stop forks, add Agent(fork) to permissions.deny or set the environment variable CLAUDE_CODE_FORK_SUBAGENT to 0.

How to split responsibilities in a real team, and what changes when review and testing get separate agents, is covered in the practical guide to subagents.

---

settings.json and hooks — Separating "Context" from "Enforcement"

.claude/settings.json is the file that defines Claude's configuration and its scope of action. Beyond permissions, it manages the whole of Claude's behavior here — environment variables, sandboxing, login method, disableBundledSkills, and more. There are three scope layers.

Scope	File	Reach	Team-shared
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)"]
  }
}

Let me sharpen the first edition's wording here. The first edition described settings.json as "legally binding rules." The direction is right, but it becomes more accurate when you round it out with the official framework. The docs put it this way: CLAUDE.md and auto-memory are strictly context, not enforced settings. If you want to reliably block a particular operation, use a PreToolUse hook or permissions.deny. In other words, "please" and "enforce" live on different layers. Write "never ever run rm -rf" in CLAUDE.md a hundred times and it's still just a strong wish. If you truly want to stop it, put it in permissions.deny or reject it with a hook. That's the correct design.

Those hooks are an important mechanism the first edition never touched. The official event list is long: SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, SubagentStart and SubagentStop, PreCompact and PostCompact, InstructionsLoaded, ConfigChange, and more. PreToolUse can intervene before a tool runs to decide allow or deny; PostToolUse can run validation or formatting after execution. InstructionsLoaded can be used to log which instruction files were loaded. Besides shell commands (command), handlers can be http, mcp_tool, prompt, or agent (experimental). If CLAUDE.md is the layer that conveys "policies I'd like you to follow," hooks and permissions are the layer that "makes them enforced." Design with these two layers in mind and you can safely widen the range of what you delegate to the AI.

Event-by-event syntax, blocking with exit codes, and common mistakes are covered with examples in the complete guide to Claude Code hooks.

MCP, for connecting external tools, is another element to keep alongside settings. There are three scopes. Local scope (~/.claude.json) is for you alone in the current project; project scope (.mcp.json at the project root) is team-shared; user scope (~/.claude.json) is for all of your projects. MCP's "local" is not the same thing as settings.local.json, so don't mix them up. For remote servers, http is the recommended transport. Writing streamable-http as the type in JSON config is treated as an alias for http, and SSE is marked deprecated. If you plan to build your own server, the MCP server self-build guide is a good starting point.

---

Auto-Memory — How Claude Accumulates Its Own Learnings

Auto-memory is a feature where Claude saves what it has learned as notes, without the developer writing anything. The storage location is ~/.claude/projects/<project>/memory/, made up of MEMORY.md as the entry point and topic-specific detail files.

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

Here, too, the first edition's explanation was incomplete. The first edition wrote "the first 200 lines of MEMORY.md are loaded," but the correct statement is "whichever comes first, the first 200 lines or 25KB." The 25KB size cap was missing. The moment either threshold is reached, everything beyond it is not loaded at session start. This is exactly why Claude is designed to keep MEMORY.md short and offload details into separate files.

The behavior around this limit is fairly detailed. Per the official docs, after Claude writes to MEMORY.md, Claude Code measures it against the 200-line and 25KB limits and reminds Claude to shorten it when it is close. If you write while over the limit, the write itself succeeds but returns an error telling you to rewrite the index, because the excess would be dropped on the next load. The limit applies only to MEMORY.md; each CLAUDE.md is passed in full as long as it is 4 MiB or smaller.

Auto-memory can be controlled, too. To turn it off entirely use the environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1; to toggle it in configuration use autoMemoryEnabled; to change the storage location use autoMemoryDirectory. A subagent's memory can be isolated from the parent, so you can design things such that a review-only agent's learnings don't pollute the main body. The contents are plain Markdown, so a human can read and fix them anytime. Type /memory mid-session to review the list, edit it, or toggle it on and off.

---

To Avoid Tripping Up in Practice — /context, /memory, /doctor, and the /compact Trap

So far this has been about configuration, but in practice what matters more is the operational discipline of confirming "whether what you configured is actually in effect." The first edition was thin on this angle, so let me close by organizing the operational commands.

/context is the command for checking what's currently loaded. It shows which of CLAUDE.md, rules, skills, and memory are actually in context. /memory is for listing, editing, and toggling auto-memory, and /doctor — as noted earlier — even takes care of trimming CLAUDE.md. Wire up the InstructionsLoaded hook and you can log which instructions were loaded. Most "the rule I wrote isn't working" trouble comes down to it never being loaded in the first place, so it's a good habit to check with /context first.

There's one more thing you'll always run into during long work: the behavior of /compact. When a conversation grows long and compaction kicks in, instructions given verbally within that conversation alone are lost. However, the project-root CLAUDE.md is re-read from disk and re-injected, so it doesn't disappear. Nested CLAUDE.md files are also reloaded when you next read that subdirectory's files. In short, the line is drawn between "temporary requests spoken within the session," which vanish, and "instructions written to a file," which persist. Understand this and you won't panic when instructions drop out during a long session. If you want an instruction to keep being followed, always commit it to a file. That's the ironclad rule.

Let me also lay out, once more, the onboarding steps for anyone setting up .claude for the first time. Start by running /init inside a session. It analyzes the codebase and auto-generates an initial CLAUDE.md reflecting your build commands, test procedures, and conventions (to try the new interactive init, use the environment variable CLAUDE_CODE_NEW_INIT=1). Next, review the output and add what Claude can't figure out on its own — the reasoning behind architectural decisions, team-specific workflows, rules for integrating with external services. After that, skill-ify recurring work, and finally lock down dangerous operations with settings.json permissions and hooks.

A word on the peripheral pieces. .claude/workflows/*.js is where Dynamic Workflows live — deterministic, script-driven orchestration of multiple subagents — and workflows you save from /workflows become commands you can call by name. For more, see our guide to Dynamic Workflows. Alongside these, keybinding management via ~/.claude/keybindings.json, .worktreeinclude (which lists gitignored files to copy into new worktrees), and output-styles/*.md (which adjust response format) all help make your environment reproducible. Plugins live under ~/.claude/plugins and are managed with the claude plugin commands.

Configuring .claude isn't a one-and-done affair. It's something you keep updating as your project grows. Even just once a month, take the time to inspect CLAUDE.md with /doctor and confirm what's loaded with /context. Just as I myself wrote a wrong number six months ago, this field moves fast, and yesterday's right answer is today's wrong one. That's exactly why continuing to consult the primary source — the official documentation — is the most reliable prompt engineering there is [1] [2] [3] [4] [5] [6] [7] [8].

---

References

[1] Claude Code Docs. "How Claude remembers your project (CLAUDE.md & auto memory)." https://code.claude.com/docs/en/memory (checked 2026-11-06)

[2] Claude Code Docs. "Extend Claude with skills." https://code.claude.com/docs/en/skills (checked 2026-11-06)

[3] Claude Code Docs. "Create custom subagents." https://code.claude.com/docs/en/sub-agents (checked 2026-11-06)

[4] Claude Code Docs. "Connect Claude Code to tools via MCP." https://code.claude.com/docs/en/mcp (checked 2026-11-06)

[5] Claude Code Docs. "Explore the .claude directory." https://code.claude.com/docs/en/claude-directory (checked 2026-11-06; the standalone settings page was not re-fetched this time)

[8] Claude Code Docs. "Hooks reference." https://code.claude.com/docs/en/hooks (checked 2026-11-06; event names and handler types only)

[6] Claude Code Docs. "Documentation index (llms.txt)." https://code.claude.com/docs/llms.txt (2026-07, not re-fetched this time)

[7] Agent Skills open standard. https://agentskills.io (2026-07, confirmed via the official skills page)