Developer PatternsHow It Works

Setting up Claude Code for your team: the leverage-ordered guide

In brief

The .claude folder has five layers. Most teams set up one and wonder why they keep correcting Claude. Here is what to configure in what order — and what you can skip entirely.

9 min read·System Prompt

Contents

♡Sign in to save

This article is about Claude Code — the terminal-based coding assistant. If you are building an application that calls the Claude API, the developer path starts here.

The .claude folder is not a feature to explore. It is a priority stack. Set up the bottom layers well and Claude behaves the way your team needs it to behave across every session. Skip them and you spend your time giving the same corrections over and over.

Most teams set up one layer — usually CLAUDE.md — and stop. That is a fine start. But if you are using Claude Code seriously, you have five tools available: CLAUDE.md, settings.json, hooks, rules, and skills/agents. Each one serves a different purpose. Each one is more optional than the last.

This guide walks through them in order of leverage, not alphabetical order.

Before anything else: there are two .claude folders

One lives inside your project. The other lives at ~/.claude/ in your home directory.

The project folder is team configuration. You commit it to git. Everyone on the team gets the same rules, the same permission policy, the same hooks. This is where your shared working agreements live.

The global folder is personal configuration. Your own preferences, your private instruction overrides, your session history. Claude loads both, and your project folder takes precedence on any conflict.

When you are wondering where a setting goes — if it is a team decision, the project folder. If it is personal preference, the global folder.

Layer 1: CLAUDE.md

This file loads into every Claude Code session as part of the system prompt. Everything you write in it, Claude holds in memory for the entire conversation.

That is worth sitting with. CLAUDE.md is not documentation. It is a live system prompt. Every line you add costs context. If you add 500 lines of background reading, you are burning token budget on information Claude rarely needs. Instruction adherence also drops as files get longer — not because Claude ignores long CLAUDE.md files, but because it weights instructions differently when there is too much to track.

What belongs in CLAUDE.md:

Your run commands. Claude will ask what commands exist if you do not tell it. Five lines solves this permanently.

Architecture decisions that are non-obvious. "We use Turborepo" or "all database access goes through the repository layer in src/db/" — things Claude would get wrong by default.

Gotchas. "TypeScript strict mode is on. Unused imports are a compile error." "Tests hit a real local database, not mocks. Run npm run db:test:reset before running the test suite." These are the things that waste 15 minutes the first time Claude gets them wrong.

Naming and import conventions that differ from common defaults. If you use a custom logger module instead of console.log, say so. If your error handling returns a { data, error } shape everywhere, say so.

What does not belong in CLAUDE.md:

Anything your linter or formatter already enforces. If ESLint catches it, Claude does not need to be told.

Long explanations. CLAUDE.md is not a wiki. If you need to explain background, link to the doc — do not paste the doc.

Things obvious from reading the code. Claude reads files. If the pattern is visible, it will pick it up.

A useful test: would Claude get this wrong on the first try without the instruction? If yes, it belongs in CLAUDE.md. If Claude would figure it out anyway, leave it out.

Keep CLAUDE.md under 200 lines. A minimal but complete file for a Node/TypeScript API covers: the four or five run commands, the stack in two sentences (Express, Node 20, PostgreSQL via Prisma), which directories hold what (handlers in src/handlers/, shared types in src/types/), and three or four conventions (zod for request validation, { data, error } response shape, the logger module not console.log). That is roughly 20 lines and it tells Claude everything it needs to work in the codebase without constant correction.

For personal preferences that should not affect the team — a different test runner preference, an editor workflow you like — create CLAUDE.local.md in the project root. It is auto-gitignored. Claude reads it alongside the main file. Your changes stay off the team's configuration.

Layer 2: settings.json

settings.json inside .claude/ controls what Claude is and is not allowed to do. Think of it as team policy written in JSON, not personal preference.

The file has two lists: allow and deny.

The allow list contains commands and operations that run automatically, without Claude prompting for confirmation. For most projects this covers your build and run scripts (Bash(npm run *) or Bash(make *)), read-only git commands (Bash(git status), Bash(git diff *)), and standard file operations (Read, Write, Edit, Glob, Grep).

The deny list contains commands that are blocked entirely, regardless of context. A sensible minimum set blocks destructive shell commands (Bash(rm -rf *)), direct network calls (Bash(curl *)), and access to credential files (Read(./.env), Read(./.env.*)).

Everything not in either list sits in the middle: Claude asks before proceeding. This is the right default for anything risky that you have not explicitly thought through. You do not need to anticipate every possible command. The ask-before behavior is the safety net for the gaps.

One note worth including: add the $schema line pointing to the Claude Code settings schema from SchemaStore. It enables autocomplete and inline validation in VS Code and Cursor, and takes 5 seconds to add.

For personal permission changes — if you want to allow something on your machine that the team has not collectively agreed to — use .claude/settings.local.json. Auto-gitignored, same format.

