Your first Claude Code project: from empty folder to shipped

Pick a project small enough to finish

Your first Claude Code project should be small enough to ship in a single sitting. Not a clone of a product you admire. Not a full SaaS. Pick something you can describe in one sentence and finish in a few hours. A landing page for a side project. A CLI that renames files based on a pattern. A small Next.js app that displays your reading list. The goal of the first project is not the project. It is learning how to drive the tool with confidence, so that the second project is twice as fast.

The smallest viable first project is one with a clear input, a clear output, and no auth. Auth multiplies the surface area of any project by three and rarely teaches you anything new about the tool. Save it for project two when you understand the rhythm. The same goes for payments, complex onboarding flows, and anything that needs a third party webhook. Strip those out of your first idea and what is left is usually the actual interesting part.

Create an empty folder and cd into it. Run git init so you have a clean history from the first commit. Then run claude. You are about to have a conversation with a teammate who has read every relevant docs page but has never seen your idea. The first thing you owe that teammate is a short, honest brief.

Write the brief before you write the prompt

Before you type anything to Claude Code, write the brief in your head or in a scratch file. What does the thing do. What stack do you want. What is explicitly out of scope. Two sentences each is enough. The brief is the difference between a session that ships and a session that wanders. When you paste this into the first message, Claude Code uses it to make a thousand small decisions for you, from folder structure to library choice. If you skip the brief, those decisions still get made, but you do not get to make them.

• One sentence on what the project is, in plain language, with no jargon
• The stack you want, named explicitly, like Next.js 14 with the app router and Tailwind
• What is out of scope so Claude Code does not over engineer the first version
• Where the project will deploy, since that changes structural choices early
• Any constraint that matters, like no external services, no auth yet, or a specific Node version

Let Claude Code scaffold the project

Hand the brief over and ask Claude Code to scaffold the project. It will propose a folder layout, run the right init command, and write the first files. Read the proposal before you approve commands. Not because you do not trust it, but because reading the proposal is how you learn the patterns it tends to use. After a few projects you will know exactly what to expect and which parts to nudge. Approve the install commands one at a time on the first project. Speed up later.

Iterate one feature at a time

Once the scaffold exists, do not ask for the entire feature set in one message. Ask for one slice. A page, a route, a single component, a single function. Let Claude Code write it, look at the diff, run the dev server, and confirm it behaves. Then commit. That commit is your save point. If the next slice goes sideways, you have a clean place to roll back to. Working in slices feels slower for the first hour and is twice as fast by the end of the session.

Run the dev server early and keep it open

Open a second terminal tab and run npm run dev or whatever your stack uses. Keep it open the entire session. Every time Claude Code finishes a change, check the browser. Not at the end, not every ten minutes. Every change. The faster you close the loop between code and what you see, the less drift accumulates. When you only check at the end, a small wrong assumption from twenty minutes ago turns into an hour of unwinding.

When to push back and when to trust

Claude Code will sometimes propose a solution you did not expect. Sometimes it is right and your instinct is wrong. Sometimes it is wrong and your instinct is right. The way to tell is to ask. Type why did you pick that approach, or what are the tradeoffs against the version I had in mind. The answer usually tells you everything. If the reasoning lines up with your goals, accept it. If it does not, say so plainly and ask for the alternative. This is the conversation that makes the tool feel like a teammate rather than a code generator.

Recovering from a wrong turn

Every first session has at least one wrong turn. A misread requirement, a library that does not behave, a typo that cascades. The recovery move is almost never to keep going. It is to roll back to your last good commit, restate the goal, and try again with a tighter brief. git reset is your friend. So is git stash if you want to keep the experiment around without keeping it in the working tree. Claude Code will happily start fresh from the last commit and try a different angle.

1. 1Run git status to see what is dirty and what is clean
2. 2Decide whether to keep the partial work in a stash or throw it out
3. 3Run git reset --hard to the last good commit if you are starting over on that slice
4. 4Restate the goal to Claude Code in one sentence and try again with the new context
5. 5Commit as soon as the smaller slice works so your next wrong turn has a closer save point

