Claude Code Setup Guide

Your complete guide to getting the most out of Claude Code — Anthropic's AI coding assistant that lives in your terminal.

Whether you just installed Claude Code or you've been using it for months and want to level up, this guide has you covered. Think of it as the missing manual — written by a developer, for developers.

Türkçe versiyonu burada →

---

Table of Contents

• What is Claude Code?
• Installation & First Steps
• The Auto-Setup Prompt
• CLAUDE.md & The Memory System
• Skills
• Custom Agents
• Hooks
• MCP Servers
• Plan Mode & Extended Thinking
• Session Management
• IDE Integrations
• Permissions & Security
• Headless Mode & CI/CD
• Tips & Best Practices
• Example Files

---

What is Claude Code?

Claude Code is an agentic AI coding assistant that runs in your terminal. It can read your codebase, edit files, run commands, manage git operations, and much more — all through natural language. Unlike other AI coding tools, it has deep context awareness and can work with your entire project, not just individual files.

What makes it different:

• Terminal-native — works where you already work
• Agentic — it doesn't just suggest, it does
• Context-aware — understands your project structure, conventions, and history
• Customizable — memory files, skills, hooks, agents, and MCP servers let you tailor it to your workflow

---

Installation & First Steps

Install

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

Start

cd your-project
claude

That's it. Claude will analyze your project and be ready to help. You can immediately start asking it to:

• Explain parts of your codebase
• Fix bugs
• Write new features
• Run tests
• Create git commits and PRs
• Refactor code

First Things to Try

> What does this project do? Give me a high-level overview.
> Find all the API endpoints and list them.
> Run the tests and fix any failures.
> Create a commit with a good message for the staged changes.

---

The Auto-Setup Prompt

Don't want to manually configure everything? We built a single prompt that analyzes your project and sets up everything automatically.

→ Get the auto-setup prompt

Just paste it into Claude Code and it will:

1. Analyze your project (language, framework, structure, dependencies)
2. Create an optimal CLAUDE.md with project-specific instructions
3. Set up .claude/rules/ with language/framework rules
4. Create custom skills (commit, test, review, deploy)
5. Configure hooks (auto-format, lint, test triggers)
6. Recommend and set up MCP servers
7. Create .claude/settings.json with optimal permissions
8. Update .gitignore for local files

It's the fastest way to go from zero to a fully configured Claude Code environment.

---

CLAUDE.md & The Memory System

This is probably the single most impactful feature. CLAUDE.md files are persistent memory that Claude reads at the start of every conversation. Think of them as instructions that stick.

The Hierarchy

Claude loads memory files in a specific order, from broadest to most specific:

File	Scope	Shared with team?	Use for
~/.claude/CLAUDE.md	All projects	No (your machine)	Personal preferences, global coding style
CLAUDE.md (project root)	This project	Yes (commit it)	Project conventions, architecture decisions, common commands
CLAUDE.local.md (project root)	This project	No (gitignored)	Your personal project notes, local paths, secrets
folder/CLAUDE.md	Subdirectory	Yes	Module-specific instructions

What to Put in CLAUDE.md

Here's the thing — Claude Code reads this at the start of every conversation. So keep it focused on things that are always relevant:

# Project: My Awesome App

## Key Commands
- `npm run dev` — start dev server (port 3000)
- `npm test` — run tests (jest)
- `npm run lint` — eslint + prettier

## Architecture
- Next.js 14 with App Router
- PostgreSQL with Prisma ORM
- Auth via NextAuth.js

## Conventions
- Use `snake_case` for database columns, `camelCase` for JS/TS
- All API routes go in `app/api/`
- Tests live next to the files they test (e.g., `foo.test.ts`)

## Important Notes
- Never modify migration files directly — use `prisma migrate dev`
- The `lib/legacy/` folder is being deprecated — don't add new code there

Importing Other Files

You can reference other files from CLAUDE.md:

@rules/typescript.md
@rules/api-standards.md
@docs/architecture.md

This keeps your CLAUDE.md clean while still giving Claude access to detailed context.

Pro Tips for Memory Files

• Keep it concise. Claude reads this every time. Don't dump your entire architecture doc here.
• Be specific. "Follow best practices" is useless. "Use Zod for all API input validation" is actionable.
• Update it. If Claude keeps making the same mistake, add a note about it.
• Use CLAUDE.local.md for personal stuff — your local database URL, your preferred branch names, etc.

See examples/CLAUDE.md.example and examples/CLAUDE.local.md.example for full templates.

---

Skills

Skills are reusable, invocable prompts that extend what Claude can do. Think of them as custom slash commands.

Creating a Skill

Skills live in .claude/skills/ and each skill is a folder with a SKILL.md file:

.claude/skills/
├── commit/
│   └── SKILL.md
├── review/
│   └── SKILL.md
└── test-runner/
    └── SKILL.md

