Claude Code transforms how you write software by providing an intelligent AI pair programmer right in your terminal. This guide gets you from zero to productive in 2 hours, covering everything from initial setup through building your first feature with AI assistance.
Before starting, ensure you have:
By the end of this guide, you’ll be able to:
Install Claude Code globally
The recommended installation method uses npm:
npm install -g @anthropic-ai/claude-codeFor macOS and Linux users, avoid using sudo as it can lead to permission issues. If you encounter errors, see the troubleshooting section.
Windows users have two options:
For native Windows:
$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"Verify installation
Navigate to your project directory and start Claude Code:
cd your-projectclaudeYou should see the Claude Code welcome message and interactive prompt.
Choose your authentication method
Claude Code offers three authentication options:
For API usage and billing
This is ideal for developers who want direct API access and usage-based billing.
Unified subscription (recommended for individuals)
For teams using cloud providers
See the enterprise deployment guide for detailed setup.
Test your setup
Run a simple command to verify everything works:
> create a hello.js file that prints "Hello from Claude Code!"Claude should create the file and show you the changes.
Now let’s configure Claude Code for optimal productivity.
Claude Code’s permission system balances safety with efficiency. Choose your preferred mode:
Claude asks permission for each file modification and command. This is the safest option for beginners.
# No special configuration neededclaudeFor experienced users who want uninterrupted workflow:
claude --dangerously-skip-permissionsThis mode bypasses all permission prompts. Claude can edit files and run commands without asking. Use this only in trusted environments or containers.
A middle ground - automatically accepts file edits but still prompts for commands:
claude --permission-mode acceptEditsClaude Code uses intelligent model selection by default:
You can override the default:
# Force a specific modelclaude --model opusclaude --model sonnet
# Or configure in settings/configInstall the Claude Code extension
The extension auto-installs when you run claude from the integrated terminal.
Features:
Cmd+Esc (Mac) or Ctrl+Esc (Windows/Linux)Install the Claude Code plugin from the marketplace:
For remote development, install on the remote host.
Configure terminal for optimal experience
Run this command to set up proper key bindings:
> /terminal-setupThis enables:
Shift+Enter for multiline inputClaude Code uses CLAUDE.md files to maintain project context across sessions. This is crucial for consistent, high-quality assistance.
Generate initial CLAUDE.md
> /initClaude analyzes your project and creates a tailored CLAUDE.md file containing:
Customize for your needs
Edit the generated CLAUDE.md to include:
# Project OverviewThis is a Next.js e-commerce application using TypeScript and Tailwind CSS.
# Key Commands- `npm run dev` - Start development server- `npm run build` - Build for production- `npm test` - Run test suite- `npm run lint` - Check code quality
# Coding Standards- Use functional components with hooks- Implement proper TypeScript types (no `any`)- Follow Airbnb ESLint rules- Write tests for all new features
# Architecture Notes- API routes in /app/api- Components in /components with .tsx extension- Use server components by default- Client components only when neededUse the # shortcut for quick updates
As you work, quickly add memories:
> # Always use Prisma for database queries, never raw SQLClaude prompts you to select which memory file to update.
This is the heart of effective Claude Code usage - a systematic approach to building features.
Why start with a PRD? Clear requirements lead to better implementations. Claude excels when given specific context and goals.
Create a feature PRD
> Create a PRD for a user authentication system with email/password> login, registration, password reset, and session managementClaude generates a comprehensive PRD including:
Refine the requirements
Review and adjust the PRD:
> Add OAuth support for Google and GitHub to the auth PRD> Include rate limiting requirements for securityStore in project memory
> Save this PRD to docs/features/authentication.md> # This project uses JWT tokens with 24-hour expiryClaude’s thinking modes unlock powerful architectural planning:
For typical features:
> Create a detailed implementation plan for the authentication systemFor complex architectural decisions:
> Think hard about the best approach for implementing secure> session management that scales to 1M usersThis triggers ~5,000 tokens of reasoning.
For critical system design:
> Ultrathink about migrating our monolithic auth to microservices> while maintaining backward compatibilityThis can use up to 128,000 tokens for extensive analysis.
Example planning session:
> Based on our authentication PRD, think deeply about the> implementation approach. Consider:> - Security best practices> - Database design> - API structure> - Testing strategy> - Potential edge casesClaude will:
Transform plans into actionable tasks:
Generate structured todos
> Convert the authentication plan into a detailed todo list> with subtasks and dependenciesClaude creates:
## Authentication Implementation Tasks
### 1. Database Setup- [ ] Create users table with email, password_hash, created_at- [ ] Add indexes for email (unique) and created_at- [ ] Create sessions table with user_id, token, expires_at- [ ] Write migration scripts
### 2. API Endpoints- [ ] POST /api/auth/register - [ ] Input validation - [ ] Password hashing with bcrypt - [ ] Email uniqueness check - [ ] Create user record- [ ] POST /api/auth/login - [ ] Validate credentials - [ ] Generate JWT token - [ ] Set secure HTTP-only cookie...Execute tasks systematically
> Let's start with task 1 - create the database schemaClaude:
Track progress
> Mark database setup as complete and move to API endpointsContinue through the todo list, with Claude maintaining context and checking off completed items.
MCP (Model Context Protocol) servers extend Claude’s capabilities with external tools.
Enhanced file operations
{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] } }}Enables advanced file searching and bulk operations.
Repository integration
{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } } }}Access issues, PRs, and repository data.
Library documentation
{ "mcpServers": { "context7": { "command": "npx", "args": ["-y", "@context7/mcp-server"] } }}Get up-to-date documentation for any library.
Create MCP configuration
Add to .claude/mcp.json in your project:
{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" } } }}Verify MCP connections
> /mcpThis shows:
Authenticate if needed
Some servers require OAuth:
> /mcp# Select "Authenticate" for servers requiring itLet’s build a real feature using Claude Code:
Start with requirements
> We need a user profile page that shows:> - User information (name, email, avatar)> - Account settings> - Recent activity> Plan the implementation but don't write code yetCreate the feature branch
> Create a new git branch called feature/user-profileImplement the UI
> Create a UserProfile component using our design system> Follow the mockup in designs/user-profile.pngClaude:
Add data fetching
> Implement the API route to fetch user profile data> Include proper error handling and loading statesWrite tests
> Write comprehensive tests for the UserProfile component> Include unit tests and integration testsFix any issues
> Run the tests and fix any failuresClaude iterates until all tests pass.
Commit and push
> Commit all changes with a descriptive message and pushClaude excels at debugging:
> TypeError: Cannot read property 'name' of undefined at UserProfile.tsx:34> Fix this errorClaude will:
Claude Code provides sophisticated Git integration:
> What files have I changed?# Claude runs git status and summarizes
> Commit these changes with a descriptive message# Claude analyzes changes and writes commit message
> The auth changes should be a separate commit# Claude creates multiple logical commits> Create a pull request for this feature# Claude:# - Pushes current branch# - Creates PR with comprehensive description# - Links related issues# - Adds reviewers if configured> Help me resolve these merge conflicts# Claude:# - Shows conflicts clearly# - Suggests resolutions# - Preserves intended functionality# - Runs tests after resolutionIf you have gh CLI installed:
> What are the open issues labeled 'bug'?> Implement a fix for issue #234> Create a PR that fixes #234Create reusable commands in .claude/commands/:
Example: .claude/commands/test-component.md
Please create comprehensive tests for: $ARGUMENTS
Requirements:- Use React Testing Library- Test all props variations- Include accessibility tests- Mock external dependencies- Achieve >90% coverageUsage:
> /test-component UserProfileConfigure in .claude/settings.json:
{ "hooks": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "prettier --write \"$CLAUDE_FILE_PATHS\"" } ] } ]}This automatically formats files after Claude edits them.
Work on multiple features simultaneously:
# Terminal 1git worktree add ../feature-auth auth-featurecd ../feature-authclaude
# Terminal 2git worktree add ../feature-profile profile-featurecd ../feature-profileclaudeEach Claude instance works independently without conflicts.
> Fix the bug> Make it better> Add some tests> Fix the authentication bug where users can't log in with> special characters in passwords
> Improve the UserList component performance by implementing> virtual scrolling for lists over 100 items
> Add unit tests for the calculateTax function covering all> tax brackets and edge casesClear between unrelated tasks
> /clearUse focused queries
# Instead of: "analyze the entire codebase"> Analyze the authentication module in src/auth/Reference specific files
> Explain how @src/utils/validation.ts works| Task | Command |
|---|---|
| Start new feature | > Create a plan for [feature description] |
| Fix a bug | > [paste error] Fix this error |
| Write tests | > Write tests for @src/components/Button.tsx |
| Refactor code | > Refactor the auth module to use hooks |
| Update docs | > Update the README with the new API changes |
| Code review | > Review my changes and suggest improvements |
| Git operations | > Create a PR for this feature |
If you see npm permission errors:
claude migrate-installerThis moves Claude Code to ~/.claude/local/
Debug MCP problems:
claude --mcp-debugCheck server logs and configuration.
For files over 10k lines, focus on specific sections:
> Analyze the authentication logic in @large-file.js#L1000-L1500Now that you’ve mastered the basics:
Remember: Claude Code is your AI pair programmer. The more context and clarity you provide, the better it can assist you. Start with simple tasks and gradually tackle more complex challenges as you build confidence.
Pro tip: Keep iterating on your CLAUDE.md file. The better you document your project’s patterns and preferences, the more consistent and helpful Claude becomes.