A plain language guide for experienced devs and newcomers to agentic coding. Get the fundamentals right.

12 min readJust now

–

Press enter or click to view image in full size

Let’s get you on the right track.

Claude Code changed how I write software. Not incrementally — fundamentally. After months of daily use, dozens of shipped features, and more than a few hard lessons, I’ve distilled everything that actually matters into this guide.

This isn’t a feature walkthrough. It’s a practitioner’s manual for getting real work done with an AI coding agent that operates directly in your terminal, understands your entire codebase, and can execute multi-step tasks autonomously.

Whether you’re evaluating Claude Code for the first time or looking to sharpen workflows you’ve already built, this guide covers the ground from installation to production-ready patterns used by teams at Anthropic and across the industry.

What Claude Code Actually Is

Claude Code is a command-line tool that gives you agentic access to Anthropic’s Claude models. “Agentic” means it doesn’t just answer questions — it takes action. It reads files, writes code, runs shell commands, manages git operations, and iterates on its own work until a task is complete.

The key distinction from chat-based AI assistants: Claude Code operates in your development environment rather than alongside it. It inherits your shell, your tools, your environment variables. When you tell it to run tests, it runs your actual test suite. When you tell it to commit, it commits to your actual repository.

This architecture choice — raw terminal access rather than IDE integration — makes Claude Code unopinionated about your workflow. It doesn’t force a particular way of working. The trade-off is a steeper learning curve. You need to develop your own patterns for getting consistent results.

That’s what this guide provides.

Getting Started Right

Installation

Claude Code installs globally. On macOS, Linux, or WSL:

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

On Windows PowerShell:

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

If you prefer Homebrew or npm:

# Homebrewbrew install --cask claude-code​# npm (requires Node.js 18+)npm install -g @anthropic-ai/claude-code

Authentication: API vs Subscription

You have two payment options:

API usage (pay-per-token): Connect your Anthropic Console account. You pay for exactly what you use. Costs can spike during heavy sessions — expect $5–50+ per day of active coding depending on task complexity and context size.

Claude subscription (Pro, Max, Teams, Enterprise): Fixed monthly cost with usage limits. The Max plan ($100/month at time of writing) is popular among heavy users because it removes the anxiety of watching API costs climb.

My recommendation: Start with a subscription if you plan to use Claude Code daily. API pricing makes sense for occasional use or CI/CD automation where you want granular cost control.

Your First Session

Navigate to any project directory and run:

cd your-projectclaude

First run triggers authentication. After that, you’re in a REPL — a persistent session scoped to that directory. Claude can see everything in the folder and its children, but nothing outside.

Type naturally. Ask questions. Give instructions. Claude will request permission before modifying files or running commands (you can adjust this later).

The Planning-First Principle

Here’s the most common mistake I see: jumping straight to “build me X” without giving Claude a chance to understand the problem.

Claude Code performs noticeably better when you separate thinking from doing. This isn’t about politeness — it’s about how the model allocates compute.

Plan Mode

Press Shift+Tab to cycle through modes until you reach Plan Mode. In this mode, Claude engages extended thinking before responding. It asks clarifying questions, considers alternatives, and produces a structured plan rather than immediately writing code.

Use Plan Mode when:

• Starting a new feature
• Tackling unfamiliar parts of the codebase
• Working on anything that touches multiple files
• Debugging complex issues

Extended Thinking Triggers

Even outside Plan Mode, specific phrases trigger deeper reasoning. These map to increasing thinking budgets:

Press enter or click to view image in full size

“ultrathink” is always my go-to for harder problems

The difference is measurable. A prompt like “add user authentication” produces different results than “think hard about how to add user authentication given our existing session management.”

The Explore-Plan-Code-Commit Workflow

Anthropic’s own engineering team uses this pattern:

1. Explore: Ask Claude to read relevant files. Be explicit: “Read the authentication module and the user model. Don’t write any code yet.”
2. Plan: Ask for a plan. “Think hard about how to implement password reset. What files need to change? What edge cases should we handle?”
3. Code: Once you’ve confirmed the plan, ask Claude to implement it. “Implement the plan. Verify each change compiles before moving on.”
4. Commit: “Commit these changes with a descriptive message. Update the README if the API changed.”