Skill File Structure

---
name: commit
description: Create a well-formatted commit
user_invocable: true
---

# Commit Skill

Analyze all staged changes and create a commit with a conventional commit message.

## Steps
1. Run `git diff --cached` to see staged changes
2. Analyze the nature of the changes
3. Generate a commit message following conventional commits format
4. Create the commit

Using Skills

Once created, you invoke skills with a slash command:

> /commit
> /review src/api/
> /test-runner --coverage

Dynamic Context

Skills can use frontmatter to configure behavior:

---
name: deploy
description: Deploy to staging or production
user_invocable: true
allowed_tools: ["Bash", "Read"]
---

See the examples/skills/ directory for ready-to-use skill templates.

---

Custom Agents

Custom agents are specialized personas you can create for specific tasks. They're like having team members with different expertise.

Project-Level Agents

Create agents in .claude/agents/:

# Security Reviewer

You are a security-focused code reviewer. When reviewing code:

1. Check for OWASP Top 10 vulnerabilities
2. Look for hardcoded secrets or credentials
3. Verify input validation and sanitization
4. Check authentication and authorization logic
5. Review dependency versions for known CVEs

Always provide severity ratings (Critical/High/Medium/Low) for findings.

User-Level Agents

For agents you want across all projects, put them in ~/.claude/agents/.

Using Agents

> @security-reviewer Review the changes in the last 3 commits
> @refactor-helper Clean up the user service module

See examples/agents/ for agent templates.

---

Hooks

Hooks let you run shell commands automatically in response to Claude Code events. They're perfect for enforcing workflows and automating repetitive tasks.

Hook Events

Event	When it fires
PreToolUse	Before a tool is executed
PostToolUse	After a tool execution completes
Notification	When Claude Code sends a notification
Stop	When Claude finishes a response turn
SubagentStop	When a subagent (Task tool) finishes

Configuration

Hooks are configured in .claude/settings.json or .claude/settings.local.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ],
    "Stop": [
      {
        "command": "echo 'Claude finished a response'"
      }
    ]
  }
}

Practical Use Cases

Auto-format after file changes:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

Run linter after edits:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

Notify on completion:

{
  "hooks": {
    "Stop": [
      {
        "command": "osascript -e 'display notification \"Claude is done!\" with title \"Claude Code\"'"
      }
    ]
  }
}

Environment Variables in Hooks

Hooks receive context through environment variables:

• $CLAUDE_FILE_PATH — the file that was modified
• $CLAUDE_TOOL_NAME — the tool that was used
• $CLAUDE_TOOL_INPUT — JSON input to the tool
• $CLAUDE_TOOL_OUTPUT — JSON output from the tool

See examples/hooks.json.example for more hook configurations.

---

MCP Servers

MCP (Model Context Protocol) servers extend Claude's capabilities by connecting it to external tools and data sources. Think of them as plugins.

Configuration

MCP servers are configured in .claude/settings.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token-here"
      }
    }
  }
}

Popular MCP Servers

Server	What it does
server-postgres	Query and manage PostgreSQL databases
server-github	Enhanced GitHub operations
server-filesystem	Extended filesystem operations
server-brave-search	Web search capability
server-puppeteer	Browser automation
server-slack	Slack integration
server-memory	Persistent key-value memory
server-sequential-thinking	Enhanced reasoning capabilities
serena	IDE-like semantic code navigation and editing (symbol-level find, references, rename — 30+ languages)

Setting Up MCP

# Add a server interactively
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost:5432/mydb

# List configured servers
claude mcp list

# Remove a server
claude mcp remove postgres

# Add Serena for IDE-like semantic code intelligence (uses uvx, not npx)
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server

Serena — Semantic Code Intelligence

Serena deserves a special mention. It's an MCP server that gives Claude IDE-like superpowers — symbol-level navigation, find references, rename across files, and more. Instead of grep-based searching, Claude can work at the semantic level, which dramatically improves accuracy on large codebases. It supports 30+ languages via language servers.

Best for: Large/complex projects, strongly-typed languages, heavy refactoring tasks.

OAuth-Based Servers

Some servers support OAuth for authentication. Claude Code handles the OAuth flow automatically — just configure the server and it will prompt you to authenticate.

See examples/mcp.json.example for configuration examples.

---

Plan Mode & Extended Thinking

Plan Mode

When facing a complex task, ask Claude to plan before executing:

> Plan how you would refactor the authentication module

Or use the /plan command. In plan mode, Claude will:

1. Analyze the relevant code
2. Design an approach
3. Present the plan for your approval
4. Only proceed when you say go

This is invaluable for large changes where you want to review the approach first.

Extended Thinking

Claude can use extended thinking for complex reasoning tasks. This is especially useful when:

