Inside the .claude/ Folder

There's a folder showing up in codebases that didn't exist two years ago. It sits next to .git/ and .github/, it rarely gets committed by accident, and most developers who use it have arrived at their own idiosyncratic structure through trial and error. The .claude/ directory — and more broadly, the project-level configuration layer for AI coding assistants — is becoming the most consequential undocumented convention in modern software development.

Nobody handed down a standard. Nobody wrote an RFC. Teams are improvising, and the patterns they're landing on reveal something important about what it actually takes to make AI coding tools work at the project level rather than the session level.

What the Folder Actually Contains

The .claude/ directory is Claude Code's primary mechanism for persistent, project-scoped context. At its core sits CLAUDE.md — a markdown file that functions as the AI's standing briefing document for your codebase. But calling it "just a markdown file" undersells what's happening.

A well-structured CLAUDE.md typically contains:

• Architecture decisions that aren't obvious from reading the code (why you're using event sourcing, why the auth layer is structured this way, which third-party SDK has the footgun you learned about the hard way)
• Conventions that aren't enforced by tooling (naming patterns, commit message formats, which abstractions are load-bearing vs. experimental)
• Explicit anti-patterns — the "don't do this" list that normally lives only in the heads of senior engineers who've been burned before
• Test and build commands so the model can run verification without asking
• Team-specific constraints like "never modify the billing module without a second reviewer flag in your response"

Beyond CLAUDE.md, the folder can hold slash command definitions — reusable prompt templates stored as markdown files in .claude/commands/. A team might define /review to mean "review this PR against our specific checklist," or /incident to mean "help me write a postmortem in our standard format." These are project-scoped shortcuts that travel with the repo.

The Context Problem This Solves

Every developer who's used an AI coding assistant for more than a few sessions has hit the same wall: the model doesn't remember anything. You explain your architecture on Monday, and by Tuesday's session you're explaining it again. The AI gives you generic advice because it doesn't know you're using an unusual database setup or that you have a firm constraint against adding new dependencies without a team vote.

This is the problem the .claude/ folder is quietly solving. It's a form of externalized project memory — context that used to exist only in human heads (or scattered across Notion docs nobody reads) now lives in a machine-readable location that gets loaded at session start.

The GitHub Blog's recent piece on how Squad runs coordinated AI agents inside repositories touches on a related challenge: when you're running multiple agents against the same codebase, shared project context isn't optional. Without it, agents contradict each other, duplicate work, or violate conventions that aren't in the code itself.

The .claude/ folder is a single-agent version of that same insight applied at human scale.

What Good Structure Looks Like

Developers experimenting with Claude Code — including several who've written up their setups on dev.to — are converging on a few structural patterns:

Keep CLAUDE.md ruthlessly pruned. Longer isn't better. Every line competes for attention in the context window. The goal is the minimum viable briefing — the things the model genuinely can't infer from reading the codebase. Architecture decisions go in. Style preferences that are already enforced by linters do not.

Separate commands by workflow, not by frequency. A .claude/commands/ folder with one massive "do everything" command is worse than no commands at all. Good command libraries mirror actual workflows: code review, incident response, PR description generation, changelog drafting. Each command is narrow and opinionated.

Version-control it, but treat it like documentation. The .claude/ folder deserves the same review process as your README or your docs/ folder. It's not configuration — it's a living description of how your team works. When your architecture changes, CLAUDE.md should change in the same PR.

Don't put secrets in it. This is obvious in retrospect but has burned people. The CLAUDE.md file is loaded into context and potentially logged. Treat it as public documentation even in private repos.

The Organizational Implication Nobody Talks About

Here's the part that gets interesting: maintaining a good .claude/ folder requires that someone on your team actually understand the system well enough to articulate it. That sounds obvious, but plenty of codebases have grown to a point where nobody can write the CLAUDE.md without discovering gaps in their own understanding.

The exercise of writing it forces the kind of documentation that teams perpetually defer. It's the same dynamic Simon Willison has written about in the context of prompting — the discipline of explaining your constraints precisely reveals which constraints you've never actually made explicit.

There's also a knowledge transfer angle. When a new engineer joins, the .claude/ folder can provide onboarding context in a form that's immediately actionable. Instead of reading docs and hoping they absorbed the important caveats, they can start a Claude Code session and interact with the codebase in a context that reflects your actual working conventions.

InfoQ's coverage of architecting portable systems on open standards touches on a relevant tension here: as teams invest more in AI-specific project configuration, there's a real question of portability. A .claude/ folder is Claude Code-specific. If you switch tools — or when you inevitably use multiple tools — that investment doesn't transfer automatically.

Some teams are hedging by writing CLAUDE.md in a way that's actually a superset: useful to any AI tool that accepts markdown context files, not just Claude. The conventions the file captures are tool-agnostic even if the filename isn't.

The Convention That Needs a Standard

The .claude/ folder is filling a genuine gap, but it's doing so in a fragmented way. Different teams are putting different things in it, there's no schema for CLAUDE.md, and there's no community-maintained guide to what a production-quality setup looks like.

That's the natural state of a convention that emerged from practice rather than design. The question is whether the ecosystem builds toward something more standardized — a shared schema, interoperability across tools, maybe an open-source registry of useful command patterns — or whether project-level AI context stays the permanently bespoke configuration layer it is today.

For now, the highest-leverage thing most teams can do is simple: open a CLAUDE.md, write down three things the AI keeps getting wrong because it doesn't know your codebase, and commit it. That's the whole starting point.

Everything else is iteration.

---

Sources: GitHub Blog on coordinated AI agents · Dev.to on AI-assisted coding in practice · InfoQ on portable system architecture · Simon Willison's blog