Claude Code is your terminal-native agentic engineering partner. This guide covers everything from getting started in 5 minutes to the advanced configurations that engineering teams build their entire workflows around.
Claude Code requires Node.js 18+ and an Anthropic API key. Installation takes under 2 minutes:
# Install globally npm install -g @anthropic-ai/claude-code # Set your API key (or add to .bashrc/.zshrc) export ANTHROPIC_API_KEY="sk-ant-..." # Navigate to your project cd my-project/ # Start an interactive session claude # Or give a one-shot task claude "Add input validation to all API endpoints and write tests"
Always start Claude Code from your project root directory. This ensures Claude's Glob and Read tools have access to your full project structure and CLAUDE.md is automatically loaded.
Once Claude Code is running, you're in an interactive REPL. Here's what you can do:
| Input | What it does |
|---|---|
| Natural language task | Give Claude a goal to accomplish autonomously |
| /help | Show available built-in slash commands |
| /plan "task" | Get an implementation plan before Claude starts coding |
| /edit filepath | Open a specific file for Claude to work on |
| /run "command" | Execute a shell command and show Claude the output |
| /clear | Clear conversation context (starts fresh awareness) |
| /cost | Show current session token usage and cost estimate |
| Ctrl+C | Cancel current Claude operation |
| exit / quit | End the Claude Code session |
Claude Code ships with a suite of built-in tools that allow it to interact with your filesystem, execute commands, and search your codebase. Understanding these helps you write better tasks:
| Tool | What Claude uses it for | When it activates |
|---|---|---|
| Read | Reads file contents into context | Understanding existing code before editing |
| Write | Creates new files from scratch | Generating new components, configs, tests |
| Edit | Makes targeted edits to existing files | Modifying specific functions, adding imports |
| Bash | Runs shell commands, sees output | Running tests, installing deps, building |
| Grep | Searches codebase for patterns | Finding all usages of a function, error patterns |
| Glob | Lists files matching patterns | Discovering project structure, finding related files |
| WebSearch | Searches the web for docs/solutions | Unfamiliar library APIs, error message research |
On a task like "add error handling to the payment module", Claude will: Glob to find all payment-related files → Read each file to understand current implementation → Grep to find all function calls → Edit targeted changes → Bash to run tests → Read failure output → iterate. This tool orchestration happens automatically.
CLAUDE.md is the single most impactful thing you can configure for Claude Code. It's loaded automatically at session start and gives Claude the context it needs to work like a team member who knows your codebase — not a stranger dropped into an unfamiliar repo.
CLAUDE.md files cascade: global (~/.claude/CLAUDE.md) → project root (./CLAUDE.md) → subdirectory (./src/CLAUDE.md). More specific files override more general ones. This lets you set global preferences while having project-specific overrides.
# Project: E-Commerce Platform API ## Architecture Overview - Node.js/Express REST API, PostgreSQL database - Monorepo: /api (backend), /web (React frontend), /shared (types) - Authentication: JWT stored in httpOnly cookies - ORM: Prisma with migrations in /prisma/migrations/ ## Coding Conventions - All functions must have JSDoc comments with @param and @returns - Error handling: wrap async route handlers with asyncHandler middleware - Validation: use Zod schemas defined in /src/schemas/ - Tests: Vitest, files named *.test.ts, coverage target 80% - Imports: always use path aliases (@/utils, @/models, etc.) ## What NOT to do - Never modify /prisma/schema.prisma — migrations require review - Do not install new dependencies without noting them in CLAUDE.md - Do not use any, always use proper TypeScript types ## Common Commands - Run tests: npm test - Start dev server: npm run dev - Run Prisma migrations: npx prisma migrate dev ## Team Preferences - Prefer functional components over class components in React - Always handle loading and error states in UI components - API responses: { data, error, meta } shape
Directory structure, technology stack, key files Claude should know about. Claude reads thousands of projects — yours needs a clear map.
ESLint caught naming issues. But "we never put business logic in route handlers" isn't lintable — that goes in CLAUDE.md as an explicit rule.
"Never modify the migrations folder" or "don't touch auth flows without running the security test suite" — guardrails that prevent costly mistakes.
How to run tests, build the project, start the dev server. Claude can then run these autonomously to verify its own work.
cd your-projecttouch CLAUDE.mdclaude and ask "Read my CLAUDE.md and tell me what's missing that would help you work on this project"Custom slash commands are reusable prompt templates stored as Markdown files. They turn common Claude Code tasks into one-keystroke operations — your team's shared vocabulary for recurring engineering workflows.
Project commands: .claude/commands/ — shared via git with your team
Personal commands: ~/.claude/commands/ — your personal library across all projects
# Code Review
Review the staged git changes as a senior engineer would.
Check for:
- Security vulnerabilities (injection, auth bypass, data exposure)
- Performance issues (N+1 queries, missing indexes, sync where async needed)
- Missing error handling and edge cases
- Violations of our coding conventions from CLAUDE.md
- Missing or inadequate tests
Output a structured review with:
1. CRITICAL issues (must fix before merge)
2. IMPORTANT issues (should fix, explain why if not)
3. SUGGESTIONS (optional improvements)
End with an overall APPROVE / REQUEST_CHANGES recommendation and one sentence summary.
# Generate Tests for $ARGUMENTS
Add comprehensive tests for the file or function: $ARGUMENTS
Requirements:
- Use Vitest (our test framework per CLAUDE.md)
- Cover: happy path, edge cases, error states, boundary conditions
- Mock external dependencies (don't hit real APIs in tests)
- Follow our pattern in existing test files as reference style
- Target 90%+ branch coverage for this unit
- Include a brief comment explaining what each test group verifies
Run the tests after writing them and fix any failures before finishing.
Use them by typing /review or /add-tests src/auth/login.ts in your Claude Code session. $ARGUMENTS captures whatever you type after the command name.
mkdir -p .claude/commands in your project/review command for PR review (use the template above, adapt to your stack)/document $ARGUMENTS command that adds JSDoc/docstring to a specified file/security-check that audits a module for OWASP Top-10 vulnerabilities/review on your latest git diff. Evaluate: does it catch real issues in your code?Plan mode is Claude Code's "show your work" setting. Instead of starting implementation immediately, Claude first proposes a detailed plan for your review and approval. This is critical for:
Any task spanning multiple files or requiring architectural decisions. Review the plan to catch misunderstandings before hours of implementation.
Authentication flows, payment processing, database schema changes — places where an incorrect implementation has serious consequences.
When Claude is working in a part of the codebase it hasn't touched yet. The plan reveals whether it understood the architecture correctly.
Share the plan with teammates before Claude implements. Catch disagreements at the planning stage, not in code review.
# In a Claude Code session, prefix task with /plan /plan "Refactor the notification system to support multiple channels (email, SMS, push) using the Strategy pattern" # Or via CLI flag claude --plan "Add OAuth2 authentication with Google and GitHub providers" # Claude responds with a structured plan like: # 1. Analysis of current notification code # 2. Files I'll create: NotificationStrategy.ts, EmailStrategy.ts, SMSStrategy.ts, PushStrategy.ts # 3. Files I'll modify: NotificationService.ts, user controller # 4. Tests I'll write: strategy unit tests, integration tests # 5. Estimated changes: +280 lines, -45 lines # Shall I proceed? (y/n/redirect)
Claude's 200K context window is large — but long sessions accumulate context that can degrade performance. Here's how to manage it effectively:
200K tokens ≈ ~150,000 words ≈ a large novel. More than enough for a full session. But as context fills with intermediate outputs, Claude's focus on your original instructions can dilute. Watch for this sign: Claude starts repeating things it already did, or misses constraints from earlier in the session. Time to /clear.
| Situation | What to do |
|---|---|
| Starting a new unrelated task | Use /clear to reset context. Reload CLAUDE.md context is automatic. |
| Session getting long, Claude seems confused | Summarize progress manually, then /clear and restart with the summary |
| Need Claude to focus on one area | Explicitly tell Claude which files to ignore: "Focus only on /src/api — don't read the frontend files" |
| Multi-day work on same feature | Add a "Current Status" section to CLAUDE.md that you update daily — persistent context across sessions |
These exercises are designed to build real proficiency, not just theoretical knowledge. Complete them in order on a real project:
Goal: Experience the full agentic loop on a real feature
/plan "your task" first. Review and give Claude any corrections before it starts/review command to run a code reviewGoal: Use Claude Code for a real-world modernization task
These workflows are used by engineering teams that have deeply integrated Claude Code into their development process:
At start of day: claude "Review yesterday's commits (git log --since=yesterday), summarize what changed, identify any technical debt created, and suggest what needs attention today". Turns commit history into actionable daily priorities in 60 seconds.
# Before creating a PR, run this custom command: /pr-prep # Which does: tests → lint → /review → generate PR description → check for security issues # Defined in .claude/commands/pr-prep.md:
For new team members: claude "Walk me through the authentication flow in this codebase — from the HTTP request hitting the router, through middleware, to the database query, and back. Explain each step and why it works the way it does." A 3-hour code walkthrough compressed to a focused session.