Lesson 14: Lab — Refactor a Real Project

Day 14 of 50 · ~20 min hands-on · Phase 2: Core Workflows

The Mission

You're going to refactor a real project using Claude Code. This isn't a toy exercise — you'll use every skill from Lessons 9–13, plus concepts from Phase 1 (Lessons 1–8).

What you'll do:

1. Clone or use a small open-source project (or use a provided starter project)
2. Ask Claude to analyze the codebase
3. Identify a concrete refactoring task (extract a utility, rename a pattern, add consistent error handling)
4. Use Claude to read code, discover dependencies, make coordinated multi-file edits
5. Run tests and iterate when things break
6. Commit changes with clear messages and create a pull request

What you'll practice:

• Reading and navigating code (Lesson 5)
• Making precise edits (Lesson 9)
• Managing context window (Lesson 10)
• Prompting effectively (Lesson 11)
• Multi-file operations (Lesson 12)
• Git workflows (Lesson 13)

What You'll Practice

From Phase 1:

• The agentic loop: asking clearly, watching Claude work, checking results
• Tool proficiency: Read, Grep, Glob, Bash, Edit, Write
• Iterating when something goes wrong

From Phase 2 (Lessons 9–13):

• Making and approving edits with confidence
• Understanding context window constraints
• Giving specific, clear prompts with file references
• Coordinating changes across multiple files
• Using git to track and ship work

Setup

Choose one of these options:

Option A: Use a provided starter project

cd /tmp
git clone https://github.com/your-org/starter-project
cd starter-project

Option B: Use a small real open-source project

• A small Python CLI tool (e.g., httpie, click)
• A small Node.js utility (e.g., lodash submodule, chalk)
• A small Go tool (e.g., cobra CLI framework)

Option C: Create your own Make a small project with 5-8 files, some repeated patterns, and inconsistent error handling. This gives you something concrete to refactor.

Get Claude running:

cd your-project
claude

Step 1: Understand the Architecture

Your task: Ask Claude to explain the project structure and identify what you're working with.

Prompt:

Explain the architecture of this project. What does it do? 
What are the main modules/files? How do they fit together?

What to notice:

• Does Claude read multiple files to build a picture?
• Does it use Glob/Grep to search, or open files one by one?
• Does it ask clarifying questions to narrow scope?
• Is the explanation clear and accurate?

Evaluate: If Claude's explanation is confused or incomplete, ask follow-up questions: "Focus on the main entry point and the modules it depends on."

Step 2: Choose a Refactoring Task

Your task: Identify a concrete refactoring you want to do. Ask Claude to help you plan it.

Pick one:

1. Extract a utility function — find code that's duplicated across 2+ files and extract it
2. Standardize error handling — add consistent error handling patterns across all files
3. Rename a core function/class — rename something used in multiple places and update all callers
4. Extract a configuration object — move hardcoded values into a config file and use it everywhere
5. Add logging — add consistent logging to key functions across the codebase

Prompt:

I want to [your refactoring task]. 
1. Where in the codebase would this affect?
2. What's your plan for making this change?
3. What files do you need to modify?

What to notice:

• Does Claude search for all affected files before proposing a plan?
• Is the plan logical? Does it handle dependencies?
• Does Claude ask clarifying questions?

Evaluate: If the plan seems incomplete, ask Claude to search for more occurrences or clarify its approach.

Step 3: Execute the Refactoring

Your task: Ask Claude to make the coordinated changes across all files.

Prompt:

Let's do this refactoring. Please:
1. Search for all the places that need to change
2. Make the edits to all affected files
3. Run the tests to verify everything works

What to notice:

• Does Claude search comprehensively for all dependencies?
• Does it make edits across multiple files in a coordinated way?
• Does it run tests and check for errors?
• If tests fail, does it read the error and adjust?

Your role:

• Review each edit Claude proposes before accepting it
• If something looks wrong, ask Claude to explain
• If tests fail, paste the error and watch Claude diagnose
• Don't auto-accept all changes — stay engaged

Key moments to watch:

• When Claude finishes one file and moves to the next, are changes coordinated?
• If an edit fails (old_string doesn't match), does Claude read the file and retry?
• If tests fail, can Claude trace the error back to its changes?

Step 4: Commit and Create a Pull Request

Your task: Ask Claude to commit the changes and create a PR.

Prompt:

These changes look good. Please:
1. Create a branch for this refactoring
2. Commit all the changes with a clear message (or multiple commits if the work is large)
3. Push to remote
4. Create a pull request with a detailed description

What to notice:

• Did Claude create a branch with a sensible name?
• Is the commit message clear? Does it explain why, not just what?
• Did Claude stage all the files it changed?
• Does the PR description explain the refactoring and why it's an improvement?

Your role:

• Read the commit message. Is it helpful to someone reviewing the history?
• Read the PR description. Would a reviewer understand the change?
• Check the diffs one more time for any issues

Reflect

Answer these questions about your experience:

1. Discovery: When Claude searched for affected files, did it find everything? Did you have to correct it?

2. Coordination: Did Claude make coordinated edits across multiple files, or did it need guidance to understand dependencies?

3. Testing: When tests failed, could Claude diagnose the problem and fix it? Or did you have to guide it?

4. Context: Did Claude manage the context window well, or did it seem to lose track of earlier files?

5. Communication: Were Claude's commit messages and PR description helpful? Would they make sense to a colleague?

6. Trust: After this exercise, do you feel more confident letting Claude handle multi-file refactoring?

Bonus Challenge

Pick one of these extensions:

Bonus A: Merge conflicts If working with a team or branch, ask Claude to create a conflicting change on another branch, then resolve the conflict. Ask Claude to read the conflict markers and propose a resolution.

Bonus B: Bigger refactoring Apply the same process to a more complex task: restructuring how a module exports functions, adding a new abstraction layer, or refactoring a large class into smaller pieces.

Bonus C: Code review Create another branch with deliberate issues (a bug, an inconsistency, a performance problem hidden in Claude's refactoring). Ask Claude to review its own PR as if it were a colleague and catch the issues.

Bonus D: Documentation Ask Claude to generate or update documentation (README, docstrings, type annotations) for the refactored code. Does Claude understand what it changed well enough to explain it to future readers?

Key Concepts Applied

What's Next

You've now applied everything from Phase 2's concept lessons in a real scenario. You've experienced:

• Claude reading and understanding your codebase
• Claude making multiple coordinated edits
• Claude running tests and fixing problems it finds
• Claude handling version control

The next lesson is a checkpoint: we'll test your understanding of all these concepts through a series of recall questions.

← Back to Curriculum · Lesson 15 →