The explicit “don’t write code yet” instruction matters. Without it, Claude tends to jump straight to implementation, which often means revisiting decisions you’d have caught during planning.

Context Engineering: The Real Skill

LLMs are stateless. Claude knows nothing about your codebase when a session starts — only what you feed into the context window. The skill of context engineering is giving Claude the right information at the right time.

CLAUDE.md Files

CLAUDE.md is a special file that Claude automatically loads at the start of every session. It’s your project’s persistent memory.

A well-crafted CLAUDE.md typically includes:

• Build commands: How to compile, test, and run the project
• Code conventions: Patterns you want followed (or avoided)
• Architecture notes: How the system fits together
• Environment quirks: Anything non-obvious about the setup

Here’s a minimal example:

# Project: Invoice API​## Commands- `npm run dev` - Start development server- `npm test` - Run test suite- `npm run typecheck` - TypeScript validation​## Conventions- Use Zod for runtime validation, not class-validator- Prefer named exports over default exports- Error responses follow RFC 7807 (Problem Details)​## Architecture- Express.js REST API with PostgreSQL- Authentication via JWT in Authorization header- All database access through repository pattern in /src/repositories

Where to Place CLAUDE.md Files

Claude Code supports a hierarchy:

LocationScope~/.claude/CLAUDE.mdAll sessions on your machineProject rootAnyone working in this repoSubdirectoriesContext for specific modulesCLAUDE.local.mdPersonal settings (gitignored)

More specific files override general ones. A frontend/CLAUDE.md takes precedence over the root file when you’re working in the frontend directory.

Less Is More

Research from HumanLayer suggests that frontier models can reliably follow about 150–200 instructions. Claude Code’s own system prompt consumes roughly 50 of those. Every instruction you add to CLAUDE.md competes for attention.

The implications:

• Keep CLAUDE.md under 300 lines (shorter is better)
• Include only universally applicable guidance
• Move task-specific instructions to separate files

HumanLayer’s analysis found that as instruction count increases, compliance decreases uniformly across all instructions — not just the newer ones. Stuffing everything into CLAUDE.md makes all your guidance less likely to be followed.

Progressive Disclosure

Instead of front-loading all possible context, tell Claude where to find information when needed:

## Documentation- Database schema: docs/database.md- API contracts: docs/api-spec.md- Testing strategy: docs/testing.md​Read these files when working on relevant areas.

Claude will pull in documentation on demand, keeping the default context lean.

The /init Command

Run /init in any project to have Claude generate a starter CLAUDE.md based on analysing your codebase. It’s a reasonable starting point, but treat it as a draft—the auto-generated version often includes too much detail. Edit it down to what’s genuinely essential.

Crafting Effective Prompts

Prompt quality determines output quality. Claude can infer intent, but it can’t read minds.

Specificity Wins

Compare these prompts:

Press enter or click to view image in full size

Specificity reduces iterations. A detailed prompt often gets it right on the first attempt; a vague one requires multiple corrections.

Using Images

Press enter or click to view image in full size

You can paste an image directly from your clipboard.

Claude processes images directly either through a file reference or directly from your clipboard. Useful for:

• UI mockups as implementation references
• Screenshots of errors or unexpected behaviour
• Diagrams explaining desired architecture

On macOS, Cmd+Ctrl+Shift+4 captures to clipboard. Then Ctrl+V (not Cmd+V) pastes into Claude Code.

You can also drag-drop images into the terminal or provide file paths: “Implement the design shown in mockups/dashboard.png”

Using URLs

Paste URLs directly into prompts. Claude will fetch and read them:

Review the approach described at https://example.com/api-design-guide and apply similar patterns to our REST endpoints.

For frequently accessed domains, add them to your permission allowlist via /permissions to skip confirmation prompts.

File References with Tab Completion

Type @ followed by a path and use tab completion to reference files:

Refactor @src/services/payment.ts to use the new error handling pattern from @src/utils/errors.ts

This is faster than asking Claude to find files and ensures you’re both looking at the same thing.

Core Workflows That Work

Test-Driven Development

TDD works remarkably well with agentic coding. Claude iterates against tests the way a human would, but faster.

