The Primer

Claude Code is a terminal-native AI coding agent. Install it with npm install -g @anthropic-ai/claude-code, navigate to your project directory, and run claude. It works in any terminal: macOS Terminal, iTerm, Windows Terminal, or Linux shells. It reads your codebase, understands context, and can edit files, run commands, and manage Git — all from the command line.

This is the primary interface. Everything else builds on top of this. If you learn nothing else from this guide, learn to use Claude Code in your terminal.

The Claude Code Desktop App gives you a native macOS/Windows application with multi-conversation support, session management, and a more visual interface. It is essentially the same engine as the terminal version but with a GUI wrapper that makes it easier to manage multiple projects and sessions.

Use the Desktop App when you want to manage multiple parallel sessions visually, or when you prefer a windowed interface over the terminal. The terminal and Desktop App are complementary, not competing — use whichever fits your current task.

When you first run Claude Code in a project, it creates a .claude/ directory for local settings and state. Add this to your .gitignore immediately. This directory contains personal configuration, session state, and potentially sensitive context that should never be committed to version control.

Also add .claude to your global gitignore so it is excluded from every repository on your machine by default.

Claude Code integrates directly with VS Code and its derivatives (Cursor, Windsurf, etc.) through the terminal panel. Open the integrated terminal in your IDE and run claude. You get the full power of Claude Code whilst seeing file changes reflected live in your editor tabs.

This is the most common workflow: IDE for viewing and navigating code, Claude Code in the terminal for executing changes. The IDE extension also adds features like inline diff viewing and one-click accept/reject for proposed changes.

Claude Code is available at code.claude.com in any browser, including mobile. This means you can start a task from your phone, review progress on a tablet, or kick off a long-running job from any device. The web interface connects to the same projects and maintains the same context.

Use this for async workflows: start a refactor before lunch from your phone, check progress from your laptop later. It is particularly useful for long-running tasks where you do not need to watch every step.

Claude Code defaults to the latest Sonnet model for speed and cost efficiency, but you can switch to Opus for complex tasks that require deeper reasoning. Use /model to change models mid-conversation. Sonnet handles most coding tasks well; Opus excels at architecture decisions, complex debugging, and multi-file refactors.

The rule of thumb: start with Sonnet, escalate to Opus when Sonnet struggles or when the task requires genuine reasoning about trade-offs. Do not waste Opus on simple file edits.

The Max plan gives you significantly higher rate limits and priority access to Opus. If you are using Claude Code as your primary development tool — which you should be — the rate limits on lower plans will become a bottleneck within days. The Max plan pays for itself in the first week through increased velocity.

For teams, the Team plan provides centralised billing, shared configuration, and usage analytics. Talk to your engineering lead about getting the team set up.

Press Shift+Tab to toggle Plan Mode. In this mode, Claude analyses your request and produces a detailed plan without making any changes. Review the plan, ask for modifications, then approve execution. This prevents Claude from charging off in the wrong direction on complex tasks.

Use Plan Mode for: multi-file changes, architectural decisions, anything involving database migrations, and any task where the wrong approach would be expensive to undo. Skip it for simple, obvious changes like fixing a typo or adding a single function.

Add “Before you start, ask me any clarifying questions” to your prompts. This forces Claude to surface ambiguities and assumptions before it starts coding. It is far cheaper to answer three questions upfront than to undo 500 lines of code built on a wrong assumption.

This is especially important for tasks where requirements are ambiguous, when working in an unfamiliar codebase, or when the task could be interpreted in multiple valid ways.

Claude Code can execute shell commands directly. Instead of switching to another terminal to run tests, install packages, or check logs, just ask Claude: “Run the test suite”, “Install the axios package”, “Show me the last 50 lines of the error log”. Claude will construct and execute the appropriate command, then interpret the output.

This keeps your entire workflow in one place and lets Claude use command output as context for its next action. It can chain commands intelligently: run tests, see failures, fix the code, re-run tests — all in one flow.

Extended Thinking gives Claude a private scratchpad to reason through complex problems before responding. Enable it for tasks that require multi-step reasoning: debugging race conditions, designing data models, planning migration strategies, or understanding complex business logic.

