Skip to main content
This is a step-by-step setup guide for Claude Code. For deeper patterns and workflows, see Claude Code Mastery.

​
Installation

Claude Code runs as a Node.js CLI tool. You need Node.js 18+ installed. 
npm install -g @anthropic-ai/claude-code
Verify the installation: 
claude --version
Authenticate with your Anthropic account: 
claude
# Follow the OAuth prompt to authenticate
Alternatively, use an API key directly: 
export ANTHROPIC_API_KEY=sk-ant-...

​
First Session

Navigate to your project directory and start Claude Code: 
cd your-project
claude
Claude Code starts a session with access to your current directory. It can read files, write files, run terminal commands, and iterate on errors. Your first session doesn’t need any special setup. Try: 
Read the main entry point of this project and give me a 3-sentence summary of what it does.
This tests that Claude Code can see your files and gives it initial context about the project.

​
CLAUDE.md: The Most Important Configuration

CLAUDE.md is a markdown file in your project root (or any subdirectory) that provides persistent context to Claude Code. Every session reads this file automatically. Without CLAUDE.md, Claude Code guesses about your project conventions. With it, Claude Code operates with the knowledge of a developer who has read your entire contributing guide.

​
Creating Your First CLAUDE.md

touch CLAUDE.md
Minimal useful content: 
# Project: [Name]

## Stack
- [Language] [version]
- [Framework] [version]
- [Database/ORM]
- [Testing framework]

## Dev Commands
- `[run command]` — start development server
- `[test command]` — run tests
- `[lint command]` — lint and format
- `[typecheck command]` — type checking

## Conventions
- [Key convention 1]
- [Key convention 2]
- [Key pattern to follow or avoid]

## Reference Files
- See [path/to/file] for the pattern to follow for [X]

​
What Makes a CLAUDE.md Effective

Be specific, not verbose. Don’t explain what TypeScript is. Tell Claude Code that you use strict mode and prohibit any. Reference example files. “See src/actions/users.ts for the server action pattern” is more effective than paragraphs of style guide. Claude Code will read that file and replicate the pattern. Include your commands. If Claude Code doesn’t know how to run your tests, it can’t verify its own work. Include every command it might need. List anti-patterns. “No default exports” or “no barrel index files” saves Claude Code from well-intentioned mistakes.

​
A Real Example

# Project: PromptLib

## Architecture
- Next.js 14 App Router, TypeScript strict mode
- PostgreSQL via Drizzle ORM — schema in `src/db/schema.ts`
- NextAuth.js authentication
- Tailwind CSS + shadcn/ui
- Server Actions for mutations (not API routes)

## Directory Structure
- `src/app/` — App Router pages and layouts
- `src/components/` — Shared components (PascalCase)
- `src/actions/` — Server actions (grouped by domain)
- `src/db/` — Schema, migrations, and repository queries
- `src/lib/` — Utilities and shared logic

## Commands
- `pnpm dev` — development server
- `pnpm test` — vitest unit tests
- `pnpm test:e2e` — Playwright end-to-end tests
- `pnpm db:push` — push schema changes
- `pnpm typecheck` — TypeScript check
- `pnpm lint` — ESLint + Prettier

## Conventions
- Named exports only (no default exports)
- Server components by default; `"use client"` only when needed
- Result<T, E> pattern for error handling — see `src/lib/result.ts`
- Zod schemas for all external input validation
- Tests next to source: `Component.test.tsx`

## Patterns to Follow
- Server action pattern: `src/actions/prompts.ts`
- Component pattern: `src/components/PromptCard.tsx`
- Database query pattern: `src/db/queries/prompts.ts`

## Do Not
- No `any` types — use `unknown` and narrow
- No barrel exports (`index.ts` re-exports)
- No `React.FC` — use plain function declarations
- Don't use `fetch` for internal API calls — use server actions
Commit your CLAUDE.md to the repository. It benefits every team member who uses Claude Code, and it evolves through code review like any other project document.

​
Nested CLAUDE.md Files

For monorepos, use nested CLAUDE.md files in subdirectories: 
CLAUDE.md                    ← global: monorepo structure, shared conventions
packages/api/CLAUDE.md       ← API-specific: Hono routes, middleware
packages/web/CLAUDE.md       ← web-specific: Next.js, component library
packages/shared/CLAUDE.md    ← shared types and utilities
Claude Code merges them hierarchically — global context plus local specifics.

​
Custom Slash Commands

