Avi Chawla, writing for his Daily Dose of Data Science newsletter on March 23, 2026, published a detailed breakdown of Claude Code’s .claude/ folder — the configuration layer that governs how the AI coding assistant behaves within a development project. The guide covers the folder’s full anatomy: instruction files, custom commands, permission rules, and session memory that persist across conversations.
- Claude Code uses two separate
.claude/directories: one at the project level and one in the user’s home directory (~/.claude/), each serving a distinct purpose. - The
CLAUDE.mdfile is loaded directly into Claude’s system prompt at the start of every session and governs behavior for the full conversation. - Multiple
CLAUDE.mdfiles — at the project root, in subdirectories, and globally — are all read and combined by Claude Code simultaneously. - Chawla sets a concrete performance threshold: files longer than 200 lines reduce instruction adherence as context is consumed.
What Happened
On March 23, 2026, Avi Chawla published “Anatomy of the .claude/ Folder” in his Daily Dose of Data Science newsletter. The post systematically documents every component of the folder that Claude Code generates in project directories, explaining what each file does and how teams can configure it deliberately rather than leaving it at defaults.
Chawla observes that despite the folder appearing automatically in project roots, most users treat it as a black box: “They know it exists. They’ve seen it appear in their project root. But they’ve never opened it, let alone understood what every file inside it does.” He argues this represents a missed opportunity to shape AI behavior at the project and team level.
Why It Matters
The ability to configure an AI coding assistant at the project level addresses a practical problem for engineering teams: ensuring consistent behavior without repeating the same instructions in every session. By committing a project-level .claude/ folder to version control, teams distribute shared rules, commands, and policies to all contributors automatically.
Without this configuration layer, individual developers must re-establish context with each new Claude Code session — specifying coding conventions, naming patterns, and architectural constraints from scratch. The .claude/ system replaces that manual overhead with a persistent, version-controlled instruction set.
Technical Details
The system consists of two directories with distinct scopes. The project-level .claude/ folder is designed to be committed to git, ensuring, as Chawla writes, that “everyone on the team gets the same rules, the same custom commands, the same permission policies.” The global ~/.claude/ folder, located in the user’s home directory, holds personal preferences and machine-local state — including session history and auto-memory — that are specific to a single developer’s environment and should not be shared.
The most consequential file in either directory is CLAUDE.md. When a Claude Code session starts, the tool loads this file directly into the system prompt and maintains it for the full conversation. “Simply put: whatever you write in CLAUDE.md, Claude will follow,” Chawla states. Claude Code reads CLAUDE.md files from multiple locations simultaneously — the project root, the global ~/.claude/ directory, and any relevant subdirectories — and combines all of them into a single unified instruction set.
Chawla identifies a concrete performance ceiling: CLAUDE.md files should stay under 200 lines. “Files longer than that start eating too much context, and Claude’s instruction adherence actually drops,” he writes. He specifies what belongs in the file — build, test, and lint commands; key architectural decisions; non-obvious project gotchas; import conventions; naming patterns; and main module structure — and what should be excluded: content that belongs in linter or formatter configs, full documentation, and lengthy theoretical explanations.
Who’s Affected
Development teams using Claude Code on shared codebases are the primary audience. Teams working in monorepos or with strict coding standards can encode those requirements directly into the project-level .claude/ folder and version-control them alongside source code, eliminating the need to onboard each team member to Claude-specific conventions separately.
Individual developers benefit from the global ~/.claude/ directory, which supports personal preferences — preferred testing frameworks, error-handling styles, or communication patterns — that apply across every project without per-project configuration. The separation between project-level and global configuration allows both team-wide and individual defaults to coexist without conflict.
What’s Next
Chawla’s guide covers additional components beyond CLAUDE.md, including custom commands, skills, agent configuration, and permission policies. Those sections of the source were not fully available at time of publication; the complete walkthrough is accessible at Daily Dose of Data Science.
One structural limitation Chawla flags is context consumption: as CLAUDE.md files accumulate rules over time, they draw on system prompt space that would otherwise be available for conversation. Teams that add configuration incrementally should periodically audit and trim these files to maintain the instruction adherence that the 200-line ceiling is designed to protect.
