Claude Code First Project Tutorial

You installed Claude Code. Now what? This tutorial walks you through building a real, working project from scratch, so you understand how Claude Code actually operates rather than just what the documentation says it does.

By the end, you will have a running Express REST API with two endpoints, a proper CLAUDE.md file, and a clean git history.

The whole process takes about 30 minutes.

What You Will Build

The project is a simple Node.js REST API with two endpoints: /health for uptime checks and /users that returns mock data. It is deliberately small.

The goal is to learn the Claude Code workflow, not to build a production system.

You will see how Claude Code reads your project context, proposes changes, and executes them. You will also see where it needs guidance and how to give it.

Prerequisites

Before you start, confirm you have three things in place:

• Claude Code installed globally: npm install -g @anthropic-ai/claude-code
• Node.js 18 or higher on your machine
• A terminal open and git available

If you run claude --version and see a version number, you are ready.

Step 1: Create the Project Directory

Start by creating a clean directory and initializing a git repository. Claude Code works best when it has a git repo to reference, because it tracks changes as diffs.

mkdir phos-api
cd phos-api
git init

Now create a minimal package.json. You do not need to fill in every field. Claude Code will help with the rest.

npm init -y

This gives you a starting point. Claude Code can read package.json to understand your project’s dependencies and scripts.

Run git add package.json && git commit -m "Initial package.json" to give Claude Code a baseline commit to compare against.

A clean first commit is not just good hygiene. It means Claude Code can show you exactly what it changed, which is how you stay in control.

Step 2: Write Your CLAUDE.md

CLAUDE.md is the file Claude Code reads at the start of every session. It is how you tell Claude Code what your project is, what conventions you use, and what it should never touch.

Create a file called CLAUDE.md in the project root with this content:

# phos-api

A simple REST API built with Node.js and Express.

## Stack
- Node.js 18+
- Express 4.x
- No database yet (mock data only)

## Conventions
- Use CommonJS (require, not import)
- All routes go in /routes directory
- Entry point is server.js
- Use port 3000

## Testing
- None yet, will add Jest later

## Do Not Touch
- package.json scripts section without asking first

This takes 5 minutes to write and saves you from constantly re-explaining your stack to Claude Code. Every session starts with Claude Code reading this file.

Step 3: Start Claude Code

In your project directory, run:

claude

Claude Code starts, reads your CLAUDE.md, and shows you a prompt. You will see it acknowledge the project context. From here, everything happens through natural language prompts.

Step 4: Your First Prompt

Type this prompt:

Create a basic Express server with a /health endpoint that returns { status: "ok", timestamp: <current ISO timestamp> }. Entry point should be server.js.

Claude Code will read your CLAUDE.md (it knows to use CommonJS, Express, port 3000, and server.js as the entry point) and propose a plan. You will see it list the files it intends to create or modify before it does anything.

Notice that it installs Express as a dependency and creates server.js with the correct structure. If it proposes something you did not expect, this is the moment to stop it.

The first prompt sets the pattern. Be specific about file names, return shapes, and conventions. Claude Code follows what you say, not what you meant.

Step 5: Review the Plan

Before Claude Code executes, use plan mode to see exactly what it will do. Type /plan or run claude --plan at startup.

You will see something like:

• Install express package
• Create server.js with Express app, /health route, and app.listen(3000)
• Update package.json with a start script

Review each item. Ask yourself: does this match what I asked for? Does it respect my CLAUDE.md constraints? If yes, approve. If not, clarify before proceeding.

A common stumbling point here is that Claude Code may propose creating a directory structure you did not ask for yet (like a /routes folder). That is fine. Your CLAUDE.md mentioned it, so Claude Code is being proactive.

You can accept or tell it to keep things in server.js for now.

Step 6: Accept and Run

Approve the plan and let Claude Code execute. It will:

1. Run npm install express
2. Create server.js
3. Update package.json

Watch the output. Claude Code shows you each file as it writes it.

If anything looks wrong, you can interrupt and correct.

