Your First Real Project with Claude Code

Your First Real Project with Claude Code

Part of the series: Claude Code: From Zero to Swarm

Before we start

You have been through the basics. You can open a terminal, navigate folders, and you have Claude Code installed. You have had a conversation with it. You know it can read files and answer questions.

But so far, everything has been abstract. You typed some commands, got some responses, maybe poked around your file system. That is useful practice. It is not a project.

Today you are going to do something real. You are going to create a small website, open it with Claude Code, understand it, change it, and build new features — all through conversation. By the end, you will have a working website you built by talking to an AI. No code written by hand.

Let's start by giving ourselves something to work with. Open your terminal and navigate to your Desktop:

cd ~/Desktop

Now create a folder for your project:

mkdir my-website

Move into it:

cd my-website

Now start Claude Code:

claude

Once Claude is running, type this:

Create a simple website with three files: index.html (a home page with a heading, a short welcome paragraph, and some placeholder content), styles.css (with clean, modern styling), and about.html (an about page with a heading and a paragraph). Make both HTML files link to the same stylesheet. Keep it simple but make it look decent.

Claude will think for a moment and then create all three files. You will see it write each one, showing you exactly what it is putting in them. When it finishes, you will have a working website sitting in your my-website folder.

Let's see it. Open the home page in your browser. You can do this from the terminal:

On Mac:

open index.html

On Windows:

start index.html

Your browser opens. There is your website. A heading, some text, basic styling. Nothing fancy, but it is real. It exists. You made it by asking for it.

This is your project now. Let's explore it.

Opening an existing project

In the real world, you will not always be starting from scratch. More often, you will be opening something that already exists — a project a colleague shared with you, something you downloaded, or something you built last week and have already half-forgotten.

Let's simulate that. Close Claude Code if it is still running (press Ctrl + C or type /exit). Now pretend you are coming back to this project fresh. Navigate to the folder:

cd ~/Desktop/my-website

Start Claude Code:

claude

The first thing you want to know is: what is this project? What is in here? Type:

Give me an overview of this project.

Watch what happens. Claude reads every file in your folder. It does not just list them like ls would. It opens each one, reads the contents, and then gives you a summary that sounds something like this:

This is a simple static website with three files:

- index.html: The home page with a welcome heading, introductory 
  paragraph, and placeholder content. It links to styles.css for 
  styling.
- about.html: An about page with a heading and description paragraph. 
  It also links to styles.css.
- styles.css: A shared stylesheet that provides modern, clean styling 
  for both pages, including typography, layout, and color scheme.

Both HTML pages share the same stylesheet, keeping the design 
consistent across the site.

This is the magic moment. Claude did not just tell you what files exist. It told you what they do and how they relate to each other. The two HTML files share one stylesheet. The home page has more content than the about page. The styling is centralized.

You got a full project briefing in three seconds by asking one question.

Think about the last time someone sent you a folder full of files and said "here's the project." You probably spent twenty minutes clicking through things trying to figure out what connected to what. Claude does that in one pass.

Asking Claude to explain code

Now that you know the shape of the project, let's go deeper. You do not need to read the code yourself. You can ask about it.

Type:

What does index.html do? Walk me through it.

Claude will break it down piece by piece. It will explain the structure — the <head> section that loads the stylesheet, the <body> where the visible content lives, the heading, the paragraph, the link to the about page. It will reference specific lines and explain what each part does in plain language.

Try another one:

Explain the CSS in styles.css. What design decisions were made?

Claude will walk through the stylesheet and explain the choices. The font family, the colors, the spacing, the layout approach. It will tell you why certain properties are set, not just what they are. You might see something like: "The body has a max-width of 800px and is centered with margin: auto, which keeps the content readable on wide screens."

Now try something more specific:

Why is the about page styled differently from the home page?

If the pages look slightly different, Claude will explain exactly which CSS rules apply to each and why. If they actually look the same, Claude will tell you that too — and point out that they share the same stylesheet so the styling is intentionally consistent.

This is what it feels like to have a pair programmer who never judges your questions. You can ask "what does this do?" a hundred times and never get a sigh or an eye roll. There is no such thing as a stupid question when you are talking to Claude.

This ability is not just useful for code you are learning. It is powerful for code you did not write. A teammate sends you a project, a freelancer hands off some files, or you open something you built three months ago and cannot remember why you did half of it. Claude reads it all and explains it back to you.

Making your first change

Understanding is good. Changing things is better. Let's make something happen.

Type:

Change the main heading color to dark blue. Use the color #1a365d.

Claude reads the relevant files, figures out which CSS rule controls the heading color, and proposes a change. You will see something like a diff — a before-and-after view showing exactly what will change:

/* Before */
h1 {
  color: #333333;
}

/* After */
h1 {
  color: #1a365d;
}

Then Claude asks for permission. This is important. Claude does not silently change your files. It shows you what it wants to do and waits for you to approve. You will see something like:

Apply this change? (Y/n)

Press Y.

Claude makes the change and confirms:

Updated styles.css — changed h1 color from #333333 to #1a365d.

Now go back to your browser and refresh the page. The heading is dark blue. You said what you wanted in plain English, Claude translated that into the right CSS change, you approved it, and it is done.

This is the feedback loop you are going to use over and over:

1. See something you want to change
2. Describe it in words
3. Claude proposes the edit
4. You approve
5. Refresh and see the result

No googling "how to change font color in CSS." No hunting through files to find the right line. No syntax errors because you forgot a semicolon. You describe the outcome you want, and Claude handles the mechanics.

Creating something new

Changing existing things is satisfying. Creating new things is where it gets exciting.

Type:

