Anatomy of the .claude/ Folder - by Avi Chawla

Daily Dose of Data ScienceSubscribeSign inAnatomy of the .claude/ FolderA complete guide to CLAUDE.md, custom commands, skills, agents, and permissions, and how to set them up properly.Avi ChawlaMar 23, 20264833ShareIs AI actually saving your engineering team time?Most teams have adopted AI in some form, but the gap between “using AI” and “getting measurable ROI from AI” is larger than people realize.Postman released a cost savings analysis that looks at six common API development workflows and benchmarks the actual time and cost difference when AI is built into the platform versus bolted on externally.It’s a short, data-driven read that helps engineering leads make the case for where AI-native tooling actually moves the needle.You can grab the guide for free here →Thanks to Postman for partnering today!Anatomy of the .claude/ folderClaude Code users typically treat the .claude folder like 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.That’s a missed opportunity.The .claude folder is the control center for how Claude behaves in your project.It holds your instructions, your custom commands, your permission rules, and even Claude’s memory across sessions. Once you understand what lives where and why, you can configure Claude Code to behave exactly the way your team needs it to.This newsletter walks you through the entire anatomy of the folder, from the files you’ll use daily to the ones you’ll set once and forget.Two folders, not oneBefore diving in, one thing worth knowing upfront: there are actually two .claude directories, not one.The first lives inside your project, and the second lives in your home directory:The project-level folder holds team configuration. You commit it to git. Everyone on the team gets the same rules, the same custom commands, the same permission policies.The global ~/.claude/ folder holds your personal preferences and machine-local state, like session history and auto-memory.CLAUDE.md: Claude’s instruction manualThis is the most important file in the entire system. When you start a Claude Code session, the first thing it reads is CLAUDE.md. It loads it straight into the system prompt and keeps it in mind for the entire conversation.Simply put: whatever you write in CLAUDE.md, Claude will follow.If you tell Claude to always write tests before implementation, it will. If you say “never use console.log for error handling, always use the custom logger module,” it will respect that every time.A CLAUDE.md at your project root is the most common setup. But you can also have one in ~/.claude/CLAUDE.md for global preferences that apply across all projects, and even one inside subdirectories for folder-specific rules. Claude reads all of them and combines them.What actually belongs in CLAUDE.mdMost people either write too much or too little. Here’s what works.Write:Build, test, and lint commands (npm run test, make build, etc.)Key architectural decisions (”we use a monorepo with Turborepo”)Non-obvious gotchas (”TypeScript strict mode is on, unused variables are errors”)Import conventions, naming patterns, error handling stylesFile and folder structure for the main modulesDon’t write:Anything that belongs in a linter or formatter configFull documentation you can already link toLong paragraphs explaining theoryKeep CLAUDE.md under 200 lines. Files longer than that start eating too much context, and Claude’s instruction adherence actually drops.Here’s a minimal but effective 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, everThat’s ~20 lines. It gives Claude everything it needs to work productively in this codebase without constant clarification.CLAUDE.local.md for personal overridesSometimes you have a preference that’s specific to you, not the whole team. Maybe you prefer a different test runner, or you want Claude to always open files using a specific pattern.Create CLAUDE.local.md in your project root. Claude reads it alongside the main CLAUDE.md, and it’s automatically gitignored so your personal tweaks never land in the repo.The rules/ folder: modular instructions that scaleCLAUDE.md works great for a single project. But once your team grows, you end up with a 300-line CLAUDE.md that nobody maintains and everyone ignores.The rules/ folder solves that.Every markdown file inside .claude/rules/ gets loaded alongside your CLAUDE.md automatically. Instead of one giant file, you split instructions by concern:.claude/rules/
├── code-style.md
├── testing.md
├── api-conventions.md
└── security.mdEach file stays focused and easy to update. The team member who owns API conventions edits api-conventions.md. The person who owns the testing standards edits testing.md. Nobody stomps on each other.The real power comes from path-scoped rules. Add a YAML frontmatter block to a rule file and it only activates when Claude is working with matching files:---
paths:
- "src/api/**/*.ts"
- "src/handlers/**/*.ts"
---
# API Design Rules

