v10

Lab 4 — Architecture to Code

Summary — what this page covers The capstone lab, exercising the full acceleration loop: architecture → construction → testing → debugging. Attendees write a specification for a Reading Progress feature, review it with Claude, implement it against the spec and their CLAUDE.md/rules, generate passing tests, then debug a deliberately introduced failure — all committed. This is where the full Day 1 toolkit comes together.

Duration: 60 min · Deliverable: working Reading Progress feature with tests, committed

Part A — Write the specification (15 min)

Create specs/reading-progress.md from the 6-section template. Feature: track current page, total pages, and reading status (reading / completed / want-to-read) with start and finish dates.

Must include: context & scope · API contract (update + get progress) · business rules (page validation, status transitions, date rules) · tests required · at least 3 explicit prohibitions.

Review it with Claude before you write any code — reviewing a page of spec is far cheaper than discovering the gaps in the implementation:

Read specs/reading-progress.md. Identify gaps, ambiguities, and edge cases. Do NOT implement yet.

Fold the good catches back into the spec, then commit it:

git add specs/reading-progress.md
git commit -m "docs: spec for reading-progress feature"

Part B — Implement from the spec (30 min)

Drive the build from the spec, not from a vague ask:

Implement specs/reading-progress.md. First read the spec and the relevant existing files
(the Endpoints, the Core services, and the Data layer). Follow CLAUDE.md and the rules under
.claude/rules. Build after each change. Pause for my approval before changing more than 4 files
at once.

This is the practice — stay in the loop:

  • Review each diff before approving; don't rubber-stamp.

  • Push back on at least one choice — "why did you put that logic in the endpoint instead of a Core service?" — and make Claude justify or revise it.

  • Ask Claude to explain anything you don't follow.

  • Catch a rule violation if one slips through (e.g. an EF entity returned instead of a DTO), point it out, and confirm the relevant rule actually loaded (/memory).

Commit when the feature builds and behaves:

git add -A
git commit -m "feat: reading-progress feature per spec"

Part C — Tests & debugging (15 min)

Tests (≈8 min) — generate the listed tests + any needed, using existing patterns in BookTracker.Tests/. Run dotnet test. If failures: paste the output, have Claude read the relevant source first, then fix the source, not the tests.

Debugging exercise (≈7 min) — practice the debugging loop deliberately:

  1. Introduce a realistic bug (e.g. an off-by-one in page validation, or a status-transition that allows completed → reading).

  2. Run the feature/tests so it fails. Paste the failing output or stack trace to Claude:

    Here's the failing output: [paste]. Read the relevant source and tests, find the root cause,
and reproduce it with a failing test before fixing.
  3. Confirm Claude diagnoses the root cause (not just the symptom), reproduces it, fixes the source, and the new test passes.

Commit the tested feature:

git add -A
git commit -m "test: reading-progress coverage + regression test for status transitions"

Checkpoint

  • specs/reading-progress.md committed
  • Claude identified at least one gap in your spec
  • You pushed back on at least one implementation choice
  • All new tests pass (dotnet test)
  • You ran the debugging loop: Claude found the root cause, reproduced it, and fixed it
  • Build hook fired during implementation
  • All changes committed with meaningful messages

Bonus — The full architecture sprint

No time pressure. Run a complete architecture exercise on BookTracker:

  1. Analyze under a real constraint — e.g. "BookTracker must serve 10k concurrent readers on one small VM." Have Claude produce three options with effort estimates and a recommendation.

  2. Capture the decision as a MADR ADR committed under docs/adr/ — what you chose and why.

  3. Spike the recommendation — implement an IMemoryCache layer for a hot read endpoint, with a cache-invalidation test proving stale data isn't served after an update.

This is the architecture + refactoring + testing loop from Section 4 at full size.

Tomorrow morning — your action plan

Don't let this fade. Tomorrow, on your real project:

  1. Run claude in the repo and ask for a codebase overview + your top 3 impactful improvements:

    Give me an overview of this codebase and your top 3 most impactful improvements.
  2. Add a CLAUDE.md — /init to scaffold, then trim it to a map (facts, commands, architecture).
  3. Add one path-scoped rule for an area you change often.
  4. Add one guardrail hook — a PreToolUse exit-2 block on something you never want run.

That's the whole Day 1 toolkit, applied where it actually pays off.

Tomorrow — Day 2: the Anthropic API track. You'll stop using Claude and start building with it: wiring the Anthropic C# SDK into BookTracker for streaming chat, tool-calling agents, a RAG recommendation engine, and your own MCP server. See Day 2.