Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Spec-Driven Development with AI-Agents: From Hi...

Sponsored · Ship Features Fearlessly Turn features on and off without deploys. Used by thousands of Ruby developers.

Spec-Driven Development with AI-Agents: From High-Level Requirements to Working Software

AI coding agents are powerful, but they often feel unpredictable. Without structure, they can jump into implementation, miss requirements, or generate code you can’t easily track. Spec-driven development is a practical approach that brings order to this process.

The method is simple: start with clear, high-level requirements, refine them into a detailed development plan, then break that plan into a task list with trackable steps. The AI agent works from these artifacts—requirements.md, plan.md, and tasks.md—instead of ad-hoc prompts. Each step becomes explicit, reviewable, and repeatable.

In this talk, I’ll show how to apply spec-driven development and explain my intuition for this approach. We’ll walk through an example: documenting requirements, generating a plan, creating tasks, and guiding the AI through execution one step at a time. Along the way, you’ll see techniques for controlling workflow, reviewing changes, and avoiding “black box” code generation.

If you’ve tried coding with AI tools but found them chaotic, this session will give you a framework to make them reliable partners.

Avatar for Anton Arhipov

Anton Arhipov

May 24, 2026

More Decks by Anton Arhipov

Other Decks in Programming

Transcript

  1. Spec-Driven Development (SDD) * Distill requirements * Generate plan *

    Breakdown to tasks * Implement Common understanding of what "SDD" means
  2. Tools Methods Context window Prompt and commands MCP Agent skills

    AGENTS.md Subagents Harness Engineering SDD?
  3. Tools Methods Context window Prompt and commands MCP Agent skills

    AGENTS.md Subagents Harness Engineering SDD? BMAD spec-kit Kiro openspec Tessl intent-integrity-chain Toolkits
  4. Implement batch job application to import temperature data from CSV

    files into MySQL database. How many clarifying questions can you ask?
  5. Implement Kotlin CLI application using Spring Boot to import temperature

    data from CSV files into MySQL database. 1. Extract "name", "datetime", and "temp" columns from the csv file, ignore other columns. 2. The "name" and "datetime" columns make a unique pair. 3. The duplicate entries should be reported and ignored. 4. Print the summary, how many records were inserted to the database, and how many duplicates were detected. 5. Use Testcontainers for integration testing (must not use H2). proposal.md Is this detailed enough now?
  6. plan.md The assumption is that datetime will be in parseable

    format, but doesn't specify the format exactly
  7. plan.md It is not possible to track the "plan". Let's

    create an ordered task list that we could track
  8. github.com/antonarhipov/eshop Let's try doing something very conventional, a CRUD app

    with Spring ... and let the teammates to review the result
  9. github.com/antonarhipov/eshop Terrible layered architecture, it's easier to rewrite than to

    refactor Should use @Transaction(readOnly=true) for read-only operations
  10. github.com/antonarhipov/eshop Terrible layered architecture, it's easier to rewrite than to

    refactor Exception handling code duplicated in controllers even if there is a GlobalExceptionHandler Should use @Transaction(readOnly=true) for read-only operations Inefficient use of Spring Data JPA features Testing with H2 - prefer Testcontainers for integration testing Application-specific settings in proper t ies file instead of the database? Mapping of entities to DTO objects should not happen in the service layer
  11. github.com/antonarhipov/eshop Terrible layered architecture, it's easier to rewrite than to

    refactor Mixing SSR and REST API REST API endpoits secured but not configured Exception handling code duplicated in controllers even if there is a GlobalExceptionHandler Should use @Transaction(readOnly=true) for read-only operations String concatenation instead of multi-line strings Inefficient use of Spring Data JPA features Testing with H2 - prefer Testcontainers for integration testing Test data created in test code, Flyway not applied Application-specific settings in proper t ies file instead of the database? Mapping of entities to DTO objects should not happen in the service layer
  12. github.com/antonarhipov/eshop Terrible layered architecture, it's easier to rewrite than to

    refactor Mixing SSR and REST API REST API endpoits secured but not configured Exception handling code duplicated in controllers even if there is a GlobalExceptionHandler Should use @Transaction(readOnly=true) for read-only operations String concatenation instead of multi-line strings Inefficient use of Spring Data JPA features Testing with H2 - prefer Testcontainers for integration testing Test data created in test code, Flyway not applied Application-specific settings in proper t ies file instead of the database? Mapping of entities to DTO objects should not happen in the service layer
  13. github.com/antonarhipov/eshop Lesson learned: if I would spend more time on

    figuring out, what and how exactly the application (or feature) should be built, then I'd get a better result
  14. /spec /criteria /rules /review /plan proposal.md Implement CLI application using

    Spring Boot to import temperature data from CSV files into MySQL database. 1. Extract "name", "datetime", and "temp" columns from the csv file, ignore other columns. 2. The "name" and "datetime" columns make a unique pair. 3. The duplicate entries should be reported and ignored. 4. Print the summary, how many records were inserted to the database, and how many duplicates were detected. 5. Use Testcontainers for integration testing (must not use H2). 6. Use Kotlin 2.3 with the new language features where applicable
  15. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md Clarified proposal We don't want any ambiguities or any open questions to get a predictable result
  16. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md Acceptance criteria in EARS* format * – Easy Approach to Requirements Syntax (EARS)
  17. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md * – Easy Approach to Requirements Syntax (EARS)
  18. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md * – Easy Approach to Requirements Syntax (EARS) Could we merge the spec and criteria?
  19. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md * – Easy Approach to Requirements Syntax (EARS) The two ar t ifacts are coupled and you don't want them to drift.
  20. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md * – Easy Approach to Requirements Syntax (EARS)
  21. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md Capture feature-level design decisions and the technical constraints that follow, traceable to acceptance criteria
  22. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md It's the only place in your pipeline where feature-level design lives.
  23. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md It's the only place in your pipeline where feature-level design lives. Rules is where you record "this feature deviates from AGENTS.md in these specific ways."
  24. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md It's the only place in your pipeline where feature-level design lives. Rules is where you record "this feature deviates from AGENTS.md in these specific ways." Helps traceability of the spec to the implementation
  25. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md Stress-test the spec pipeline outputs against each other and the codebase before implementation begins
  26. Review and fix the blockers/majors. (I asked the model to

    fix the specs according to the suggested resolution)
  27. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md Feed the review results back into the spec
  28. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md The process and format is not set in stone, you can adjust everything! 1
  29. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md DISCUSSION POINT: do you need all these artefacts or is it an overkill?
  30. spec.md criteria.md rules.md /spec /criteria /rules /review /plan review.md plan.yaml

    proposal.md For instance, the technical constraints could be replaced with a reusable agent skill that enforces the style and the technology decisions of your organization Or maybe it's fi ne to create a fl at list of tasks in *.md fi le? And maybe the clarifying promp could be made better to clarify even more details? YAGNI?
  31. Spec-Driven Development (SDD) * Distill requirements * Generate plan *

    Breakdown to tasks * Implement Spend more time clarifying the requirements Clarify details, find missing information, ambiguities, contradictions, etc This will lead to a better result
  32. More tools (skills) to check out * "grill-me" & "grill-me-with-docs"

    * superpowers * BMAD, openspec, spec-kit, tessl
  33. More tools (skills) to check out * "grill-me" & "grill-me-with-docs"

    * superpowers * BMAD, openspec, spec-kit, tessl Very useful for planning for your workflow with AI agents, with or withough adopting SDD
  34. More tools (skills) to check out * "grill-me" & "grill-me-with-docs"

    * superpowers * BMAD, openspec, spec-kit, tessl Now that you understand the idea, pick the tools as you like!
  35. Learn from SDD principles (better planning, structured speci fi cations,

    architectural thinking) but don't treat it as dogma.