Once it finishes, test the server:

node server.js

In a second terminal:

curl http://localhost:3000/health

You should see {"status":"ok","timestamp":"2026-06-16T..."}. If you do, the first step worked.

Step 7: Commit the Output

Never let Claude Code make more changes before committing what it already did. This gives you a rollback point and keeps your git history meaningful.

git add -A && git commit -m "Initial Express server with /health endpoint"

Now if the next change breaks something, you can git diff HEAD~1 to see exactly what changed.

You can also run git checkout HEAD~1 -- server.js to revert a single file.

Treat each Claude Code task as one commit. Small, frequent commits are your safety net when working with AI-generated code.

Step 8: Iterate

Now add the second endpoint. Type:

Add a /users endpoint to server.js that returns a JSON array of 3 mock users. Each user should have id (number), name (string), and email (string) fields.

Claude Code will modify server.js and add the route. Review the plan again before accepting.

The common stumbling point here is that Claude Code may refactor the existing /health route as part of adding the new one. That is usually fine, but check that the health endpoint still works after the change.

Test the new endpoint:

curl http://localhost:3000/users

You should see an array of 3 user objects. Commit:

git add -A && git commit -m "Add /users endpoint with mock data"

Common Stumbling Points

Claude Code ignores CLAUDE.md conventions. This usually means the CLAUDE.md instruction was too vague. Use CommonJS is clear. Follow best practices is not. Rewrite vague instructions as specific rules.

Claude Code modifies files you did not ask about. It is trying to be helpful, but this can be a problem. Use the “Do Not Touch” section of CLAUDE.md to protect files. You can also say in your prompt: Only modify server.js.

The plan shows more changes than expected. This often happens when Claude Code infers that related files also need updating. Read the plan carefully. If the extra changes look correct, approve them. If not, ask Claude Code to scope down.

npm install runs but fails. Claude Code may try to install a package version that conflicts with your Node.js version. Check the error output and tell Claude Code which version to use: Install express@4.18.2 specifically.

Tests fail after Claude Code makes changes. You do not have tests in this tutorial, but when you add them: always run tests before committing, not after. Claude Code can run your test suite if you include the test command in CLAUDE.md.

What Comes Next

You now have a working REST API and a repeatable workflow: write CLAUDE.md, start Claude Code, prompt specifically, review the plan, accept, test, commit. Every Claude Code session follows this same loop.

From here, you can add database connections (tell Claude Code your DB type in CLAUDE.md), add authentication middleware, or write tests. The workflow is identical regardless of what you build.

If you want Claude Code to handle more complex tasks reliably, the next step is learning how to write prompts that give it enough context to succeed without over-specifying every detail.

The Claude Code Course covers these prompt-writing techniques in depth.

Start Building with Phos

Phos is a CCA-F certified Claude partner with 400+ AI engagements. If your team is adopting Claude Code and wants to move faster without breaking things, we can help you build the right foundations from the start.

Talk to the Phos team to learn how we help engineering teams get productive with Claude Code.

FAQ

How long does a typical Claude Code session last before I need to use /compact?

For a project this size, you can work for 30 to 60 minutes before context becomes an issue. When responses start feeling less precise or Claude Code seems to forget earlier instructions, run /compact. It compresses the session history into a summary without losing the key context.

Can I use Claude Code on an existing project, not just new ones?

Yes. Run claude in the root of any existing repository. The most important step is running /init first so Claude Code generates a CLAUDE.md based on what it finds in your codebase.

Review and edit that file before your first real prompt.

What happens if I accept a change and it breaks something?

This is exactly why you commit before each new task. Run git diff HEAD~1 to see what changed, and git revert HEAD or manually restore the file.

Claude Code does not have an undo button. Git does.

Do I need to be in the project directory to run Claude Code?

Yes. Run claude from the project root so it can read your CLAUDE.md and access all your files.

If you run it from a subdirectory, it will only have context for that subdirectory and may miss important project-level files.