Claude Code Guide
বাংলায় পড়ুন

15 min / intermediate / 5 steps

Debug and Refactor Like a Senior Dev

Use Claude Code the way senior engineers do: feed it real stack traces, refactor with tests staying green, and build a 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.

follow along in

You need: A Claude account. Open claude.ai in a browser, or the Claude desktop app.

  1. step 01 / 05

    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.

    Prompt
    Generate a CLAUDE.md for this Next.js TypeScript project. We use Vitest, Prisma, and Tailwind. Always run tests after refactoring. No any types. No console.log in production.
    markdown
    # 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 files

    what you should see

  2. step 02 / 05

    Debug 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.

    Prompt
    Fix this: TypeError: Cannot read properties of undefined (reading 'userId') at getEnrollmentStatus (src/lib/enrollment.ts:47:28) at EnrollmentButton (src/components/EnrollmentButton.tsx:23:18) Happens when visiting /courses/ without being logged in.

    Click a violet field and type your own details, then copy.

    what you should see

  3. step 03 / 05

    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.

    Prompt
    Refactor UserCard.tsx to extract the avatar logic into a separate AvatarWithFallback component. Keep all existing tests passing. Do not change the external props interface.

    what you should see

  4. step 04 / 05

    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.

    Prompt
    CourseProgress shows stale data after a lesson completion. Do NOT suggest fixes yet. Trace the data flow from the API through to the render. Check git history for recent changes on this path. Tell me the most likely cause.

    what you should see

  5. step 05 / 05

    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.

    Prompt
    Add what we just learned to CLAUDE.md: the staleTime issue, the session?.user guard pattern, and a preference to always trace data flow before suggesting fixes.
    markdown
    # 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 change

    what you should see

Tell someone what you built

Just finished "Debug and Refactor Like a Senior Dev" on Claude Code Guide. Took about 15 min, and it's free: https://claudecodeguide.dev/tutorials/debug-and-refactor

Share on LinkedIn

New guides, when they ship

One email, roughly weekly. CLAUDE.md templates, workflows I actually use, and the cut-for-length stuff that does not make the public guides. One-click unsubscribe.

Or read Product Field Notes, the Substack