Claude Code Init: Project Setup Guide

Claude Code Project Setup — Proper Claude Code project setup makes every session faster. Learn to use /init, generate CLAUDE.md, configure path-specific rules, and set local preferences.

Claude Code Project Setup: What You’ll Learn

In this guide to Claude Code Project Setup, you’ll work through practical, hands-on steps with real examples. Claude Code Project Setup is explained from the ground up so you can apply it immediately in your own projects.

Getting Claude Code working well on a project takes about ten minutes of setup. The payoff is that Claude understands your conventions from the first message, has the right permissions to do useful work, and behaves consistently for everyone on the team. This lesson walks through the setup steps in order.

Claude Code Init Command: Initializing Project Memory

Start with /init. Claude scans your codebase — reading package.json, existing docs, directory structure — and generates a CLAUDE.md that captures your tech stack, key commands, and initial conventions. Commit this file to git immediately so teammates get the same context.

A good CLAUDE.md is concise and specific. Aim for under 200 lines per file. Every line should be relevant to nearly every session — if something only matters for one feature, put it in a path-scoped rules file instead. The most valuable sections are: tech stack and versions, development commands (install, test, build, lint), naming conventions that aren’t obvious, and known gotchas that would trip up a new developer.

# Project: Payment Service

## Stack

- Node.js 20, TypeScript 5, PostgreSQL 15
- Express for API, Prisma for ORM, Jest for tests

## Commands

- `npm run dev` — start with hot reload
- `npm test` — run test suite
- `npm run migrate` — apply pending migrations
- `npm run lint` — ESLint + Prettier check

## Conventions

- All monetary values stored as integers (cents)
- Use `Result<T, E>` pattern for error handling, never throw in service layer
- Database columns: snake_case; TypeScript: camelCase

Configuring Permissions

Claude Code operates within a permission system that controls which tools it can use without asking. The default mode requires approval for most file writes and all bash commands. For active development, you’ll want to pre-approve common operations.

Open the permission manager with /permissions. Add patterns for the commands Claude will use repeatedly. Use Bash(git *) to allow all git commands, Bash(npm *) for npm, or Bash(npx jest *) for a specific tool. File operations can be scoped to specific paths.

Settings files control permissions at project and user level. .claude/settings.json is committed to git for the team. .claude/settings.local.json is git-ignored for personal overrides:

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Read(**/*)",
      "Write(src/**/*)",
      "Edit(src/**/*)"
    ]
  }
}

For sensitive operations like production deploys, leave them requiring approval or use disable-model-invocation: true on skills so Claude can never trigger them automatically.

When a task needs files outside the project root — a sibling library, a shared types package, a generated bundle — use --add-dir at launch (or /add-dir mid-session) to extend Claude’s working directories for that session. Each path must exist as a directory and the flag only grants file access, not the rest of .claude/ configuration in that tree:

# Start a session with read/edit access in two sibling directories
claude --add-dir ../shared-types --add-dir ../design-tokens

To persist those directories across every session in the project instead of typing them each time, set permissions.additionalDirectories in .claude/settings.json. --add-dir is the temporary, per-session form of the same grant.

Security — Marketplace Restrictions

Use blockedMarketplaces to restrict which plugin marketplaces can be used. Entries support hostPattern to block by domain (e.g., "*.example.com") and pathPattern to block by repository path (e.g., "acme/corp-plugins"):

{
  "blockedMarketplaces": [
    { "hostPattern": "*.untrusted-domain.io" },
    { "pathPattern": "acme/corp-plugins" }
  ]
}

This is enforced at the policy level — users cannot override it with local settings. Available in managed policy for enterprise deployments.

When writing plugin manifests for your project, note that monitors and themes are experimental and should be declared under experimental: {} rather than at the top level of plugin.json. Top-level declarations still work but claude plugin validate will warn, and a future release will require the nested form.

Settings and Environment