You will see a “thinking” indicator while Claude works through the problem. The resulting output is typically more thorough and accurate than standard responses for complex tasks, though it takes longer and uses more tokens.

The Explore subagent reads and indexes your codebase to answer questions about structure, dependencies, and patterns. Ask it things like: “How is authentication implemented?”, “Where are database migrations defined?”, “What is the data flow from the API endpoint to the database?”

Use Explore when you are new to a codebase, when onboarding to an unfamiliar module, or when you need to understand existing patterns before making changes. It is your codebase tour guide.

The CLAUDE.md file is Claude Code's project memory. Place it in your project root and fill it with: coding standards, architectural decisions, deployment procedures, testing conventions, and anything you find yourself repeatedly telling Claude. Claude reads this file at the start of every conversation.

A good CLAUDE.md includes: the tech stack and key dependencies, how to run the project locally, how to run tests, the preferred code style, naming conventions, and any project-specific patterns or anti-patterns. Update it continuously as the project evolves. This is the single highest-leverage file in your repository for AI-assisted development.

Use /clear between unrelated tasks within the same session. Claude's context window is large but finite. Stale context from a previous task can confuse Claude on the current task, leading to hallucinations or referencing files that are no longer relevant.

Think of /clear as closing browser tabs. After finishing a feature, before starting a bug fix in a different module, run /clear to give Claude a fresh context. It will re-read CLAUDE.md and start clean.

When your conversation grows long, Claude Code automatically compacts the context by summarising earlier messages to free up token space. This is usually transparent, but be aware that compaction can lose nuanced details from earlier in the conversation. If you notice Claude forgetting earlier decisions or constraints, it may be due to compaction.

Mitigation: for long sessions, periodically restate critical constraints. If a task is complex enough to need a very long conversation, consider breaking it into smaller sub-tasks with /clear between them, each with explicit context in the prompt.

Claude Code can process images. When debugging UI issues, paste or drag a screenshot directly into the conversation. Combine this with error messages and log output for multimodal debugging: “Here is the error in the console [paste error], here is what the page looks like [paste screenshot], and here is the relevant log output [paste logs]. Fix it.”

This dramatically reduces debugging cycles because Claude can see exactly what you see, rather than trying to infer the visual state from code alone.

Claude Code can stage, commit, push, create branches, handle merges, and write commit messages. Ask it to: “Commit what we just did with a descriptive message”, “Create a feature branch for this work”, “Rebase on main and resolve any conflicts”.

Claude writes better commit messages than most developers because it has full context of what changed and why. Let it handle the Git workflow so you can focus on the engineering decisions.

Claude Code automatically creates checkpoints before making changes. If something goes wrong, use /rewind to roll back to a previous state. This is your safety net: it lets you experiment aggressively knowing you can always undo.

Think of checkpoints as automatic save points in a game. You can try risky refactors, experiment with different approaches, and rewind if the result is not what you wanted. This encourages bolder, faster iteration.

The /statusline command lets you customise what information Claude displays in its status bar. Configure it to show model name, token usage, cost estimates, or project-specific metrics. This gives you real-time visibility into your session without interrupting your workflow.

Useful configurations: show remaining tokens to know when you are approaching compaction, show model name to confirm you are on Opus for complex tasks, show session cost to stay within budget.

More context produces better results. Instead of “fix the login bug”, say “The login form on /auth/login submits but the session cookie is not being set. The Express session middleware is configured in server.js. The issue started after we upgraded express-session from v1.17 to v1.18. Fix the session configuration.”

Include: what you are trying to achieve, what you have already tried, relevant file paths, error messages, and any constraints. The more Claude knows, the fewer wrong turns it will take.

If you do not know how to approach a problem, just describe it to Claude in plain language. You do not need to know the technical terms or the right library. Say “I need to make this page load faster” or “Users are complaining that the search is slow when there are more than 10,000 records”. Claude will figure out the technical approach.

This is the most underutilised tip. Developers waste hours searching documentation and Stack Overflow when they could describe the problem to Claude and get a contextual solution in seconds.

