Lab 1.7: Full Codebase Reconnaissance

Day 1 Capstone | ← SlidesDuration: 1 hour Sample Project: hackathon-starter

The Scenario

You've joined a new team. They hand you a legacy module and say:

"We need to refactor this next sprint. Can you figure out what it does and how risky it is to change?"

You have 1 hour to deliver a briefing.

Learning Objectives

This capstone integrates everything from Day 1:

• Codebase exploration (Module 1.2)
• Project context with CLAUDE.md (Module 1.3)
• Dependency mapping (Module 1.5)
• Documentation generation (Module 1.6)

Prerequisites

• Completed all Day 1 labs (1.2, 1.3, 1.5, 1.6)
• hackathon-starter project cloned

Setup

# Navigate to the capstone project (different from earlier labs!)
cd sample-projects/hackathon-starter

# Install dependencies
npm install

# Start Claude Code
claude

The Mission

Complete these 5 phases within 1 hour:

Phase	Task	Time
1	Overview	10-12 min
2	CLAUDE.md	8-10 min
3	Dependencies	15 min
4	Documentation	12-15 min
5	Briefing	8-10 min

---

Phase 1: High-Level Overview

Time: 10-12 minutes Goal: Understand what this module/application does.

Prompts to try:

What is the purpose of this application?

What are its main components?

How does the authentication system work?

Output: Write a 3-5 sentence summary of what this application does.

Success criteria:

• [ ] Can explain the app's purpose in one sentence
• [ ] Identified the main components (auth, routes, models, etc.)
• [ ] Understand how the pieces fit together

---

Phase 2: Create CLAUDE.md

Time: 8-10 minutes Goal: Document initial findings for future sessions.

Create CLAUDE.md in the project root:

touch CLAUDE.md

Include:

# Hackathon Starter - Claude Instructions

## Purpose
[Your 1-sentence summary from Phase 1]

## Key Components
- [List the main modules/directories]

## Building & Running
- `npm install` — Install dependencies
- `npm start` — Start the application
- `npm test` — Run tests

## Coding Conventions
- [Note any patterns you've observed]

## Known Issues / Gotchas
- [Document anything surprising you've found]

Success criteria:

• [ ] CLAUDE.md created with purpose and components
• [ ] Build/run commands documented
• [ ] At least one coding convention or gotcha noted

---

Phase 3: Map Dependencies

Time: 15 minutes Goal: Understand the blast radius of changes.

Pick a critical module (e.g., controllers/user.js, authentication system, or models/User.js).

Prompts to try:

What other parts of the codebase depend on the User model?

What external libraries does the authentication system use?

If I changed the User model schema, what would break?

Output: A dependency map with:

• Downstream dependencies (what uses this)
• Upstream dependencies (what this uses)
• Blast radius assessment (small/medium/large)

Success criteria:

• [ ] Listed downstream dependencies
• [ ] Listed upstream dependencies
• [ ] Assessed blast radius for refactoring

---

Phase 4: Generate Documentation

Time: 12-15 minutes Goal: Document 2-3 key functions or create a module README.

Option A: Inline Documentation

Add JSDoc comments to the login function in controllers/user.js

Document the validatePassword method in models/User.js

Option B: Module README

Create a README.md for the models/ directory explaining each model.

Validation: Check any generated examples against tests or runtime behavior.

Success criteria:

• [ ] Generated documentation for at least 2 functions OR 1 module README
• [ ] Validated at least one piece of generated content
• [ ] Noted any inaccuracies

---

Phase 5: Prepare Your Briefing

Time: 8-10 minutes Goal: Synthesize findings into a 2-minute presentation.

Your briefing should answer:

1. What does this module/app do? (1-2 sentences)

2. What are the key risks?

   • High coupling / dependencies
   • Lack of tests
   • Complexity / code smells
   • External dependencies

3. What's your recommendation?

   • Safe to refactor?
   • Needs tests first?
   • High-risk, proceed with caution?
   • Specific approach suggested?

Briefing template:

# Briefing: [Module/App Name]

## Purpose
[1-2 sentence summary]

## Key Risks
- [Risk 1]
- [Risk 2]
- [Risk 3]

## Blast Radius
[Small / Medium / Large] - [Brief explanation]

## Recommendation
[Your actionable recommendation]

## Next Steps
1. [Specific action]
2. [Specific action]

Success criteria:

• [ ] Clear, concise summary prepared
• [ ] Risks identified and prioritized
• [ ] Actionable recommendation ready

---

The Four Pillars of Codebase Understanding

This capstone tested all four pillars:

Pillar	What You Did
Understand	Exploration, asking questions, tracing flows
Contextualize	Created CLAUDE.md with project conventions
Map Risks	Dependency mapping, blast radius analysis
Document	Generated docs, captured knowledge

---

Debrief Questions

After completing the capstone, reflect on:

1. What was the most surprising thing you discovered?
2. Which Day 1 technique was most valuable?
3. What would you do differently next time?
4. How long would this have taken without Claude?

---

Deliverables

At the end of this capstone, you should have:

1. CLAUDE.md file in hackathon-starter root
2. Dependency map for a critical module
3. Documentation for 2+ functions or 1 module
4. Written briefing ready to present
5. Confidence to approach any legacy codebase

---

Congratulations!

You've completed Day 1 of Claude for Coders.

What's Next

Tomorrow (Day 2): You'll learn to make safe modifications to legacy code using:

• Plan Mode (read-only analysis)
• Test Generation (creating safety nets)
• TDD with Claude (Red-Green-Refactor)
• Safe Refactoring (incremental improvements)

Rest up - Day 2 is where it gets real!