How to Use Claude Code: A Complete Guide for Developers
Claude Code is Anthropic's terminal-based AI coding agent. This guide covers everything from installation to running your first agentic task — including the parts the docs skip over.
What Makes Claude Code Different
Most AI coding tools are assistants — they suggest, you decide. Claude Code is an agent — it decides, executes, checks, and loops until the task is done.
You describe a task in plain English. Claude Code reads your codebase, makes a plan, writes code across multiple files, runs your tests, fixes failures, and commits the result. You supervise. It executes.
This guide covers the full setup and the workflows that make Claude Code worth using daily.
Installation
Claude Code requires Node.js 18+.
npm install -g @anthropic-ai/claude-code
Verify the install:
claude --version
Authentication
You'll need an Anthropic API key from console.anthropic.com. Set it as an environment variable:
export ANTHROPIC_API_KEY="sk-ant-..."
Add this to your .zshrc or .bashrc so it persists across sessions.
On first run, Claude Code will prompt you to authenticate if the key isn't set.
Your First Session
Navigate to any project directory and run:
claude
You're now in an interactive session. Claude Code can see every file in your project.
Try a simple task:
Add input validation to the login form — email format check and password minimum length of 8 characters. Add tests.
Claude Code will:
- Read your project structure
- Find the relevant files
- Plan the changes
- Make edits across multiple files
- Run your test suite
- Fix any failures
You'll see each step in the terminal as it happens.
Core Commands
Running a one-shot task (no interactive session)
claude -p "Refactor the UserService class to use dependency injection"
Use -p (print) for tasks where you want the output directly in your terminal without opening an interactive session.
Running from a file
claude < task.md
Useful for longer task descriptions or when you want to version-control your prompts.
Continue the last session
claude --continue
Picks up where the last session left off — same context, same conversation history.
How Claude Code Reads Your Codebase
Claude Code doesn't index your project like Cursor does. It reads files on demand as part of its reasoning process.
When you give it a task, it will:
- Read
package.json,pyproject.toml, or whatever your project's root config is - Scan directory structure to understand the layout
- Read files that are likely relevant to the task
- Form a plan before writing any code
This means it builds real context — not a vector search approximation. The tradeoff is that cold starts (first prompt in a new project) take longer than Cursor's indexed search. After a few exchanges, Claude Code has read enough to work efficiently.
Tip: Add a CLAUDE.md file to your project root. Claude Code always reads this file first. Use it to document conventions, architecture decisions, and things Claude should know about your codebase.
# CLAUDE.md
## Stack
- Next.js 15, TypeScript, Tailwind CSS
- Postgres via Drizzle ORM
- Tests: Vitest + Testing Library
## Conventions
- Components go in src/components/
- Server actions go in src/actions/
- Always run `pnpm typecheck` before committing
Slash Commands
Type / inside a Claude Code session to see available commands.
| Command | What it does |
|---|---|
/help | List all commands |
/clear | Clear conversation history (frees context) |
/compact | Summarize the conversation to save context |
/model | Switch models mid-session |
/cost | Show token usage and cost so far |
/init | Generate a CLAUDE.md for the current project |
/review | Review recent changes |
Permissions and Tool Use
Claude Code can run shell commands, but it asks for permission first. You'll see prompts like:
Claude wants to run: npm test
Allow? [y/n/always]
y— allow oncen— denyalways— allow this command type for the rest of the session
You can pre-authorize common commands in your .claude/settings.json:
{
"permissions": {
"allow": [
"Bash(npm test)",
"Bash(npm run lint)",
"Bash(git status)",
"Bash(git diff*)"
]
}
}
This eliminates the friction for commands you trust Claude Code to run without asking.
MCP Servers — Connecting External Tools
MCP (Model Context Protocol) lets Claude Code talk to external services. Once configured, you can do things like:
Query the production database and tell me which users signed up in the last 7 days
Create a Linear ticket for this bug and assign it to the backend team
Check the Sentry errors from this morning and fix the most frequent one
Adding an MCP server
claude mcp add
Follow the prompts. MCP servers are configured per-project in .claude/settings.json.
Popular MCP servers:
- GitHub — read/write issues, PRs, code
- Postgres / SQLite — query databases directly
- Slack — read channels, post messages
- Linear — manage issues and projects
- Browserbase — control a browser for web automation
Effective Prompting for Claude Code
Claude Code handles ambiguity better than most tools, but clear prompts produce better results.
Be specific about the outcome, not the steps:
# Too vague
Fix the authentication bug
# Better
Users are getting logged out after 30 minutes even with "remember me" checked.
The session token should persist for 30 days. Fix this and add a test that
verifies session persistence across server restarts.
Tell it what not to do:
Refactor the PaymentService to use the new Stripe SDK v5.
Don't change the public API — other services depend on the method signatures.
Don't modify any test files.
Give it context it can't find in the code:
We're migrating from REST to tRPC. Add a tRPC endpoint for the user profile fetch.
The REST endpoint is in src/api/users/[id].ts — match its behavior exactly.
The tRPC router is in src/server/routers/. Follow the existing pattern there.
Watching Claude Code Work
By default, Claude Code shows you what it's doing as it goes. You'll see:
- Files it's reading
- Plans it's forming
- Code it's writing
- Commands it's running
- Test output
- Fixes it's applying
You can interrupt at any point with Ctrl+C. Claude Code will stop and ask what you'd like to do instead.
If a session goes sideways — Claude Code is on the wrong track — interrupt early rather than waiting. The earlier you redirect, the less context gets consumed.
Cost Management
Claude Code uses the Anthropic API, billed per token. A few habits keep costs manageable:
- Use
/compactwhen sessions get long — it summarizes the conversation and frees context - Use
/clearto start fresh if you're switching to an unrelated task - Use
-pfor one-shot tasks instead of opening full interactive sessions - Check
/costperiodically to see where you stand
Typical usage:
- Simple one-shot tasks: $0.05–0.20
- Full feature implementation (many files): $0.50–2.00
- Complex multi-session refactors: $3–10
Heavy daily use runs $30–80/month on average.
Common Workflows
Ship a feature end-to-end
Implement a CSV export feature for the orders table.
- Add an "Export CSV" button to the orders list page
- Create a server action that streams the CSV response
- Handle large datasets (pagination in memory, not loading everything at once)
- Add a loading state to the button
- Write a test for the server action
Refactor safely
Refactor the database queries in src/lib/db/ to use prepared statements.
Run the test suite after each file change and fix any failures before moving on.
Don't change the function signatures — only the internals.
Debug a specific error
I'm getting this error in production:
TypeError: Cannot read properties of undefined (reading 'userId')
at middleware.ts:34
Find the root cause and fix it. Add a null check and a test that would
catch this error in the future.
The Learning Curve
Claude Code has a steeper learning curve than Cursor. The payoff is higher autonomy — once you learn to write good task descriptions, it can handle multi-hour tasks without intervention.
The best way to get good at it: start with real tasks on your actual projects. Small, well-defined tasks first. Then gradually hand it larger workflows as you build trust in its output.
The developers who get the most out of Claude Code treat it like a capable junior engineer — they give clear briefs, review the output carefully, and gradually increase the scope of what they delegate.