Skip to content

Claude Code guide in three levels, Beginner to Advanced: hands-on lessons with checked exercises, every volatile fact cited to its source. Independent community guide.

10.6 KB
Raw Blame

Beginner capstone: fix a reported bug, from plan to commit

Beginner · Capstone · 30 to 60 minutes · Needs: the five Beginner lessons, or their skills · Verified against Claude Code v2.1.308 (stable) on 2026-10-25

This task puts the whole Beginner level together. Unlike the lessons, it has no worked example: the steps say what to do, and you choose the prompts and make the calls. The Beginner Exit is the list of what you can do by the end of this level. The check reads the files and the commit this task leaves behind, and you tick the rest of the Exit yourself under What the check can't see. When both are done, you've shown the Beginner Exit, whether you took the lessons or not.

You need

  • Your copy of the practice template, with no uncommitted changes, and Node.js LTS (a Codespace on your copy has it). If git status --porcelain (git status) lists files, commit them. The capstone runs in the template only.
  • If you skipped the lessons: create the .practice/ folder in your copy (mkdir -p .practice; Windows: New-Item -ItemType Directory -Force .practice). The template already tells git to ignore it.
  • A committed CLAUDE.md in your copy that names the test command, npm test: git show HEAD:CLAUDE.md shows it. Lesson 5 gives you one; if yours doesn't name npm test, add it.
  • If you skipped lesson 5: start claude in your copy and run /init. In the new CLAUDE.md, delete what it says about the course's own files (checks/, learn/, capstone/ and .github/) and about npm run check, npm run learn and npm run test:checks, including any rule to keep your work off main: that rule is for the template repository, not your copy. Make sure the file names npm test, then end that session with /exit, so the task starts in a new one.
  • Commit any change to CLAUDE.md on its own before you start (git add CLAUDE.md, then git commit -m "Add CLAUDE.md"): the fix commit may change only the files the plan names.
  • Two terminals open in your copy: one for Claude Code, one for your own commands.
  • Usage: moderate.

[!NOTE] On native Windows, run every command in PowerShell. A command with no Windows line works there as written; where a Windows line follows a command, use it instead. If Shift+Tab does nothing, press Alt+M instead (Interactive mode).

The task

A missing folder in linkcheck.json passes silently: make linkcheck fail on it, test first. A teammate filed the bug report in capstone/beginner-bug.md in your practice copy: the tool says every link resolves and exits with code 0. Read it first: its "What should happen" section is what done means.

Fix it the way the Beginner lessons taught:

  1. Reproduce the bug before you fix it. In your own terminal, make a new folder outside your practice copy and save { "files": ["docs"] } in it as linkcheck.json. Then run npm run linkcheck -- <that folder> in your copy: until the bug is fixed, it prints All relative links resolve. Don't put a linkcheck.json in your copy, because the check counts it as a change. Windows: save the file with '{ "files": ["docs"] }' | Set-Content <that folder>\linkcheck.json, not >. In Windows PowerShell 5.1, > writes UTF-16 (about_Character_Encoding), which the tool rejects as invalid JSON with exit code 2, even before the fix.
  2. Start a new session in your copy. It usually starts in auto mode. Here you want to approve the plan before any file changes, so switch to plan mode before your first prompt: press Shift+Tab until the status bar shows ⏸ plan mode on, or start the prompt with /plan (Permission modes).
  3. Have Claude read the bug report and plan the fix. Don't name the files to change: let Claude find them. Ask for a plan that adds the test first and runs it before changing the code, so you see it fail (Best practices: "write a failing test that reproduces the issue, then fix it").
  4. Review the plan before you approve it. Open the files it names and check that the code it describes is there, as you checked Claude's answer in lesson 1. The plan should add a test of what the bug report's "What should happen" asks for, run it and see it fail before any source file changes, and change only the files the bug needs. If it falls short, use the plan menu to tell Claude what to change, as in lesson 2 (Permission modes).
  5. While the final plan is on screen, in your own terminal, save git status --porcelain to .practice/capstone-before.txt. Save the files the plan will change, every test file included, to .practice/capstone-plan.txt: one path per line, relative to the repository root, with forward slashes, such as src/cli.js.
  6. Approve with Yes, and use auto mode, as in lesson 2: you've approved what Claude will do, so it can work without a prompt for each edit. Watch the new test fail, then pass after the fix. Claude may write a test or run the tests with a shell command, so read the test output itself, not only Claude's summary: press Ctrl+O, as in lesson 3, and Ctrl+O again to go back (Interactive mode).
  7. Review the whole diff, the tests included, against the bug report, as in lesson 3. If the diff panel is open beside the conversation, its list skips test files and generated files and counts them on one line: click that count line to see the test (Diff panel). Does the error name the missing folder? Does the tool exit with code 2? Does the test check the case the report describes? git diff (git diff) leaves out a new file until you run git add -N <file> (git add). Ask Claude to correct anything that falls short, inside the files the plan names, and make sure npm test passes.
  8. Commit the fix and its test together, then save the commit with git rev-parse HEAD > .practice/capstone-commit.txt (git rev-parse). The check reads only that commit, so if you change it later, save it again.

If Claude's fix heads the wrong way, press Esc, or rewind and re-prompt as in lesson 4, then check git status: rewind doesn't undo a shell command's change to a file Claude hadn't edited (Checkpointing).

Check

You are done when all of these are true:

  • .practice/capstone-before.txt, saved while the plan was on screen, lists no changed files.
  • The commit in .practice/capstone-commit.txt changes only files listed in .practice/capstone-plan.txt, including a test file.
  • The commit's test fails without its fix: with the other files the commit changes put back as they were before it, npm test fails.
  • The bug is fixed: with the bug report's linkcheck.json in a folder outside your copy, npm run linkcheck -- <that folder> exits with code 2, and its error names the missing folder, docs.
  • npm test passes.
  • A committed CLAUDE.md names the test command, npm test.
  • git status --porcelain prints nothing.

Run npm run check -- b-capstone in your practice copy. Each item that fails prints what to fix.

What the check can't see

The check doesn't look at these parts of the Beginner Exit. Tick them yourself, honestly:

  • I can tell which model and account a session uses, with /status (Commands), and I check what Claude tells me against the code.
  • I can say which permission mode a task needs: auto mode for work whose direction I trust, plan mode when I want to approve a plan before any change, and Manual mode when I want Claude Code to ask before most edits and commands. I skip the plan when I could describe the diff in one sentence.
  • I read the whole diff, the tests included, against the bug report before committing, and asked Claude to correct anything that fell short, or found nothing to correct.
  • I know how to get back on track: Esc to stop Claude mid-action, /rewind to put the code and the conversation back, and git status for anything a shell command changed. I know when I'd use the session commands: /compact to keep going on the same task in a long conversation, /clear to start a new task with empty context, and /resume to go back to an earlier conversation.
  • I've seen a new session follow a rule from CLAUDE.md that I didn't repeat in the prompt. If you skipped lesson 5, its Worked example shows you how.

When every box on this page is ticked, you're ready for the Intermediate level. Its "ready if" list is the Beginner Exit.

If this level helped, a star helps other developers find the guide.


Sources: Permission modes · Commands · Best practices · Interactive mode · Checkpointing · git add · about_Character_Encoding · the Beginner lessons, which cite the official pages for each step. · git status · git diff · git rev-parse

← Project memory with CLAUDE.md · Beginner index · Intermediate index → · Stuck on this capstone?