- All handlers return { data, error } shape
- Use zod for request body validation
- Never expose internal error details to clientsClaude won’t load this file when editing a React component. It only loads when it’s working inside src/api/ or src/handlers/. Rules without a paths field load unconditionally, every session.This is the right pattern once your CLAUDE.md starts feeling crowded.The commands/ folder: your custom slash commandsOut of the box, Claude Code has built-in slash commands like /help and /compact. The commands/ folder lets you add your own.Every markdown file you drop into .claude/commands/ becomes a slash command.A file named review.md creates /project:review. A file named fix-issue.md creates /project:fix-issue. The filename is the command name.Here’s a simple example. Create .claude/commands/review.md:---
description: Review the current branch diff for issues before merging
---
## Changes to Review

!`git diff --name-only main...HEAD`

## Detailed Diff

!`git diff main...HEAD`

Review the above changes for:
1. Code quality issues
2. Security vulnerabilities
3. Missing test coverage
4. Performance concerns

Give specific, actionable feedback per file.Now run /project:review in Claude Code and it automatically injects the real git diff into the prompt before Claude sees it. The ! backtick syntax runs shell commands and embeds the output. That’s what makes these commands genuinely useful instead of just saved text.Passing arguments to commandsUse $ARGUMENTS to pass text after the command name:---
description: Investigate and fix a GitHub issue
argument-hint: [issue-number]
---
Look at issue #$ARGUMENTS in this repo.

!`gh issue view $ARGUMENTS`

Understand the bug, trace it to the root cause, fix it, and write a
test that would have caught it.Running /project:fix-issue 234 feeds issue 234’s content directly into the prompt.Personal vs. project commandsProject commands in .claude/commands/ are committed and shared with your team. For commands you want everywhere regardless of project, put them in ~/.claude/commands/. Those show up as /user:command-name instead.A useful personal command: a daily standup helper, a command for generating commit messages following your convention, or a quick security scan.The skills/ folder: reusable workflows on demandYou now know how commands work. Skills look similar on the surface, but the trigger is fundamentally different. Here’s the distinction before we go any further:Skills are workflows that Claude can invoke on its own, without you typing a slash command, when the task matches the skill’s description. Commands wait for you. Skills watch the conversation and act when the moment is right.Each skill lives in its own subdirectory with a SKILL.md file:.claude/skills/
├── security-review/
│ ├── SKILL.md
│ └── DETAILED_GUIDE.md
└── deploy/
├── SKILL.md
└── templates/
└── release-notes.mdThe SKILL.md uses YAML frontmatter to describe when to use it:---
name: security-review
description: Comprehensive security audit. Use when reviewing code for
vulnerabilities, before deployments, or when the user mentions security.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for security vulnerabilities:

1. SQL injection and XSS risks
2. Exposed credentials or secrets
3. Insecure configurations
4. Authentication and authorization gaps

Report findings with severity ratings and specific remediation steps.
Reference @DETAILED_GUIDE.md for our security standards.When you say “review this PR for security issues,” Claude reads the description, recognizes it matches, and invokes the skill automatically. You can also call it explicitly with /security-review.The key difference from commands: skills can bundle supporting files alongside them. The DETAILED_GUIDE.md reference above pulls in a detailed document that lives right next to SKILL.md. Commands are single files. Skills are packages.Personal skills go in ~/.claude/skills/ and are available across all your projects.The agents/ folder: specialized subagent personasWhen a task is complex enough to benefit from a dedicated specialist, you can define a subagent persona in .claude/agents/. Each agent is a markdown file with its own system prompt, tool access, and model preference:.claude/agents/
├── code-reviewer.md
└── security-auditor.mdHere’s what a code-reviewer.md looks like:---
name: code-reviewer
description: Expert code reviewer. Use PROACTIVELY when reviewing PRs,
checking for bugs, or validating implementations before merging.
model: sonnet
tools: Read, Grep, Glob
---
You are a senior code reviewer with a focus on correctness and maintainability.

