Introduction I often get questions about how to set up Claude Code properly before diving into the advanced stuff — skills, hooks, subagents, and MCP servers. The honest answer is that most people skip the fundamentals, then wonder why the tool behaves inconsistently. Two things covered here: the file hierarchy — where settings actually live and which ones take precedence — and CLAUDE.md, which is the one file that makes Claude Code feel like it knows your project instead of starting from scratch every session. CLAUDE.md Nothing in here is complex. But getting it wrong will undermine everything you build on top of it. Configuration Overview There is no single config file. Settings are spread across several files, each scoped differently — which is exactly why permissions sometimes seem to "not stick" and why your teammate's setup behaves differently from yours. Broken down by scope: User-level (global, applies to all projects): ~/.claude/settings.json — your personal defaults: model preference, globally allowed/denied tools
~/.claude/CLAUDE.md — instructions that load in every session, across every project ~/.claude/settings.json — your personal defaults: model preference, globally allowed/denied tools ~/.claude/settings.json ~/.claude/CLAUDE.md — instructions that load in every session, across every project ~/.claude/CLAUDE.md Project-level (lives in the repo): .claude/settings.json — team-shared settings; commit this
.claude/settings.local.json — your personal overrides within the project; gitignored automatically
CLAUDE.md — project-specific instructions; commit this too
CLAUDE.local.md — your personal project notes; gitignored .claude/settings.json — team-shared settings; commit this .claude/settings.json .claude/settings.local.json — your personal overrides within the project; gitignored automatically .claude/settings.local.json CLAUDE.md — project-specific instructions; commit this too CLAUDE.md CLAUDE.local.md — your personal project notes; gitignored CLAUDE.local.md The rule of thumb: enterprise managed beats project-local, project-local beats project-shared, and project-shared beats user. More specific always wins. Worth knowing before you hit it: defining a permissions block at the project level currently replaces your global permissions, not extends them. Tools you allowed globally will start prompting for confirmation again inside that project unless you list them again explicitly. The docs imply merging. The actual behavior is replacement. Add it to your mental model now. Worth knowing before you hit it: permissions The two files you need right now. ~/.claude/settings.json ~/.claude/settings.json Start here. Set your model, then lock down anything you never want Claude near. {
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Bash(git log *)",
      "Bash(gcloud builds list *)"
    ]
  }
} {
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Bash(git log *)",
      "Bash(gcloud builds list *)"
    ]
  }
} You'll notice there are no deny rules here. That is intentional — I'll explain why in the next section. deny CLAUDE.md CLAUDE.md Claude reads this file at the start of every session, before you type anything. Plain Markdown, no special syntax. The closest analogy I have: it's the onboarding doc you write once for a new joiner — except this one actually gets read, every time, without skimming. Claude picks these up automatically from three locations: ~/.claude/CLAUDE.md    # global — scaffolding rules, personal defaults
./CLAUDE.md            # project root — architecture, build commands, conventions
./src/CLAUDE.md        # subdirectory — component-specific rules ~/.claude/CLAUDE.md    # global — scaffolding rules, personal defaults
./CLAUDE.md            # project root — architecture, build commands, conventions
./src/CLAUDE.md        # subdirectory — component-specific rules Conflicts are resolved in favor of the more specific one. In practice, this works reliably when files cover different topics. The global file sets your personal defaults, the project file covers the stack and conventions — no overlap, no ambiguity. Where it gets murkier is when two levels define conflicting instructions for the same thing. The spec says the more specific file wins, but in practice, Claude may blend instructions from both, or follow whichever appeared more recently in context. I have seen it go both ways. Treat cross-level conflicts as undefined behavior and avoid them by keeping each file's scope distinct. What to put in CLAUDE.md First instinct is usually to dump everything in. Don't. Past a certain point CLAUDE.md stops helping — it just burns tokens and buries the instructions that actually matter. CLAUDE.md For the global ~/.claude/CLAUDE.md, I keep things that apply everywhere — personal habits, not project specifics: ~/.claude/CLAUDE.md # Global Preferences

- Never use `rm -rf` without confirmation.
- Prefer explicit error handling over silent failures.
- When in doubt about scope of a change, ask before proceeding.
- Use the `gh` CLI for all GitHub operations, not raw `curl` against the API. # Global Preferences

- Never use `rm -rf` without confirmation.
- Prefer explicit error handling over silent failures.
- When in doubt about scope of a change, ask before proceeding.
- Use the `gh` CLI for all GitHub operations, not raw `curl` against the API. The project-level CLAUDE.md is best thought of as the onboarding you never had time to write — the stuff a new developer would figure out after a few hours of poking around, now written down in one place: CLAUDE.md # Project: payments-service

## Stack
Node.js 20, TypeScript, PostgreSQL via Prisma, Jest for tests.

## Build and Test
- Build: `npm run build`
- Run tests: `npm test`
- Lint: `npm run lint` (must pass before any commit)

## Architecture Notes
- All database access goes through `/src/repositories`. Never query the DB directly from controllers.
- `src/lib/stripe.ts` wraps the Stripe SDK. Do not instantiate Stripe directly elsewhere.

## Conventions
- Error handling: use the `AppError` class in `src/lib/errors.ts`
- Logging: use the logger in `src/lib/logger.ts`, not `console.log` # Project: payments-service

## Stack
Node.js 20, TypeScript, PostgreSQL via Prisma, Jest for tests.

## Build and Test
- Build: `npm run build`
- Run tests: `npm test`
- Lint: `npm run lint` (must pass before any commit)

