Anatomy of the .claude/ folder

TL;DR Highlight

A detailed guide explaining the structure of the .claude/ folder—Claude Code's core configuration directory—and the role of each file within it, providing practical setup instructions for developers looking to effectively use Claude at the team level.

Who Should Read

Developers who have adopted or are considering adopting Claude Code in their projects, especially tech leads and senior developers who want the entire team to share consistent AI coding rules.

Core Mechanics

The .claude/ folder serves as the 'control panel' for Claude Code and exists in two locations: a team-shared folder at the project root and a personal configuration folder in the home directory (~/.claude/). The team-shared folder should be committed to git so all team members operate under the same rules.
CLAUDE.md is the first file read when a Claude Code session starts and is injected directly into the system prompt. Writing rules like 'always write tests first' or 'use the custom logger module instead of console.log' causes Claude to follow those rules throughout the session.
What belongs in CLAUDE.md: build/test/lint commands, key architectural decisions, non-intuitive caveats, import conventions, and folder structure. What to leave out: content replaceable by linter config, lengthy theoretical explanations, and documentation already accessible via links.
Keeping CLAUDE.md under 200 lines is important. The longer the file, the more of Claude's context it consumes, which in practice leads to lower rule-compliance rates. The example provided in the original article is about 20 lines, containing only the essential information needed for an Express API project.
Creating a CLAUDE.local.md file in the project root allows personal settings to be separated from team settings. This file is automatically added to .gitignore, so personal preferences are never pushed to the team repository.
Using a rules/ folder lets you split CLAUDE.md into separate files organized by feature. As teams grow, a single CLAUDE.md can exceed 300 lines and become hard to manage—modularization solves this problem.
The ~/.claude/plans/ directory stores plan files generated when Claude runs in plan mode, saved in Markdown format. The ability to open or back up these files is a useful detail omitted from the original article.
If Claude has directly edited CLAUDE.md or .claude/INSTRUCTIONS.md, it retains the previous version in its context and will not automatically reflect the changes. After updating the file, you must explicitly instruct Claude to 're-read this file' for the latest content to take effect.

Evidence

"Across the community, a common sentiment was 'the more complex the configuration, the worse the results.' The analogy that 'AI is like a competent but anxious adult—the more you give it, the dumber it gets' resonated widely, and many users shared experiences of getting better results by starting with an empty .claude folder and minimal configuration. There were also skeptical counterarguments to the original article's claim that 'Claude strictly follows what is written in CLAUDE.md.' In practice, CLAUDE.md is closer to a 'suggestion' than a 'contract'—when the context window fills up or compaction (context compression) occurs, the instructions in CLAUDE.md can become diluted. Some users shared success stories using MCP (Model Context Protocol) servers they built themselves, connected to agents. The effective approach described was to write only 'what tools are available' in AGENT.md and let the agent compose its own workflow without complex instructions. An advanced use case was also shared where the .claude/ folder operates in a self-replicating and self-updating manner—a main agent writes the .claude/ files directly, evaluates the results after completing tasks, and autonomously improves the .claude/ configuration, described as 'not writing code, but writing .claude/,' which illustrated an interesting new paradigm. There were also voices pointing out stability issues with the Claude Code CLI itself: documentation for plugin LSP configuration is so lacking that users have to dig through GitHub issues, hooks render errors even when there are none, and permission settings are barely documented. It was noted that issues opened as early as early 2025 remain unresolved."

How to Apply

"When introducing Claude Code to a new project, start with a CLAUDE.md of 20–30 lines at most. Include only build/test commands, key architectural decisions (e.g., ORM, folder structure), and genuinely non-intuitive caveats—leave everything else for Claude to infer by reading the codebase directly, which actually produces more accurate behavior. For team projects, commit the .claude/ folder to git to share team rules, and have each team member manage personal settings separately in CLAUDE.local.md. This maintains shared team rules without configuration conflicts arising from individual preferences. If you have Claude directly edit CLAUDE.md, you must explicitly instruct it to 're-read this file' after the edit. Even after modifying the file, Claude retains the previous version in its context and will not automatically recognize the changes. Periodically checking the ~/.claude/plans/ directory lets you view or back up plan files generated by Claude in plan mode, stored in Markdown format. This is useful for reusing or sharing plans for complex tasks with your team."

Code Example

snippet

# Project: Acme API

## Commands
npm run dev    # Start dev server
npm run test   # Run tests (Jest)
npm run lint   # ESLint + Prettier check
npm run build  # Production build

## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- All handlers live in src/handlers/
- Shared types in src/types/

## Conventions
- Use zod for request validation in every handler
- Return shape is always { data, error }
- Never expose stack traces to the client
- Use the logger module, not console.log

## Watch out for
- Tests use a real local DB, not mocks. Run `npm run db:test:reset` first
- Strict TypeScript: no unused imports, ever

Terminology

CLAUDE.mdAn instruction file that is automatically read when a Claude Code session starts. Think of it as an 'onboarding document you hand to Claude'—its contents are injected into the system prompt and persist throughout the session.

MCP (Model Context Protocol)A standard protocol that connects external tools (file systems, APIs, databases, etc.) to AI models. Think of it as the specification for hooking up a 'toolbox' that an agent can use.

compactionThe process of compressing older conversation history when Claude Code's context window fills up. During this process, instructions from CLAUDE.md can become diluted or some context may be lost.

system promptThe initial instruction text injected into the AI before a user starts a conversation. Claude inserts the contents of CLAUDE.md here so it can be referenced throughout the session.

LSP (Language Server Protocol)The communication standard between code editors and language-specific analysis tools. Used in the Claude Code CLI to connect features like code autocompletion and error detection.

skillsA configuration in Claude Code that defines reusable units of work. Specific task patterns can be saved like commands and called repeatedly.