When reviewing code:
- Flag bugs, not just style issues
- Suggest specific fixes, not vague improvements
- Check for edge cases and error handling gaps
- Note performance concerns only when they matter at scaleWhen Claude needs a code review done, it spawns this agent in its own isolated context window. The agent does its work, compresses the findings, and reports back. Your main session doesn’t get cluttered with thousands of tokens of intermediate exploration.The tools field restricts what the agent can do. A security auditor only needs Read, Grep, and Glob. It has no business writing files. That restriction is intentional and worth being explicit about.The model field lets you use a cheaper, faster model for focused tasks. Haiku handles most read-only exploration well. Save Sonnet and Opus for the work that actually needs them.Personal agents go in ~/.claude/agents/ and are available across all projects.settings.json: permissions and project configThe settings.json file inside .claude/ controls what Claude is and isn’t allowed to do. It’s where you define which tools Claude can run, which files it can read, and whether it needs to ask before running certain commands.The complete file looks like this:{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git status)",
"Bash(git diff *)",
"Read",
"Write",
"Edit"
],
"deny": [
"Bash(rm -rf *)",
"Bash(curl *)",
"Read(./.env)",
"Read(./.env.*)"
]
}
}Here’s what each part does.The $schema line enables autocomplete and inline validation in VS Code or Cursor. Always include it.The allow list contains commands that run without Claude asking for confirmation. For most projects, a good allow list covers:Bash(npm run *) or Bash(make *) so Claude can run your scripts freelyBash(git *) for read-only git commandsRead, Write, Edit, Glob, Grep for file operationsThe deny list contains commands that are blocked entirely, no matter what. A sensible deny list blocks:Destructive shell commands like rm -rfDirect network commands like curlSensitive files like .env and anything in secrets/If something isn’t in either list, Claude asks before proceeding. That middle ground is intentional. It gives you a safety net without having to anticipate every possible command upfront.That said, you can also have settings.local.json for personal overrides. It has the same idea as CLAUDE.local.md. Create .claude/settings.local.json for permission changes you don’t want committed. It’s auto-gitignored.The global ~/.claude/ folderYou don’t interact with this folder often, but it’s useful to know what’s in it.~/.claude/CLAUDE.md loads into every Claude Code session, across all your projects. Good place for your personal coding principles, preferred style, or anything you want Claude to remember, regardless of which repo you’re in.~/.claude/projects/ stores session transcripts and auto-memory per project. Claude Code automatically saves notes to itself as it works: commands it discovers, patterns it observes, and architecture insights. These persist across sessions. You can browse and edit them with /memory.~/.claude/commands/ and ~/.claude/skills/ hold personal commands and skills available across all projects.You generally don’t need to manually manage these. But knowing they exist is handy when Claude seems to “remember” something you never told it, or when you want to wipe a project’s auto-memory and start fresh.The full pictureHere’s how everything comes together:your-project/
├── CLAUDE.md # Team instructions (committed)
├── CLAUDE.local.md # Your personal overrides (gitignored)
│
└── .claude/
├── settings.json # Permissions + config (committed)
├── settings.local.json # Personal permission overrides (gitignored)
│
├── commands/ # Custom slash commands
│ ├── review.md # → /project:review
│ ├── fix-issue.md # → /project:fix-issue
│ └── deploy.md # → /project:deploy
│
├── rules/ # Modular instruction files
│ ├── code-style.md
│ ├── testing.md
│ └── api-conventions.md
│
├── skills/ # Auto-invoked workflows
│ ├── security-review/
│ │ └── SKILL.md
│ └── deploy/
│ └── SKILL.md
│
└── agents/ # Specialized subagent personas
├── code-reviewer.md
└── security-auditor.md

