Spec-driven development: Using Markdown as a programming language with AI (github.blog)

An engineering manager on GitHub’s Licensing team describes a “spec‑driven” workflow that treats Markdown as the app’s source code: instead of writing Go directly, they author an AI-readable specification (main.md) plus user docs (README.md) and a compile prompt (compile.prompt.md). Using GitHub Copilot’s agent mode in VS Code, the agent compiles main.md into main.go, with a loop of edit-spec → invoke agent → build/test. The spec encodes CLI behavior (pull and mcp commands), a Config struct, GraphQL queries for repos/discussions/issues/pulls, an SQLite schema per org, logging via log/slog, pagination rules, and persistence semantics (save/update by primary key url, stop when updatedAt is older than stored timestamp). A separate lint prompt cleans and normalizes the Markdown spec. This approach is significant because it keeps documentation, design decisions, and implementation in one machine‑readable artifact, reducing the “forgetfulness” and context drift common in AI coding agents and making changes reproducible and portable across agents or languages. Practical notes: it works but compilation slows as generated code grows; tests are still essential; modularizing specs into modules is a next step; and the workflow relies on clear, unambiguous spec writing. The pattern demonstrates a pragmatic way to offload boilerplate and synthesis to AI while preserving explicit architecture and data rules in a single living spec.