Beginner's Guide to Spec-Driven Development (SDD) With OpenSpec

Summary

The video is a beginner’s guide to spec-driven development (SDD) using OpenSpec. The presenter explains how written specifications can help AI coding agents work reliably across multiple sessions, then demonstrates the workflow by planning and building a simple Kotlin Multiplatform to-do app.

Why Use Spec-Driven Development?

AI sessions have limited context. When a developer starts a new session, the agent may not remember earlier discussions, design decisions, or requirements. SDD addresses this by recording project context in Markdown files that remain available in the codebase.

A specification is developed before implementation. It describes what the software should do, why it is needed, and how the work can be divided into tasks. These documents become a persistent source of context for both agents and developers. The presenter describes this as a form of context engineering.

OpenSpec Compared with Other Approaches

The presenter compares OpenSpec with GitHub Spec Kit and the spec-oriented IDE Windsurf (rendered as “Cairo” in the subtitles):

• GitHub Spec Kit: The presenter considers it too verbose, with lengthy documents and a multi-step process.
• Windsurf: It offers built-in spec features, but the presenter sees using a dedicated IDE as potentially limiting—especially for mobile development, where Android Studio or Xcode may be preferable.
• OpenSpec: The presenter describes it as lightweight and flexible. Teams can adjust the level of specification detail and customize templates. Its delta specifications document changes to existing requirements rather than rewriting the full specification, which the presenter finds useful for existing projects.

These are the presenter’s personal assessments, based on his experience.

OpenSpec Setup and Workflow

OpenSpec is installed as a CLI tool and initialized in a project from a regular terminal with openspec init. During setup, users select the AI agent tools they want OpenSpec to configure. The resulting project setup includes agent commands or skills. The presenter focuses on four:

1. Explore — Discuss and clarify an idea with an agent before creating specification files. The agent asks questions to resolve missing or ambiguous requirements.
2. Propose — Turn the agreed-upon requirements into project artifacts, including specifications, a design document, and an implementation task list.
3. Apply — Implement the proposed change using the saved documents as context. Work can be done in stages or across separate sessions.
4. Archive — Complete the workflow by archiving finished changes. This step is listed but not demonstrated in detail.

The OpenSpec configuration file, config.yaml, can hold project-wide context, such as technology choices, coding conventions, and guidance that applies across changes. The presenter cautions against putting feature-specific details there.

Demonstration: A To-Do App

The example project is a basic to-do app using Compose Multiplatform, Material 3, and a local Room database. During exploration, the presenter clarifies requirements with the agent, including:

• List and task-details screens, with create, edit, delete, and completion-status features.
• Filters for all, open, and completed tasks.
• A delete confirmation dialog.
• A save button rather than autosaving.
• A save action that is disabled when the task title is empty.
• Support for Android and iOS.

The example shows why discussion before implementation matters: an initially proposed autosave behavior revealed edge cases, so the requirement was revised during planning.

OpenSpec Artifacts

The proposal creates files in an active-change folder under openspec/changes. The demonstrated structure includes:

• Capability specifications: Describe requirements for distinct parts of the change, such as the app shell, task list, task details, and persistent storage. They focus on what the feature should do and why, rather than on source-code implementation.
• Proposal: Summarizes why the change is being made, what it includes, and which capabilities are new or changing.
• Design document: Records technical implementation decisions, constraints, goals, and non-goals.
• Tasks document: Breaks implementation into checkable steps. Completed tasks can be tracked, and work can be split across sessions.

The presenter emphasizes that these documents are relatively concise and can be reviewed or revised in natural language before implementation begins.

Implementation and Testing

After reviewing the documents, the presenter starts a new agent session and applies the change. The agent can use the saved Markdown files to recover requirements and decisions without relying on the previous session’s conversation.

The generated app is run on an emulator, where the presenter manually checks task creation, editing, completion toggling, filtering, and deletion. An iOS version is also shown.

The presenter warns that having an agent test an app by clicking through the UI can be slow. For larger or production projects, he recommends a broader validation workflow with unit tests, UI or end-to-end tests, and other checks. OpenSpec helps organize AI-assisted development, but specifications alone do not prove that an implementation works.

Main Guide Points

• Preserve important project context in specifications instead of relying on an AI session’s memory.
• Clarify requirements and edge cases before implementation.
• Review and revise the proposal, design, and task files before applying a change.
• Use project-wide configuration only for guidance that applies broadly.
• Start a fresh agent session when useful; the saved artifacts provide continuity.
• Pair specification-driven work with appropriate automated testing and validation.

Main Speaker

• Philipp Lackner — presenter and narrator.