Claude Code has a built-in guide subagent that can answer questions about Claude Code itself. Ask it about features, commands, configuration options, and best practices. Use it when you are unsure how to use a specific feature or want to discover capabilities you did not know existed.

Think of it as the manual that actually answers your questions. Instead of searching documentation, ask the guide: “How do I set up MCP servers?”, “What is the difference between plugins and skills?”, “How do I configure parallel subagents?”

Define custom slash commands in .claude/commands/ to automate repeated workflows. Each command is a Markdown file with a prompt template. For example, create .claude/commands/review.md that instructs Claude to review code for security issues, performance problems, and style violations.

Good candidates for custom commands: code review checklists, deployment procedures, database migration templates, test generation patterns, and PR description generators. If you type the same kind of prompt more than twice, make it a command.

Model Context Protocol (MCP) servers connect Claude Code to external tools and data sources: databases, APIs, monitoring systems, design tools, and more. Configure them in your project settings to give Claude direct access to your infrastructure.

Popular MCP servers include: PostgreSQL for direct database queries, GitHub for issue and PR management, Figma for design specs, and Sentry for error tracking. Each server exposes tools that Claude can call naturally during conversation. Set up the ones relevant to your stack and Claude becomes dramatically more capable.

Skills are curated knowledge packages that give Claude expertise in specific frameworks, libraries, or domains. Install community skills for your tech stack: React, Django, Kubernetes, AWS, and hundreds more. Skills contain best practices, common patterns, and domain-specific guidance that improves Claude’s output quality.

Browse available skills in the Claude Code marketplace. Install them per-project so each project gets the relevant expertise without bloating others.

When third-party skills do not cover your specific domain, create your own. Skills are Markdown files that describe patterns, conventions, and expertise. Create skills for your company’s internal frameworks, proprietary APIs, or domain-specific business logic.

A custom skill for your internal component library, for example, would describe each component’s API, common usage patterns, accessibility requirements, and gotchas. Claude would then use these components correctly without you explaining them every time.

Plugins bundle multiple customisations — skills, commands, MCP configurations, and settings — into a single installable package. Create a plugin for your team that encapsulates your entire development workflow: coding standards, deployment procedures, testing patterns, and tool configurations.

This means a new team member can install one plugin and immediately have Claude configured with all your team’s conventions and tools. Plugins are the highest-level abstraction for sharing Claude Code configurations.

Customisations can be scoped at three levels: global (all projects), project (specific repository), or session (current conversation only). Choose the right scope to keep your configuration clean.

Global scope: personal preferences, your IDE settings, general coding standards. Project scope: tech-stack-specific skills, project MCP servers, team conventions. Session scope: temporary tools for one-off tasks. Getting scope right prevents configuration bloat and ensures Claude loads only relevant context.

The Frontend Design plugin gives Claude access to a headless browser for visual development. Claude can render components, take screenshots, compare against design specs, and iterate on visual output. This closes the loop between code and visual result without you having to manually check every change.

Use it for: building UI components, matching Figma designs, fixing responsive layout issues, and visual regression testing. Claude can see what the code produces and adjust accordingly.

Define custom subagents that specialise in specific domains: a security auditor, a performance analyser, a documentation writer, a test generator. Each subagent has its own system prompt, tools, and context, making it an expert in its narrow domain.

Claude can delegate to these subagents during a conversation. Ask Claude to “run the security audit subagent on this PR” and it will spin up a focused analysis using the security subagent’s specialised prompt and tools.

When using Opus, you can set the effort level to “high” for tasks that benefit from deeper analysis. High effort tells Opus to spend more time thinking and exploring before responding. This produces significantly better results for architectural decisions, complex refactors, and debugging subtle issues.

Reserve high effort for tasks where quality matters more than speed. Do not use it for simple changes — it will just burn tokens without improving the result.

Write a specification document before asking Claude to implement a feature. The spec should include: what the feature does, acceptance criteria, edge cases, error handling requirements, and any constraints. Feed the spec to Claude and ask it to implement against it.

