Claude Code for Beginners: Real Commands, Real Workflow, First Project

What Claude Code Actually Is

Claude Code is a terminal-based AI coding assistant built by Anthropic. It is not an IDE extension or a chat window you paste code into. You run it from your command line, and it reads your actual project files, understands your codebase context, and executes multi-step coding tasks: writing features, fixing bugs, running tests, and committing changes.

The practical difference from chatbot-style AI coding help is significant. Claude Code can open and read multiple files at once, understand how components connect, and make coordinated changes across your codebase rather than just answering isolated questions. This guide covers installation, the core workflow, real commands, and how to get the most out of your first project.

Installing Claude Code

You need Node.js version 18 or later. Install Claude Code with npm:

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

After installation, start an interactive session in your project directory:

cd your-project-folder
claude

The first time you run it, you will be prompted to authenticate with your Anthropic account or API key. Once authenticated, you are in an interactive session. Type your task in plain English and press Enter.

To run a one-shot task without entering the interactive session:

claude -p "add input validation to the registration form in auth.js"

Or pipe content directly:

cat error.log | claude -p "what is causing this error and how do I fix it?"

The Core Interactive Commands

Inside an interactive session, slash commands control the session behavior. These are the ones you will use most often:

Your First Real Project: A Node.js REST API

The best way to learn Claude Code is to build something real. Here is a step-by-step walkthrough of building a simple REST API for a task list, which demonstrates the core workflow you will use on every project.

Step 1: Initialize the Project and Create CLAUDE.md

mkdir task-api && cd task-api
npm init -y
claude

Once in the interactive session, type:

Initialize this project. We are building a REST API for task management using
Express and Node.js. The API should support creating, reading, updating, and
deleting tasks. Tasks have an id, title, description, status (todo/in-progress/done),
and created_at timestamp. Use in-memory storage for now, no database required.

Claude Code will create the project structure, install Express, and set up a basic server file. It tells you exactly what it is creating before it creates it, and asks for confirmation on significant changes.

Step 2: Add the CRUD Endpoints

Add all four CRUD endpoints: GET /tasks (list all), POST /tasks (create),
PUT /tasks/:id (update status), DELETE /tasks/:id (delete).
Include input validation: title is required, status must be one of the three valid values.

Claude Code reads the existing server.js, understands the current structure, and adds the endpoints in a consistent style. It handles edge cases like missing task IDs and invalid status values without you having to specify each one.

Step 3: Write Tests

Write Jest tests for all four endpoints. Cover the happy path and at least one
error case per endpoint. Set up the test file in a __tests__ directory.

Then run the tests:

npm test

If any tests fail, paste the error output back into Claude Code and ask it to fix the issue. Debugging with Claude Code follows the same conversational pattern: show it the error, let it analyze the cause, apply the fix.

Step 4: Request a Code Review

Before you consider the project done, use the built-in review command:

/review

Then add context:

Review this API for: missing error handling, security issues in the input
validation, and any performance concerns that would matter at 1,000 requests
per minute.

Claude Code reads all your project files and returns a structured review. It will catch things like unhandled promise rejections, missing rate limiting on the create endpoint, or input fields that are not sanitized before storage.

Effective Patterns for Working with Claude Code

Be Specific About What You Already Have

VAGUE:
Fix the authentication.

SPECIFIC:
The login endpoint in routes/auth.js is returning 200 even when credentials are
wrong because the bcrypt.compare result is not being awaited. Fix the async
handling and add a proper 401 response for failed logins.

Use /init to Set Project-Wide Instructions

The CLAUDE.md file created by /init gives Claude Code standing instructions for your project. Add your coding standards, architecture decisions, and context that should apply to every task:

# Project: Task API

## Tech Stack
Node.js 20, Express 4, Jest for tests, no database (in-memory for now)

## Code Standards
- Use async/await, never raw callbacks or .then chains
- All routes must validate input with express-validator
- Error responses always include: { error: string, code: string }
- Every new endpoint needs a corresponding test

## Architecture
routes/ -> controllers/ -> services/ (keep business logic out of route handlers)

Tackle Complex Refactors in Stages

