Build 12 lesson 03: Architecture Decision Records (ADRs) + Human Review for Safe AI Deployments

Описание: Learn how to write production-grade Architecture Decision Records (ADRs) and add a human review gate to your canary deployment pipeline — the same structural fix that prevents “perfect metrics, bad release” failures in real AI systems.

In Cortex Build 12, Lesson 03, we document real architecture decisions using the Michael Nygard ADR format (Title, Status, Context, Decision, Consequences) and make technical writing testable with automated structural quality checks — not subjective prose grading.

What You'll Learn
How to write Architecture Decision Records (ADRs) that teams actually use
The Michael Nygard ADR template explained with real examples
How to enforce ADR quality with pytest structural checks (alternatives, negative consequences, substantive context)
Why quantitative metrics alone are not enough for safe ML/AI rollouts
How to implement a human_review_required override in a canary controller
How to close deployment gaps found in postmortem audits (including lessons from real-world AI incidents)
Three Real ADRs Covered
ADR-001 — OCR as Bridge for Multimodal Retrieval
Documents why Cortex uses OCR instead of a joint embedding model when CLIP-class models are unavailable — a practical multimodal retrieval decision for production RAG systems.

ADR-002 — Redis Streams Instead of Kafka
Explains the streaming ingestion pipeline choice when a real Kafka broker cannot run in the target environment — consumer groups, crash recovery, and pragmatic infrastructure trade-offs.

ADR-003 — Human Review Override for Canary Promotion
A new, implemented decision: block canary promotion even when Hit@1 scores are perfect, until a human reviewer clears qualitative concerns — closing the exact gap that allowed problematic AI updates to ship despite expert warnings.

The Core Problem This Lesson Solves
Automated canary controllers that promote solely on quantitative thresholds can miss qualitative regressions — behavior that “feels off” but still passes metrics. This lesson shows the fix in code and documents it in ADR-003 so architecture docs and implementation stay in sync.

Without human review: high-scoring candidates promote normally.
With human_review_required: promotion is held back despite perfect scores until review is cleared.


Keywords:
Architecture Decision Records, ADR template, Michael Nygard ADR, technical writing for engineers, software architecture documentation, canary deployment Python, ML deployment safety, human-in-the-loop review, AI rollout best practices, postmortem-driven engineering, Redis Streams vs Kafka, multimodal retrieval OCR, pytest architecture tests, Cortex AI series, production ML engineering