Debug and Refactor Like a Senior Dev
Use Claude Code the way senior engineers actually do. Feed it real stack traces, refactor components with tests staying green, and build a systematic debugging habit that scales.
Claude Code is not a magic wand. It is a pair programmer who reads your codebase, traces data flow, checks your git history, and forms one hypothesis at a time. This tutorial shows you how to drive that process deliberately, the way you would with a senior engineer who just joined the team.
Set up your project context
The difference between useful Claude output and generic Claude output is almost always the CLAUDE.md. For a React/TypeScript project, you want build commands, test commands, key patterns, and any non-obvious conventions. Claude will use this on every request without you repeating yourself.
# CLAUDE.md for a React/Next.js/TypeScript project
## Stack
Next.js 15 (App Router), TypeScript strict, Tailwind CSS, Prisma, Vitest
## Commands
npm run dev # Dev server
npm run build # Production build (runs tsc + next build)
npm test # Vitest unit tests
npm run test:e2e # Playwright end-to-end tests
npx tsc --noEmit # Type check only
## Key Patterns
- Functional components only, explicit prop interfaces
- No barrel files (import directly from source)
- Server Components by default, 'use client' only when needed
- Zod for all external input validation
- Error boundaries on every major route segment
## Testing Rules
- Always run tests after refactoring
- Never mock the database layer in unit tests (use Prisma test DB)
- Co-locate test files: UserCard.tsx lives next to UserCard.test.tsx
## Never
- No any types
- No console.log in production code
- No default exports from component filesDebug a real error
Stop describing bugs in prose. Paste the exact stack trace. Claude will trace through the actual files, check recent git changes, and give you a root cause before suggesting a fix. The key: let it look at the code before forming a hypothesis.
# Paste the full stack trace, not a summary
claude "Fix this error:
TypeError: Cannot read properties of undefined (reading 'userId')
at getEnrollmentStatus (src/lib/enrollment.ts:47:28)
at EnrollmentButton (src/components/EnrollmentButton.tsx:23:18)
at renderWithHooks (react-dom/cjs/react-dom.development.js:14985:18)
This happens when a user visits /courses/[id] without being logged in."Refactor with confidence
Tell Claude what you want to change, tell it the tests must stay green, and let it work. The CLAUDE.md "always run tests after refactoring" rule means Claude runs the suite automatically and reports if anything breaks. You review the diff, not the process.
# Good refactoring prompt: scope + constraint
claude "Refactor the UserCard component to extract the avatar logic
into a separate AvatarWithFallback component. Keep all existing
tests passing. Do not change any external props interface."The systematic approach
Senior engineers do not guess. They trace data flow backward from the symptom, check what changed recently, and form one hypothesis at a time. You can ask Claude to do exactly this. Prompt it explicitly and it will show its work before touching any code.
# Ask Claude to trace before it fixes
claude "The CourseProgress component is showing stale data after
a user completes a lesson. Do NOT suggest fixes yet.
First: trace the data flow from the API call through to the UI
render. Check git history for recent changes to this path.
Identify the most likely cause. Then wait for my confirmation."Make it stick
The best thing you can do after a debugging session is add what you learned to CLAUDE.md. Every project has patterns that trip people up. Document them once, and Claude will avoid the same mistakes automatically on every future request in this codebase.
# Append to CLAUDE.md after each session
## Known Gotchas
- React Query: never set staleTime: Infinity on mutation-dependent
queries. Use staleTime: 0 or omit it (React Query defaults are fine).
- session?.user can be undefined on public routes even if the page is
not in the (auth) route group. Always guard before accessing userId.
- AvatarWithFallback requires explicit width/height props.
It does not inherit size from the parent via CSS alone.
## Debugging Preferences
- Trace data flow before suggesting a fix
- Check git log for recent changes on the affected file
- Run npm test after every refactor
- Show root cause plus one-line explanation before the code changeShare what you built
Let your network know. Pre-filled post (edit before posting).
Just completed "Debug and Refactor Like a Senior Dev" on Claude Code Guide in 15 min. No coding experience needed. Claude does the work, you do the thinking. 👇 Free tutorial: https://claudecodeguide.dev/tutorials/debug-and-refactor
What's next?
Next: PR Review Workflow