Claude Code Tutorial: Build Your First Project with AI in 30 Minutes

You have heard about AI coding tools. Maybe you have tried chatting with an AI about code in a browser window. But Claude Code is something different. It is an AI coding agent that lives in your terminal, reads and writes files on your machine, runs commands, and builds real software alongside you. It does not just suggest code in a chat window and leave you to copy-paste. It actually creates files, edits them, runs your project, and fixes errors, all while you guide it with plain English.

This tutorial will take you from zero to a working web application in about 30 minutes. You do not need prior programming experience, though a basic familiarity with using a terminal will help. By the end, you will have Claude Code installed, configured, and you will have used it to build a fully functional project.

What You Need Before Starting

Before we begin, make sure you have the following:

If you are not sure whether Node.js is installed, open your terminal and type:

node --version

If you see a version number like v20.11.0 or higher, you are good to go. If not, head to nodejs.org and install the latest LTS version.

Step 1: Install Claude Code

Claude Code is distributed as an npm package, which makes installation straightforward. Open your terminal and run:

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

The -g flag installs it globally, meaning you can use the claude command from any directory on your system. The installation typically takes less than a minute.

Once it is installed, verify it works:

claude --version

You should see the version number printed to your terminal. If you get a "command not found" error, make sure your npm global bin directory is in your system PATH.

Step 2: Configure Your API Key

Claude Code needs to authenticate with Anthropic's API. There are two ways to set this up.

Option A: Interactive login. Simply run claude in your terminal, and it will walk you through the authentication process if you have not set it up before. This is the easiest approach for most users.

Option B: Environment variable. If you have an API key, you can set it as an environment variable:

export ANTHROPIC_API_KEY=sk-ant-your-key-here

To make this permanent, add the line to your shell profile file (.bashrc, .zshrc, or equivalent).

With authentication configured, run claude in any directory to start an interactive session:

claude

You should see a prompt where you can start typing messages to Claude. That is it for setup. You are ready to build.

Step 3: Create Your Project

Let us build a personal bookmark manager, a web application that lets you save, categorize, and search your favorite links. It is simple enough to build in 30 minutes but useful enough to actually be worth keeping.

Start by creating a project directory and launching Claude Code inside it:

mkdir bookmark-manager
cd bookmark-manager
claude

Now you are in an interactive Claude Code session inside your project directory. Type your first prompt:

Create a bookmark manager web application with the following features:
- A clean, modern single-page interface
- Ability to add bookmarks with a URL, title, and category
- Categories displayed as filterable tags
- A search bar that filters bookmarks by title or URL
- Bookmarks stored in the browser's localStorage so they persist
- Built with vanilla HTML, CSS, and JavaScript (no frameworks)
- Responsive design that works on mobile and desktop

Press Enter, and watch Claude Code work. It will create the project files, write the HTML structure, implement the CSS styling, and build out the JavaScript logic. You will see it creating files in real time, and it will tell you what it is doing at each step.

This is the core vibe coding workflow: you describe what you want, and the AI builds it. But the magic is in what comes next, the iteration.

Step 4: Run and Review Your Project

Once Claude Code finishes generating the files, open the HTML file in your browser to see your application. You can ask Claude to help with this:

What files did you create? How do I open this in my browser?

For a simple static site like this, you can open the index.html file directly in your browser, or you can ask Claude to start a local development server:

Start a simple local server so I can view this in my browser

Claude Code might create a simple server script or suggest using Python's built-in server:

python3 -m http.server 8000

Open http://localhost:8000 in your browser and you should see your bookmark manager. Take a moment to try it out. Add a few bookmarks, test the search, try the category filters.

Step 5: Iterate and Improve

Here is where Claude Code really shines. You have a working application, but you probably want to improve it. This is the iterative conversation that makes vibe coding so powerful. Try prompts like these:

Improving the design:

The design is functional but plain. Make it more visually appealing:
- Add a gradient background
- Use card-style layouts for each bookmark with subtle shadows
- Add smooth animations when bookmarks are added or removed
- Use a modern color scheme with a dark mode toggle

Adding features:

Add the ability to edit existing bookmarks. When I click on a bookmark,
it should open an edit form pre-filled with the current values. Include
a delete confirmation dialog too.

Fixing issues:

If you notice a bug, just describe it:

When I add a bookmark without a category, the app shows "undefined"
as the category tag. It should default to "Uncategorized" instead.

Adding data management:

Add an export button that downloads all bookmarks as a JSON file,
and an import button that lets me upload a JSON file to restore
bookmarks. Include error handling for invalid files.

Each time you send a prompt, Claude Code will read the existing files, understand the current state of your project, and make the appropriate changes. It does not start from scratch each time. It builds on what is already there.

Tips for Effective Prompting

The quality of your results depends heavily on how you communicate with Claude Code. Here are the most important prompting strategies:

Be specific about what you want. Instead of "make it look better," say "add a card layout with rounded corners, subtle box shadows, and 16px padding between cards." Specificity reduces back-and-forth and gets you closer to your vision on the first try.