Spec-driven development produces dramatically better results because Claude has a clear, unambiguous target. It also makes verification straightforward: does the implementation meet the spec? This is the professional way to use AI-assisted development.

Before integrating a new library, API, or technology, ask Claude (or ChatGPT) to compile a research report. The report should cover: what it does, how it works, common pitfalls, alternatives considered, licensing implications, and a recommended integration approach. Save this report to your docs/scratchpad/ directory.

This prevents the common failure mode of diving into integration without understanding the tool. The research report becomes a reference document for anyone who needs to understand why a particular technology was chosen and how it should be used.

Write tests first, then ask Claude to implement the code that makes them pass. This is TDD with AI: you define the expected behaviour through tests, Claude writes the implementation. The tests act as an unambiguous specification that Claude can verify against.

This workflow produces higher-quality code because Claude has a concrete verification mechanism. It can run the tests, see what fails, and iterate until everything passes. You get both working code and a test suite in one pass.

For any non-trivial task, follow the RPIT loop: Research the problem space and constraints, Plan the approach (use Plan Mode), Implement the solution, Test to verify it works. This prevents the common failure of jumping straight to implementation without understanding the problem.

Each phase can involve both Claude and ChatGPT. Research with Claude exploring the codebase and ChatGPT reviewing findings. Plan with Claude in Plan Mode and ChatGPT reviewing the plan. Implement with Claude. Test with Claude running tests and ChatGPT reviewing coverage.

Connect Claude Code to your project management tool (Jira, Linear, GitHub Issues, etc.) via MCP. This lets Claude read task descriptions, acceptance criteria, and context directly from where your team plans work. No more copy-pasting requirements into prompts.

The workflow becomes: assign a ticket, tell Claude to implement it, Claude reads the ticket details via MCP, implements the solution, and can even update the ticket status when done. This keeps your project management tool as the single source of truth.

Structure your work around issues (GitHub Issues, Jira tickets, etc.) rather than ad-hoc requests. Each issue should have a clear description, acceptance criteria, and scope. Tell Claude to work on a specific issue, and it will create a branch, implement the solution, write tests, and prepare a PR — all scoped to that single issue.

Issue-based development creates a clean audit trail: every code change is linked to a specific requirement. Combined with the scratchpad logs, you have complete traceability from requirement to implementation to documentation.

Do not review every line of AI-generated code. Instead, verify at higher levels: do the tests pass? Does the feature work as specified? Does the architecture make sense? Are the API contracts correct? Line-by-line review of AI-generated code is a poor use of your time.

Your job shifts from writing code to verifying behaviour. Run the tests, check the feature in a browser, review the API responses. If the high-level behaviour is correct and the tests pass, the implementation details are probably fine. Focus your review time on architectural decisions and edge cases, not syntax.

Always ensure Claude can run tests, linters, type checkers, or other verification tools after making changes. A Claude that can verify its own work will catch and fix errors before you even see them. Include verification commands in your CLAUDE.md so Claude knows how to check its work.

The ideal workflow: Claude makes changes, runs the test suite, sees failures, fixes them, re-runs tests, confirms everything passes, then reports to you. This self-correction loop dramatically improves first-pass quality.

Use Claude to generate and maintain documentation automatically. After implementing a feature, ask Claude to update the README, API docs, and architecture diagrams. Use ChatGPT to review and refine the documentation for clarity and completeness.

Create a custom /command like /document that instructs Claude to scan recent changes and update all relevant documentation. Run it at the end of each development session to keep docs in sync with code. Documentation debt accumulates fast; automate it away.

Point Claude at legacy code and ask it to explain what it does, identify issues, and propose refactoring strategies. Claude excels at reading complex, poorly-documented code and producing clear explanations. Use this to onboard to unfamiliar codebases or to plan modernisation efforts.

Start with understanding: “Explain what this module does and identify any issues.” Then plan: “Propose a refactoring plan that maintains backward compatibility.” Then execute incrementally, with tests at each step. Document the legacy patterns in your scratchpad so the knowledge is preserved.

Never hardcode API keys, database credentials, or other secrets in your code. Use .env files for local development and environment variables in production. Add .env to your .gitignore and create a .env.example with placeholder values so new team members know which variables are required.

