Learn how to write precise specifications before prompting an AI coding tool, so the generated code is more reliable and testable.
Use SpecKit to turn a project idea into a constitution, numbered requirements, and a task list an AI agent can implement.
Study a real safety-critical system (medication alerts) to see how spec-driven development handles strict state transitions and audit logging.
See a side-by-side comparison of vague-prompt vs specification-driven AI output to understand the concrete difference in code quality.
Primarily slides and TypeScript demo code from a conference talk. Clone the repo and follow the README to run the MDAM demo locally.
This repository accompanies a conference talk titled "Spec First, Agents Second: Engineering AI Systems with Discipline," presented at Open Source North 2026. The talk's central argument is that AI coding tools produce better results when given precise written specifications to work from, rather than vague natural-language prompts. The slides are included in the repository. The repository also contains the source code for a live demo system called MDAM, short for Medication Dose Alert Monitor. MDAM tracks scheduled medication doses in a care setting, detects any dose that goes unacknowledged past a configurable time threshold (the default is 15 minutes), alerts the care team, and then escalates to a charge nurse if the alert is still open after another window (10 minutes by default). Every state change is written to an append-only audit log before the change commits, and closing any alert requires authenticated acknowledgment. The talk uses this system specifically because it concentrates several engineering challenges into a small surface area: timing constraints with clear boundaries, strict state transitions, safety-critical behavior where silent failure is the worst outcome, and real accountability obligations. The README includes a direct comparison between how a vague prompt would produce this system versus how a specification-driven prompt does, showing the concrete differences in code structure, testability, and traceability. The demo walks through a tool called SpecKit, which generates a project constitution (non-negotiable principles and safety constraints), numbered requirements, an architecture plan, and an implementation task list. From those artifacts, an AI coding agent implements the code, and every exported function is annotated with the requirement number it satisfies. The test suite is also organized by requirement number. The code is TypeScript, written with strict typing, pure functions, and timestamps injected as arguments so the business logic has no hidden dependencies on the system clock.
← justingrammens on gitmyhub — every repo by this author, as a profile.
Verify against the repo before relying on details.