# 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](09-section-4-sdlc.md#the-specification-first-workflow).
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:

```text
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:

```bash
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:

```text
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:

```bash
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:

   ```text
   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:

```bash
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](09-section-4-sdlc.md) 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**:

   ```text
   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](<../Day 2/index.md>).