Claude Code Technical Guide: From Installation to Production

🤖 Ghostwritten by Claude Opus 4.5 · Curated by Tom Hundley

This article was written by Claude Opus 4.5 and curated for publication by Tom Hundley.

Claude Code is Anthropic's terminal-native AI assistant designed for developers who prefer working in the command line. Unlike browser-based interfaces, Claude Code operates directly in your development environment, reading your codebase, executing commands, and making changes under your supervision.

This guide covers the full journey from installation through production workflows, based on official documentation and real-world usage patterns.

Installation

Claude Code runs on macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (with WSL or Git for Windows). You'll need at least 4GB of RAM and an internet connection for authentication and AI processing.

Native Installation (Recommended)

Anthropic recommends the native binary installation, which avoids package manager conflicts:

macOS/Linux/WSL:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Homebrew (macOS):

brew install --cask claude-code

NPM Installation

If you prefer npm, ensure you have Node.js 18 or higher:

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

Important: Do not use sudo npm install -g as this can cause permission issues.

Post-Installation Verification

After installation, verify your setup:

claude doctor

If you see "command not found," add the installation path to your shell configuration:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Authentication

Navigate to your project and start Claude Code:

cd your-project
claude

Claude Code supports three authentication methods:

Claude Console (default): OAuth through console.anthropic.com. Requires active billing.
Claude Pro/Max subscription: Unified subscription covering Claude Code and the web interface.
Enterprise platforms: Amazon Bedrock, Google Vertex AI, or Microsoft Foundry for organizational deployments.

How Claude Code Understands Your Codebase

When you start Claude Code in a directory, it builds understanding through several mechanisms:

Directory traversal: It can read files, explore directory structures, and understand project layout.
Tool execution: It runs commands like git status, npm test, or language-specific tooling.
Memory files: It loads CLAUDE.md files that provide persistent project context.
Conversation context: It maintains context within a session about what you've discussed and changed.

Claude Code doesn't index your entire codebase upfront. Instead, it explores relevant files as needed based on your requests. This approach scales to large projects without preprocessing overhead.

This on-demand exploration has implications for how you work. When starting a new task, explicitly point Claude to relevant files: "Read the user authentication module before we discuss adding OAuth." This front-loads context and prevents Claude from making assumptions based on incomplete information.

CLAUDE.md: Persistent Project Instructions

CLAUDE.md files are the most important configuration mechanism for Claude Code. They provide instructions that persist across sessions, ensuring consistent behavior.

File Locations and Hierarchy

Claude Code uses a multi-tier memory system:

Location	Scope	Shared via Git
`./CLAUDE.md` or `./.claude/CLAUDE.md`	Project team	Yes
`./.claude/rules/*.md`	Modular project rules	Yes
`./CLAUDE.local.md`	Individual (current project)	No (auto-gitignored)
`~/.claude/CLAUDE.md`	Individual (all projects)	No

Higher-tier files load first, with lower tiers building on that foundation.

Basic Structure

There's no required format. Keep it concise and human-readable:

# Project Overview
See @README.md for complete project information.

# Development Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

# Code Style
- Use 2-space indentation
- Prefer TypeScript strict mode
- Follow existing patterns in the codebase

# Architecture Notes
This is a Next.js 15 project using the App Router.
API routes are in `/src/app/api/`.

File Imports

Use @path/to/file syntax to include external files:

# Git Workflow
@docs/git-instructions.md

# API Conventions
@docs/api-design.md

Imports support relative and absolute paths.

Conditional Rules

For larger projects, create modular rules in .claude/rules/ with path-specific scope:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All endpoints must include input validation
- Use the standard error response format
- Include JSDoc comments for OpenAPI generation

Creating CLAUDE.md

Run /init to have Claude Code generate an initial CLAUDE.md based on your project structure:

claude
> /init

This scans your project and creates a bootstrapped configuration file.

What to Include vs. Exclude

Include:

Build commands (especially if non-standard)
Testing conventions specific to your project
Naming conventions that differ from language defaults
Important architectural patterns
Known gotchas or legacy decisions

Exclude:

Information easily derived from file structure
Standard language conventions (Claude already knows these)
Documentation that exists elsewhere in your codebase

The goal is additive context, not comprehensive documentation. If Claude can figure something out by reading your code, don't repeat it in CLAUDE.md.

MCP Servers: Extending Capabilities

The Model Context Protocol (MCP) allows Claude Code to connect to external tools and services. MCP servers provide specialized capabilities—database access, API integrations, custom tooling—that extend what Claude Code can do.

Adding MCP Servers

Use the CLI to add servers:

claude mcp add github --scope user

Key commands:

claude mcp add [name] — Add a server
claude mcp list — List configured servers
claude mcp remove [name] — Remove a server
claude mcp get [name] — Test a server

Configuration File

For complex setups, directly edit ~/.claude/settings.json or .mcp.json in your project root:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Checking MCP Status

Inside Claude Code, run /mcp to see server status and available tools.

Security Considerations

MCP servers run with your environment's credentials. Use servers you trust, and be cautious with servers that fetch untrusted content—they may expose you to prompt injection risks.

Common MCP Servers

The MCP ecosystem includes servers for:

GitHub: PR creation, issue management, repository operations
PostgreSQL/MySQL: Database queries and schema exploration
Filesystem: Extended file operations beyond the built-in tools
Slack: Channel messaging and notifications
Google Drive: Document access and management

Before installing any MCP server, review its source code and understand what permissions it requires. The convenience of extended capabilities comes with expanded attack surface.

Hooks: Custom Automation

Hooks are user-defined shell commands that execute at specific points in Claude Code's lifecycle. They provide deterministic control over behavior that would otherwise depend on Claude's judgment.

Hook Events

