Lesson 03: Your First Real Project

Reading about Claude Code is one thing. Using it on a real codebase is another. This lesson walks you through a complete first-project workflow: exploring code, creating project memory, planning a change, implementing it, and committing the result.

Pick a Project

Choose a small repository you are familiar with — a personal project, a side tool, or a practice repo. Avoid starting with a massive monorepo. You want something with a few hundred to a few thousand lines of code so you can verify Claude's work easily.

# Clone a project you want to work on (or use an existing one)
cd ~/projects
git clone https://github.com/your-username/your-repo.git
cd your-repo

Tip: If you do not have a project handy, create a simple one. A small Express API, a CLI tool, or a static site all work well for a first session.

Step 1: Explore the Codebase

Start Claude Code and ask it to look around:

claude

> Summarize this project. What does it do, what technologies does it use,
  and how is the code organized?

Claude will read files, check package.json or equivalent config files, and give you a structured overview. This is useful even for your own projects — Claude often spots things you have forgotten about.

Pay attention to whether Claude's summary is accurate. If it misses something important, correct it:

> You missed the database migration scripts in the db/ directory.
  Those are important — this project uses PostgreSQL.

This early correction teaches you a key principle: Claude works best when you guide it with your knowledge of the project.

Step 2: Create a CLAUDE.md File

A CLAUDE.md file gives Claude persistent context about your project. The fastest way to create one is with the /init command:

> /init

Claude will analyze your project structure, dependencies, and conventions, then generate a CLAUDE.md for you. Review the result and refine it:

> Good start, but we use tabs not spaces, and the test command
  is "npm run test:unit" not "npm test". Update those details.

Alternatively, you can be more hands-on and tell Claude exactly what to include:

> Create a CLAUDE.md file for this project. Include:
  - A one-paragraph project description
  - The tech stack and key dependencies
  - How to build and run the project
  - How to run tests
  - Code style conventions used in this project
  - Any important architecture decisions

Once you are satisfied, the CLAUDE.md file will be loaded automatically in every future session. This is one of the highest-leverage things you can do early — ten minutes spent on a good CLAUDE.md saves hours later.

Step 3: Plan an Enhancement

Before jumping into code, use Claude's planning ability. Pick a small, well-defined enhancement:

• Add input validation to a form
• Create a new API endpoint
• Add a configuration option
• Improve error handling in a specific module

Tell Claude to plan before implementing:

> I want to add rate limiting to the /api/login endpoint.
  Before writing any code, create a plan:
  - What approach should we use?
  - What files need to change?
  - What edge cases should we handle?
  - What tests should we write?

Review the plan. Push back on anything that seems wrong:

> I'd rather use an in-memory store than Redis for now.
  This is a small app and I don't want to add a dependency.
  Update the plan.

Key insight: Planning before coding leads to better results. When Claude has a clear plan, it writes more coherent code that matches your expectations. Skipping the plan often means more back-and-forth corrections later.

Step 4: Implement the Enhancement

Once the plan looks good, tell Claude to execute it:

> Go ahead and implement the rate limiting based on the plan above.
  Write the implementation and the tests.

Claude will:

1. Create or modify the relevant files
2. Write the implementation code
3. Write tests if you asked for them
4. Possibly run the tests to verify they pass

Watch the output as Claude works. You will see which files it reads, what changes it makes, and what commands it runs. If something looks off, interrupt and redirect:

> Stop — that middleware should go in src/middleware/, not in the
  route handler directly. Move it to its own file.

Step 5: Review Changes

Before committing anything, review what Claude did:

> Show me a summary of all the changes you've made.

Also check the git diff yourself:

> Run git diff and walk me through each change.

This is your quality gate. Look for:

• Correctness: Does the code do what you asked?
• Style: Does it match the rest of the codebase?
• Completeness: Are there missing edge cases or error handling?
• Unwanted changes: Did Claude modify files you did not expect?

If something needs fixing:

> The rate limit error response should return a 429 status code
  with a JSON body, not a plain text response. Fix that.

Step 6: Commit with Claude's Help

Once you are satisfied with the changes, have Claude help you commit:

> Stage and commit these changes with a descriptive commit message.
  Use conventional commit format.

Claude will run git add and git commit with an appropriate message. Review the message before approving:

feat(auth): add in-memory rate limiting to login endpoint

- Add RateLimiter middleware with configurable window and max attempts
- Apply rate limiting to POST /api/login
- Return 429 with retry-after header when limit exceeded
- Add unit tests for rate limiter behavior

Tips for Iterating

Be specific when you know what you want:

> Change the rate limit window from 15 minutes to 5 minutes
  and the max attempts from 100 to 10.

Be open when you want Claude to explore:

> This error handling feels fragile. What would you suggest
  to make it more robust?

Break large tasks into smaller steps. Instead of "build a complete user authentication system," try "add a password hashing utility function" followed by "add a signup endpoint that uses the hasher" and so on.

Use follow-up prompts to refine. Your first request rarely produces the perfect result. The power is in the conversation — each follow-up gets closer to what you want.

Common First-Project Mistakes

1. Asking for too much at once. Start with one file, one function, one feature. Build up from there.
2. Not reviewing changes before committing. Always check git diff. Claude is good but not infallible.
3. Skipping the CLAUDE.md. Without project context, Claude makes more assumptions and more mistakes.
4. Being too vague. "Make this better" is a weak prompt. "Add input validation that rejects empty strings and emails without @ symbols" is a strong one.
5. Not correcting early mistakes. If Claude misunderstands your project structure in step 1, every later step inherits that confusion. Correct misunderstandings immediately.

Key Takeaways

• Start with a small, familiar project — not a massive monorepo
• Explore the codebase first so Claude (and you) have shared context
• Create a CLAUDE.md early; it is the single highest-leverage setup task
• Plan before implementing, especially for anything non-trivial
• Always review changes with git diff before committing
• Be specific when you know what you want; be open when exploring
• Break large tasks into small, verifiable steps