TL;DR
Install Claude Code with the native installer (curl -fsSL https://claude.ai/install.sh | bash), write a short CLAUDE.md, set explicit allow/ask/deny rules in .claude/settings.json, then complete one small task end to end before doing anything bigger. Budget about 30 minutes. You need a paid Claude plan — Pro at $20/month (which bundles Claude Code and Cowork as of June 2026), Max at $100 or $200, or an API/Console account. The free Claude.ai plan does not include Claude Code.
What this tutorial solves
Claude Code is genuinely capable, but the first run on a real codebase feels like a wall of unfamiliar pieces: settings, permissions, CLAUDE.md, slash commands, subagents, MCP servers. The common failure is skipping all of that, asking for something large, and bailing when the diff is 40 files and unreviewable. This guide gets you to a productive baseline: enough context that the agent stops guessing, enough guardrails that you can review every change, and one small successful task on record before you scale up.
This is for developers trying Claude Code for the first time on a real project (not a throwaway repo), or anyone who installed it months ago, ran it once, and let it gather dust. Good moments to do this: starting a new project, joining an existing codebase, or migrating from Cursor or Copilot to a terminal-based agent.
When this is NOT the right tool
- One-off scripts where the setup overhead exceeds the task.
- Production-critical code with no test suite — the agent has nothing to verify against.
- Teams that merge without code review.
- Any directory holding live secrets the agent could read. Keep
.envandsecrets/**on the deny list (covered below).
Before you start
- Get a paid plan. Claude Code requires Pro, Max, Team, Enterprise, or a Console (API) account. Pro is $20/month and now bundles Claude Code plus Cowork. Free Claude.ai accounts cannot run it.
- Start from a clean commit. The agent’s blast radius is everything changed since your last commit, so commit (or stash) first to keep a rollback point.
- Install Git. On native Windows, Git for Windows lets Claude Code use the Bash tool instead of PowerShell-only mode. macOS and Linux already have a shell.
- Pick the small first task ahead of time. A typed fix, one new test, one rename — not “modernize the auth flow.”
- Skim your repo’s README so you can summarize it in
CLAUDE.mdrather than rewrite it.
Install Claude Code
The native binary installer is Anthropic’s recommended method as of June 2026 — it needs no Node.js and auto-updates in the background.
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# Homebrew (macOS/Linux) — does not auto-update
brew install --cask claude-codenpm still works if you prefer it (requires Node.js 18+), but it is no longer the default path:
npm install -g @anthropic-ai/claude-codeVerify the install, then run a deeper check:
claude --version
claude doctorclaude doctor reports your install method, version, and the result of the last auto-update — run it first whenever something looks off.
Step by step
-
Start Claude Code in your project root: run
claude. The first launch opens a browser handshake to authenticate against your Claude account. -
Create
CLAUDE.mdat the repo root. Describe the project in one paragraph, list the exact build/test/lint commands, note conventions, and name the files the agent must not touch. Keep it tight — one or two screens beats 500 lines, because everything in it is read into context on every run. You can also run/initto have Claude Code draft a first pass from your codebase, then trim it. -
Set permissions in
.claude/settings.json. Rules are evaluateddeny→ask→allow, and the first match wins, so deny always overrides. A safe starter budget:\{ "permissions": \{ "allow": [ "Read", "Grep", "Glob", "Bash(npm run test:*)", "Bash(npm run lint:*)", "Bash(git status)", "Bash(git diff:*)", "Bash(pnpm typecheck)" ], "ask": [ "Bash(git push:*)", "Bash(npm install:*)" ], "deny": [ "Read(./.env)", "Read(./secrets/**)", "Bash(rm -rf:*)", "Bash(git push --force:*)", "Bash(npm publish:*)" ] \} \}Anything unmatched falls back to a prompt, which is exactly what you want early on.
-
Use Plan Mode for the first real change. Press
Shift+Tabto cycle into Plan Mode, or just say “Plan only. List the files you’d touch, the tests you’d add, and anything out of scope. Do not write code yet.” Read the plan before letting it write a single line. -
Watch the run, and stop it the moment it drifts. Cancelling is free; recovering from a 40-file wrong diff is not.
-
Commit after every productive run. Treat commits as save points — each subsequent agent run sees the latest commit as its new baseline.
First-run exercise
A concrete 15-minute loop that earns trust without risk:
- Pick one small utility function with no tests. Tell Claude Code: “Write tests for the current behavior of
src/utils/formatDate.ts. Cover the happy path plus 3 edge cases. Show me the diff before writing.” - Review the proposed test file before approving the write. Run the suite; it should pass.
- Commit. Then ask for a small refactor of the same function and re-run the tests.
- If anything went sideways, note exactly which step failed. That note becomes a rule in
CLAUDE.md— that is how a setup gets better instead of repeating mistakes.
Quality check after each step
- Diff against
main. The agent should be touching only the files you expected. Unexpected files means the plan was too loose. - Tests pass. If they don’t, revert before continuing — never compound work on a broken state.
- CLAUDE.md was obeyed. If a constraint was ignored, the wording was probably vague; rewrite the rule with a concrete example.
- The suggested commit message matches your repo style. Rewrite it if not.
Going further: subagents, slash commands, MCP
Once the basic loop feels comfortable, three features pay off in order of value:
| Feature | What it is | When to add it |
|---|---|---|
| Plan Mode | Built-in read-only planning before any edit (Shift+Tab) | Day 1, every non-trivial task |
| Slash commands | Reusable prompts in .claude/commands/*.md (e.g. a /commit with your message format) | Once you retype the same prompt twice |
| Subagents | Specialized instances with their own context — built-ins include Explore (read-only) and Plan | For large-codebase research that would otherwise bloat your main context |
| MCP servers | Connectors to external tools (Playwright, databases, GitHub) | Only after the core loop is solid; add one at a time |
Add an MCP server with, for example, claude mcp add playwright npx @playwright/mcp@latest. Start without any — they add moving parts, and most first projects never need them.
Common mistakes
- Skipping CLAUDE.md. The agent makes wrong assumptions on every run.
- Granting blanket permissions on day 1. The learning curve is exactly when expensive mistakes happen. Keep destructive commands on
askordeny. - Running on a dirty or git-less repo. No clean commit means no rollback path.
- Letting it run unsupervised for 30+ minutes. Long runs accumulate small errors into one big unreviewable diff.
- Asking for a giant task before earning trust. Stay on single-file changes for the first week.
- Auto-approving every prompt. Read each one for the first dozen tasks. That habit is the safety mechanism, not the permission file.
How to reuse this setup
- Template it: copy your
.claude/settings.jsonand aCLAUDE.mdskeleton across new projects. - Save the planning prompt that worked best (“Plan only. List files, tests, and out-of-scope items.”) and reuse it verbatim, or wire it into a
/planslash command. - Build the habit: plan → run → diff → tests → commit → repeat. Don’t skip a step because “this one looks fine.”
- Revisit
.claude/settings.jsonmonthly. Your sense of which commands are safe to auto-allow shifts as trust builds.
FAQ
Do I need a paid plan to use Claude Code? Yes. As of June 2026 Claude Code requires Pro ($20/month, which bundles Claude Code and Cowork), Max ($100 or $200), Team, Enterprise, or a Console (API) account. The free Claude.ai plan does not include it.
Which models does Claude Code run? Anthropic models only — Claude Opus 4.7 for the hardest work and Sonnet 4.6 as the everyday workhorse, both with a 1M-token context window. It does not run GPT-5.5 or Gemini. If you need those, that is a job for Cursor or another multi-model IDE.
Cursor vs Claude Code — which should I use? Cursor is IDE-native and multi-model; Claude Code is terminal-native, agentic, and Anthropic-only. Many developers run both: Cursor for quick inline edits, Claude Code for multi-step tasks. See Claude Code vs Cursor.
Will Claude Code break my code? It can. Always run on a committed repo, keep destructive commands on the deny list, and review every diff before accepting.
Where do slash commands and skills live?
Slash commands are Markdown files in .claude/commands/; skills are SKILL.md files under .claude/skills/. Both can also live at the user level in ~/.claude/. Type / in a session to list everything available.
How do I share the setup with a teammate?
Commit CLAUDE.md and .claude/settings.json to the repo. Each teammate runs claude in the repo and inherits both. Keep machine-specific or secret-bearing overrides in .claude/settings.local.json, which is git-ignored.