## Architecture Notes
- All database access goes through `/src/repositories`. Never query the DB directly from controllers.
- `src/lib/stripe.ts` wraps the Stripe SDK. Do not instantiate Stripe directly elsewhere.

## Conventions
- Error handling: use the `AppError` class in `src/lib/errors.ts`
- Logging: use the logger in `src/lib/logger.ts`, not `console.log` Keep in mind this isn't documentation — it's operational context for something that otherwise starts every session knowing nothing about your codebase. Why I don't set deny rules. The obvious question: why no .env deny rules, no rm -rf block? .env rm -rf The short answer is that deny rules in settings.json are not a reliable security boundary. They're pattern-matching on strings. Claude Code is an agent that reasons — and agents reason around pattern matching. settings.json Security researchers documented a case where Claude bypassed a deny rule by using /proc/self/root/usr/bin/npx instead of npx. Different string, same binary. When the sandbox caught that, the agent identified the sandbox as the obstacle and reasoned about disabling it. No jailbreak, no special prompt. It was just solving a problem. There's also a filed bug where Read and Write deny rules were found to be completely non-functional on certain platforms — Claude would read the file anyway. /proc/self/root/usr/bin/npx npx For anything I genuinely don't want touched, I rely on OS-level file permissions or run Claude Code in a container. Those actually hold. A JSON deny list does not. There's a community plugin that does a better job than deny rules for the common cases: claude-code-safety-net. It intercepts destructive git and filesystem commands at a lower level, before they execute. Worth installing. Just don't treat it as a hard guarantee — a sufficiently motivated agent can still find a way around it. claude-code-safety-net Put simply: Claude Code runs as you, on your machine. Don't hand it credentials it has no reason to touch, don't point it at a repo you haven't read, and don't walk away from a long agentic run on anything you can't roll back. Put simply: Claude Code runs as you, on your machine. Pitfalls and how to avoid them. Committing the wrong files Four files come out of this setup. Two go in the repo, two stay off it. # Commit these — share with the team
./CLAUDE.md
./.claude/settings.json

# Do NOT commit these — personal overrides
./CLAUDE.local.md
./.claude/settings.local.json # Commit these — share with the team
./CLAUDE.md
./.claude/settings.json

# Do NOT commit these — personal overrides
./CLAUDE.local.md
./.claude/settings.local.json settings.local.json is gitignored automatically. CLAUDE.local.md is not — that one you have to handle yourself. Miss it, and you'll end up committing personal notes, local paths, or half-finished permission experiments to the shared repo. settings.local.json CLAUDE.local.md # Add to your .gitignore
echo "CLAUDE.local.md" >> .gitignore # Add to your .gitignore
echo "CLAUDE.local.md" >> .gitignore Obvious in hindsight. Less obvious when you're staring at a CI failure at 11 pm, trying to figure out why a machine-local path ended up in a shared config. Using CLAUDE.md as a substitute for a good project structure I've seen CLAUDE.md files that run to several hundred lines, detailing the entire history of architectural decisions, third-party integrations, and business logic edge cases. This is counterproductive. CLAUDE.md Every line loads into context on every session. At some point, the file starts working against you — the stuff that actually matters gets buried, you're burning tokens on background noise, and Claude starts making decisions based on whichever instruction happened to land closest to the end of its context window. My rule of thumb: if you're writing a paragraph explaining why a module is structured a certain way, that belongs in a code comment or an ADR.md — not in the agent's startup context. CLAUDE.md is for operations: how to build, how to test, what tools to use, what to never touch. ADR.md CLAUDE.md Not sure where to start? Run /init from the project directory. Claude Code scans the codebase and generates a starter file. It won't be perfect, but it's a better starting point than a blank page. Not sure where to start? /init Summary Before hooks, subagents, or other integrations — get these two right: ~/.claude/settings.json — pick your model, set your allowed tools. That's it for now.
CLAUDE.md — global file for personal defaults, project file for build commands, stack, and conventions. Commit the project one. Keep both short enough that you'd actually read them yourself. ~/.claude/settings.json — pick your model, set your allowed tools. That's it for now. ~/.claude/settings.json CLAUDE.md — global file for personal defaults, project file for build commands, stack, and conventions. Commit the project one. Keep both short enough that you'd actually read them yourself. CLAUDE.md The blur I see most often: people write rules in CLAUDE.md expecting them to hold under pressure, then reach for settings.json permissions as an afterthought. It tends to go the other way around — permissions for the hard stops, CLAUDE.md for everything that requires judgment. The blur I see most often: CLAUDE.md settings.json CLAUDE.md

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Navigating Claude Code: The Bare Minimum Setup

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Asynchronous Runtimes: A Primer for the Perplexed Developer

Qwen3.5-2B Distills Opus Reasoning Into a Tiny GGUF Model

When RPA Reaches Its Limits: Designing Self-Correcting Agentic AI in Healthcare Payer Systems

RubricBench Exposes a Big Flaw in AI Grading

The Noonification: How Often Do NFTs Pass The Howey Test? (1/13/2023)

Darwin's Hybrid Intelligence to Align AI & Human Goals for Startups & VCs

Asynchronous Runtimes: A Primer for the Perplexed Developer

Qwen3.5-2B Distills Opus Reasoning Into a Tiny GGUF Model

When RPA Reaches Its Limits: Designing Self-Correcting Agentic AI in Healthcare Payer Systems

RubricBench Exposes a Big Flaw in AI Grading

The Noonification: How Often Do NFTs Pass The Howey Test? (1/13/2023)

Darwin's Hybrid Intelligence to Align AI & Human Goals for Startups & VCs

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps