Lab 2.1: The Architect

Module: 2.1 - Plan Mode & Analysis | ← SlidesDuration: 30 minutes Sample Project: hackathon-starter

Learning Objectives

By the end of this lab, you will be able to:

• Use Plan Mode for read-only analysis
• Create detailed refactoring plans before writing code
• Identify risks and dependencies in a proposed change
• Document step-by-step implementation strategies

Prerequisites

• Completed Day 1 labs
• hackathon-starter project set up

What is Plan Mode?

Plan Mode is a read-only mode where Claude can:

• Explore the codebase
• Analyze dependencies
• Create step-by-step plans
• Identify risks

But cannot:

• Modify files
• Run commands (except safe read operations)
• Make commits

When to Use Plan Mode

Use it when the change will touch >3 files or take >1 hour.

Setup

# Navigate to the sample project
cd sample-projects/hackathon-starter

# Start Claude in Plan Mode
claude --permission-mode plan

Or from an existing session:

/plan

---

Task 1: Identify a Refactoring Target

Time: 5 minutes

Find something in the codebase that needs refactoring.

Prompts to try:

What are the most complex or hard-to-maintain parts of this codebase?

Are there any "God classes" or modules that do too many things?

Which files have the most lines of code?

Good candidates:

• Large controller files (>300 lines)
• Modules with many responsibilities
• Files with high cyclomatic complexity

Success criteria:

• [ ] Identified a refactoring target
• [ ] Understand why it needs refactoring

---

Task 2: Create a Refactoring Plan

Time: 15 minutes

Ask Claude to create a detailed plan.

Prompts to try:

Create a plan to refactor the user controller into smaller, single-responsibility modules.

What would be the safest approach to split the passport configuration into separate auth strategies?

How should I approach extracting the email functionality into a separate service?

Your plan should include:

• Current state analysis
• Proposed changes (step by step)
• Dependencies that need updating
• Potential risks
• Testing strategy

Success criteria:

• [ ] Received a multi-step refactoring plan
• [ ] Plan includes dependency analysis
• [ ] Risks are identified

---

Task 3: Refine the Plan

Time: 10 minutes

Ask follow-up questions to improve the plan.

Prompts to try:

What would break if we do step 2 before step 1?

Are there any edge cases we should handle?

What tests should we write before starting this refactor?

Can you break down step 3 into smaller sub-steps?

Success criteria:

• [ ] Plan has been refined with more detail
• [ ] Edge cases identified
• [ ] Testing strategy is clear

---

Example Plan Structure

A good refactoring plan looks like this:

# Refactoring Plan: Split UserController

## Current State
- UserController handles: auth, profile, settings, admin
- 450 lines, 15 methods
- High coupling with passport.js

## Proposed Changes

### Step 1: Extract AuthController
1. Create controllers/auth.js
2. Move login, logout, signup methods
3. Update routes/index.js imports
4. Verify tests pass

### Step 2: Extract ProfileController
...

## Risks
- Session handling depends on auth order
- Some methods share private helpers

## Testing Strategy
- Run existing test suite after each step
- Add integration tests for auth flow

---

Common Plan Mode Questions

Question Type	Example
Scope	"How many files will this affect?"
Risk	"What could go wrong?"
Order	"What's the safest sequence?"
Testing	"What tests do I need first?"
Rollback	"How do I undo if it fails?"

---

Tips for Success

1. Be specific about the goal - "Improve maintainability" is vague; "Split into <100 line files" is specific
2. Ask about dependencies - Changes cascade; understand the blast radius
3. Request test strategies - How will you know if you broke something?
4. Get time estimates - Ask Claude how long each step might take

---

Pro Tip: To Do Lists Persist Across Compaction

When using Plan Mode, explicitly ask Claude to create a comprehensive To Do list:

Create a comprehensive To Do list for this refactoring plan.

Why this matters:

• Plans and To Do lists persist across context compaction
• Even in very long sessions (50+ minutes), your task list remains intact
• This prevents Claude from losing track of multi-step changes

TIP

Start with Plan Mode + a detailed To Do list for any task that will take more than 30 minutes.

---

Deliverables

At the end of this lab, you should have:

1. A written refactoring plan (saved to a file or notes)
2. Understanding of dependencies and risks
3. A testing strategy before implementation

---

Next Steps

After completing this lab, move on to Lab 2.2: Safety Net Construction to generate tests before refactoring.