v10

Section 4 — AI in the SDLC

Summary — what this page covers Bringing it together into a real workflow across the five activities Claude Code accelerates: architecture design, code construction, refactoring, testing, and debugging. Attendees drive a specification-first build, refactor at scale with approval gates, generate and fix tests, and use Claude to diagnose failures from stack traces and reproductions. The capstone lab takes a spec to a working, tested feature — and debugs it when something breaks. Pair with Lab 4.

3:30 – 5:00 PM · 90 min — 30 min lecture/demo + 60 min lab

Learning objectives

This section completes the outcome: use Claude Code to accelerate architecture design, code construction, refactoring, testing, and debugging.

  • Architecture design: analyze trade-offs under real constraints; capture decisions as ADRs

  • Code construction: drive a specification-first workflow (write the spec → review with Claude → implement against it)

  • Refactoring: change at scale safely with the approval-gate pattern ("pause every N changes")

  • Testing: generate xUnit coverage from the spec and fix failing tests (source, not the test)

  • Debugging: diagnose from an error/stack trace — reproduce, find root cause, fix, verify

  • Recognize and prevent common .NET AI code failure modes

Content

The specification-first workflow

Why a spec beats a vague prompt. "Add reading progress" leaves a hundred decisions to chance; a spec makes them precise, so the result is consistent and the review is faster — you review the spec (cheap, a page of text) instead of discovering the misunderstandings later in the code (expensive). The spec becomes the shared contract you and Claude both build against.

The specification template (6 sections). Use the template in the repo's specs/ folder:

  1. Context & scope — the problem, the goal, and explicitly what's out of scope.
  2. API contract — endpoints, request/response DTOs, status codes.
  3. Data model & persistence — entities/fields touched and any migration needed.
  4. Business rules — validation, state transitions, invariants.
  5. Tests required — the concrete cases the implementation must satisfy.
  6. Prohibitions & acceptance criteria — explicit "do not"s and the definition of done.

Steering tie-in. The recurring spec → review → implement process is a great skill. And the failure-mode checks below belong in a code-review skill plus a PostToolUse build/test hook — not a CLAUDE.md "don't do this" list (a prohibition there is a suggestion, not enforcement; see Section 2).

Refactoring at scale

The safe pattern for a change that spans many files: read → propose → approve → execute N at a time → build. Have Claude survey the affected code, propose the change set, then apply it in small batches — "pause every N changes for approval." Why bother instead of one big sweep? It keeps you in control, prevents a 40-file runaway you can't review, and lets the build gate correctness after each batch so a mistake surfaces immediately, not at the end.

Testing with Claude Code

Generate xUnit tests straight from the spec's "tests required" list, reusing the existing patterns in BookTracker.Tests/ so they match the house style. This is mechanical work — a good fit to offload to the test-writer subagent (Haiku) from Section 2, keeping your main session on the higher-value reasoning. (Deep testing and CI come in Day 2 Section 5; here, test generation is just one step in the feature loop.)

Debugging with Claude Code (completes the outcome)

The debugging loop:

  1. Paste the failing output or stack trace.

  2. Make Claude read the relevant source and test files first — grounding, so it fixes the real bug, not an imagined one.

  3. Identify the root cause, not the symptom. "The test fails" is a symptom; "status transitions don't validate the previous state" is a cause.

  4. Propose a fix → apply → re-run to verify.

Two disciplines that keep this honest:

  • Fix the source, not the test — unless the test itself encodes the bug. A green suite you got by weakening the test is worse than a red one.

  • Reproduce before fixing — ask Claude to write a failing test that reproduces the bug, then make it pass. Now the fix is verified and regression-protected.

Steering tie-in: the PostToolUse build/test hook from Section 2 surfaces failures into Claude's context automatically — so it often starts self-correcting before you even ask.

.NET AI code failure modes

AI-generated .NET code fails in predictable ways. Know the six, and catch them with a /code-review skill plus deterministic hooks rather than hoping a prompt prevents them:

  1. Leaking EF entities across the API boundary instead of mapping to DTOs (over-posting, lazy-load surprises).
  2. Sync-over-async / blocking calls (.Result, .Wait()) and missing CancellationToken threading.
  3. Missing input validation — trusting client input straight into the data layer.
  4. String-concatenated SQL instead of parameterized queries / EF (injection risk).
  5. Swallowed exceptions — empty catch, no logging, failures that vanish silently.
  6. Hallucinated or outdated APIs/packages — invented method names, deprecated patterns, wrong versions.

These map directly onto the BookTracker conventions you encoded as rules in Lab 2 — which is the point: the same standards that steer construction also become the checklist for review.

Architecture & ADRs

Use Claude for architecture analysis under real constraints — expected load, team size, hosting budget — not in the abstract. Have it produce three options with effort estimates and a recommendation, then do domain modeling against BookTracker. Capture the decision as an ADR (Architecture Decision Record) in MADR format (Markdown ADR) — a short, versioned record of what you decided and why, committed alongside the code so the reasoning survives.

Demos referenced here

  • Domain Modeling · Full Feature from Spec (write the spec live, execute, narrate review) · Debugging from a Stack Trace (introduce a bug → diagnose → reproduce → fix → verify).

→ Continue to Lab 4.