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.

Stack choice and why it matters early

The stack you choose for a first project shapes everything else in the session. Claude Code by Anthropic has seen a lot of code and performs best on widely used stacks where documentation is dense and patterns are established. Next.js with the app router, FastAPI, Express, Rails, and SvelteKit all fall in this category. Experimental frameworks and custom build tools work but require more prompting corrections and slower iteration. The first project is not the time to evaluate a new framework. It is the time to get comfortable with the tool. Pick a stack you already understand somewhat so you can tell the difference between a Claude Code mistake and a framework quirk.

Language choice follows the same logic. TypeScript over plain JavaScript if you are building frontend work - the type system gives Claude Code more to reason about and produces fewer subtle wrong-shape bugs. Python for scripts and data work where the standard library carries most of what you need. The pairing that consistently underdelivers is a novel language choice combined with a complex first project. If you want to learn a new language, pick an extremely simple project to learn it with and keep Claude Code in a teaching role rather than a building role.

The CLAUDE.md file: your permanent brief

After your first session, create a CLAUDE.md file in the project root. This is a plain markdown file that Claude Code reads at the start of every session. Put in it what the project is, what stack it uses, the conventions you have established, and any decisions that took time to make. The file is your permanent brief that means you never have to re-explain the project context. The next session starts with shared understanding instead of a cold start.

Keep CLAUDE.md short. One paragraph on what the project does, a bullet list of stack choices, a bullet list of naming and folder conventions, and a note on anything Claude Code should never do in this repo - like touching a legacy folder you are not ready to refactor. Longer files dilute the signal. A tight CLAUDE.md reads like a good README. A bloated one reads like documentation nobody updates. Write it once, keep it honest, and edit it when a decision changes.

How to phrase prompts that produce clean code

The prompts that work best with Claude Code are specific about inputs, outputs, and constraints, and leave the implementation open. Add a route that accepts a POST request with a JSON body containing an email and a name, validates both fields, and returns a 201 with the created user ID is a good prompt. Add a signup route is a weak prompt. The difference is not the length - it is the specificity of the contract. When the contract is clear, Claude Code fills in the implementation details correctly most of the time. When the contract is vague, it guesses and the guess is often close but not quite right.

Negative constraints are equally important. Tell Claude Code what you do not want. Do not use a third party auth library, keep this function under thirty lines, do not add error handling yet - we will add it in the next slice. Constraints are not limitations on what Claude Code can do. They are information about your project's standards. More information produces better output. The habit of adding two or three explicit constraints per prompt is the single biggest prompt improvement most first-time users can make.

• State the input shape, the output shape, and the side effects explicitly
• Name the file or module you want the code to land in so it does not end up somewhere unexpected
• Say which libraries to use rather than leaving the choice open if you have a preference
• Add one or two explicit constraints like no external dependencies or keep it under fifty lines
• End with what done looks like - a passing test, a visible UI element, a curl that returns 200

Handling libraries Claude Code has not seen

When you are using a library that shipped recently or a less popular one, Claude Code may have outdated API knowledge. The tell is when it imports methods that do not exist or uses a pattern from an older major version. The fix is quick: paste the relevant section of the library's current docs or README into the session and say here is the current API, use this instead. Claude Code picks up the current shape and rewrites the affected code. You do not need to explain the whole library. Just the part that matters for this slice.

A practical habit is to keep a browser tab open on the library docs for any major dependency you are using. When something looks wrong in the output, a quick scan of the docs usually confirms whether the method exists and which version it appeared in. This is not extra work - it is the same verification you would do on any code review. The difference with Claude Code is that the volume of new code per hour is higher, so the verification habit pays off more.

Environment setup inside the session

Some projects need environment variables to run locally. A database URL, an API key, a feature flag. Set these up before the first dev server run rather than after. Claude Code can draft a .env.local or .env.example file from the list of variables it used in the code it wrote. Ask it to generate the example file after the scaffold step. Fill in the real values, confirm gitignore is covering the real file, and then run the dev server. The order matters. Running the dev server against a missing env is a red herring that costs ten minutes of tracing a startup error back to a missing variable.

What to do when the session goes cold

Long sessions drift. After four hours, Claude Code may start losing context from the early decisions you made. The signs are subtle. It suggests a naming convention that contradicts the one you established in hour one. It proposes a library it previously decided against. It rewrites a function in a style that does not match the rest of the file. When you notice drift, stop and restate the ground rules. Paste the key decisions back in. Or close the session, restart it, and start with a message that summarizes where things stand before picking up the next slice.

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.

Project two is also where the monetization question starts to matter. Claude Code Club exists specifically for this transition - from builder to someone who builds things that earn. The $9 a month community at claudecodeclub.ai is 4,500+ builders who went through the same first project and are now building real tools, landing clients, and shipping products they charge for. The skills compound faster in that company than in isolation, and the library of project templates, prompt patterns, and skill files the community maintains is the shortcut that makes project two materially faster than project one.