Settings follow this precedence from highest to lowest: (1) Managed settings (cannot be overridden by anything, including command-line arguments), (2) Command-line arguments, (3) Local (.claude/settings.local.json) — which overrides project and user settings, (4) Project (.claude/settings.json), (5) User (~/.claude/settings.json). Local settings override project settings, not the reverse. Managed delivery can use platform policy files or managed configuration directories, but those are implementation details for the top managed layer rather than separate everyday scopes.

The native installer auto-updates in the background by default. Homebrew and WinGet installations do not auto-update by default — to opt in, set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1. Claude Code will then run the package manager upgrade in the background when a new version is available and prompt you to restart on success.

To upgrade manually instead, run brew upgrade claude-code (or brew upgrade claude-code@latest) or winget upgrade Anthropic.ClaudeCode. You can control the release channel with the autoUpdatesChannel setting — "latest" (default) receives new features immediately, while "stable" uses a version about one week old that skips releases with major regressions. To disable auto-updates entirely, set DISABLE_UPDATES to "1" in your settings env block — this blocks all update paths including manual claude update. For a less strict option, DISABLE_AUTOUPDATER suppresses package manager update notifications only.

Beyond permissions, useful settings include env for environment variables that should be present in every session, agent to set a custom default agent, and claudeMdExcludes for filtering out irrelevant memory files in monorepos. You can also set the default model and effort level:

{
  "model": "claude-sonnet-4-6",
  "env": {
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug"
  }
}

Add .claude/settings.local.json to your .gitignore so personal overrides stay personal. Share .claude/settings.json, CLAUDE.md, .claude/rules/, .claude/skills/, and optionally .claude/agents/ with the team via git. That gives teammates the same shared project instructions and project-scoped extensions, while personal settings and auto memory remain local to each machine.

Real-World Code Examples: Memory Configuration

Example 1: Project CLAUDE.md

A comprehensive project configuration file that defines architecture, standards, and conventions:

# Project Configuration

## Project Overview
- Name: E-commerce Platform
- Tech Stack: Node.js, PostgreSQL, React 18, Docker
- Team Size: 5 developers

## Architecture
@docs/architecture.md
@docs/api-standards.md
@docs/database-schema.md

## Development Standards

### Code Style
- Use Prettier for formatting
- Use ESLint with airbnb config
- Maximum line length: 100 characters

### Naming Conventions
- Files: kebab-case (user-controller.js)
- Classes: PascalCase (UserService)
- Functions/Variables: camelCase (getUserById)

### Git Workflow
- Branch names: feature/description or fix/description
- Commit messages: Follow conventional commits
- PR required before merge

Example 2: Personal CLAUDE.local.md (Not Committed to Git)

Personal preferences that stay local and are never shared with the team:

# My Development Preferences

## About Me
- Experience Level: 8 years full-stack development
- Preferred Languages: TypeScript, Python
- Communication Style: Direct, with examples

## Code Preferences

### Error Handling
I prefer explicit error handling with try-catch blocks.
Avoid generic errors. Always log errors for debugging.

### Testing
I prefer TDD (test-driven development).
Write tests first, then implementation.

### Architecture
I prefer modular, loosely-coupled design.
Use dependency injection for testability.

Example 3: Directory-Scoped Rules for src/api/

A CLAUDE.md file placed in src/api/ that overrides root settings for that directory:

# API Module Standards

This file overrides root CLAUDE.md for everything in /src/api/

### Request Validation
- Use Zod for schema validation
- Always validate input
- Return 400 with validation errors

### Authentication
- All endpoints require JWT token
- Token in Authorization header
- Token expires after 24 hours

### Response Format
{
  "success": true,
  "data": {},
  "timestamp": "2025-11-06T10:30:00Z",
  "version": "1.0"
}

### Rate Limiting
- 1000 requests per hour for authenticated users
- 100 requests per hour for public endpoints

Pro Tips