For large changes, break them into steps and confirm each one before moving to the next. "Refactor the entire codebase to use TypeScript" is better approached as: first add TypeScript config, then convert one file, then convert the rest. This gives you checkpoints where you can review and course-correct.

Before and After: Unstructured vs Claude Code Workflow

BEFORE (typical solo developer workflow):
1. Copy error message from terminal
2. Paste into Google
3. Read through Stack Overflow answers
4. Find one that seems relevant
5. Adapt it to your specific code
6. Test
7. Repeat for each new error
Average time for a non-trivial bug: 30-90 minutes

AFTER (Claude Code workflow):
1. Paste error and relevant code to Claude Code
2. Get a diagnosis with the specific cause and fix
3. Apply the fix (Claude Code can do this directly)
4. Run tests to confirm
Average time for a non-trivial bug: 5-15 minutes

Frequently Asked Questions

Does Claude Code work with any programming language?

Yes. Claude Code reads and writes code in Python, JavaScript, TypeScript, Go, Rust, Ruby, Java, C++, and most other mainstream languages. It understands framework conventions for React, Django, Rails, Spring, and others. The quality of suggestions is generally highest for Python and JavaScript because they have the most training data representation, but all common languages are well-supported.

How does it handle large codebases?

Claude Code reads files in your project directory and uses them as context. For very large projects, it focuses on the files most relevant to your current task. You can use /add to bring in specific files that are not being picked up automatically. The /compact command helps manage context when a session has been running long and the conversation history is large.

Is my code sent to Anthropic's servers?

Yes. The files Claude Code reads and the tasks you describe are sent to Anthropic's API to generate responses. If you are working with proprietary code or sensitive data, review Anthropic's data usage policies before using it on those projects. Many enterprises have separate API agreements that address data retention and privacy requirements.

What is the CLAUDE.md file and do I need it?

CLAUDE.md is a markdown file you create in your project root using /init. It gives Claude Code standing instructions about your project: the tech stack, coding standards, architecture decisions, and anything else it should know in every session. You do not need it for simple one-off tasks, but it is very valuable for ongoing projects because it eliminates the need to re-explain project context at the start of every session.

Can Claude Code run tests and commands on my machine?

Yes, with your permission. Claude Code can run shell commands, including test suites, build scripts, and linters. It will show you the command it wants to run and ask for confirmation before executing. You can set up allowed commands in your configuration so that common operations like npm test or git status run without requiring confirmation each time.

Debugging with Claude Code

Debugging is one of the strongest use cases for Claude Code because it excels at reading multiple files simultaneously to understand what is actually happening versus what you expected. When you hit an error, the effective approach is to give Claude Code both the error output and the relevant code together:

Here is the error I am seeing:
TypeError: Cannot read properties of undefined (reading 'id')
  at createTask (routes/tasks.js:23:24)
  at Layer.handle [as handle_request] (express/lib/router/layer.js:95:5)

Here is the route handler in routes/tasks.js:
[paste the function]

And here is the Task model in models/task.js:
[paste the model]

What is causing this error and what is the correct fix?

This approach works far better than pasting just the error message, because the root cause is almost always in how two pieces of code interact, not in the error location itself. Claude Code traces the data flow from where the error occurs back to where the data originated, which is exactly how an experienced developer would diagnose it.

Working with an Existing Codebase

When you bring Claude Code into a project that already exists, the first step is orientation. Run /init to create a CLAUDE.md file and fill it with what you know about the project: the tech stack, the main entry points, any non-obvious conventions, and which parts of the code are most actively changing. This gives every future session a starting context so you are not explaining the same things repeatedly.

For large codebases, use /add to bring in the specific files relevant to your current task. If you are working on the authentication system, add the auth routes, middleware, and model files. Claude Code will focus its analysis on those files rather than trying to understand the entire project at once. This produces faster, more targeted suggestions than asking it to understand everything at once.

A practical first task when bringing Claude Code into an existing project: ask it to explain a confusing part of the codebase. "Read auth.js and explain what the token refresh logic is doing and why." This both tests its understanding and often surfaces documentation opportunities or potential bugs you had not noticed.