Skip to content

Setting Up a New Project with Claude Code

A step-by-step guide to bootstrapping a project with Claude Code the right way from installation to a production-ready workflow.

Prerequisites

  • Node.js 18+ installed
  • An Anthropic account with API access
  • Git installed and configured

Step 1: Install Claude Code

Install the CLI globally via npm:

npm install -g @anthropic-ai/claude-code

Authenticate with your Anthropic account:

claude

Claude will prompt you to log in via OAuth or set your API key. To use an API key directly, add it to your shell profile:

export ANTHROPIC_API_KEY=sk-ant-...

Verify installation:

claude --version

Step 2: Initialize Your Project

Create and navigate to your project directory:

mkdir my-project && cd my-project
git init

Launch Claude Code from the project root. This is important — Claude Code works best when run from the root of your repo so it has full context of the codebase:

claude

Step 3: Generate Your CLAUDE.md File

CLAUDE.md is the most important configuration file for Claude Code. It's read at the start of every session and gives Claude persistent context about your project — things it can't infer from code alone.

Run the init command to auto-generate a starter file:

/init

Claude will analyze your project structure, detect build systems, test frameworks, and coding patterns, then produce a baseline CLAUDE.md. Refine it over time.

A good CLAUDE.md looks like this:

# My Project

## Overview
A REST API built with Node.js, Express, and PostgreSQL.

## Tech Stack
- Runtime: Node.js 20+
- Framework: Express
- Database: PostgreSQL via Prisma ORM
- Testing: Vitest

## Common Commands
- `npm run dev` — start development server
- `npm run test` — run test suite
- `npm run lint` — lint the codebase
- `npm run build` — production build

## Code Style
- Use ES modules (import/export), not CommonJS (require)
- Prefer async/await over .then() chains
- Always add JSDoc comments to exported functions
- Functional components with hooks for any UI work

## Architecture Notes
- API routes are in `src/routes/`
- Business logic lives in `src/services/`
- Database models are in `src/models/`

## What Claude Gets Wrong
- Never modify `prisma/schema.prisma` without running `npx prisma generate` after
- Always use the `logger` utility in `src/utils/logger.ts`, not `console.log`

Tips for a great CLAUDE.md:

  • Keep it under 100–200 lines. Move detailed docs to per-folder CLAUDE.md files if needed.
  • Favor documenting what Claude tends to get wrong over general conventions.
  • Don't @-file large docs directly — instead, write "For complex usage, see path/to/docs.md".
  • Never say "Never use --foo-bar flag" — always offer the alternative: "Never use --foo-bar; prefer --baz instead."

Step 4: Configure .claude/settings.json

Create a .claude/ directory with a settings.json file to set up hooks, permissions, and automation:

mkdir .claude

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "[ \"$(git branch --show-current)\" != \"main\" ] || { echo '{\"block\": true, \"message\": \"Cannot edit files on main branch. Create a feature branch first.\"}' >&2; exit 2; }",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --silent 2>&1 | head -20"
          }
        ]
      }
    ]
  }
}

This configuration does two things:

  • Blocks edits on main — forces Claude to always work on a feature branch.
  • Auto-lints after edits — gives Claude immediate feedback to self-correct.

You can also add hooks to run Prettier, type-check TypeScript, or run tests on changed files automatically.

Step 5: Set Up Custom Slash Commands

Create reusable prompt templates in .claude/commands/. These become /command-name shortcuts inside Claude Code.

Example: a new feature command

Create .claude/commands/new-feature.md:

Create a new feature following this project's conventions:

1. Create a feature branch: `git checkout -b feat/$ARGUMENTS`
2. Ask me to describe the feature requirements
3. Enter Plan Mode and explore 2-3 implementation approaches
4. Once I approve the plan, implement it in small, testable diffs
5. Write or update tests for all new logic
6. Run `npm run lint && npm run test` and fix any failures
7. Generate a PR description summarizing intent, risks, and test coverage

Usage inside Claude Code: /new-feature user-auth

Other useful commands to create:

  • .claude/commands/review.md — code review checklist
  • .claude/commands/debug.md — structured debugging workflow
  • .claude/commands/refactor.md — safe refactoring steps

Step 6: Use Plan Mode Before Every Feature

This is the single highest-impact habit. Always plan before coding.

Activate Plan Mode by pressing Shift + Tab twice. In this mode, Claude can read files and reason over your codebase but cannot make any changes. Think of it as "architect mode."