• Less is more in CLAUDE.md. Include only information relevant to EVERY session — project name, tech stack, essential commands, and non-obvious conventions. Keep it under 300 lines. Everything else goes in modular rules or @imports.
• Use modular rules for path-specific overrides. Instead of one giant CLAUDE.md, create .claude/rules/*.md files with YAML paths frontmatter. This keeps context lean — rules only load when you’re working in matching directories.
• Never auto-generate CLAUDE.md. Craft it manually with careful consideration. Auto-generated files tend to be verbose, generic, and filled with low-value information that wastes context tokens.
• Commit project memory to git. Your CLAUDE.md and .claude/rules/ should be version-controlled so the whole team benefits. Use CLAUDE.local.md (git-ignored) for personal project-specific preferences.
• Use /team-onboarding to generate ramp-up guides. This built-in command inspects your CLAUDE.md, skills, and configuration to auto-produce an onboarding document — perfect for bringing new teammates up to speed quickly.

Hands-On Challenge: Onboard a Project with CLAUDE.md + Skills

Task: Set up a complete Claude Code project configuration — a well-crafted CLAUDE.md, a modular rules directory, and a project-specific skill — so a new teammate can be productive in minutes.

Steps

1. Create a root CLAUDE.md with: project name, tech stack, essential dev commands (npm run dev, npm test, etc.), and 3–5 critical conventions
2. Create .claude/rules/testing.md with path-specific rules using frontmatter: paths: ["tests/**/*.ts"] — e.g., “Use Jest, follow AAA pattern, mock external calls”
3. Create .claude/rules/api.md with frontmatter paths: ["src/api/**/*.ts"] — e.g., “All endpoints require input validation and return a standard JSON envelope”
4. Create a project skill at .claude/skills/onboarding/SKILL.md that generates a ramp-up guide by reading the project structure, CLAUDE.md, and available skills
5. Run /onboarding to generate a teammate onboarding document, then verify it accurately reflects your project setup

Expected Outcome

A new developer running /onboarding should receive a comprehensive guide covering the project purpose, tech stack, development commands, coding conventions, available skills, and testing requirements — all derived from your configuration files.

Hint: Use the /team-onboarding built-in command (v2.1.101+) as a starting point. It inspects your CLAUDE.md, installed skills, and hooks to auto-generate a ramp-up guide. Customise the output by enriching your CLAUDE.md first.

Knowledge Check: Setting Up Your Claude Code Project

Test your understanding with these quiz questions. Try to answer each question before revealing the answer.

1. What does the /init command do?

1. Initializes a new Claude Code project from scratch
2. Generates a template CLAUDE.md based on your project structure
3. Resets all memory to defaults
4. Creates a new session

Correct Answer: B. /init analyzes your project and generates a template CLAUDE.md with suggested rules and standards. It is a one-time bootstrapping tool.

2. You want personal project preferences that are NOT committed to git. Which file should you use?

1. ~/.claude/CLAUDE.md
2. CLAUDE.local.md
3. .claude/rules/personal.md
4. .claude/memory/personal.md

Correct Answer: B. CLAUDE.local.md in the project root is for personal project-specific preferences. It should be git-ignored.

3. How do you scope a rule file to only apply to files in src/api/?