The pattern:

1. “Write tests for [feature] based on these requirements. Don’t implement the feature yet — I want the tests to fail initially.”
2. Confirm the tests are comprehensive.
3. “Now implement the feature to make the tests pass. Don’t modify the tests.”
4. Claude iterates until green.
5. “Commit the tests and implementation separately.”

Harper Reed, who’s written extensively about Claude Code workflows, notes that “the robots LOVE TDD.” Tests give Claude a concrete target to iterate against, reducing hallucination and scope drift.

Visual Iteration

For frontend work, give Claude a way to see its output:

1. Set up the Puppeteer MCP server (or similar)
2. Provide a mockup image
3. “Implement this design. After each change, take a screenshot and compare it to the mockup. Iterate until they match.”

Claude’s output improves with visual feedback. The first version might be close; after 2–3 iterations it’s usually spot on.

Codebase Q&A

Claude Code excels at explaining unfamiliar codebases:

• “How does authentication work in this project?”
• “What happens when a user submits a payment?”
• “Why are we using redis here instead of postgres?”
• “Walk me through the request lifecycle for POST /api/orders”

This is often faster than reading code yourself and surfaces details you’d otherwise miss. Many teams now use Claude Code as their primary onboarding tool for new developers.

Git Operations

Claude handles most git workflows. I use it for 90%+ of my git interactions:

• “What changed between v1.2 and v1.3?”
• “Who last modified the payment processing logic and why?”
• “Create a commit with an appropriate message for these changes”
• “Resolve the merge conflicts in feature-branch, preferring our changes for the API layer”

The time savings add up. Claude writes better commit messages than I do because it considers the full diff and recent history.

Course Correction and Recovery

Things go wrong. Claude takes an approach you don’t like, or starts editing files you didn’t intend. Recovery options:

Escape to Interrupt

Press Escape during any phase—thinking, tool execution, file editing. Context is preserved. You can redirect: "Stop. Let’s try a different approach."

Double-Escape to Rewind

Press Escape twice to jump back in conversation history. Select an earlier point and continue from there, discarding everything after. Useful when Claude went down a wrong path several turns ago.

/clear for Fresh Context

Between tasks, run /clear to reset the context window. This prevents irrelevant earlier conversation from confusing current work. I clear after every distinct feature or bug fix.

/compact for Compression

If you need to preserve some context but the window is filling up:

/compact Keep the database schema decisions and current test failures. Discard the earlier exploration of the authentication options we rejected.

/rewind for Checkpoint Recovery

If Claude made changes you don’t want, /rewind shows your message history. Select the point before the unwanted changes to roll back.

When to Start Fresh

Sometimes the cleanest option is a new session. Signs it’s time:

• Claude keeps repeating the same mistakes after correction
• The conversation has accumulated contradictory context
• You’ve pivoted to a completely different area of the codebase

Tools, Commands, and Hooks

Custom Slash Commands

Create reusable prompts as markdown files in .claude/commands/:

<!-- .claude/commands/review.md -->Review the code I've changed since the last commit:1. Check for logic errors and edge cases2. Verify error handling is comprehensive3. Confirm test coverage for new code paths4. Flag any security concerns5. Suggest readability improvements​Focus on substance over style—we have linters for formatting.

Now /project:review runs this workflow. The $ARGUMENTS keyword passes parameters: /project:fix-issue 1234 with a command containing $ARGUMENTS substitutes the issue number.

MCP Servers

The Model Context Protocol connects Claude to external tools. Common setups:

• Puppeteer: Browser automation and screenshots
• GitHub: Enhanced issue and PR management beyond the gh CLI
• Sentry: Error monitoring integration
• Database servers: Direct query access (use cautiously)

Add servers via:

claude mcp add server-name -s project -- npx @modelcontextprotocol/server-name

Check status with /mcp.

The gh CLI

If you work with GitHub, install the gh CLI. Claude uses it for:

• Creating and updating pull requests
• Reading and responding to PR comments
• Managing issues
• Fetching CI status

Without gh, Claude falls back to API calls, which work but are less ergonomic.

Hooks

Hooks are shell commands that run at specific lifecycle points:

