Anatomy of the .claude/ folder

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

# 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

Related Papers

• Show HN: ctx – Search the coding agent history already on your machine

  Claude Code, Cursor, Codex 등 코딩 에이전트가 이전 세션의 논의·결정·실패 시도를 잊지 않도록 SQLite로 인덱싱해 재사용할 수 있게 해주는 오픈소스 CLI 도구다.

• Micro-Agent: Beat Frontier Models with Collaboration Inside Model API

  vLLM 팀이 단일 모델 API 호출 뒤에서 여러 모델이 협업하는 'Micro-Agent' 개념을 공개했습니다. 별도의 에이전트 코드 없이 라우터 레이어에서 모델 조합을 실행해 GPT-4급 결과를 더 저렴하게 낼 수 있다는 아이디어입니다.

• Ornith-1.0: self-improving open-source models for agentic coding

  Gemma 4와 Qwen 3.5를 기반으로 파인튜닝한 코딩 특화 오픈소스 모델로, RL(강화학습)을 통해 스캐폴드(에이전트 실행 구조)까지 함께 최적화하는 방식을 주장하지만, 커뮤니티에서는 벤치마크 과최적화에 불과하다는 의심을 받고 있다.

• Entity Binding Failures in Tool-Augmented Agents

  AI 에이전트가 올바른 도구를 선택해도 잘못된 대상에 실행하는 'Entity Binding 실패' 문제를 정의하고, 이를 막는 실행 정책을 평가한 논문.

• Herdr: Agent multiplexer that lives in your terminal

  여러 AI 코딩 에이전트(Claude, Codex 등)를 하나의 터미널에서 동시에 실행·관리할 수 있는 Rust 기반 오픈소스 툴로, tmux처럼 세션이 유지되고 SSH로 원격 접속도 가능해 멀티 에이전트 워크플로우를 크게 단순화해준다.

• Ornith-1.0: Self-scaffolding LLMs for agentic coding

  모델이 문제 풀이 전략(scaffold)을 직접 생성하고 개선하는 자기강화 학습 프레임워크를 적용한 오픈소스 코딩 특화 LLM으로, 9B 소형 모델부터 397B 대형 모델까지 라인업을 갖추고 SWE-Bench 등 주요 벤치마크에서 Claude Opus 4.7을 능가하는 성능을 보여줬다.

Related Resources

• Anatomy of the .claude/ folder (original article)
• Claude Fast - CLAUDE.md Mastery Guide
• claude-code-types (npm package for parsing ~/.claude/projects)