Add a contact form to the bottom of the home page. Include fields for name, email, and a message, with a submit button.

Watch what Claude does. It does not just edit one file. It modifies index.html to add the form HTML, and it updates styles.css to style the form so it matches the rest of the site. Two files, changed together, in one move.

After you approve the changes and refresh your browser, you will see a clean contact form sitting at the bottom of your home page, styled consistently with everything else.

But it is not exactly how you want it. That is fine. This is where the real workflow starts. You iterate.

Type:

Make the form wider — it should take up the full width of the content area.

Claude adjusts the CSS. Approve, refresh.

Add a phone number field between the email and message fields.

Claude adds the new input to the HTML and makes sure it matches the styling of the other fields. Approve, refresh.

Make the submit button green with white text.

Claude updates the button styles. Approve, refresh.

Add more padding around the entire form so it doesn't feel so cramped.

Claude adds spacing. Approve, refresh.

Four changes, four sentences, maybe two minutes of total work. Each time, Claude did the right thing in the right file. You never opened an HTML file in an editor. You never looked up a CSS property. You described what you wanted, and it happened.

This is how real development works. Nobody sits down, writes a fifty-page specification, and then builds the whole thing in one pass. You build something, look at it, adjust it, look again, adjust again. The difference is that with Claude Code, the adjust step takes seconds instead of minutes. The feedback loop is so fast that building things starts to feel like a conversation instead of a construction project.

Working with multiple files

So far, you have seen Claude edit one file or two files at a time. But one of its most useful abilities is understanding how files in your project relate to each other.

Try this:

Which files reference styles.css?

Claude will scan every file in your project and come back with a precise answer: both index.html and about.html link to styles.css in their <head> sections. It tells you not just the file names, but where in those files the reference appears.

This is useful when projects get bigger. If you have ten HTML pages and you want to know which ones use a particular stylesheet or script, Claude can tell you in a second. No manual searching required.

Now try something that requires cross-file coordination:

Add a navigation bar that appears on both pages. It should have links to Home and About, and it should be styled with a dark background and white text.

This is interesting. Claude needs to:

1. Add the same navigation HTML to index.html
2. Add the same navigation HTML to about.html
3. Add navigation styles to styles.css
4. Make sure the links point to the right files

You will see Claude edit all three files in one go. It adds a <nav> section to both HTML pages with the correct links, and it adds the styling rules to make the navigation bar look the way you described. The nav bar in index.html links to about.html, and the one in about.html links back to index.html.

Approve the changes, refresh both pages in your browser, and you will see the same navigation bar at the top of each page. Click the links and they take you back and forth.

Claude kept track of the consistency so you did not have to. It knew that both pages needed the same HTML. It knew the CSS needed to be in the shared stylesheet. It made sure the links were correct relative to each file. You just said what you wanted and Claude coordinated the details across files.

As projects grow from three files to thirty or three hundred, this ability to maintain consistency across a codebase becomes the difference between a project that holds together and one that slowly falls apart.

Tips for better results

You have seen how the basic workflow goes: describe, approve, refresh, repeat. Here are some things that make it work even better.

Be specific. "Change the header color to #1a365d" gives Claude a clear target. "Make it look better" forces Claude to guess what you mean by "better." The more precise your request, the more likely the first result is what you wanted. You do not need to know the technical terms — "make the text bigger" is specific enough. "Improve the design" is not.

Give context. If you tell Claude "this is a portfolio website for a photographer," it changes how Claude approaches every decision. Font choices, layout, color palette — all of it shifts based on what the site is for. You can say this once at the start of a session and Claude remembers it for the entire conversation.

Iterate instead of specifying everything upfront. Start broad: "add a contact form." Look at what Claude creates. Then refine: "make it match the rest of the styling," "move the button to the right," "make the fields taller." Three quick iterations gets you closer to what you want than one long, detailed specification ever would.

Course-correct freely. If Claude goes in a direction you did not want, just say so. "Actually, I meant the sidebar should be on the left, not the right." Claude does not take it personally. It adjusts immediately. You are not locked into any direction. Every conversation turn is a chance to steer.

One thing at a time. "Add a navigation bar" gets better results than "add a navigation bar, change the footer, update the colors, and reorganize the layout." When you ask for four things at once, there is more room for misunderstanding. Focused requests get focused results. You can always ask for the next thing in your next message.

What you just learned

Let's take a step back and look at what you actually did today.

You created a project from nothing — three files, a working website — by describing what you wanted. You opened that project and got an instant overview, understanding the structure without reading a single line of code yourself. You asked questions and got explanations that referenced specific files and specific lines. You made a targeted change — one color, one line of CSS — and saw it in your browser seconds later. You created an entirely new feature, a contact form, and refined it through quick iterations. You watched Claude coordinate changes across multiple files, keeping everything consistent.

The workflow you used today is the same workflow that professionals use:

Explain — ask Claude to help you understand what exists.
Change — describe what you want different and approve the edit.
Create — describe something new and let Claude build it.
Iterate — refine through quick, focused follow-ups.

There is a shift happening here that is worth naming. You are not "coding" in the traditional sense. You did not memorize syntax. You did not study documentation. You did not debug an error by staring at a screen for forty-five minutes. You directed an AI that codes, and you got results.

That does not make what you did less real. The website works. The contact form is there. The navigation links to the right pages. Whether those changes were typed character by character or generated through conversation does not change the outcome. What matters is that you built something, and you understood what you were building at every step.

In the next article, we will go deeper into something that separates casual Claude Code users from effective ones: context. The more Claude knows about what you are trying to accomplish, the better it performs. There are specific techniques for giving Claude the right context, and they make a dramatic difference. That is where we are headed next.