Tests as you go, not at the end

Ask Claude Code to write tests for the slice you just finished, then run them. Even a single happy path test per feature changes the energy of the session. You stop second guessing whether something still works, because the test tells you. On a first project you do not need full coverage. You need enough tests that the next change does not silently break the last one. Members at claudecodeclub.ai trade test patterns by stack, and the value of a copy paste test setup on day one is hard to overstate.

Pick a test runner that matches your stack and stick with it for the whole project. Vitest for Vite based projects, Jest for older React work, Playwright for end to end runs against the browser. Switching test runners mid project is a tax you do not need to pay. Claude Code can usually write a working test setup in one round, so the cost of picking on day one is essentially nothing. Run the tests after every slice, not just before you commit. The faster you see red, the cheaper red is to fix.

Shipping the first cut

When the slice list is done, ship. Push to a repo, deploy to Vercel or Fly or wherever fits the project, and put the link in front of one person who is not you. The first project is a feedback loop, not a portfolio piece. The deploy step is covered in detail in our /guides/deploying-to-vercel-with-claude-code guide. Get the link out before you polish, because polish is endless and feedback is the only thing that tells you what to polish.

Naming things in your first project

Naming is hard, but on a first project you do not need it to be perfect. You need it to be consistent. Pick one casing convention for files, one for folders, one for component names, and ask Claude Code to follow them. Mention the conventions in your first message so the scaffold lands the right way. Inconsistent naming compounds quickly in a codebase, and the fix later is more painful than the discipline now. The point is not that camelCase is better than kebab-case. The point is that mixing the two in one project is the actual problem.

Managing scope inside a single session

The biggest reason first projects do not finish is scope creep inside a single session. You start out building a landing page and four hours later you are designing a CMS. The agent is happy to follow your wandering, which is exactly the problem. Keep a small text file open next to your terminal with three columns. Doing now, doing next, parked. Every time you have an idea mid session that is not the slice in front of you, write it in parked and keep going. The discipline is in the writing, not in the not having ideas.

When the current slice is done, look at the parked column and pick the next thing. Sometimes the parked idea is the actual next move. Sometimes it has aged poorly in the half hour since you wrote it down. Either is useful information. The list keeps your session productive without forcing you to be ruthless in the moment, which is the right balance for first projects where you are still calibrating what fits in a session.

Asking for explanations as you go

Some part of your first project will involve a library or pattern you have not used before. When Claude Code reaches for it, ask why. Not as a challenge, as a request for a short explanation. The reply teaches you the pattern in the context of your project, which is the form of learning that sticks. By the end of the project you will have absorbed three or four real patterns that you can apply to the next project without prompting for them.

The trap is asking for explanations in the abstract. Tell me about React Server Components produces a wall of generic text. Why did you pick a server component here instead of a client one produces a paragraph that ties directly to your code. The specific question gets the specific answer. The specific answer is what you remember a week later when you face the same choice in a different file.

Avoiding the rewrite spiral

There is a temptation on a first project to keep asking for the same component to be written again because it is almost right. Three or four passes in, the code is shaped like committee work and nothing fits cleanly anymore. Catch yourself early. If you are on the third pass at the same file in one session, stop and either accept the second pass or write the change by hand. The cost of accepting an imperfect version and moving on is much lower than the cost of looping. You can always come back to it on the next slice with fresh eyes.

What changes on project two

By the end of the first project you will have a feel for the rhythm. Brief, scaffold, slice, diff, run, commit, repeat. Project two is where speed shows up. You will skip steps that felt necessary on day one because you trust the parts of the workflow that already paid off. You will also know which of your own habits to keep and which to drop, which is the only learning that actually compounds. The members at claudecodeclub.ai who shipped fastest were not the ones with the most experience going in. They were the ones who treated their first project as deliberate practice and wrote down what they learned at the end of each session.