The .claude/ directory is not a black box – it is your control centre

There is a moment almost everyone who starts using Claude Code in earnest will recognise: at some point you notice a .claude/ directory appear in the project root. You open it briefly. You take a look inside. You close it again. And you carry on as before.

That is an expensive mistake – not in money, but in wasted control.

Last week Akshay Pachaar published an excellent Anatomy of the .claude/ folder that systematically breaks down what lives in this directory and why it matters. I recommend reading the original. What I want to do here is ask a different question: what changes in the way we work with AI tools once we take this folder seriously?

Claude does not behave randomly — it responds to context

The first mental shift that is needed: Claude Code is not a deterministic tool like a linter or a compiler. It is a context-driven system. That means: how it behaves depends directly on what it knows about your project.

Anyone who ignores .claude/ leaves this context to chance. Claude then has to guess from scratch at every session which conventions apply, which architectural decisions have been made, what is off-limits. That explains many of the frustrating moments you know from working with LLM coding tools: the answer was technically correct, but wrong for this project.

CLAUDE.md solves exactly that. It is not a configuration file in the technical sense — it is a briefing. And as with any good briefing: the clearer and more concise, the better. Akshay recommends staying under 200 lines. I would go even further: if it takes you more than 20 minutes to write, you have not yet thought clearly enough about what you actually expect from Claude.

The underrated benefit: team knowledge becomes explicit

There is a second, less obvious reason why .claude/ matters — and it has little to do with AI.

When you are forced to write down which architectural decisions apply, which gotchas exist, which conventions are non-negotiable — then you externalise implicit team knowledge. You make visible what otherwise only lives in the heads of individual senior developers.

The rules/ directory is particularly elegantly designed for this: modular Markdown files that activate by path scope. api-conventions.md only loads when Claude is working in src/api/. This is not only efficient for the context window — it is also a sensible ownership structure for the team. Whoever is responsible for API design maintains exactly one file.

This sounds like documentation. It is documentation — only with direct effects on the behaviour of your AI tool.

Commands and Skills: the difference matters

Here is a detail that causes confusion in everyday use: the difference between Commands and Skills.

Commands are explicit. You type /project:review, and a predefined prompt is executed — enriched with live data from shell commands. That is automation: fast, predictable, controlled.

Skills are implicit. Claude itself decides whether a skill fits the current situation and activates it without you entering anything. That is a different paradigm: less control, more autonomy — and therefore higher demands on the quality of the description in SKILL.md.

My assessment: for most teams, Commands are the better starting point. They are transparent, traceable and easy to debug. Skills make sense when you have workflows that are genuinely situational and contextual — for example a security review that should always kick in whenever someone touches authentication logic. But for a /pr-review command that you want to trigger deliberately anyway, you do not need any magic.

Agents: isolation as a feature

The section on .claude/agents/ is the one I had underestimated the most.

The idea is not new — subagents that take on specialised tasks in isolated contexts have existed as a concept for some time. But the implementation via simple Markdown files with YAML frontmatter is remarkably pragmatic. You define a security-auditor agent, give it only Read, Grep and Glob permissions, choose a cheaper model for exploration — and the main context stays clean.

The tool-restriction field (tools: Read, Grep, Glob) is more than a security feature here. It is also a thinking discipline: what does this agent really need? An agent that only reads cannot break anything. That is a form of software design applied to AI workflows.

settings.json: security as an explicit decision

The allow/deny mechanism in settings.json is the area that is most strongly underestimated by companies and teams.

The default setting — “ask if unclear” — is a sensible starting point. But as soon as Claude works in CI/CD pipelines, automated workflows or on critical infrastructure, “ask” is not an option. There it has to be explicitly defined what is allowed and what is not.

"deny": [
  "Bash(rm -rf *)",
  "Bash(curl *)",
  "Read(./.env)",
  "Read(./.env.*)"
]

This is not paranoia. This is sensible boundary-setting — the same thing you would do for any other automated process in your infrastructure.

What convinces me about this system

Over the past few months I have observed various ways in which teams integrate AI coding tools into their workflows. The most common patterns:

1. Ad-hoc use: everyone prompts however they see fit. Inconsistent results, plenty of frustration.
2. Prompt libraries: shared prompts in Notion or Confluence. Not contextual, hard to maintain.
3. Code-generator thinking: Claude as autocomplete on steroids. Useful for repetitive tasks, but wastes the potential.

The .claude/ system is something different: it moves the configuration of Claude directly into the repository. Versioned, reviewable, documenting. That has a quality the other approaches do not have: it scales with the project.

A team that maintains its .claude/ directory well gives every new developer — whether human or AI — the same context from day one. That is the real value.

Where to start?

If you use Claude Code and have ignored .claude/ so far:

Start with /init. Claude analyses your project and generates a starter CLAUDE.md. Then: trim, sharpen, commit.

Then settings.json with a sensible deny block for sensitive files and destructive commands.

Then — only once you notice you keep typing the same prompts over and over — a few commands in .claude/commands/.

The rest follows. But these three steps alone will noticeably change the quality of your Claude Code sessions.

This post is inspired by Akshay Pachaar’s thread Anatomy of the .claude/ folder from 21 March 2026 – highly recommended as an in-depth technical reference.