Event	When It Runs
PreToolUse	Before tool calls (can block them)
PostToolUse	After tool calls complete
Notification	When Claude sends notifications
Stop	When Claude finishes responding
SessionStart	When a session starts or resumes

Example: Code Formatting

Automatically format TypeScript files after Claude edits them:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

Example: File Protection

Block edits to sensitive files:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json']) else 0)\""
          }
        ]
      }
    ]
  }
}

A non-zero exit code blocks the tool use.

Setting Up Hooks

Run /hooks in Claude Code to access the interactive hook configuration, or edit settings files directly at ~/.claude/settings.json for user-level hooks or .claude/settings.json for project-level hooks.

Hooks Best Practices

Start observational. Your first hooks should log, not block. Understand Claude's behavior patterns before adding enforcement.

Keep hooks fast. Slow hooks degrade the interactive experience. If a hook takes more than a second, consider running it asynchronously or moving the logic to a PostToolUse hook.

Test hooks outside Claude Code first. Write and debug your hook commands in a regular terminal. Pipe test JSON to confirm they behave correctly before registering them.

Use matchers precisely. The matcher field supports regex. Edit|Write matches both tools; Edit alone won't catch file creation via Write.

Workflow Patterns

Explore-Plan-Code

The most effective workflow for non-trivial tasks:

Explore: Ask Claude to read relevant files without writing code. "Read the authentication module and the user model—I want to understand how login works."
Plan: Have Claude outline an approach before implementing. "Now outline how we should add password reset functionality."
Code: Only then implement. "Implement the plan, starting with the database migration."

This prevents Claude from jumping into code prematurely with incomplete understanding.

Extended Thinking

For complex problems, trigger deeper reasoning with the ultrathink keyword:

Include "ultrathink" in your prompt for maximum reasoning depth
Use the Tab key to toggle thinking mode on

Extended thinking is valuable for architectural decisions, challenging bugs, and multi-step implementations.

Subagents for Verification

Delegate verification tasks to preserve main context:

"Use a subagent to check if this change breaks any existing tests."

Subagents run in isolated contexts, exploring questions without consuming your main conversation's token budget.

Multi-Claude Workflows

For larger features, run multiple Claude instances:

# Use git worktree for parallel branches
git worktree add ../feature-a feature-a
git worktree add ../feature-b feature-b

# Run Claude in each directory
cd ../feature-a && claude
cd ../feature-b && claude

This allows parallel work on independent features without context pollution.

Test-Driven Development

Claude works well with TDD:

"Write tests for the password reset feature—they should fail initially."
"Run the tests to confirm they fail."
"Now implement the feature to make the tests pass."

This gives Claude a clear success criterion to iterate against.

Managing Long Tasks

For features that exceed a single context window:

Ask Claude to break the work into a project plan and save it to a markdown file.
Work through the plan one section at a time.
After completing each section, update the plan and use /clear to reset context.
Reference the plan file in subsequent sessions to maintain continuity.

This approach treats the plan file as persistent state, allowing multi-session work on complex features.

Configuration and Settings

Slash Commands

Common commands:

/init — Generate CLAUDE.md for your project
/memory — View or edit memory files
/permissions — Configure tool allowlists
/hooks — Configure automation hooks
/mcp — Check MCP server status
/clear — Clear conversation context

Custom Slash Commands

Create project-specific commands in .claude/commands/:

<!-- .claude/commands/deploy.md -->
Run the deployment checklist:
1. Run all tests
2. Build the production bundle
3. Check for TypeScript errors
4. Review the git diff

Access via /project:deploy in Claude Code.

Headless Mode

For CI/CD integration, run Claude Code non-interactively:

claude -p "Run tests and report any failures" --output-format json

Production Tips

Start with Observer Hooks

Don't try to automate everything immediately. Begin with hooks that log and observe:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

After a week, review the logs to identify patterns worth automating.

Keep CLAUDE.md Concise

Resist the urge to document everything. Include:

Commands you run frequently
Conventions that differ from common patterns
Architecture decisions that aren't obvious

Exclude documentation Claude can find by reading your codebase.

Use Progressive Disclosure

Instead of putting all information in CLAUDE.md, tell Claude how to find information:

# Where to Find Things
- API documentation: `@docs/api/`
- Database schema: Run `npm run db:schema`
- Environment setup: `@docs/setup.md`

Claude loads this information only when relevant, preserving context for actual work.

Course-Correct Early

If Claude heads in the wrong direction, interrupt immediately. Press Escape or run /clear to reset. Providing better instructions upfront is more efficient than letting Claude complete the wrong approach.

Version Control Your Configuration

Commit .claude/CLAUDE.md and .claude/commands/ to git. This ensures team consistency and allows configuration to evolve with your codebase.

Troubleshooting

"Command not found"

Add the installation path to your shell:

export PATH="$HOME/.local/bin:$PATH"

MCP Server Not Connecting

Check server status with /mcp and verify credentials in ~/.claude/settings.json or .mcp.json. Run claude mcp get [name] to test individual servers.

Context Getting Exhausted

For long sessions, context fills up. Signs include Claude forgetting earlier conversation or making inconsistent suggestions. Use /clear to reset, or break work into smaller sessions.

Hooks Not Running

Verify hook configuration with /hooks. Check that matchers match your tool names exactly (case-sensitive). Test commands manually to ensure they work in your shell.

Claude Code represents a different model for AI-assisted development—one where the AI operates in your environment rather than asking you to copy code back and forth. The learning curve is real, but so is the productivity gain once you've configured it for your workflow.

The patterns that work best: clear CLAUDE.md files, the explore-plan-code workflow, and hooks for repetitive tasks. Start simple, observe how Claude works with your codebase, and gradually add automation as you identify patterns.