Tell Claude about your secrets management approach in CLAUDE.md. Include instructions like: “All secrets are in .env. Never hardcode credentials. Use process.env.VARIABLE_NAME to access them.” This prevents Claude from accidentally exposing secrets in committed code.

For large features with independent components, spawn parallel subagents to work on different parts simultaneously. Claude can coordinate multiple subagents, each working on a separate file or module, and merge their results. This can cut implementation time dramatically for features with natural parallelism.

Example: building a new API endpoint might parallelise into: one subagent writes the route handler, another writes the database migration, a third writes the tests, and a fourth writes the documentation. Claude orchestrates all four and merges the results.

Open multiple terminal tabs or windows, each running a separate Claude Code instance in a different branch or directory. Work on multiple features simultaneously, each in its own isolated context. This is “multi-Clauding” — the developer equivalent of parallel processing.

The key is isolation: each instance should work on a separate Git branch to avoid file conflicts. You become a project manager coordinating multiple AI developers, each focused on a different task. This scales your output linearly with the number of instances you can manage.

Git worktrees let you check out multiple branches simultaneously in separate directories, all sharing the same Git history. This is the safest way to run multiple Claude Code instances: each worktree is a fully independent working directory with its own branch.

Create worktrees with git worktree add ../project-feature-x feature-x. Each Claude instance operates in its own worktree, making file conflicts impossible. When the feature is done, merge the branch and remove the worktree. This is the professional approach to multi-Clauding.

The Claude Code Desktop App provides a visual interface for managing multiple simultaneous sessions. Each session gets its own tab with status indicators, making it easy to monitor progress across parallel workstreams. Use it as your command centre when multi-Clauding.

The Desktop App also makes it easier to switch context between sessions, review outputs, and coordinate work. It is particularly useful when you have three or more parallel sessions and the terminal tabs become hard to track.

Configure Claude to learn from its mistakes within a session. When Claude makes an error, do not just fix it — tell Claude what went wrong and why, and ask it to update its approach. Add the lesson to CLAUDE.md if it is a recurring pattern. Over time, your CLAUDE.md becomes a refined instruction set that prevents repeated mistakes.

The feedback loop: Claude makes a mistake → you explain the error → Claude adjusts → you update CLAUDE.md → future sessions start with the corrected knowledge. This compounds over weeks and months into dramatically better first-pass quality.

A “Ralph Wiggum Loop” is an autonomous cycle where Claude implements, tests, reviews the results, and iterates — all without human intervention. Set up the loop by giving Claude a clear goal, verification criteria, and permission to iterate. Claude will keep going until the tests pass and the goal is met.

This is powerful for well-defined tasks with clear success criteria: fix all failing tests, achieve 90% code coverage, resolve all TypeScript errors, or optimise a function until it meets a performance benchmark. Set a maximum iteration count to prevent runaway loops and monitor cost.

Autonomous loops and Opus with high effort can consume significant tokens. Set cost guardrails: configure maximum spend per session, per task, or per day. Monitor your usage dashboard regularly. Set up alerts for unusual consumption patterns.

Practical guardrails: set a maximum iteration count for autonomous loops (typically 10–20), use Sonnet for exploratory work and only escalate to Opus for confirmed complex tasks, and review cost reports weekly. The goal is aggressive usage within controlled bounds.

The Claude Code GitHub Action integrates Claude into your CI/CD pipeline. It can automatically review PRs, run code analysis, generate documentation updates, and even fix failing tests. Configure it in your .github/workflows/ directory to run on PR creation, push events, or on a schedule.

Common CI/CD integrations: automated code review on every PR, documentation generation on merge to main, test coverage analysis, security scanning, and dependency update PRs. This makes Claude a permanent member of your development pipeline.

The Claude Code Slack integration lets your team interact with Claude directly in Slack channels. @mention Claude to ask questions about the codebase, request code reviews, or trigger automated workflows. This makes Claude accessible to non-developers on the team — product managers can ask about feature status, designers can check implementation details.