Claude Code supports custom slash commands defined as markdown files in .claude/commands/. 
mkdir -p .claude/commands
Each command is a .md file whose content becomes the prompt. Use $ARGUMENTS to accept parameters.

​
Useful Commands to Create

Feature implementation: 
<!-- .claude/commands/add-feature.md -->
Implement a new feature. Here's the specification:

$ARGUMENTS

Steps:
1. Read the relevant existing patterns in the codebase first
2. Create necessary types and schemas
3. Implement the data layer if needed
4. Implement the business logic
5. Create UI components
6. Write tests for the critical paths
7. Run the test suite and fix any failures
8. Run the type checker and fix any errors
Usage: /add-feature User notification preferences with email, push, and in-app toggles Pre-PR review: 
<!-- .claude/commands/review.md -->
Review the changes I've made since the last commit:

1. Read the full git diff (staged and unstaged)
2. For each changed file, read the complete file for full context
3. Check for: bugs, security issues, missing error handling, N+1 queries, performance problems
4. Verify changes follow the patterns in CLAUDE.md
5. Check that tests cover new code paths
6. Look for debug artifacts: console.log, TODO comments, commented-out code

Rate each finding: must-fix, should-fix, or nice-to-have.
Be direct. If the code is fine, say so.
Usage: /review Test generation: 
<!-- .claude/commands/test-gen.md -->
Generate tests for: $ARGUMENTS

1. Read the source file and understand its public API
2. Identify critical paths and edge cases
3. Write tests following the patterns in the nearest existing test file
4. Test behaviour, not implementation — tests should not break during internal refactors
5. Include edge cases: empty inputs, null/undefined, boundary values, error paths
6. Run the tests to verify they pass
Usage: /test-gen src/actions/notifications.ts

​
Settings and Configuration

​
Global Settings

Claude Code settings live at ~/.claude/settings.json. Common configuration: 
{
  "autoApprove": false,
  "theme": "dark",
  "model": "claude-sonnet-4-6"
}
autoApprove: false keeps you in control — Claude Code will ask permission before running commands or writing files. Set to true only for trusted, well-understood workflows.

​
Project-Level Settings

Create .claude/settings.json in your project for project-specific overrides: 
{
  "model": "claude-sonnet-4-6",
  "allowedCommands": ["pnpm *", "git *", "npx *"]
}
allowedCommands restricts which shell commands Claude Code can run automatically. Useful for CI environments or when you want tighter control.

​
Working Effectively

​
The Warm-Up Prompt

Before asking Claude Code to implement anything, give it context: 
Read CLAUDE.md, then read src/db/schema.ts and src/actions/users.ts.
Tell me what patterns you see before we start.
This loads the important context before the real work begins. The quality difference in subsequent output is significant.

​
Architect Then Implement

For any task touching more than 3 files, split into two phases: 
Phase 1 — Architecture:
I need to add [feature]. Before writing any code, create a plan:
- What files need to change?
- What's the data model?
- What are the edge cases?
- What's the migration path?
Don't implement yet.

Phase 2 — Implementation (after reviewing the plan):
Good plan. Implement it with these adjustments: [your changes].
Run tests after each major step.

​
Conversation Management

Start fresh when:
  • Switching to a completely different task
  • The conversation has accumulated wrong assumptions
  • Claude Code seems confused about the current state of files
  • The context window is getting full (responses slow down, more mistakes)
Continue when:
  • Iterating on the same feature
  • In a debug loop where context about what’s been tried is valuable
The checkpoint technique for long sessions: 
Let's checkpoint. Summarise:
1. What we've implemented so far
2. What decisions we've made and why
3. What's remaining
4. Any open questions
This forces Claude Code to consolidate its understanding and gives you a summary you can paste into a fresh session.

​
Common Mistakes

Not reviewing output. Claude Code is fast. It’s not infallible. Review every change — especially database migrations, security-sensitive code, and deletion operations. Over-scoping. “Refactor the entire API layer” will exhaust context and produce inconsistent results. “Refactor the user authentication endpoints” is sized correctly. No test coverage. Without tests, Claude Code can’t verify its own work. If your project has no tests, ask Claude Code to add them before major features. Fighting the tool. If you’re making ten corrections to steer Claude Code toward your approach, it’s usually faster to start a fresh conversation with clearer instructions than to continue correcting.

​
Getting More

For advanced usage — multi-file refactors, CI integration, git workflows, and production patterns — see Claude Code Mastery.