Claude Code Getting Started: Safe Setup Guide

Q: Troubleshooting Common Issues

⚠️ **Common mistake:** Skipping `CLAUDE.md` and then complaining the agent "doesn't understand the project." Without a project file, every session starts from zero context and re-learns your conventions by guessing.

How do you start using Claude Code without accidentally letting it rewrite half your repo on the first run? That's the question that stops most people at the install step — they've heard a terminal agent can edit files and run commands, and the natural next thought is what if it edits the wrong ones. Fair worry. This Claude Code getting started guide is built around exactly that fear: get productive fast, but stay in control the whole time.

By the end you'll have it installed, configured with guardrails, and doing real work on a task you choose.

Claude Code Getting Started in 60 Seconds

Claude Code is Anthropic's terminal agent, distributed as an npm package. You need Node.js installed first, then it's one command.

hljs bash

npm install -g @anthropic-ai/claude-code
claude --version   ,[object Object],
,[object Object], your-project
claude              ,[object Object],

What this does: Installs Claude Code globally, prints the version so you know it's there, then launches an interactive session scoped to your current project directory. On first launch it walks you through authentication.

That's the whole install. The version check matters more than it looks — features and flags are version-specific, and the tool ships fast, so knowing you're on a current build (the 2.1.x series as of August 2026) saves you from chasing docs that don't match your binary.

⚡ Pro tip: Don't run your first session in a repo with uncommitted work you care about. Start in a scratch clone or a branch. Any Claude Code getting started run should assume you'll want a clean

git status

to diff against afterward.

Understanding the Variables

Two files and one mode do most of the work of keeping you safe and productive.

The first is

CLAUDE.md

, a plain markdown file in your repo root that Claude Code reads automatically at the start of every session. This is the single most valuable step you can take, and most quick-starts skip it entirely. You encode your project's conventions once, and every future session inherits them without you lifting a finger.

hljs markdown

# CLAUDE.md
- Test command: `npm test`
- Never edit files under /migrations without asking first
- Match existing code style; no new dependencies without flagging
- After any change, run the test command and report results

What this does: Gives the agent standing instructions it will follow on every run, so you're not re-typing "run the tests" and "don't touch migrations" into every prompt. It's project memory that survives across sessions.

The second variable is the model. Claude Sonnet 5 is the default in current builds, with a large context window (up to 1M tokens). It's the fast, capable everyday model; when a task needs heavier reasoning you switch up with

/model opus

for that session, then drop back. Most getting-started work never needs to leave the default.

The third is the mode. Plan mode lets the agent describe what it would do without changing anything — a read-only dry run you approve before execution.

Step-by-Step: Your First Real Task

Let's fix a real bug the safe way.

Step one: open a session and switch to plan mode so nothing changes yet.

hljs bash

claude
,[object Object],
,[object Object],
,[object Object],

What this does: The

Concise

output style makes Claude lead with results and skip the narration. Asking for a plan first means the agent surfaces its intended edits for your review before touching disk.

Step two: read the plan. If it wants to change a file it shouldn't, say so now. This is the two-minute checkpoint that prevents the messy runs people warn each other about.

Step three: approve execution. The agent makes the edits, runs your test command (because your

CLAUDE.md

told it to), and reports whether the tests pass.

Step four: diff and commit yourself.

git diff

shows you exactly what changed. You stay the author of the commit.

⚡ Pro tip: Scope permissions before you let an agent run commands unattended. Current Claude Code builds support scoped permissions that enforce least privilege on sub-agents, so a child agent can't do more than the task needs. Turn that on for anything running without you watching.

Pro-Level Variations

Once the basics click, three patterns pay off.

A frontend engineer at an e-commerce company runs Claude Code headlessly in a pre-commit hook:

claude -p "review the staged diff for accessibility issues"

. The

-p

flag runs one pass and exits, so it fits inside a script.

A platform engineer decomposes a large migration with nested sub-agents — a parent agent coordinates while child agents each own a service — then checkpoints the whole tree before logging off, resuming the next morning.

A technical writer with a documentation repo keeps a

CLAUDE.md

that says "update the changelog and the docs index whenever a public API changes," so the agent maintains cross-references she used to track by hand.

hljs bash

claude -p ,[object Object], > /dev/null

What this does: Runs a single non-interactive pass to draft changelog entries from recent commit history, discarding stdout so it's quiet enough to drop into a release script.

Once one person's Claude Code getting started run works, the natural next step is making it repeatable for everyone. Two things make that clean.

First, commit your

CLAUDE.md

to the repo. It's just a markdown file, so it version-controls like anything else, and now every teammate's session — and every CI run — inherits the same conventions. When someone tightens a rule ("never bump a dependency's major version without flagging"), the whole team gets it on their next pull.

