Claude Code Setup Guide: From Installation to CLAUDE.md Configuration for Local Development
Claude Code Setup Guide: Complete Local Development Environment Configuration
Claude Code is Anthropic’s AI-powered coding assistant that runs directly in your terminal, providing context-aware code generation, debugging, and project management. This guide walks you through the complete setup process — from initial installation to advanced CLAUDE.md configuration — so you can maximize productivity in your local development environment.
Prerequisites
- Node.js 18+ installed on your system- An Anthropic API key or Claude Pro/Max subscription- A terminal application (Terminal, iTerm2, Windows Terminal, etc.)- Git installed and configured
Step-by-Step Installation
Step 1: Install Claude Code via npm
Open your terminal and run the following command to install Claude Code globally:
npm install -g @anthropic-ai/claude-code
Verify the installation was successful:
claude —version
Step 2: Authenticate with Your API Key
Launch Claude Code for the first time by navigating to any project directory and running:
cd /path/to/your/project
claude
On first launch, you will be prompted to authenticate. If using an API key, set the environment variable before launching:
export ANTHROPIC_API_KEY=YOUR_API_KEY
claude
For persistent configuration, add the export to your shell profile:
# For bash
echo 'export ANTHROPIC_API_KEY=YOUR_API_KEY' >> ~/.bashrc
source ~/.bashrc
For zsh
echo ‘export ANTHROPIC_API_KEY=YOUR_API_KEY’ >> ~/.zshrc
source ~/.zshrc
Step 3: Verify the Setup
Run a quick test to confirm everything works:
claude "explain the structure of this project"
If Claude responds with a summary of your project directory, you are ready to proceed.
Understanding CLAUDE.md Configuration
CLAUDE.md is a special markdown file that provides persistent instructions to Claude Code. It acts as a project-level system prompt, giving Claude context about your codebase, coding standards, and workflow preferences. There are three levels of CLAUDE.md:
| Level | Location | Scope |
|---|---|---|
| Global (User) | ~/.claude/CLAUDE.md | All projects for the current user |
| Project Root | ./CLAUDE.md (repo root) | Everyone working on this project |
| Subdirectory | ./src/CLAUDE.md | Context for specific directories |
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md << 'EOF'
# Global Claude Code Preferences
Coding Style
- Use TypeScript over JavaScript when possible
- Prefer functional programming patterns
- Always add error handling for async operations
Response Preferences
- Be concise in explanations
- Show code diffs rather than full file rewrites
Use conventional commits for git messages EOF
Step 5: Create a Project-Level CLAUDE.md
Navigate to your project root and create a project-specific configuration:
cat > CLAUDE.md << 'EOF'
# Project: My Web Application
Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript
- Styling: Tailwind CSS
- Database: PostgreSQL with Prisma ORM
- Testing: Vitest + React Testing Library
Project Structure
- src/app/ — Next.js app router pages
- src/components/ — Reusable UI components
- src/lib/ — Utility functions and shared logic
- prisma/ — Database schema and migrations
Coding Conventions
- Components use PascalCase file names
- Utilities use camelCase file names
- All database queries go through Prisma client in src/lib/db.ts
- API routes return typed responses using zod schemas
Commands
- Dev server: npm run dev
- Tests: npm run test
- Lint: npm run lint
Database migrate: npx prisma migrate dev EOF
Step 6: Start Using Claude Code with Context
Now when you launch Claude Code in your project, it automatically reads the CLAUDE.md files and applies the instructions:
claude
Example prompts that leverage your CLAUDE.md context:
create a new API route for user authentication write tests for the UserProfile component fix the database connection error in src/lib/db.ts refactor the dashboard page to use server components
Common Workflow Commands
Here are essential Claude Code commands for daily development:
# Start an interactive session
claude
Run a single command without interactive mode
claude “add input validation to the signup form”
Resume the previous conversation
claude —continue
Pipe content into Claude
cat error.log | claude “explain this error and suggest a fix”
Use a specific model
claude —model claude-opus-4-6
Pro Tips for Power Users
- Use slash commands: Type
/helpinside a session for available commands. Use/compactto compress conversation context when it gets long.- Leverage memory: Claude Code has a persistent memory system. Tell it to remember key decisions, and it will save them for future sessions.- Permission modes: Useclaude —dangerously-skip-permissionsin CI/CD pipelines for non-interactive automation (use with caution).- Multi-file edits: Claude Code can read, edit, and create multiple files in a single request. Describe the full feature you want rather than file-by-file changes.- Chain with git: Ask Claude to review staged changes with prompts like “review my staged changes and suggest improvements before I commit.”- Keep CLAUDE.md updated: Treat it like living documentation. When your stack evolves, update the file so Claude stays aligned.
Troubleshooting Common Issues
| Issue | Cause | Solution |
|---|---|---|
command not found: claude | npm global bin not in PATH | Run npm config get prefix and add the /bin directory to your PATH |
| Authentication failure | Invalid or expired API key | Regenerate your key at console.anthropic.com and update the env variable |
| CLAUDE.md not being read | File placed in wrong directory | Ensure the file is in the repo root or ~/.claude/ directory, and named exactly CLAUDE.md |
| Context window exceeded | Very large codebase or long session | Use /compact to compress context, or start a new session with claude |
| Slow responses | Large files being read | Add a .claudeignore file to exclude build artifacts, node_modules, and large binary files |
Do I need a paid Anthropic plan to use Claude Code?
Claude Code requires either an Anthropic API key with available credits or a Claude Pro or Max subscription. The Pro plan provides a generous usage allowance suitable for individual developers, while the Max plan is designed for heavy, professional usage with higher rate limits. You can sign up at anthropic.com and generate an API key from the developer console.
Can I commit CLAUDE.md to my repository for team-wide use?
Yes, and it is strongly recommended. Placing a CLAUDE.md file at your repository root ensures that every team member who uses Claude Code gets the same project context, coding conventions, and workflow instructions. This promotes consistency across the team. Personal preferences should go in the global ~/.claude/CLAUDE.md file, which is not committed to the repo.
How does CLAUDE.md differ from .cursorrules or .github/copilot-instructions.md?
While all three serve as AI assistant configuration files, CLAUDE.md is specifically designed for Claude Code and supports a hierarchical, directory-scoped system. Unlike flat instruction files, you can place CLAUDE.md files in subdirectories to provide context specific to that part of your codebase. Claude Code also features a persistent memory system that works alongside CLAUDE.md to learn your preferences over time, creating a more adaptive development experience.