v10

Lab 1 — Install, Configure & Explore BookTracker

Summary — what this page covers The first hands-on lab. By the end, every attendee has a working Claude Code session against BookTracker and a committed CLAUDE.md. Three parts: install/authenticate, author CLAUDE.md, run five exploration prompts. Keep instructions copy-paste exact.

Duration: 50 min · Deliverable: functioning Claude Code session + committed CLAUDE.md

Part A — Install & authenticate (15 min)

From the BookTracker folder, confirm Claude Code runs and is authenticated:

claude --version
claude "Hello — what is today's date?"

Per-OS notes:

  • macOS / Linux — run these in your normal terminal.
  • Windows — run them inside the WSL2 (Ubuntu) terminal, not PowerShell or CMD.
  • If claude --version isn't found, reinstall: npm install -g @anthropic-ai/claude-code.
  • The first time you run claude, it prompts you to authenticate — sign in with your Claude.ai subscription (browser) or use an API key. See Before You Begin.

A TA is circulating for install friction — flag them early rather than burning lab time.

Part B — Author your CLAUDE.md (15 min)

Open the placeholder CLAUDE.md at the repo root and write a complete one. It must include:

  • Project description — purpose, stack, .NET version

  • The four essential commands — build, test, run, migrations

  • At least five project-specific conventions — the ones from The BookTracker App

  • Architecture notes — the project dependency structure you confirmed in Part C / Section 1

Tip: run /init to scaffold a starting CLAUDE.md from the codebase, then edit it — don't ship the raw scaffold. Make sure all four pieces above are present and accurate.

Teaching note (carry into Section 2): keep CLAUDE.md for facts and soft conventions — "the API uses Minimal APIs," "prefer DTOs over entities." A hard "never do X" prohibition (never run rm -rf, never commit secrets) does not reliably bind the model from a CLAUDE.md line — it's guidance, not a guardrail. Real guardrails are deterministic hooks and permissions, which you'll build in Section 2. So don't lean on CLAUDE.md to stop Claude from doing something; lean on it to inform Claude.

Commit it:

git add CLAUDE.md
git commit -m "feat: configure CLAUDE.md for workshop"

Part C — Codebase exploration (20 min)

Run these in order in the REPL. Spend ~60s checking each answer against the real code — the skill you're practicing is verifying Claude, not trusting it. (Per Section 1: grounded answers beat recall, so notice when Claude reads files before answering.)

1. Architecture overview

Read the BookTracker solution. Give me an architecture overview: the projects, each one's
responsibility, and the dependency direction between them. Cite the files you used.

Check: does the dependency direction match — Core depends on nothing, Data → Core, Api → Core + Data?

2. Quality assessment

Assess the code quality of this solution. Call out concrete strengths and weaknesses —
naming, structure, error handling, consistency — and point to specific files and lines.

Check: are the cited files/lines real, or did it generalize? Open one and confirm.

3. Gap analysis

What's missing for production readiness? Check specifically for authentication, logging,
health checks, caching, and observability. For each, tell me whether it exists, where, and
what's absent.

Check: pick one "missing" item and verify it's actually absent (not just unread).

4. EF Core exploration

Explain the data layer. Read BookTracker.Data: describe the DbContext, the entities and their
relationships, and the existing migrations. Then show me how I'd add a new migration.

Check: do the entities and relationships match what's in the code?

5. Test coverage

Read BookTracker.Tests. What is currently tested, and what are the most important untested
code paths? List the top three tests you'd write first and why.

Check: are the "untested paths" genuinely untested? This previews Section 4's testing work.

Checkpoint

  • claude --version returns a version
  • Claude read your CLAUDE.md on startup
  • Architecture overview matched the code
  • You spotted at least one inaccuracy in Claude's analysis
  • CLAUDE.md committed to your fork

Bonus — The Legacy Audit

No time pressure — do this over lunch or after the day. Point Claude at the messier BookTracker-Legacy variant and have it produce three artifacts:

  1. A full audit report — code smells, security issues, performance risks, and outdated patterns, each tied to specific files.

  2. A phased migration plan — concrete steps to bring it up to the modern BookTracker's standards, sequenced so each phase ships safely.

  3. A one-page executive summary — the risks and the plan, written for a non-technical stakeholder.

This is a preview of the architecture and refactoring work in Section 4.