Second, layer a personal choice on top of the shared one. A backend engineer tackling a gnarly refactor might switch up to Opus for that one session, while the team default stays on Sonnet 5 for everyday speed. Per-session

/model

handles that without touching the shared file.

hljs bash

claude --model opus   ,[object Object],
,[object Object],

What this does: Launches a session on the heavier Opus model for a genuinely hard change while keeping every rule from the committed

CLAUDE.md

. Team conventions and per-task model choice stop fighting each other, and you drop back to the fast default when the hard part is done.

Three teams, three shapes of this. A platform team keeps a strict

CLAUDE.md

that names off-limits directories and runs agents only in CI behind PR review. A two-person startup keeps a loose one and runs interactively all day, trusting the plan-then-approve loop. A large enterprise adds scoped permissions so sub-agents can't exceed their task, then audits the session transcripts. Same tool, tuned to the blast radius each team can tolerate.

⚡ Pro tip: Treat

CLAUDE.md

as living documentation, not a one-time setup file. Every time the agent does something you had to correct, add a line to

CLAUDE.md

so it never makes that mistake again. Over a few weeks it becomes the single best description of how your project actually works — useful to humans, not just the agent.

Troubleshooting Common Issues

⚠️ Common mistake: Skipping

CLAUDE.md

and then complaining the agent "doesn't understand the project." Without a project file, every session starts from zero context and re-learns your conventions by guessing. Ten minutes writing a good

CLAUDE.md

fixes ninety percent of the "it did the wrong thing" complaints in any Claude Code getting started experience.

The most common first-run stumble is authentication, not editing. Claude Code can run against your Claude subscription or an API key, and the two bill differently: subscription usage draws from your plan's limits, while an API key bills at standard per-token rates. For interactive work on a personal machine the subscription login is simplest; for scheduled or high-volume automation an API key gives you predictable pay-as-you-go costs. Pick deliberately, because a heavy overnight script on a subscription login can quietly eat your daily quota in one run.

If a session feels like it's ignoring your model choice, note that switching

/model

in one session historically affected settings in others in some builds — check that you set it in the session you're actually using. If MCP servers won't connect, run with

--debug

to surface the real error instead of guessing at the config.

And if costs climb faster than you expected, it's almost always context, not the model. A session that's been open for an hour accumulates a long history that gets re-sent on each turn, and you pay for those tokens every time. Start a fresh session for a genuinely new task instead of continuing one indefinitely, and drop to a lighter model with

/model

for routine edits. Current builds autocompact long sessions to manage this, but a clean session is still cheaper than a compacted marathon one. Most "why is this so expensive" surprises trace back to one endless session doing five unrelated jobs.

⚡ Pro tip: When a run goes sideways,

/resume

lets you jump back into a prior session rather than starting fresh, and it keeps the context you already built. Losing your place is usually recoverable; you rarely need to start over.

Your Turn

You now have a Claude Code getting started path that never puts you at the agent's mercy: install, write a

CLAUDE.md

, start in plan mode, review, approve, diff, commit. The guardrails aren't training wheels you'll outgrow — experienced users keep the plan-then-approve loop precisely because it's fast and it prevents the expensive mistakes.

Pick one small, annoying task — the kind you keep putting off, like adding validation to a form handler or writing tests for a neglected module — and run it end to end in a scratch branch tonight. Doing one real task teaches you more than reading five more guides, because you'll hit the exact spot where you want to intervene, and you'll learn where your own comfort line sits. And save the

CLAUDE.md

template and the plan-mode prompt that worked — a library like PromptABCD is the right home for the project files and instructions you'll reuse across every repo, so your next setup takes two minutes instead of twenty.

By the end you'll have it installed, configured with guardrails, and doing real work on a task you choose.

Claude Code Getting Started in 60 Seconds

Claude Code is Anthropic's terminal agent, distributed as an npm package. You need Node.js installed first, then it's one command.

hljs bash

npm install -g @anthropic-ai/claude-code
claude --version   ,[object Object],
,[object Object], your-project
claude              ,[object Object],

git status

to diff against afterward.

Understanding the Variables

Two files and one mode do most of the work of keeping you safe and productive.

The first is

CLAUDE.md

hljs markdown

# CLAUDE.md
- Test command: `npm test`
- Never edit files under /migrations without asking first
- Match existing code style; no new dependencies without flagging
- After any change, run the test command and report results

/model opus

for that session, then drop back. Most getting-started work never needs to leave the default.

The third is the mode. Plan mode lets the agent describe what it would do without changing anything — a read-only dry run you approve before execution.

Step-by-Step: Your First Real Task