~/.claude/
├── CLAUDE.md # Your global instructions
├── settings.json # Your global settings
├── commands/ # Your personal commands (all projects)
├── skills/ # Your personal skills (all projects)
├── agents/ # Your personal agents (all projects)
└── projects/ # Session history + auto-memoryA practical setup to get startedIf you’re starting from scratch, here’s a progression that works well.Step 1. Run /init inside Claude Code. It generates a starter CLAUDE.md by reading your project. Edit it down to the essentials.Step 2. Add .claude/settings.json with allow/deny rules appropriate for your stack. At minimum, allow your run commands and deny .env reads.Step 3. Create one or two commands for the workflows you do most. Code review and issue fixing are good starting points.Step 4. As your project grows and your CLAUDE.md gets crowded, start splitting instructions into .claude/rules/ files. Scope them by path where it makes sense.Step 5. Add a ~/.claude/CLAUDE.md with your personal preferences. This might be something like “always write types before implementations” or “prefer functional patterns over class-based.”That’s genuinely all you need for 95% of projects. Skills and agents come in when you have recurring complex workflows worth packaging up.The key insightThe .claude folder is really a protocol for telling Claude who you are, what your project does, and what rules it should follow. The more clearly you define that, the less time you spend correcting Claude and the more time it spends doing useful work.CLAUDE.md is your highest-leverage file. Get that right first. Everything else is optimization.Start small, refine as you go, and treat it like any other piece of infrastructure in your project: something that pays dividends every day once it’s set up properly.Thanks for reading!4833SharePreviousNextDiscussion about this postCommentsRestacksjonathanfishner11 8hReally useful guide, Avi. Quick question that's been on my mind.The deny list in settings.json works well when a human is driving. But when Claude Code runs as an agent (headless, CI pipelines, automated workflows), a deny list isn't enough. The agent has Bash access, it can get creative.We built OneCLI (https://github.com/onecli/onecli) around this problem. Proxy layer that swaps placeholder tokens for real creds at the network level, so the agent never touches actual secrets.But beyond credentials, do you think the entire .claude/ config should look different for agent mode vs human mode? Different rules, different permissions, maybe even different skills that activate? Would love to hear your take. (onecli.sh)ReplyShareRandy Lutcavich 3dThis is good, but no need to separate out Commands now that they have been merged with Skills.https://code.claude.com/docs/en/slash-commands#skill-tool"Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Your existing .claude/commands/ files keep working. Skills add optional features: a directory for supporting files, frontmatter to control whether you or Claude invokes them, and the ability for Claude to load them automatically when relevant."ReplyShare1 more comment...TopLatestDiscussionsNo postsReady for more?Subscribe© 2026 Avi Chawla · Privacy ∙ Terms ∙ Collection notice Start your SubstackGet the appSubstack is the home for great culture

This site requires JavaScript to run correctly. Please turn on JavaScript or unblock scripts

The .claude/ Folder: A Comprehensive Guide

Avi Chawla, Mar 23, 2026

AI’s impact on engineering teams is being questioned, with a significant gap between AI adoption and realizing tangible returns. Postman’s cost analysis highlights the value of AI-native tooling, demonstrating how integrating AI into development workflows can dramatically reduce time and costs. This guide, authored by Avi Chawla, delves into the anatomy of the .claude/ folder, a crucial component for optimizing Claude Code’s behavior within your projects. The folder serves as a central control point for instructions, custom commands, permissions, and memory, allowing teams to tailor Claude’s responses precisely to their needs.

Two-Folder Structure

The .claude/ folder isn’t a single entity; it comprises two distinct directories: a project-level folder and a global ~/.claude/ folder. The project-level folder maintains team-wide configuration settings, including shared rules, commands, and permissions. These settings are committed to a Git repository, ensuring consistency across the team’s development environment. Conversely, the global ~/.claude/ folder is dedicated to personal preferences and machine-local state, such as session history and auto-memory, providing a tailored experience for each user.

The CLAUDE.md File: The Core Instruction Manual

The CLAUDE.md file is the most critical element within the .claude/ folder. When Claude Code initiates a session, the first document it loads and interprets is CLAUDE.md. This file effectively acts as Claude’s instruction manual, dictating its behavior throughout the conversation. It’s crucial to understand the content of this file, as any instructions within it will be diligently followed by Claude.

