Content
# Claude Code Setup Guide
> **Your complete guide to getting the most out of [Claude Code](https://docs.anthropic.com/en/docs/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
```bash
npm install -g @anthropic-ai/claude-code
```
### Start
```bash
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:
```markdown
# 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:
```markdown
@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
```markdown
---
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:
```yaml
---
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/`:
```markdown
# 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`:
```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:**
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
}
]
}
}
```
**Run linter after edits:**
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"command": "npx eslint --fix \"$CLAUDE_FILE_PATH\""
}
]
}
}
```
**Notify on completion:**
```json
{
"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`:
```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`](https://github.com/oraios/serena) | IDE-like semantic code navigation and editing (symbol-level find, references, rename — 30+ languages) |
### Setting Up MCP
```bash
# 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](https://github.com/oraios/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
```bash
# 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:
```bash
# 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
```json
// .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 *)"
]
}
}
```
```json
// .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
```bash
# 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:**
```yaml
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:**
```bash
#!/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](prompts/auto-setup.md) 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](examples/CLAUDE.md.example) | Project memory file template |
| [CLAUDE.local.md.example](examples/CLAUDE.local.md.example) | Local memory file template |
| [settings.json.example](examples/settings.json.example) | Shared settings template |
| [settings.local.json.example](examples/settings.local.json.example) | Local settings template |
| [hooks.json.example](examples/hooks.json.example) | Hook configurations |
| [mcp.json.example](examples/mcp.json.example) | MCP server configurations |
| [skills/commit/](examples/skills/commit/SKILL.md) | Commit message skill |
| [skills/review/](examples/skills/review/SKILL.md) | Code review skill |
| [skills/test-runner/](examples/skills/test-runner/SKILL.md) | Test runner skill |
| [agents/security-reviewer.md](examples/agents/security-reviewer.md) | Security review agent |
| [agents/refactor-helper.md](examples/agents/refactor-helper.md) | Refactoring agent |
| [rules/typescript.md](examples/rules/typescript.md) | TypeScript rules |
| [rules/python.md](examples/rules/python.md) | Python rules |
| [rules/api-standards.md](examples/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](LICENSE)
---
*Built with love and a lot of Claude Code sessions.*
