# 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](05-section-2-steering.md)).

### 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](05-section-2-steering.md),
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**](10-lab-4-spec.md).