Configure which repositories Claude has access to and which channels it monitors. Set up dedicated channels for different projects. The Slack integration is particularly useful for asynchronous workflows where team members across time zones need AI assistance.

Agent Teams coordinate multiple specialised agents working on a shared goal. Unlike simple parallel subagents, Agent Teams have a coordinator that manages dependencies, resolves conflicts, and ensures the final result is coherent. Use them for large features that require multiple specialisations working together.

Example: building a full-stack feature might use a team with a backend agent (API design), a frontend agent (UI implementation), a database agent (schema and migrations), and a testing agent (integration tests). The coordinator ensures the API contracts match between frontend and backend, and that the database schema supports the required queries.

Claude Code asks for permission before executing potentially dangerous commands. Pre-configure permissions to allow safe operations automatically while requiring approval for risky ones. This lets Claude work autonomously on safe tasks whilst maintaining a guardrail for destructive operations.

Allow automatically: running tests, linting, type checking, reading files, Git operations on feature branches. Require approval: deleting files, modifying production configs, running database migrations, installing new dependencies, pushing to main. Get the balance right and Claude can work independently for long stretches.

Hooks let you define actions that run automatically after Claude completes certain operations. For example: automatically run the linter after every file edit, run tests after every code change, or send a notification when a task completes. Hooks make Claude’s workflow deterministic and consistent.

Configure hooks in your project settings. Common hooks: post-edit linting, post-commit test runs, post-task Slack notifications, and automatic formatting. Hooks ensure quality gates are never skipped, regardless of how the conversation flows.

When integrating Claude Code into automated pipelines, use structured output mode to get predictable JSON responses. This makes it easy to parse Claude’s output programmatically and feed it into other tools. Structured output is essential for CI/CD integration, automated reporting, and tool chains.

Example: ask Claude to analyse a codebase and output a JSON report with categories like security issues, performance concerns, and code quality scores. Feed this JSON into your dashboard, alerting system, or project management tool automatically.

Create a shared library of effective prompts that your team can reuse. Store them as custom /commands or in a shared documentation directory. Include prompts for: architecture reviews, security audits, performance analysis, code review checklists, and onboarding guides.

A prompt library prevents each developer from reinventing the wheel. When someone discovers a particularly effective prompt pattern, add it to the library. Over time, this becomes a collective knowledge base of how your team communicates with AI tools most effectively.

Before opening a PR for human review, ask Claude to review your changes first. Claude can catch common issues, suggest improvements, verify test coverage, and ensure the code follows project conventions. This means human reviewers spend their time on architectural and business logic concerns rather than style and obvious bugs.

Create a custom /pre-review command that runs Claude through a checklist: Does it follow the coding standards? Are there tests for new functionality? Are there any security concerns? Is error handling complete? This pre-flight check dramatically improves PR quality.

When Claude encounters errors during autonomous operation, configure retry logic that includes context from the error. Instead of simply retrying the same approach, Claude should analyse the error, adjust its strategy, and try a different approach. This is more effective than blind retries.

Implement this with hooks and custom commands: on error, capture the error message, feed it back to Claude with the original goal, and ask for an alternative approach. Set a maximum retry count (typically 3–5) to prevent infinite loops on genuinely unsolvable problems.

Claude Code automatically caches prompts and system context to reduce costs and improve response times. You do not need to configure this — it happens transparently. Understanding this helps you make better decisions: long system prompts and CLAUDE.md files are cached efficiently, so do not worry about making them comprehensive.

Prompt caching means your CLAUDE.md, skills, and plugin configurations are only processed once per session, not on every request. This is why a detailed CLAUDE.md is cost-effective: the initial processing cost is amortised across all subsequent requests in the session.

Schedule regular audits of your Claude Code setup: review your CLAUDE.md for accuracy, remove outdated skills and plugins, update MCP server configurations, and review custom commands for relevance. As your project evolves, your Claude Code configuration should evolve with it.

Monthly audit checklist: Is CLAUDE.md accurate? Are all installed skills still relevant? Are MCP connections working? Are custom commands still useful? Are permission settings appropriate? Are cost guardrails set correctly? A well-maintained configuration compounds in value; a neglected one accumulates confusion.