Claude Code Developer Guide

Your comprehensive guide to using Claude Code effectively. Learn workflows, best practices, and tips to supercharge your development.

2Installation & Setup

macOS / Linux (Recommended)

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

Homebrew

brew install --cask claude-code

for updating:

brew upgrade --cask claude-code

Windows

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

3Getting Started

Basic Commands

Command	Description
`claude`	Start Claude Code in current directory
`claude --dangerously-skip-permissions`	Start without permission prompts (Recommended)
`/clear`	Clear conversation context
`/init`	Generate a CLAUDE.md file
`/permissions`	Manage tool permissions
`Shift + Tab`	Toggle between Normal and Plan modes
`Escape`	Interrupt Claude
`Escape × 2`	Go back to edit previous prompt

Operation Modes

Normal Mode

For small, routine tasks. Claude can freely execute commands without step-by-step approval.

Plan Mode

For larger features. Claude creates a plan before executing, letting you review each step.

Starting a session:

# Navigate to your project
cd /path/to/your/project

# Start Claude Code
claude

# Or start without permission prompts (safe environments only)
claude --dangerously-skip-permissions

4Core Concepts

Context Window

Claude pulls relevant files, documentation, and conversation history into its context. Keep this in mind:

Use /clear frequently between unrelated tasks
Be specific about which files to focus on
Paste screenshots or drag-and-drop images
Provide URLs for Claude to fetch and read

Extended Thinking

Use specific words to trigger deeper analysis:

Phrase	Thinking Depth
`"think"`	Basic extended thinking
`"think hard"`	More thorough analysis
`"think harder"`	Deep analysis
`"ultrathink"`	Maximum thinking budget

5Recommended Workflows

Explore → Plan → Code → Commit

Best for most development tasks:

1. Explore

Read the authentication module and understand how user sessions work.
Don't write any code yet.

2. Plan

Think hard about how to add OAuth2 support. Create a plan but don't code yet.

3. Code

Now implement the OAuth2 support according to your plan.

4. Commit

Commit these changes with a descriptive message and create a PR.

Test-Driven Development (TDD)

Ideal for changes verifiable with tests:

1Write tests first (explicitly tell Claude not to create mock implementations)
2Verify tests fail
3Commit tests
4Implement to pass tests (tell Claude to keep going until all pass)
5Commit implementation

Visual Development (Screenshot-Based)

For UI development:

1Provide Claude with a visual mock (paste screenshot or give file path)
2Ask Claude to implement and screenshot the result
3Iterate until the implementation matches the mock
4Commit when satisfied

Codebase Q&A

When onboarding or exploring, ask Claude:

→"How does authentication work in this project?"
→"What edge cases does the PaymentProcessor handle?"
→"Why are we using this particular library for X?"
→"Show me how to add a new API endpoint following existing patterns"

6Project Configuration (CLAUDE.md)

What is CLAUDE.md?

A special file that Claude automatically reads at the start of each session. Use it to document project-specific commands, code style, testing instructions, and important patterns.

Build commandsCode styleTesting instructionsGit workflowProject structure

CLAUDE.md Template:

# Project: [Project Name]

## Build & Run Commands
- `npm run dev` — Start development server
- `npm run build` — Build for production
- `npm run test` — Run test suite
- `npm run lint` — Run linter

## Code Style
- Use TypeScript strict mode
- Use ES modules (import/export), not CommonJS
- Destructure imports when possible

## Testing
- Write tests for all new features
- Run single tests: `npm test -- --grep "test name"`
- Ensure all tests pass before committing

## Git Workflow
- Branch naming: `feature/[ticket-id]-short-description`
- Commit messages: Start with ticket ID
- Always rebase on main before creating PR

## Project Structure
- `/src/api` — API routes and controllers
- `/src/services` — Business logic
- `/src/models` — Database models

Location	Scope
`./CLAUDE.md`	Current project (commit to git)
`./CLAUDE.local.md`	Current project, personal (add to .gitignore)
`~/.claude/CLAUDE.md`	All your Claude sessions

7MCP Integrations

What is MCP?

Model Context Protocol (MCP) allows Claude to interact with external services like Jira, GitHub, Puppeteer, and more.

Jira MCP Configuration (.mcp.json):

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-jira"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USER": "${JIRA_USER}",
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
      }
    }
  }
}

Jira Commands

"Show me all open bugs assigned to me"
"Create a task in PROJ for the login feature"
"Update PROJ-123 status to In Progress"
"Add a comment to PROJ-456"

GitHub (via gh CLI)

Create pull requests
Review code
Manage issues
Handle complex git operations

Debugging MCP

Launch with claude --mcp-debug to identify configuration issues.

8Custom Commands

Store prompt templates in .claude/commands/ for reusable workflows.

.claude/commands/fix-github-issue.md:

Please analyze and fix the GitHub issue: $ARGUMENTS.

Follow these steps:

1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR

Remember to use the GitHub CLI (`gh`) for all GitHub-related tasks.

Usage: Type /project:fix-github-issue 1234 to fix issue #1234

9Best Practices

Vague Instruction

Add tests for the user module

Specific Instruction

Write tests for src/services/user.ts covering: successful user creation, duplicate email handling, password validation (min 8 chars, special char required). Use Jest and follow existing test patterns in __tests__/

Be Specific in Instructions

Clear directions upfront reduce course corrections later.

Course Correct Early

Press Escape to interrupt, double-tap to go back and try different approaches.

Use Subagents for Complex Problems

Tell Claude to use subagents to verify findings before proposing solutions.

Leverage Checklists for Large Tasks

For migrations or refactoring, have Claude create and work through a checklist.

Manage Context Wisely

Run /clear between unrelated tasks and be explicit about which files to focus on.

Review Before Committing

Always review Claude's changes: "Show me a summary of all changes you've made."

Use Git Effectively

Let Claude handle git: commit messages, rebasing, reviewing history.

10Troubleshooting

Claude jumps straight to coding

Solution: Explicitly separate exploration and coding phases:

First, read the relevant files and understand the current implementation.
Don't write any code until I approve your plan.

Context gets cluttered

Solution: Use /clear frequently, especially between different tasks.

Claude makes unwanted changes

Solution: Press Escape to interrupt, tell Claude to undo changes, then be more specific about scope.

MCP connection issues

Solution: Run claude --mcp-debug to see detailed logs. Check environment variables and network access.

Tests keep failing

Solution: Tell Claude to iterate:

Keep iterating until all tests pass. After each change, run the tests
and adjust your approach based on the failures.

11Quick Reference Card

Starting a Session

cd /your/project
claude                                    # Normal start
claude --dangerously-skip-permissions     # Skip prompts

Essential Keys

Shift + TabToggle modes

EscapeInterrupt

Escape × 2Go back

#Add to CLAUDE.md

Prompt Patterns

"Think hard about..."

Trigger extended thinking

"Don't write any code yet..."

Force planning phase

"Use subagents to verify..."

Enable parallel verification

"Keep going until..."

Iterative improvement