Lesson C.1 — Write the Architecture Document Before Writing Any Code

THE NAIVE APPROACH TRAP

A developer who has only worked with Claude.ai interactively treats the capstone the way they treated every prior exercise: open a chat, describe "a Skill that reviews PRs, writes changelogs, and generates test stubs," paste the response into SKILL.md, and start iterating in the editor. There is no design document — the chat transcript is the design.

This works for a single-purpose Skill like standup-formatter because it does one thing. pr-assistant does three: review, changelog generation, and test-stub scaffolding, each needing a different --allowedTools scope and a different headless claude -p invocation. Without a written boundary between the three action handlers, the naive build produces one oversized SKILL.md body that tries to describe all three behaviors in a single trigger description. Claude's triggering engine sees an unfocused description, matches it against unrelated prompts ("update the changelog" fires the review handler), and the student has no artifact to point at and say "this is wrong" — because nothing was ever specified as "right." By the time Lesson C.4's eval gate runs, the 10-case evals.json fails in ways that are expensive to diagnose: is the failure in the description, the routing logic, or the handler itself? Nobody wrote down which one owns what.

THE FAILURE MODE

Skipping the architecture document doesn't fail loudly — it fails as scope creep. Three concrete breakages follow directly from it:

1. Handler boundary collision. With no written routing contract, two action handlers get triggered by the same phrasing during manual testing in Module 6 style loops, and the fix becomes patching the description string repeatedly rather than fixing the underlying routing logic — the exact under-triggering/over-triggering failure mode from Lesson 5.2, now multiplied by three handlers instead of one.

2. Untestable eval gate. Lesson C.4 requires a 10-case evals.json with an >80% pass-rate gate before package_skill.py runs. You cannot write meaningful test cases for "the Skill does the right thing" — you can only write test cases against a documented contract: given input X, handler Y should fire, calling headless Claude Code with allowed-tools set Z. No document, no testable contract, no real gate — just a rubber-stamp script.

3. No onboarding surface. Lesson C.5 ships a teammate README and a fresh-install simulation. A README written after the fact describes what the code happens to do; a README derived from an architecture document describes what the system is supposed to do, which is what a teammate installing pr-assistant cold actually needs.

THE CLAUDEFORGE ARCHITECTURE

ARCHITECTURE.md is the single upstream artifact for the rest of Module C. It sits between everything you learned in Modules 5–7 and everything you're about to build: