Writing New Features and Debugging

This is where Claude Code truly shines. Writing new features and fixing bugs are the bread and butter of daily development work, and Claude Code can handle both with remarkable efficiency. In this lesson, you will learn practical workflows for building features from natural language descriptions and diagnosing and fixing bugs.

What You Will Learn

• How to describe features effectively to Claude Code
• The workflow for building new features step by step
• How to use Claude Code for debugging errors
• Techniques for fixing test failures and runtime bugs
• How to use error messages and stack traces with Claude Code
• Common pitfalls and how to avoid them

---

Writing New Features

The Basic Workflow

The simplest way to build a feature with Claude Code is to describe what you want:

Add a search bar to the top of the products page.
It should filter products by name as the user types.
Use the existing ProductCard component to display results.

Claude Code then:

1. Reads the products page to understand the current structure
2. Reads the ProductCard component to understand its props
3. Creates or modifies the search component
4. Integrates it into the products page
5. Runs your linter to check for issues

Writing Better Feature Prompts

The quality of your results depends heavily on how you describe the feature. Here are techniques that work well:

Specify the behavior, not the implementation:

When a user clicks "Add to Cart," show a success toast notification
that disappears after 3 seconds. If the item is already in the cart,
show the current quantity instead.

This tells Claude Code WHAT the feature should do without dictating HOW to build it. Claude Code can then choose the best implementation approach based on your project's existing patterns and libraries.

Reference existing code:

Create a settings page that follows the same layout pattern as
the existing profile page. Include sections for notification
preferences and display settings.

By pointing to existing code as a reference, Claude Code matches your project's style and patterns automatically.

Break complex features into steps:

Instead of asking for an entire feature at once, build it incrementally:

Step 1: Create the data model for a blog post with title,
content, author, tags, and timestamps.

Then after reviewing:

Step 2: Create an API endpoint to create and retrieve blog posts.
Use the same error handling pattern as the existing user endpoints.

Then:

Step 3: Build the frontend form to create a new blog post.
Validate that title and content are not empty before submitting.

This incremental approach gives you more control and makes it easier to course-correct along the way.

Handling Multiple Files

One of Claude Code's strongest capabilities is making coordinated changes across multiple files. For example:

Add a "last login" timestamp to the user system. This needs:
- A new column in the users table migration
- An update to the User model/type
- Logic to update the timestamp on successful login
- Display of the last login time on the profile page

Claude Code creates or modifies all four files in a coordinated way, ensuring types are consistent, imports are correct, and the changes work together.

---

Debugging with Claude Code

Debugging is often the most time-consuming part of development. Claude Code transforms this process by reading your error messages, understanding your code context, and proposing targeted fixes.

Pasting Error Messages

The most direct way to debug with Claude Code is to share the error:

I am getting this error when I run the app:

TypeError: Cannot read properties of undefined (reading 'map')
    at ProductList (src/components/ProductList.tsx:23:18)
    at renderWithHooks (node_modules/react-dom/cjs/react-dom.development.js:14985:18)

Claude Code reads the stack trace, opens the relevant file (ProductList.tsx at line 23), examines the data flow that leads to the undefined value, and proposes a fix. It typically identifies not just the symptom but the root cause.

Describing Unexpected Behavior

Sometimes there is no error message; the code just does not behave as expected:

The discount calculation is wrong. When I apply a 20% coupon
to a $100 order, it shows $85 instead of $80.
The discount logic is in src/services/pricing.ts.

Claude Code reads the pricing logic, identifies the mathematical error (perhaps the discount is being applied after tax instead of before), and fixes it.

Runtime Debugging

When the issue only happens at runtime, you can ask Claude Code to help instrument the code:

The API endpoint /api/orders sometimes returns an empty array
even when there are orders in the database. Help me debug this.

Claude Code examines the endpoint, checks the database query, looks for common issues like missing await keywords, incorrect query filters, or race conditions, and either fixes the issue directly or adds logging to help identify it.

Fixing Test Failures

When your tests fail, paste the test output:

These tests are failing after my recent changes. Fix them:

FAIL src/__tests__/auth.test.ts
  Authentication
    x should return 401 for expired tokens (15ms)
    x should refresh tokens automatically (22ms)

  Expected: 401
  Received: 200

Claude Code reads both the test file and the source code being tested, understands what changed, and either fixes the source code (if your changes introduced a bug) or updates the tests (if the tests need to reflect new behavior).

---

Advanced Debugging Techniques

Using Claude Code as a Rubber Duck

Sometimes the best way to debug is to explain the problem:

I am trying to understand why the WebSocket connection drops
after exactly 30 seconds. Here is what I know:
- The client connects successfully
- Messages flow normally for 30 seconds
- Then the connection closes with code 1006
- This only happens in production, not locally

Claude Code can correlate these symptoms with common causes (in this case, likely a proxy timeout) and guide you to the fix.

Comparing Working and Broken States

The user registration worked yesterday but broke today.
Can you check what changed in the auth-related files recently?

Claude Code can look at git history to identify recent changes and correlate them with the bug, narrowing down the cause quickly.

Fixing Build Errors

Build errors are common and often involve configuration issues:

My build is failing with:
Module not found: Can't resolve '@/components/Button'
But the file exists at src/components/Button.tsx

Claude Code checks your TypeScript configuration, path aliases, build configuration, and import statements to find and fix the mismatch.

---

Common Pitfalls When Writing Features

Being too vague. "Make the app better" gives Claude Code nothing to work with. Be specific about what you want.

Not reviewing the output. Always review what Claude Code writes before moving on. It is very capable, but it can make mistakes, especially with complex business logic.

Trying to build too much at once. Breaking features into smaller steps gives you better results and is easier to debug if something goes wrong.

Ignoring existing patterns. If Claude Code does not know about your project's patterns, it invents its own. Reference existing code or use CLAUDE.md (covered in a later lesson) to guide it.

---

Practice Exercise

Try this debugging and feature-building exercise:

1. Open Claude Code in a project that has tests
2. Ask Claude Code to run the test suite and report results
3. If there are failures, ask Claude Code to fix them
4. Then ask Claude Code to add a small new feature (like a utility function)
5. Ask Claude Code to write tests for the new feature
6. Run the tests to verify everything passes

This gives you a complete cycle of debugging, feature development, and verification.

---

Key Takeaways

• Describe features by specifying behavior and desired outcomes rather than implementation details
• Reference existing code patterns to ensure Claude Code matches your project's style
• Break complex features into incremental steps for better control and easier debugging
• Claude Code excels at multi-file changes, coordinating types, imports, and logic across files
• For debugging, paste error messages and stack traces directly; Claude Code traces the root cause, not just the symptom
• Use Claude Code to fix test failures by sharing test output, then let it determine whether to fix the source code or update the tests
• Always review Claude Code's output before moving on, especially for complex business logic