1. Put the rule in src/api/CLAUDE.md
2. Add paths: src/api/** YAML frontmatter to a .claude/rules/*.md file
3. Name the file .claude/rules/api.md
4. Use @scope: src/api in the rule file

Correct Answer: B. Files in .claude/rules/ support a paths: frontmatter field with glob patterns to scope rules to specific directories.

4. What is the maximum depth for @path/to/file imports in CLAUDE.md?

1. 3 levels deep
2. 5 levels deep
3. 10 levels deep
4. Unlimited

Correct Answer: B. The @import syntax supports recursive imports up to a maximum depth of 5 to prevent infinite loops.

5. You work across two repositories and want Claude to load CLAUDE.md from both. What flag do you use?

1. –multi-repo
2. –add-dir /path/to/other
3. –include /path/to/other
4. –merge-context /path/to/other

Correct Answer: B. The –add-dir flag loads CLAUDE.md from additional directories, allowing multi-repo context.

Additional Resources

Do I have to set up every project from scratch?

No. Run the initialisation command to generate a starting file, then adjust it rather than writing everything by hand.

What is the single most useful thing to configure?

The build, test, and lint commands. With those recorded, the assistant can verify its own changes before handing them back.

How do monorepos work?

Use path-specific rules so each folder gets the right conventions without bloating the root configuration file.

Putting It All Together

A clean project setup pays for itself almost immediately. The few minutes you spend running the init command, recording your commands, and separating shared from personal configuration are repaid every single session in fewer corrections and faster, more reliable results.

The goal is a configuration that a new teammate could clone and use without asking questions. When the build, test, and lint commands are written down and the conventions live in version control, onboarding becomes a matter of cloning the repository rather than scheduling a walkthrough with whoever set things up first.

Claude Code Project Setup: Frequently Asked Questions

What does the claude code init command actually do?

It scans your project and generates a starting CLAUDE.md skeleton describing your stack and structure. That skeleton is a first draft, not a finished file, and usually needs editing before it reflects how your team actually works.

Should I use the generated CLAUDE.md file without editing it?

No. The raw output often includes generic boilerplate that does not match your real conventions. Treat it as a starting point, then trim and rewrite it so every line is something the assistant should genuinely follow.

What is the risk of skipping build, test, and lint command setup?

Without those commands recorded, the assistant cannot verify its own changes, which means every mistake has to be caught by hand instead of being flagged automatically after an edit.

How large should CLAUDE.md be before I split it up?

Once it grows past a few hundred lines, move path-specific conventions into .claude/rules/ instead of continuing to dump everything into the root file — a bloated file becomes harder for both you and the assistant to trust.

What happens if I accidentally commit settings.local.json?

It leaks personal preferences and machine-specific paths into the shared repository, so keep that file out of version control and double-check your .gitignore during initial setup.

Claude Code Project Setup gives you a solid, repeatable workflow. Bookmark this Claude Code Project Setup guide and revisit the steps whenever you need them.

A Repeatable Setup Checklist

Treat a new project setup as a short, repeatable checklist so you never forget a step. Run the initialisation command, confirm the generated file describes the project accurately, then add the commands the assistant needs to build, test, and lint without asking you each time.

Next, decide what belongs in shared configuration versus your own machine. Conventions the whole team relies on go in the committed file; personal preferences and local paths stay in settings that are never pushed. This single decision prevents most of the friction teams hit when several people use the assistant on the same repository.

For larger repositories, lean on path-specific rules. A monorepo with a Python service in one folder and a TypeScript app in another can give each its own conventions without bloating the root file. The assistant then applies the right rules automatically based on which files it is working in.

Claude Code Project Setup: Common Mistakes to Avoid

A rushed claude code init pass causes more friction than it saves. These are the mistakes that show up most often once a project has been running Claude Code for a few weeks.

• Accepting the raw output of claude code init without editing it — the generated CLAUDE.md is a starting draft, not a finished file, and often includes generic boilerplate that doesn’t match how the team actually works.
• Letting CLAUDE.md grow past a few hundred lines by dumping every convention into the root file instead of moving path-specific rules into .claude/rules/.
• Committing .claude/settings.local.json by accident, which leaks personal preferences and machine-specific paths into the shared repository.
• Never recording build, test, and lint commands, which leaves Claude unable to verify its own changes and forces you to catch every mistake by hand.

Claude Code Project Setup: Best Practices

• Run /init first to auto-generate a CLAUDE.md skeleton from your codebase.
• Add the build, test, and lint commands so the assistant can verify its own work.
• Set local preferences for anything personal so they never get committed.
• Use path-specific configuration for monorepos with different stacks per folder.
• Commit CLAUDE.md so the whole team shares the same project memory.