Effective Content in CLAUDE.md

The content of CLAUDE.md directly impacts Claude’s effectiveness. Overly verbose files or those lacking essential details can lead to confusion and inconsistent responses. However, a concise and well-structured CLAUDE.md is paramount. It should encompass:

* **Build, Test, and Lint Commands:** Including commands such as `npm run test` or `make build` provides Claude with the context it needs to execute these tasks directly.
* **Architectural Decisions:** Documenting key architectural choices, like the use of a monorepo with Turborepo, helps Claude understand the broader project structure.
* **Gotchas and Conventions:** Highlighting non-obvious technical constraints, such as TypeScript strict mode or import conventions, prevents Claude from making suboptimal decisions.
* **File and Folder Structure:** Defining the organization of your main modules and code files streamlines Claude's understanding of the codebase.

A minimal CLAUDE.md example, containing roughly 20 lines, is recommended. Avoid lengthy explanations or philosophical discussions, as these can negatively impact Claude’s adherence to the instructions.

CLAUDE.local.md: Personal Overrides

While CLAUDE.md governs shared team preferences, CLAUDE.local.md allows individual developers to define personal customizations that don’t need to be disseminated across the team. This file, located in your project root, enables you to set different preferences for things like testing frameworks or file opening patterns. Importantly, it’s automatically gitignored, ensuring that these changes don't contaminate the team’s shared configuration.

The Rules/ Folder: Modular Instructions

For larger teams or projects, a single CLAUDE.md can become unwieldy. The rules/ folder provides a solution by allowing you to break down instructions into modular files, each focused on a specific concern. For example, you might have a `code-style.md` defining coding standards, a `testing.md` outlining testing methodologies, and an `api-conventions.md` establishing API design rules. Each rule file can be scoped to specific paths within the codebase using YAML frontmatter, ensuring that the instruction is applied only when Claude is working with relevant files, significantly improving efficiency. Unscoped rules apply unconditionally.

Commands/ Folder: Custom Slash Commands

The commands/ folder enables the creation of custom slash commands within Claude Code. Each markdown file in this folder becomes a slash command, offering a streamlined way to trigger specific actions. For example, a `review.md` file creates `/project:review`, and a `fix-issue.md` creates `/project:fix-issue`. The filename itself becomes the command name, and the content of the file defines the command’s logic. Utilizing backticks within the files allows you to run shell commands and embed their output directly into Claude’s prompt.

Skills/ Folder: Automated Workflows

Skills represent a more sophisticated approach than commands, providing reusable workflows that can be invoked automatically by Claude. Each skill resides in its own subdirectory with a SKILL.md file, which defines its description, allowed tools, and model preference. The SKILL.md file utilizes YAML frontmatter to control when the skill should be activated, adding a degree of flexibility and relevance to Claude’s responses.

Agents/ Folder: Specialized Subagent Personas

When a task requires a specialized skillset, the agents/ folder allows you to define subagent personas—dedicated specialists that can operate within Claude’s context. Each agent possesses a system prompt tailored to its specific role, access to relevant tools, and a distinct model preference. This compartmentalized approach isolates complex tasks and enhances clarity, improving the overall efficiency of the development process.

Settings.json: Permission Control

The settings.json file within the .claude/ folder governs Claude’s permissions, defining which commands it is allowed to execute and which files it can access. Restricting command access prevents accidental or malicious actions, while controlling file access protects sensitive information. The “allow” and “deny” lists in the configuration file provide granular control over Claude’s capabilities.

Conclusion: Optimizing Claude Code

By diligently configuring the .claude/ folder, engineering teams can significantly enhance Claude Code’s performance and productivity. The judicious use of CLAUDE.md, the structure of the rules/ folder, custom commands in the commands/ folder, skills, agents, and granular permission settings unlocks the full potential of Claude Code, transforming it from a “black box” into a reliable and adaptable tool tailored to your team's specific needs, ultimately driving greater efficiency and measurable returns on investment.