Your first Claude Code project: a step-by-step walkthrough
By Shubhranshu, creator of claudeagents · Last reviewed
This walkthrough takes about fifteen minutes. You'll open a real project, let Claude Code explain it, give it a CLAUDE.md file, plan and make one small change, check it, and commit it. You'll also learn the two safety nets that make experimenting low-risk: Git and /rewind.
Use a project you know. It's much easier to judge Claude's work when you understand the code. If you haven't installed Claude Code yet, start with the installation guide.
Step 1: Start from a clean state#
Open your project in a terminal and check that Git has nothing uncommitted. Then every change Claude makes shows up clearly, and you can always get back to where you started. If the project isn't a Git repository yet, run git init and make a first commit.
cd your-project
git statusStep 2: Start Claude Code#
claudeA prompt appears. Type in plain English and press Enter. Shift+Enter adds a new line without sending. Type @ followed by a file name to point Claude at a specific file. If you prefer buttons and windows, the desktop app works the same way.
Step 3: Ask before you change anything#
Questions are the cheapest way to see how well Claude understands your code. Try a few of these:
- What does this project do, and how is it organized?
- Where does login happen? Walk me through the flow.
- Which files would I change to add a new setting to the profile page?
- Are there tests, and how do I run them?
If an answer is wrong, correct it. Claude uses your corrections for the rest of the session.
Step 4: Create a CLAUDE.md#
Run /init. Claude reads the project and writes a CLAUDE.md file with how to build, test and run it, plus the conventions it noticed. Claude Code loads this file at the start of every session, so you don't have to explain your project again.
Open the file and edit it. Keep it short and specific: the commands, the folder layout, and the rules you care about, such as "use TypeScript strict mode" or "never edit generated files". Our CLAUDE.md template shows good examples, and configuration basics explains where else settings live.
Step 5: Plan, then make one small change#
Pick something small and specific. Press Shift+Tab until the mode says Plan, then describe the change:
Add a loading state to the signup button. Show a spinner and disable
the button while the request is running. Plan it first.In Plan mode Claude reads the code and proposes an approach without editing anything. Read the plan, ask questions, then approve it. Switch back to Manual mode (Shift+Tab) so Claude shows each edit and waits for your OK. Press Esc at any time to stop and redirect it.
Step 6: Check that it works#
Don't take Claude's word for it. Ask it to prove the change works:
Run the tests and the type checker, and fix anything that fails.For anything visual, also look at it yourself in the browser. Claude can run your dev server, and in the desktop app it can open a built-in browser preview and check the page itself.
Step 7: Review the diff and commit#
Read every line that changed. Run /diff in Claude Code, or git diff in your terminal. Ask Claude to explain anything you don't understand. Type /code-review to have Claude review its own work for bugs.
When you're happy, ask Claude to "commit these changes with a clear message", or commit yourself.
git diff
git add -A
git commit -m "Add loading state to signup button"If something goes wrong: undo it#
/rewind(or Esc twice on an empty prompt) takes the conversation and Claude's file edits back to an earlier point.- Git undoes anything else.
git restore .throws away uncommitted changes, andgit logshows what you committed. - Rewind doesn't undo shell commands Claude ran, such as database migrations or deleted files. That's why Manual mode and Git matter while you're learning.
Habits that make Claude Code work well#
- Be specific. Name the file, the behavior and the result you want. Vague requests make Claude search the whole project.
- One task per session. Run
/clearwhen you move to an unrelated job. See context management. - Plan big changes first. Plan mode is cheap; undoing a wrong approach isn't.
- Give Claude a way to check itself: tests, a type checker, or the expected output.
- Keep your project in Git and commit small, working steps.
Frequently asked questions
What should my first Claude Code task be?
Start with questions about a project you know, then one small, specific change such as a UI tweak or a missing validation. Small tasks make it easy to judge Claude's work and undo it if needed.
What does /init do?
/init reads your project and creates a CLAUDE.md file with how to build, test and run it, plus conventions it noticed. Claude Code loads that file at the start of every session.
How do I undo Claude Code's changes?
Run /rewind, or press Esc twice on an empty prompt, and choose the point to go back to. For anything else, including shell commands Claude ran, use Git: git restore . discards uncommitted changes.
Should I let Claude Code edit files without asking?
Not at first. Use Manual mode so you approve each edit, and Plan mode for bigger changes. Move to Accept edits or Auto mode once you trust how Claude works in your project.