Claude Code Tutorial: Complete Beginner's Guide to AI-Powered Development

Learn Claude Code from zero to productive. Installation, first project, advanced techniques, and real workflow examples for developers of all levels.

What is Claude Code?

Claude Code is Anthropic's AI-powered development tool that can:

- Write code from natural language descriptions - Read and understand your entire codebase - Run commands and tests - Debug and fix errors - Refactor and improve code

Think of it as a senior developer who never gets tired and knows every programming language.

---

Installation

Prerequisites

- Node.js 18+ installed - A code editor (VS Code recommended) - Anthropic API key or Claude subscription

Step 1: Install Claude Code

```bash npm install -g @anthropic/claude-code ```

Step 2: Authenticate

```bash claude-code auth

Opens browser for authentication

```

Step 3: Verify Installation

```bash claude-code --version

Should show: claude-code 2.x.x

```

---

Your First Project

Starting a New Project

```bash mkdir my-first-project cd my-first-project claude-code init ```

This creates: - `.claude/` directory for config - `CLAUDE.md` for project instructions

Hello World

Start Claude Code: ```bash claude-code ```

Then type: ``` Create a simple hello world web page with a button that shows an alert ```

Claude Code will: 1. Create `index.html` 2. Add necessary HTML, CSS, JS 3. Show you the result

---

Basic Workflow

The Conversation Pattern

``` 1. DESCRIBE what you want └── 'Add a dark mode toggle to the header'

2. REVIEW what Claude proposes └── Check the plan before executing

3. APPROVE or ADJUST └── 'Yes, but use CSS variables instead of inline styles'

4. VERIFY the result └── 'Run the tests' or check manually ```

Essential Commands

CommandWhat It Does `/help`Show available commands `/clear`Clear conversation `/compact`Summarize long context `/cost`Show API usage `/diff`Show pending changes

---

Effective Prompting

Bad Prompt

``` make it better ```

Good Prompt

``` Refactor the user authentication to: 1. Use bcrypt for password hashing 2. Add rate limiting (5 attempts per minute) 3. Return proper HTTP status codes 4. Add unit tests for the new functionality ```

The SPEC Pattern

Situation: What's the current state? Problem: What needs to change? Expectation: What should the result look like? Constraints: Any limits or requirements? Example: ``` Situation: We have a REST API for user management. Problem: The login endpoint is slow (2+ seconds). Expectation: Login should complete in under 200ms. Constraints: Don't change the database schema. ```

---

Project Configuration

The CLAUDE.md File

Create a `CLAUDE.md` in your project root:

```markdown

Project: My App

Tech Stack

- React 19 - TypeScript 5.5 - Tailwind CSS - PostgreSQL

Architecture

- Components in /src/components - API routes in /src/api - Database models in /src/models

Conventions

- Use functional components with hooks - Prefer named exports - Tests alongside source files (*.test.ts) - Use 2-space indentation

Common Tasks

- Run tests: `npm test` - Start dev server: `npm run dev` - Build: `npm run build` ```

Claude Code reads this automatically and follows your conventions.

---

Real Workflow Examples

Example 1: Adding a Feature

``` You: Add a search feature to the products page

Claude: I'll add search with the following approach: 1. Add search input component 2. Create search API endpoint 3. Add debounced search logic 4. Update product list to filter

Shall I proceed?

You: Yes, but use the existing Input component from /src/components/ui

Claude: [Creates files, writes code]

You: Run the tests

Claude: [Executes npm test] All tests pass. ```

Example 2: Debugging

``` You: I'm getting 'Cannot read property map of undefined' in ProductList

Claude: Looking at ProductList.jsx...

The issue is on line 23. You're calling `products.map()` before the data loads. The products state initializes as undefined.

Fix: - Initialize products as empty array: useState([]) - Or add null check: products?.map()

Shall I apply the fix? ```

Example 3: Refactoring

``` You: The user service is getting too big. Split it into smaller modules.

Claude: I'll split UserService into: 1. AuthService - login, logout, tokens 2. ProfileService - user data, preferences 3. PermissionService - roles, access control

Here's the proposed structure: /services /user auth.ts profile.ts permissions.ts index.ts (re-exports)

Shall I proceed? ```

---

Advanced Techniques

Multi-File Operations

``` Update all API routes to use the new authentication middleware. The middleware is in /src/middleware/auth.ts. ```

Claude Code will scan all files and update each one.

Test-Driven Development

``` Write tests for the CartService first, then implement: - addItem(productId, quantity) - removeItem(productId) - getTotal() - checkout() ```

Code Review

``` Review this PR for security issues, performance problems, and code style. Be thorough—this is going to production. ```

---

Tips from Power Users

1. Start Specific, Then Expand

``` ❌ 'Build me an e-commerce site' ✅ 'Create the product model with name, price, and inventory fields' ```

2. Verify After Each Step

Don't let Claude make 10 changes without checking each one.

3. Use Git Branches

``` git checkout -b feature/new-feature claude-code

Make changes

git diff # Review git commit ```

4. Keep Context Clean

Use `/compact` when conversations get long.

5. Read What It Writes

Always understand the code Claude produces—you're responsible for it.

---

Common Pitfalls

1. Over-trusting Output

Claude is very capable but not infallible. Always review.

2. Vague Instructions

The more specific you are, the better the results.

3. Ignoring Context

Claude forgets previous sessions. Keep CLAUDE.md updated.

4. Fighting the Tool

If Claude's approach differs from yours, explain why yours is better.

---

Troubleshooting

ProblemSolution 'Context too long'Use `/compact` Wrong frameworkUpdate CLAUDE.md with tech stack Keeps using old patternExplicitly state the new pattern Won't run commandsCheck permissions, restart API errorsCheck connection, restart auth

---

Getting More Help

- Documentation: docs.anthropic.com/claude-code - Discord: Join the Claude Code community - GitHub Issues: Report bugs and request features

---

What's Next?

1. Complete the tutorial project in your terminal 2. Try it on a real project you're working on 3. Experiment with complex tasks like refactoring 4. Share what you learn with the community

Claude Code is a tool that rewards practice. The more you use it, the better you'll get at prompting and the more productive you'll become.

---