Layer 3: hooks

CLAUDE.md is a suggestion. Hooks are a guarantee.

If you write "always run the linter after editing files" in CLAUDE.md, Claude follows it most of the time. If you write a PostToolUse hook that runs the linter automatically, it runs every single time, without exception.

Hooks are shell scripts that fire at specific points in Claude's workflow. They receive a JSON payload on stdin and communicate back via exit codes. The configuration lives under a hooks key in settings.json.

The exit code mistake that kills most hook implementations:

Exit code 2 is the only code that blocks execution. Exit 0 is success. Exit 1 is "error, but non-blocking" — it logs a message and does nothing else. If you write a security hook and exit with code 1, you have written a hook that logs warnings while Claude proceeds anyway. For any hook meant to prevent an action, the exit code must be 2.

The two hooks worth setting up first:

A PostToolUse formatter that runs automatically after every file edit. Wire up the Write|Edit|MultiEdit matcher in settings.json to a command that reads the edited file path from the JSON payload (via jq -r '.tool_input.file_path') and runs Prettier on it. Claude edits a file, Prettier runs immediately, the file is formatted before Claude sees it again.

A PreToolUse bash firewall that blocks dangerous commands before they execute. A script reads the proposed command from stdin, checks it against a list of blocked patterns (rm -rf /, git push --force main, DROP TABLE, chmod 777), and exits with code 2 if there is a match. The match causes Claude to see the error and self-correct rather than proceeding.

The Stop hook trap:

Stop hooks fire when Claude finishes its work. A Stop hook that runs your test suite and exits 2 on failure prevents Claude from declaring done until tests pass — useful for quality gates. The trap: if you do not check the stop_hook_active flag in the JSON payload, the hook will block Claude, Claude will retry, the hook will block again, and you have an infinite loop. Always check this flag and return exit 0 on the second attempt.

One more thing: hooks do not hot-reload mid-session. Change a hook while Claude Code is running and you need to restart the session for it to take effect.

Layer 4: rules/

At some point CLAUDE.md grows. Different people own different parts. The API conventions section gets long. You want certain rules to only apply when Claude is working in specific directories.

That is when you reach for the rules/ folder.

Every markdown file inside .claude/rules/ loads alongside CLAUDE.md automatically. Instead of one file that everyone edits, you have separate files organized by concern — api-conventions.md, testing.md, code-style.md, security.md. The person who owns API conventions edits api-conventions.md. Nobody steps on each other.

The more useful feature is path-scoped rules. Add YAML frontmatter to a rules file and it only activates when Claude is working with matching paths. A file with paths: ["src/api/**/*.ts", "src/handlers/**/*.ts"] in its frontmatter loads when Claude is in those directories and nowhere else. The same API conventions that you want enforced in your handler code stay out of Claude's context when it is editing a React component.

Rules files without a paths field load unconditionally, every session.

Most teams do not need rules/ early on. When your CLAUDE.md hits around 200 lines, or when two people edit it in the same week and create a merge conflict — that is the signal.

Layer 5: skills and agents

Most teams never need these. That is not a reason to ignore them, but it is worth being honest about.

Skills are workflows that Claude invokes based on context — it reads the description in a skill's frontmatter and activates the skill when the task matches. They bundle a set of instructions with any supporting files the workflow needs. You can also call them explicitly with a slash command. The right use case: recurring workflows complex enough to be worth packaging — a security audit checklist before PRs, a deployment notes template, a release process guide.

Agents are specialized subagent personas. When a task is exploratory enough to flood your main context window with intermediate steps — reading 40 files, correlating findings across them, building a report — spawning an agent keeps that work in a separate context window and returns a compressed result. The tools field in an agent's config restricts what it can do: a code reviewer only needs Read, Grep, and Glob. A security auditor should not be writing files. The model field lets you run focused read-only tasks on a cheaper, faster model and reserve the heavier one for work that actually needs it.

The signal for skills: you find yourself giving Claude the same multi-step workflow instructions more than a few times a week. The signal for agents: a task is big enough that the exploration work would consume most of your context budget, and the final output is a distillation of that work rather than the exploration itself.

Where to start

Day one: CLAUDE.md with your run commands, architecture essentials, and non-obvious gotchas. Keep it under 50 lines. Add .claude/settings.json with an allow list for your build commands and a deny list for destructive operations and credential files.

First week: Add a PostToolUse formatter hook. This is the highest-leverage hook for most teams and takes about ten minutes to set up.

When you hit friction: If CLAUDE.md starts growing or causing merge conflicts, split it into .claude/rules/ files. If you have a security-critical workflow, add a PreToolUse bash firewall.

When you have recurring complexity: Skills and agents, for workflows you repeat often enough to formalize.

The 80/20: CLAUDE.md and settings.json get you most of the value. Every layer after that is an optimization on a working foundation — not a substitute for having the foundation right.