• Debugging tricky issues
• Designing architecture
• Working through complex logic
• Planning multi-step changes

You can enable it in settings or let Claude decide when to use it.

---

Session Management

Resume a Session

# Resume the most recent session
claude --resume

# List recent sessions
claude --sessions

# Resume a specific session
claude --resume <session-id>

Git Worktrees

For parallel work, Claude Code works great with git worktrees:

# Create a worktree for a feature
git worktree add ../my-feature feature-branch

# Run Claude in the worktree
cd ../my-feature
claude

This lets you have multiple Claude sessions working on different features simultaneously.

Checkpoints

Claude automatically creates checkpoints as it works. If something goes wrong, you can ask it to revert to a previous checkpoint.

---

IDE Integrations

VS Code

Claude Code integrates directly with VS Code. Features include:

• Status line showing Claude's current activity
• Code diagnostics from your editor available to Claude
• Direct file navigation from Claude's responses

JetBrains IDEs

Similar integration available for JetBrains IDEs (IntelliJ, WebStorm, PyCharm, etc.).

Terminal

Claude Code works in any terminal. For the best experience, use a modern terminal that supports:

• 256 colors
• Unicode
• Mouse events (optional, for some UI features)

---

Permissions & Security

Permission Model

Claude Code asks for permission before:

• Running shell commands
• Writing or editing files
• Performing network operations

Settings Levels

// .claude/settings.json (shared with team)
{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run *)",
      "Bash(npx prettier *)",
      "Bash(git *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

// .claude/settings.local.json (personal, gitignored)
{
  "permissions": {
    "allow": [
      "Bash(docker *)",
      "Bash(kubectl *)"
    ]
  }
}

Best Practices

• Allow common read operations — no risk, saves time
• Allow project-specific commands — your test runner, linter, formatter
• Deny destructive commands — rm -rf, sudo, anything that could cause real damage
• Use local settings for personal tools — Docker, k8s, cloud CLI tools

See examples/settings.json.example and examples/settings.local.json.example.

---

Headless Mode & CI/CD

Claude Code can run without human interaction, perfect for CI/CD pipelines.

Basic Usage

# Run a single task
claude -p "Run the test suite and report results" --output-format json

# With a specific model
claude -p "Review the code for security issues" --model claude-sonnet-4-5-20250929

# From a file
claude -p "$(cat prompts/review.md)" --output-format json

CI/CD Examples

GitHub Actions — PR Review:

name: Claude Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Review this PR for bugs, security issues, and style problems."

Pre-commit Hook:

#!/bin/bash
claude -p "Review the staged changes for issues. Output only if there are problems." \
  --output-format text

Output Formats

• text — plain text (default)
• json — structured JSON (great for parsing in CI)
• stream-json — streaming JSON events

---

Tips & Best Practices

1. Start Every Project with CLAUDE.md

Even a minimal one. It compounds over time as you add instructions Claude needs.

2. Use the Auto-Setup Prompt

Don't configure manually — use the auto-setup prompt to bootstrap your configuration. You can always tweak it after.

3. Be Specific in Your Instructions

# Bad
> Make the code better

# Good
> Refactor the UserService class to use dependency injection
> and add unit tests for the createUser method

4. Use Plan Mode for Big Changes

Before refactoring a module or adding a complex feature, ask Claude to plan first. Review the plan, then execute.

5. Let Claude Run Tests

Don't just ask Claude to write code — ask it to run the tests too. It can fix failures in real time.

6. Use Skills for Repetitive Tasks

If you do something regularly (commits, reviews, deployments), create a skill for it.

7. Keep CLAUDE.md Updated

When you notice Claude making repeated mistakes, add a note. This file is your leverage.

8. Use Local Files for Secrets

Never put API keys or local paths in committed files. Use CLAUDE.local.md and .claude/settings.local.json.

9. Leverage Git Worktrees for Parallel Work

Need Claude to work on two features at once? Use git worktrees to give each task its own directory.

10. Check the Diff Before Committing

Claude is good, but always review its changes. Use git diff or your IDE's diff view before committing.

---

Example Files

This repository includes ready-to-use example files:

File	Description
CLAUDE.md.example	Project memory file template
CLAUDE.local.md.example	Local memory file template
settings.json.example	Shared settings template
settings.local.json.example	Local settings template
hooks.json.example	Hook configurations
mcp.json.example	MCP server configurations
skills/commit/	Commit message skill
skills/review/	Code review skill
skills/test-runner/	Test runner skill
agents/security-reviewer.md	Security review agent
agents/refactor-helper.md	Refactoring agent
rules/typescript.md	TypeScript rules
rules/python.md	Python rules
rules/api-standards.md	API design rules

---

Contributing

Found something wrong or have a suggestion? Open an issue or PR. This guide is for the community.

License

MIT

---

Built with love and a lot of Claude Code sessions.