Spec Driven Development: API Design First with GitHub Spec Kit and Specmatic MCP

Logos are property of their respective owners

This is a summary of the article originally published on LinkedIn.

Specification Driven Development (SDD) addresses the intent-versus-implementation gap in software development. Coming from an Extreme Programming (XP) background with TDD and fast feedback, SDD resonated as a way to capture intent upfront and leverage coding agents for implementation without deviating from original goals.

Key Takeaways

1. SDD captures intent before implementation — By creating specifications upfront, you avoid the “vibe coding” problem where implementations drift from original intentions, especially important when using coding agents that optimize for speed.

2. GitHub Spec Kit provides structured workflow phases — The tool guides development through four distinct phases: /specify (create feature-level spec), /plan (generate OpenAPI spec as API contract), /tasks (break down implementation), and implement (execute tasks).

3. Specialized sub-agents handle different concerns — Using dedicated agents like api-mock-manager, api-resiliency-tester, contract-test-runner, openapi-spec-author, and ui-component-tester with MCP tools (Playwright MCP and Specmatic MCP) provides focused expertise for each development phase.

4. Three-phase strategy enables parallel development — Build backend independently using contract and resiliency testing with OpenAPI spec, build frontend independently with mock backend using the same spec, then integrate and test end-to-end, creating a true contract-driven workflow.

5. API contract at repo root evolves incrementally — Rather than co-locating specs per feature, maintaining a single evolving OpenAPI specification ensures consistency and prevents endpoint duplication across features.

Read the full article on LinkedIn →

Originally published on LinkedIn on September 9, 2025