Claude Code — Hand Your Entire Codebase to AI from the Terminal

Chapter 4: Claude Code — Hand Your Entire Codebase to AI from the Terminal

Claude Code is Anthropic's official command-line AI coding tool. The difference from Cursor isn't "better" or "worse" — it's a different use case: Cursor is an IDE assistant, Claude Code is a terminal Agent that reads and writes files, executes commands, and autonomously completes multi-step tasks. This chapter covers installation, configuration, the core workflow, and a complete database migration case study.

Agent vs Editor Assistance: The Core Difference

Conclusion: Cursor is for interactive "write and see" development. Claude Code is for "give it a goal and let it handle it" Agent tasks. They're complementary, not competing.

Installation

npm install -g @anthropic-ai/claude-code

Requires Node.js 18+. After installation, run claude to enter interactive mode.

Authentication (3 Methods)

Method 1: Anthropic API Key (recommended for individuals)

export ANTHROPIC_API_KEY="sk-ant-api03-..."
claude

Method 2: Claude.ai account (Pro/Max subscription)

claude  # First run opens a browser for Claude.ai account authorization

For users with an existing Claude subscription who don't want to manage a separate API key.

Method 3: Amazon Bedrock / Google Vertex AI

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
claude

For enterprise users — code doesn't pass through Anthropic servers, meeting data sovereignty requirements.

CLAUDE.md: Giving Claude Code Project Context

Create CLAUDE.md in your project root. Claude Code reads it on every startup — the Claude Code equivalent of .cursorrules:

# Project: E-commerce Admin System

## Tech Stack
- Backend: Python 3.12 + FastAPI + SQLAlchemy 2.0
- Database: PostgreSQL 16 (primary) + Redis 7 (cache)
- Testing: pytest + pytest-asyncio

## Directory Structure
- src/api/ — FastAPI routes
- src/models/ — SQLAlchemy models
- src/services/ — business logic
- src/tests/ — test files

## Development Standards
- All database operations in services/ layer, not in api/
- New features must have corresponding pytest tests
- Run ruff check . and pytest before committing

## Common Commands
- Start dev server: uvicorn src.main:app --reload
- Run tests: pytest src/tests/ -v
- Database migration: alembic upgrade head

## Notes
- DB connection config is in src/config.py — don't hardcode
- Production DB uses DATABASE_URL environment variable

Case Study: MongoDB to PostgreSQL Migration (3 Phases)

A real scenario: migrating 150 API endpoints from MongoDB to PostgreSQL. Estimated manual effort: 2–3 weeks. Claude Code completed it in 3 days.

Phase 1: Analyze existing code

claude> Analyze all Python files under src/, find all MongoDB operations
(pymongo and mongoengine), and generate a report: which collections each file
touches, and at which line numbers.

Claude Code read all files and generated a detailed migration inventory: 24 collections, 150+ query operations.

Phase 2: Generate PostgreSQL schema and migration scripts

claude> Based on the MongoDB Schema you just analyzed, design equivalent PostgreSQL
database tables. Requirements:
1. Use SQLAlchemy 2.0 mapped_column syntax
2. Keep original field names, adjust types (ObjectId → UUID, nested docs → JSONB)
3. Generate Alembic migration files
4. Generate a data migration script to import MongoDB data into PostgreSQL

Phase 3: Update the API layer

claude> @src/api/products.py — replace all MongoDB queries in this file with
SQLAlchemy queries. Reference the new schema in @src/models/product.py.
After replacing, run pytest src/tests/test_products.py to confirm tests pass.

Claude Code modifies files, automatically runs tests, and if they fail, automatically analyzes errors and fixes them.

.claudeignore: Control What Claude Code Can Access

# .claudeignore
.env
.env.*
secrets/
*.pem
*.key
node_modules/
dist/
build/

Claude Code will skip these files and directories, preventing accidental reading of secrets or modification of build artifacts.

Cost Reference

Use claude --model claude-haiku-4-5 to switch to a cheaper model for simple tasks.

Chapter Key Points

1. Claude Code is an Agent; Cursor is an assistant: The former autonomously executes multi-step tasks; the latter requires you to confirm each step. They complement each other.
2. CLAUDE.md is the Agent's context foundation: More detail means output that better matches your project standards.
3. 3 authentication methods for different needs: API key for individuals, Claude.ai auth for subscribers, Bedrock/Vertex for enterprises.
4. Large migration tasks are Claude Code's specialty: Database migrations, API refactors, batch restructuring — these tasks take weeks manually but hours with Claude Code.
5. Use .claudeignore to protect sensitive files: Never let AI access key files, production configs, or build artifacts you don't want it to touch.