The Complete Claude Code Setup Guide (2026)

You just installed Claude Code. You typed claude in your terminal and... it works. It can read your files, run commands, write code. Pretty cool.

But here's the thing: you're leaving 90% of its power on the table.

In our analysis of 800+ configurations at jeanclaudecode.ai, the average setup scores 3.2 out of 10. Most people install Claude Code, maybe write a couple lines of instructions, and stop there. Ten minutes of setup separates a basic chatbot from a genuine coding partner.

Let's fix that right now.

The one file that changes everything

Create a file called CLAUDE.md at the root of your project. That's it. That's the single most important thing you'll do today.

touch CLAUDE.md

CLAUDE.md is the first thing Claude reads when you start a session. Think of it as a briefing document — you're telling Claude who it's working with, what the project looks like, and what the rules are.

Here's a minimal one to start with. Open CLAUDE.md and paste this:

# My Project

## Tech Stack
- Next.js 15, TypeScript, PostgreSQL

## Key Commands
- `npm run dev` — start dev server
- `npm run test` — run tests
- `npm run build` — production build

## Rules
- Always run tests before saying a task is done
- Never modify files in src/legacy/

Five lines of tech stack. Three commands. Two rules. That's all you need to start.

Try it now. Open Claude Code and ask: "Read my CLAUDE.md and tell me what project this is." Claude should describe your project back to you. If it does, you're set. If it doesn't, check that the file is at your project root (not inside a subfolder).

You just gave Claude something 68% of setups are missing: basic project awareness.

Build it up: the CLAUDE.md that top setups use

That minimal file works. But the setups scoring 7+ out of 10 in our analysis go further. Here's what they add — and why each section matters.

Architecture section (found in 78% of top setups)

Claude doesn't know where your files live. Without a map, it guesses — and it guesses wrong. Add this:

## Architecture
- src/app/ — App Router pages and API routes
- src/lib/ — shared utilities and database client
- src/components/ — React components (colocated tests)

Now when you say "create a new API route," Claude puts it in src/app/api/ instead of inventing a random location.

Conventions section (65% of top setups)

You have opinions about how code should look. Claude doesn't know them unless you say so:

## Conventions
- Imperative commit messages, lowercase, no period
- One component per file, named exports only
- All API routes validate input with zod schemas

Be specific. "Write clean code" gives Claude nothing. "Use zod for all API input validation" gives it a concrete rule to follow.

Known issues section (only 34% of top setups — biggest missed opportunity)

This is the section most people skip, and it's the one that saves you the most frustration:

## Known Issues
- The Stripe webhook handler needs `raw` body parsing — don't use express.json() middleware on /api/webhooks/stripe
- Safari doesn't support `structuredClone` in workers — use the polyfill in src/lib/clone.ts
- CI has 4GB RAM — tests that exceed this will OOM silently

Every time Claude makes a mistake you've seen before, add it here. Over time, this becomes the most valuable section in the file — a living record of "don't step on this landmine."

Now let's add permissions (so Claude stops asking you for every little thing)

Out of the box, Claude asks for permission before running any shell command. Every. Single. Time. It gets old fast.

The fix: create a settings file that tells Claude what it can do without asking.

mkdir -p .claude

Now create .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(npm run test*)",
      "Bash(npm run build)",
      "Bash(npm run lint*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)"
    ]
  }
}

The allow list says "go ahead, don't ask." The deny list says "never do this, even if I accidentally tell you to."

Important: Never put "Bash(*)" in the allow list. That gives Claude full shell access with zero guardrails. Be specific about what's allowed.

Try running Claude Code now. Ask it to check the git status or run tests. Notice how it just... does it? No permission popup. That flow is what separates setups people abandon from setups people actually use every day.

Add rules that activate automatically

You might be wondering: "Should I put all my coding conventions in CLAUDE.md?" You could. But there's a smarter way.

Rules are markdown files that activate based on which files Claude is working on. When Claude edits a .tsx file, it loads your frontend rules. When it touches a migration file, it loads your database rules. When it's working on CSS, it doesn't waste time reading your SQL conventions.

Create the rules directory:

mkdir -p .claude/rules

Here's a frontend rule. Save this as .claude/rules/frontend.md:

---
globs: ["*.tsx", "*.jsx", "*.css"]
---

- Use named exports, not default exports
- Every component must have a corresponding .test.tsx file
- CSS modules only — no inline styles except for dynamic values
- All images need alt text (accessibility requirement)

