Claude Code Setup

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 →](README.tr.md)

---

Table of Contents

• [What is Claude Code?](#what-is-claude-code)
• [Installation & First Steps](#installation--first-steps)
• [The Auto-Setup Prompt](#the-auto-setup-prompt)
• [CLAUDE.md & The Memory System](#claudemd--the-memory-system)
• [Skills](#skills)
• [Custom Agents](#custom-agents)
• [Hooks](#hooks)
• [MCP Servers](#mcp-servers)
• [Plan Mode & Extended Thinking](#plan-mode--extended-thinking)
• [Session Management](#session-management)
• [IDE Integrations](#ide-integrations)
• [Permissions & Security](#permissions--security)
• [Headless Mode & CI/CD](#headless-mode--cicd)
• [Tips & Best Practices](#tips--best-practices)
• [Example Files](#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](prompts/auto-setup.md)

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](examples/CLAUDE.md.example) and [examples/CLAUDE.local.md.example](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/](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/](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](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](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 

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](examples/settings.json.example) and [examples/settings.local.json.example](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: ``

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CanArslanDev
• Source: CanArslanDev/claude-code-setup
• License: MIT

Install and usage instructions live in the source repository linked above.