Let's fix a real bug the safe way.

Step one: open a session and switch to plan mode so nothing changes yet.

hljs bash

claude
,[object Object],
,[object Object],
,[object Object],

What this does: The

Concise

output style makes Claude lead with results and skip the narration. Asking for a plan first means the agent surfaces its intended edits for your review before touching disk.

Step two: read the plan. If it wants to change a file it shouldn't, say so now. This is the two-minute checkpoint that prevents the messy runs people warn each other about.

Step three: approve execution. The agent makes the edits, runs your test command (because your

CLAUDE.md

told it to), and reports whether the tests pass.

Step four: diff and commit yourself.

git diff

shows you exactly what changed. You stay the author of the commit.

Pro-Level Variations

Once the basics click, three patterns pay off.

A frontend engineer at an e-commerce company runs Claude Code headlessly in a pre-commit hook:

claude -p "review the staged diff for accessibility issues"

. The

-p

flag runs one pass and exits, so it fits inside a script.

A technical writer with a documentation repo keeps a

CLAUDE.md

that says "update the changelog and the docs index whenever a public API changes," so the agent maintains cross-references she used to track by hand.

hljs bash

claude -p ,[object Object], > /dev/null

What this does: Runs a single non-interactive pass to draft changelog entries from recent commit history, discarding stdout so it's quiet enough to drop into a release script.

Once one person's Claude Code getting started run works, the natural next step is making it repeatable for everyone. Two things make that clean.

First, commit your

CLAUDE.md

/model

handles that without touching the shared file.

hljs bash

claude --model opus   ,[object Object],
,[object Object],

What this does: Launches a session on the heavier Opus model for a genuinely hard change while keeping every rule from the committed

CLAUDE.md

. Team conventions and per-task model choice stop fighting each other, and you drop back to the fast default when the hard part is done.

Three teams, three shapes of this. A platform team keeps a strict

CLAUDE.md

⚡ Pro tip: Treat

CLAUDE.md

as living documentation, not a one-time setup file. Every time the agent does something you had to correct, add a line to

CLAUDE.md

so it never makes that mistake again. Over a few weeks it becomes the single best description of how your project actually works — useful to humans, not just the agent.

Troubleshooting Common Issues

⚠️ Common mistake: Skipping

CLAUDE.md

and then complaining the agent "doesn't understand the project." Without a project file, every session starts from zero context and re-learns your conventions by guessing. Ten minutes writing a good

CLAUDE.md

fixes ninety percent of the "it did the wrong thing" complaints in any Claude Code getting started experience.

If a session feels like it's ignoring your model choice, note that switching

/model

in one session historically affected settings in others in some builds — check that you set it in the session you're actually using. If MCP servers won't connect, run with

--debug

to surface the real error instead of guessing at the config.

/model

⚡ Pro tip: When a run goes sideways,

/resume

lets you jump back into a prior session rather than starting fresh, and it keeps the context you already built. Losing your place is usually recoverable; you rarely need to start over.

Your Turn

You now have a Claude Code getting started path that never puts you at the agent's mercy: install, write a

CLAUDE.md

CLAUDE.md

Getting Started With Claude Code: A Safe Setup Guide

Claude Code Getting Started in 60 Seconds

Understanding the Variables

Step-by-Step: Your First Real Task

Pro-Level Variations

Troubleshooting Common Issues

Your Turn

Continue Reading

Using a CLI Agent for Large Refactors

CLI Agent Workflows for Bug Fixing

How to Give a CLI Agent Access to Your Repo

Getting Started With Claude Code: A Safe Setup Guide

Claude Code Getting Started in 60 Seconds

Understanding the Variables

Step-by-Step: Your First Real Task

Pro-Level Variations

Troubleshooting Common Issues

Your Turn

Continue Reading

Using a CLI Agent for Large Refactors

CLI Agent Workflows for Bug Fixing

How to Give a CLI Agent Access to Your Repo

Claude Code Getting Started in 60 Seconds

Understanding the Variables

Step-by-Step: Your First Real Task

Pro-Level Variations

Setting Up a Config Your Whole Team Can Share

Troubleshooting Common Issues

Your Turn

Continue Reading

Using a CLI Agent for Large Refactors

CLI Agent Workflows for Bug Fixing

How to Give a CLI Agent Access to Your Repo

Claude Code Getting Started in 60 Seconds

Understanding the Variables

Step-by-Step: Your First Real Task

Pro-Level Variations

Setting Up a Config Your Whole Team Can Share

Troubleshooting Common Issues

Your Turn

Continue Reading

Using a CLI Agent for Large Refactors

CLI Agent Workflows for Bug Fixing

How to Give a CLI Agent Access to Your Repo