Skip to content
SE Course

Module 4 — Specs, rules & AI-assisted development

Estimated: 1 week · Syllabus · ← Module 3 · Next → Module 5

Concepts

Section titled “Concepts”
  • Spec-driven development. Write the specification — inputs, outputs, edge cases, invariants, constraints — before implementation. Benefits compound with AI: a precise spec is a precise target, and vague prompts yield vague code. The spec is also your test oracle.
  • Levels of specification. Informal (prose), semi-formal (schemas, types, examples), formal (mathematical contracts). You’ll live mostly in semi-formal — types and schemas are specs the machine checks.
  • Design by contract (Bertrand Meyer). Every function has preconditions (what must be true on entry), postconditions (what it guarantees on exit), and invariants (what stays true throughout). Encode these as types, assertions, and validation.
  • Rules files for AI tools. A CLAUDE.md (and Antigravity’s equivalent) at the repo root injects your conventions, architecture, and gotchas into AI context every session — so the assistant follows your standards without re-explanation. Treat it as living documentation; stale rules actively mislead.
  • Working effectively with an AI collaborator. Give it the spec and the constraints, not just the ask. Review its output as you’d review a junior engineer’s — the responsibility for correctness stays with you. Small, well-specified units produce better AI output than sprawling vague ones.
  • Encoding invariants in code, not prose. TypeScript’s strict mode + Zod schemas (validated at runtime, inferred into static types) and assertions turn “please remember X” into “the machine enforces X.” A Zod schema is a spec the compiler and the runtime both check — and one definition gives you both the type and the validator.

Practice

Section titled “Practice”
  • Write a real spec for Project B (FeeForge)’s core: the fee-model schema as Zod (phases, disciplines, line items, rates, multipliers, contingency), with each business rule stated as precondition/postcondition (e.g. precondition: every line item’s rate ≥ 0; postcondition: total fee = Σ(hours × rate) × (1 + contingency), never negative). Define the proposal and template schemas the same way.
  • Author a CLAUDE.md for Project B: stack, structure, the pure-domain boundary, the schemas, conventions, and “don’t do X” rules (e.g. “the fee engine must not import from app/ or lib/db”). Do the equivalent rules file for Antigravity.
  • Implement the fee-calculation engine from the spec, using Claude — a pure, well-specified module is the ideal case for AI collaboration and for the next module’s testing.

This repo is itself an example. CLAUDE.md at the root of the course repo is exactly the artifact this module describes. Read it as a worked sample before writing FeeForge’s — including where it falls short.

Milestone

Section titled “Milestone”

☐ A Zod-backed fee-model schema, a spec doc, a CLAUDE.md, and a working pure fee calculator that computes a real proposal’s fee from structured input.

Notes

Section titled “Notes”

(working notes go here)