Module 01Term 1 · Foundations

The AI-Assisted Engineering Workflow

Sign in to save your progress across devices. Until then it is kept in this browser.

Why this matters

DORA's 2025 research describes AI as an amplifier of whatever system it lands in. Teams with small batches, tests and fast feedback get faster. Teams without them ship bugs faster. This module installs the system before you install more AI.

Learning outcomes

  1. Write a spec and acceptance tests that an AI can build against.
  2. Engineer context: rules files, architecture notes, examples, constraints.
  3. Work in small, reviewable batches with git as the safety net.
  4. Review AI output systematically, and make the AI prove its claims.
  5. Measure delivery with the five DORA metrics.

Lessons

1.1 Spec first, prompt second

A good AI task contains: goal, context, constraints, interfaces, acceptance criteria, out of scope.

GOAL: Users can reset their password by email.
CONTEXT: Next.js app router, Supabase auth, Resend for email. See /docs/architecture.md.
CONSTRAINTS: Token single-use, expires in 30 min, stored hashed. Rate limit 5 requests/hour per email and per IP. Same response whether or not the email exists.
ACCEPTANCE: tests in /tests/reset.spec.ts must pass (write them first).
OUT OF SCOPE: SMS reset, UI redesign.

1.2 Context engineering

  • A repo-level rules file (AGENTS.md Template) with standards the AI must follow every time.
  • /docs/architecture.md: components, data flow, trust boundaries.
  • /docs/decisions/: ADRs so the AI does not re-litigate settled choices.
  • Point the AI at one good existing example in the codebase; it will copy patterns faithfully, good or bad.

1.3 Small batches and git discipline

  • One feature per branch; one concern per commit.
  • Commit before every AI session so you can git diff everything it changed and git restore anything you dislike.
  • Never let an agent run git push --force, migrations against production, or delete commands without approval.
  • Small changes are the single most effective lever DORA identifies for both speed and stability.

1.4 Testing as the specification

The testing pyramid, adapted for AI:

  • Unit tests: pure logic (pricing, eligibility, validation).
  • Integration tests: real database in Docker, real queries, real RLS policies.
  • End-to-end tests: Playwright on critical journeys (sign-up, pay, core action).
  • Security tests: authorization tests for "user A cannot read user B's data." The most valuable test you will write.
  • Evals: for LLM features (see 06 · AI and Agent Security).

Rule: write or review the tests yourself; let the AI write the implementation. If the AI writes both, it can make both wrong in the same way.

1.5 Reviewing AI output

The review checklist (paste into your PR template):

  1. Does every endpoint check who is calling and whether they own the resource?
  2. Any secret, key or token outside server-side env?
  3. Any external call without a timeout?
  4. Any DB query inside a loop?
  5. Any new dependency? Does it exist, is it maintained, is it pinned?
  6. Are errors handled, logged and surfaced, or swallowed?
  7. Is the change reversible? Is there a migration? Is it backwards compatible?
  8. Did it touch files outside the task scope?

Make the AI prove claims: "Run the tests and paste the output." "Show me the EXPLAIN plan." "Show the curl that proves user A gets 403 on user B's record."

1.6 Measuring delivery: DORA's five metrics

Group Metric
Throughput Change lead time; Deployment frequency; Failed deployment recovery time
Instability Change fail rate; Deployment rework rate

DORA warns against turning these into targets (Goodhart's law). Use them to find bottlenecks.

1.7 Quality basics the AI skips

Linting and formatting in CI, TypeScript strict mode, accessibility (semantic HTML, labels, keyboard navigation, contrast to WCAG 2.2 AA), and input validation with a schema library (Zod, Valibot) at every boundary.

Lab 1: Build a feature the professional way

Build "password reset" or "invite a teammate" using the spec template.

  1. Write the spec and the tests first (AI may help draft, you approve).
  2. Have the AI implement in a branch.
  3. Review with the checklist; log every issue found.
  4. Open a PR; CI must run lint, type-check and tests.

Definition of Done

AI prompt pack

  • "Before writing code, list the edge cases and failure modes for this spec. Do not implement yet."
  • "Write tests that would fail if authorization were missing."
  • "Review this diff as a hostile senior engineer. List problems only, ranked by severity."