Recommended workflow:

  1. Enter Plan Mode (Shift + Tab twice)
  2. Orient Claude: "Read /src/auth and understand how sessions and login work."
  3. Ask for a plan: "I want to add Google OAuth. Propose a 3-step implementation plan with small diffs and tests for each step."
  4. Review and approve the plan
  5. Start a fresh session (/clear) and paste in the approved plan to execute it

Why a fresh session? A new session has clean context focused entirely on implementation. Long sessions with irrelevant history degrade Claude's performance.

Step 7: Adopt a Git-First Workflow

Always have Claude work on a feature branch. This isolates its changes and gives you a safe rollback point.

git checkout -b feat/my-feature

Use Claude's checkpoint and rewind features as safety nets:

  • Esc — stop Claude mid-action, context is preserved, you can redirect
  • Esc + Esc or /rewind — open the rewind menu to restore previous conversation and code state
  • /clear — reset context between unrelated tasks

Commit often and review diffs before each commit. Never let Claude accumulate hundreds of lines of unreviewed changes.

Step 8: Manage Context Like a Pro

Context degradation is the primary failure mode with Claude Code. Long sessions with unrelated history cause Claude to lose focus and make more mistakes.

Rules to follow:

  • Use /clear between unrelated tasks — don't carry old context forward.
  • Scope each chat to one feature or bug fix.
  • For large features, ask Claude to write a plan.md or todo.md file first. Then execute it one section per session.
  • For complex problems, open multiple parallel Claude sessions on separate git worktrees:
git worktree add ../my-project-feature-a feature-a
cd ../my-project-feature-a && claude

Step 9: Add Quality Gates with Tests

AI-generated code often works superficially but contains subtle bugs. Tests are the only reliable validation mechanism.

Set up your test framework early:

npm install -D vitest  # or jest, mocha, etc.

Tell Claude your testing expectations in CLAUDE.md:

## Testing
- Every new function requires a corresponding test file
- Use Vitest with the `describe/it/expect` pattern
- Run `npm run test` after every set of changes
- Run single tests with `npx vitest run src/path/to/file.test.ts`

Instruct Claude to run and fix tests as part of every workflow — not as an afterthought.

Step 10: Extend with MCP Servers (Optional)

Model Context Protocol (MCP) servers let Claude connect to external tools and services. This is how you extend Claude Code far beyond local file editing.

Add a web search capability:

claude mcp add brave-search -s project -- npx @modelcontextprotocol/server-brave-search

Popular MCP integrations:

  • Brave Search — lets Claude search the web for current best practices and docs
  • Puppeteer — browser automation for UI testing and debugging
  • Supabase / PostgreSQL — direct database access for schema-aware queries
  • GitHub — read and write issues, PRs, and comments
  • Sentry — dig through error logs and traces

List your project's MCP servers in CLAUDE.md so Claude knows they're available.

Project Structure Checklist

After setup, your project root should look like this:

my-project/
├── .claude/
│   ├── settings.json        # hooks, permissions, automation
│   └── commands/
│       ├── new-feature.md   # custom slash commands
│       ├── review.md
│       └── debug.md
├── CLAUDE.md                # project brain — read every session
├── src/
│   └── ...
├── tests/
│   └── ...
├── .gitignore
└── package.json

Quick Reference: Key Commands

Command What It Does
/init Generate a starter CLAUDE.md
/clear Reset context (use often)
/rewind Restore previous conversation/code state
Shift + Tab (×2) Toggle Plan Mode
Esc Stop Claude mid-action
↑ arrow Navigate previous sessions
claude -p "query" One-shot mode for scripts
claude mcp add ... Add an MCP server

Key Principles to Remember

Plan, then execute. Never let Claude jump straight to coding. Use Plan Mode to research and design before a single file is touched.

Context is everything. A well-crafted CLAUDE.md is more valuable than any single prompt. Treat it as living documentation and update it when Claude makes recurring mistakes.

Tight feedback loops win. Correct Claude as soon as it goes off track. The best results come from active collaboration — not "set it and forget it."

Tests are non-negotiable. AI-generated code needs automated verification. Invest in making your test suite fast and reliable.

Git is your safety net. Feature branches, frequent commits, and the /rewind command give you the confidence to let Claude move fast without breaking things permanently.

For the latest Claude Code documentation, visit docs.anthropic.com.