And a database rule — save as .claude/rules/database.md:

---
globs: ["*.sql", "**/migrations/**", "**/prisma/**"]
---

- Never modify existing migration files
- All queries must use parameterized inputs — never string concatenation
- Include rollback logic in every migration

The globs line at the top is the trigger. When Claude reads or edits any file matching that pattern, the rule automatically loads. No extra tokens wasted when it's not relevant.

See what you've built

Here's what your project should look like now:

your-project/
├── CLAUDE.md                          # Your project briefing
├── .claude/
│   ├── settings.json                  # Permissions (committed, shared with team)
│   └── rules/
│       ├── frontend.md                # Activates for .tsx, .jsx, .css
│       └── database.md                # Activates for .sql, migrations
├── .gitignore
└── src/
    └── ...

One more thing — add this line to your .gitignore:

# Claude Code local settings
.claude/settings.local.json

That settings.local.json file is for personal preferences (like your preferred model). It shouldn't be in version control. The regular settings.json? Commit that — it's shared team configuration.

Verify everything works

Open Claude Code and try this:

> Read my CLAUDE.md and tell me what project this is. What rules do you see?

Claude should describe your project, list the rules it found in .claude/rules/, and confirm the permissions from settings.json. If it can, you're done. If something's missing, check that your files are in the right locations.

You can also score your setup with our analyzer — it checks all four layers (CLAUDE.md, settings, rules, directory structure) and tells you exactly what's working and what's missing.

The mistakes that drag setups down

After reviewing hundreds of setups, these are the patterns that consistently score low:

Vague instructions. "Write clean code" and "follow best practices" give Claude zero useful information. Compare: "validate inputs properly" (useless) vs "Use zod for all API input validation" (actionable).

No permission allowlist. Every tool call requires manual approval, the developer gets frustrated, abandons Claude Code, and concludes it's not productive. Five minutes of settings.json prevents this entirely.

Everything crammed into CLAUDE.md. Your database conventions don't matter when Claude is editing CSS. Move file-specific instructions to rules files — they keep context focused and save tokens.

No architecture section. Without a file map, Claude puts files in the wrong directories, uses incorrect import paths, and generates code that doesn't fit your project. A 5-line architecture section prevents this.

Missing .gitignore for local settings. Team members override each other's preferences, or worse, API keys end up in version control.

What's next

You've got a solid foundation. Your CLAUDE.md tells Claude about your project, your settings keep it productive, and your rules keep it on track.

Ready for more? Here's where to go:

• Automate the boring stuff — hooks that format code automatically, skills that run multi-step workflows with a slash command, and when to use which
• Connect Claude to your tools — MCP servers that let Claude query your database, search your GitHub issues, and pull Sentry errors directly
• Keep your bill under control — real cost numbers, the /compact trick, and when Opus is worth the premium

Frequently Asked Questions

Where should CLAUDE.md go — project root or .claude directory?

Project root. Claude Code looks for CLAUDE.md at the root of your working directory first. You can also create ~/.claude/CLAUDE.md for global instructions that apply to all your projects. If both exist, both are loaded — global first, then project-specific.

Can the whole team share one CLAUDE.md?

Yes, and they should. CLAUDE.md belongs in your repository. It's shared context — project architecture, conventions, commands. For personal preferences (like which model you prefer or custom aliases), use .claude/settings.local.json which stays gitignored.

How long should CLAUDE.md be?

The best setups we've analyzed are between 100 and 500 lines. Under 100 means you're probably missing critical context (architecture, conventions, known issues). Over 500 means you're including stuff that belongs in rules files instead. The goal is focused, high-signal instructions.

Does Claude Code work without any of this setup?

Technically yes, but poorly. Without CLAUDE.md, Claude has no knowledge of your project structure, conventions, or constraints. It still generates code, but it puts files in the wrong places, uses incorrect patterns, and ignores your project-specific rules. Our data shows unconfigured setups average 1.8/10. Setup isn't optional if you want real productivity gains.

How often should I update my CLAUDE.md?

Whenever your project changes: new conventions, new tools, new known issues. A good habit is adding a "Known Issues" entry every time Claude makes a mistake that shouldn't happen again. Over time, CLAUDE.md becomes a living document that prevents the same errors from recurring — and that's one of the highest-value uses of the file.