• PreToolUse: Before Claude executes any tool
• PostToolUse: After successful tool execution
• Stop: When Claude completes a task

Example: Run linters automatically after every file edit. Configure via /hooks.

Permission Management

Claude asks permission for potentially destructive operations. Adjust defaults via:

• /permissions during a session
• .claude/settings.json in your project
• ~/.claude.json globally

Common additions to the allowlist:

• Edit - Allow file modifications without prompting
• Bash(git commit:*) - Allow commits
• Bash(npm test) - Allow running tests

For fully autonomous operation (risky): claude --dangerously-skip-permissions. Only use this in isolated environments like containers.

Multi-Claude Strategies

Complex projects benefit from running multiple Claude instances:

Git Worktrees

Git worktrees let you check out multiple branches in separate directories, all sharing the same repository:

# Create worktrees for parallel featuresgit worktree add ../project-auth feature/authenticationgit worktree add ../project-dashboard feature/dashboard​# Start Claude in each (separate terminals)cd ../project-auth && claudecd ../project-dashboard && claude

Each Claude works independently. No context switching, no conflicts until merge time.

Reviewer-Implementer Pattern

Have one Claude write code while another reviews:

1. Claude A implements a feature
2. /clear or start Claude B in another terminal
3. Claude B reviews A’s work, identifies issues
4. Claude A (or a fresh instance) addresses the feedback

The separation produces better results than single-Claude self-review.

Headless Mode for Automation

claude -p "prompt" runs Claude non-interactively, useful for:

• CI pipelines
• Pre-commit hooks
• Batch operations

Example in CI:

- name: Check for translation updates  run: |    claude -p "If there are new user-facing strings, add French translations and create a PR for the i18n team to review."

Add --output-format stream-json for structured output in automation contexts.

Defensive Coding Practices

Claude writes code quickly. That speed is dangerous without safeguards.

Testing

Write tests before or alongside features, not after. Tests give Claude a target to iterate against and catch regressions before they compound.

Linting and Formatting

Don’t ask Claude to follow style guidelines — it’s slow and unreliable. Use deterministic tools:

• Prettier/Biome for formatting
• ESLint/Ruff/Clippy for linting

Configure pre-commit hooks so Claude’s commits get validated automatically. The pre-commit Python package works well:

uv tool install pre-commitpre-commit install

Now every commit — including Claude’s — runs through your checks.

Why This Matters for AI Coding

Claude wants to commit. When you tell it to implement and commit, it will do so eagerly. Pre-commit hooks catch problems before they hit your repository, saving cleanup later.

Cost and Subscription Considerations

Claude Code uses tokens. Lots of them. Every file read, every command output, every iteration consumes context.

API pricing makes costs visible but unpredictable. A complex debugging session can easily burn through $20–50 in tokens. One user joked: “Someone with lots of tokens, please help me budget this. My family is dying.”

Subscription tiers provide predictability:

• Pro ($20/month): Good for evaluation and light use
• Max ($100/month): Removes most rate limits; popular for daily users
• Teams/Enterprise: Additional features for organisations

Managing Costs

• Use /clear between tasks to avoid bloated context
• Be specific to reduce iterations
• Use /compact strategically to preserve essential context
• For large codebases, guide Claude to specific files rather than letting it search broadly

Pulling It Together

The developers getting the most from Claude Code share a few habits:

1. They plan before coding. Explicit exploration and planning phases before asking for implementation.
2. They invest in context engineering. Lean, well-maintained CLAUDE.md files. Progressive disclosure of detailed documentation.
3. They stay specific. Detailed prompts upfront rather than vague requests followed by corrections.
4. They use safety nets. Tests, linting, pre-commit hooks, git branches. Claude is fast but imperfect.
5. They clear context aggressively. Fresh sessions for fresh tasks.
6. They course-correct early. Escape, rewind, redirect. Don’t let Claude wander.

Claude Code isn’t magic. It’s a tool that amplifies your ability to ship code — but it amplifies your mistakes too. The practices in this guide help you capture the upside while limiting the downside.

Start small. Run /init on an existing project. Ask Claude some questions about the codebase. Try the explore-plan-code-commit workflow on a contained feature. Build your own patterns from there.