Describe the what, not the how. Unless you have a strong opinion about implementation, focus on describing the desired outcome. "Add a search feature that filters bookmarks as the user types" is better than "create an event listener on the input field that filters the array on each keyup event." Let Claude choose the implementation approach.

Provide context when it matters. If you have preferences about code style, architecture, or libraries, state them up front. "I prefer using CSS Grid over Flexbox for layouts" or "keep all JavaScript in a single file for simplicity" helps Claude make choices aligned with your preferences.

Iterate in small steps. Rather than asking for ten features at once, add them one or two at a time. This makes it easier to review changes, catch issues early, and maintain a working application at each step.

Share error messages directly. When something breaks, paste the exact error message. Claude Code is exceptionally good at diagnosing errors when given the precise text. "It is broken" is far less useful than the actual error output from your browser console or terminal.

Ask Claude to explain. If you are learning, do not hesitate to ask "explain what this code does" or "why did you choose this approach." Claude Code is an excellent teacher when you engage it as one.

Common Mistakes to Avoid

New Claude Code users often fall into a few predictable traps. Knowing about them in advance will save you time and frustration.

Mistake 1: Accepting everything without reviewing. Claude Code is powerful, but it is not infallible. Always review the changes it makes, especially for anything security-related, data-handling, or user-facing. A quick scan of the code, or better yet, testing the application after each change, catches most issues early.

Mistake 2: Writing prompts that are too vague. "Build me a website" will produce something, but it probably will not match your vision. The more detail you provide about layout, functionality, and behavior, the closer the result will be to what you actually want.

Mistake 3: Not using version control. Initialize a git repository before you start working with Claude Code. This gives you the ability to roll back changes if something goes wrong. Run git init in your project directory and commit after each major milestone:

git init
git add .
git commit -m "Initial bookmark manager implementation"

Then after each set of changes you are happy with, commit again. This safety net is invaluable.

Mistake 4: Ignoring the terminal output. Claude Code shows you what it is doing as it works. Pay attention to the files it creates and modifies, the commands it runs, and any warnings or notes it provides. This output is your window into the AI's decision-making process.

Mistake 5: Fighting the tool instead of guiding it. If Claude Code takes an approach you do not like, do not try to micromanage every line. Instead, explain why you prefer a different approach and let it refactor. "I'd rather use a class-based structure for the JavaScript. Can you refactor the code to use a BookmarkManager class?" is more effective than line-by-line corrections.

Going Beyond the Basics

Once you are comfortable with the basic workflow, Claude Code can help you with significantly more advanced tasks:

Adding a backend. You can ask Claude to create a Node.js or Python backend with a real database, turning your client-side application into a full-stack project:

Convert this from localStorage to use a Node.js backend with Express
and SQLite. Create a REST API for bookmarks and update the frontend
to call the API instead of using localStorage.

Writing tests. Claude Code can generate comprehensive test suites for your code:

Write unit tests for the bookmark manager using Jest. Cover the add,
edit, delete, search, and filter functionality.

Deploying your project. You can ask for help with deployment configuration:

Create a Dockerfile for this application and a docker-compose.yml
that sets up both the frontend and backend.

Using MCP servers. Claude Code supports the Model Context Protocol, which lets it connect to external tools and data sources. This means it can interact with databases, APIs, and services directly while building your project.

Understanding What Claude Code Created

Let us take a step back and understand the project structure Claude Code likely generated for you. A typical output might look like this:

bookmark-manager/
├── index.html          # Main HTML structure
├── styles.css          # All styling and responsive design
├── app.js              # Application logic and event handling
└── README.md           # Project documentation

The HTML file contains the structure of your page: the header, the add-bookmark form, the search bar, the category filters, and the bookmark list container. Claude Code typically writes semantic, accessible HTML.

The CSS file handles all visual styling. It usually includes responsive breakpoints, a thoughtful color scheme, and modern layout techniques like CSS Grid or Flexbox.

The JavaScript file contains the application logic: adding and removing bookmarks, filtering by category, searching by text, and persisting data to localStorage. Claude Code tends to write well-organized, readable JavaScript with clear function names and comments.

This clean separation of concerns is a good architectural practice, and it is worth noting that Claude Code generally follows best practices by default. When it does not, you can ask it to refactor.

What You Built and What Comes Next

In roughly 30 minutes, you went from an empty directory to a functional, styled, interactive web application. You did this by having a conversation with an AI that understood your intent and turned it into working code. That is the power of vibe coding with Claude Code.

But this tutorial is just the beginning. The same workflow scales to much larger and more complex projects. Developers use Claude Code to build full-stack applications, automate DevOps pipelines, create data processing systems, and refactor legacy codebases. The principles are the same: describe clearly, review carefully, iterate relentlessly.

To dive deeper into AI-assisted development and learn advanced techniques for working with Claude Code and other AI tools, read our free Vibe Coding and Working with AI Tools Effectively textbooks.