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.

Transcript

1. Spec-Driven Development with AI Agents @antonarhipov
2. Spec-Driven Development with AI Agents @antonarhipov Context
3. Spec-Driven Development (SDD) * Distill requirements (STOP) * Generate plan (STOP) * Breakdown to tasks (STOP) * Implement (AUTONOMOUS)
4. Spec-Driven Development (SDD) * Distill requirements (STOP) * Generate plan (STOP) * Breakdown to tasks (STOP) * Implement (AUTONOMOUS) What people mean by "SDD"
6. Answer: No
7. In this talk In focus Intuition for SDD The process: proposal -> plan -> tasks -> (execute) SDD toolkits (openspec) Out of focus (but present to some extent) Agentic capabilities: skills, AGENTS.md, commands, etc Benchmarking
8. Implement batch job with Spring Batch with JDBC to import temperature data from csv files into MySQL database.
9. Implement batch job with Spring Batch with JDBC 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 Java 21 compatible features. Use Java records instead of POJOs for data. proposal.md
11. Don't ask the agent to generate the project skeleton. Do it yourself with tools.
12. Par t 1 : The naive process
13. proposal.md Model: GPT-5
14. proposal.md Model: Sonnet 4.5
15. proposal.md Model: Sonnet 4.5 Model: GPT-5
16. plan.md
17. plan.md
18. plan.md
19. plan.md
20. plan.md
21. plan.md "Make no mistakes!"
22. plan.md
23. plan.md prompt
24. plan.md prompt GPT-5
25. plan.md prompt GPT-5 Sonnet 4.5
26. plan.md prompt GPT-5 Sonnet 4.5
27. plan.md
28. Naturally tracking the progress Done Next task
29. proposal.md
30. proposal.md plan.md REVIEW! prompt
31. proposal.md plan.md prompt tasks.md REVIEW! REVIEW! prompt
32. plan.md prompt tasks.md REVIEW! REVIEW! prompt
41. github.com/antonarhipov/eshop
42. github.com/antonarhipov/eshop Terrible layered architecture, it's easier to rewrite than to refactor
43. github.com/antonarhipov/eshop Terrible layered architecture, it's easier to rewrite than to refactor Should use @Transaction(readOnly=true) for read-only operations
44. 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
45. 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
46. Par t 2 : Custom SDD process
47. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt
48. # Role You are a Senior Business Analyst preparing requirements for implementation by an AI coding agent. # Task Analyze the following feature request and identify: 1.AMBIGUITIES - unclear or vague statements that need clarification 2.MISSING INFORMATION - what's not specified but needed for implementation 3.IMPLICIT ASSUMPTIONS - things that seem assumed but should be explicit 4.EDGE CASES - scenarios not addressed in the description 5.CLARIFYING QUESTIONS - questions to ask the stakeholder **Important** Use the AskUserTool to clarify the questions with the user. Ask the questions sequentially, one question at a time, one by one. # Feature Request See @file:proposal.md # Output Format Provide your analysis in structured sections. For each clarifying question, explain WHY this information matters for implementation. # Output File Write the results into spec/requirements.md file
49. # Role You are a Senior Business Analyst preparing requirements for implementation by an AI coding agent. # Task Analyze the following feature request and identify: 1.AMBIGUITIES - unclear or vague statements that need clarification 2.MISSING INFORMATION - what's not specified but needed for implementation 3.IMPLICIT ASSUMPTIONS - things that seem assumed but should be explicit 4.EDGE CASES - scenarios not addressed in the description 5.CLARIFYING QUESTIONS - questions to ask the stakeholder **Important** Use the AskUserTool to clarify the questions with the user. Ask the questions sequentially, one question at a time, one by one. # Feature Request See @file:proposal.md # Output Format Provide your analysis in structured sections. For each clarifying question, explain WHY this information matters for implementation. # Output File Write the results into spec/requirements.md file Previously:
50. # Role You are a Senior Business Analyst preparing requirements for implementation by an AI coding agent. # Task Analyze the following feature request and identify: 1.AMBIGUITIES - unclear or vague statements that need clarification 2.MISSING INFORMATION - what's not specified but needed for implementation 3.IMPLICIT ASSUMPTIONS - things that seem assumed but should be explicit 4.EDGE CASES - scenarios not addressed in the description 5.CLARIFYING QUESTIONS - questions to ask the stakeholder **Important** Use the AskUserTool to clarify the questions with the user. Ask the questions sequentially, one question at a time, one by one. # Feature Request See @file:proposal.md # Output Format Provide your analysis in structured sections. For each clarifying question, explain WHY this information matters for implementation. # Output File Write the results into spec/requirements.md file Force the LLM to ask clarifying questions
53. For the demo: assume the LLM can choose the best option (don't try this at home!)
62. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt
63. # Role You are a QA Architect writing formal acceptance criteria for an AI coding agent. # Context See @file:proposal.md file # Task Analyze the list of requirements in @file:requirements.md Write acceptance criteria using WHEN-THEN-SHALL format. ## Format Rules •WHEN: describes the precondition or trigger •THEN: describes the action or input •SHALL: describes the expected observable outcome •Each criterion must be independently testable •Focus on BEHAVIOR, not implementation •Include happy path, edge cases, and error scenarios •Group criteria by category Output File: Write the results to `spec/acceptance_criteria.md`
64. Looks like a good input for generating the tests
65. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt
66. # Role You are a Software Architect defining technical constraints for an AI coding agent. # Project context See @file:proposal.md # Task Analyze the @file:requirements.md and @file:acceptance_criteria.md and define technical constraints covering: 1. Project structure (packages, modules) 2. Component design (classes, interfaces, patterns) 3. Technology decisions (specific libraries, configurations) 4. Code style (naming, patterns to follow, anti-patterns to avoid) 5. Testing strategy (what to test, how to test) # Output Format Use clear, imperative statements. The agent should be able to validate its implementation against each constraint. # Constraint Categories For each category, specify: • MUST: mandatory requirements • SHOULD: strong preferences • MUST NOT: explicit prohibitions # Output file Write the results to `spec/constraints.md` file and link to the relevant specs
72. Is this all part of the speci fi cation, or could these be agent skills?
73. # Role You are a Specification Reviewer ensuring completeness before implementation. # Task Review the specification package (Requirements + Acceptance Criteria + Technical Spec) and identify any gaps, contradictions, or ambiguities that could cause implementation issues. # Checklist ## Completeness • [ ] Every acceptance criterion has a clear test strategy • [ ] All error scenarios have defined behavior • [ ] Edge cases are explicitly addressed • [ ] Performance requirements are measurable ## Consistency • [ ] No contradictions between acceptance criteria and technical spec • [ ] Package structure supports all specified components • [ ] Data types are consistent throughout ## Implementability • [ ] Technical constraints are specific enough to be validated • [ ] No circular dependencies in component design • [ ] All external dependencies are identified ## Testability • [ ] Each acceptance criterion maps to at least one test case • [ ] Test data requirements are clear • [ ] Success/failure conditions are unambiguous # Output List any issues found with severity (BLOCKER / MAJOR / MINOR) and suggested resolution.
74. "Apply more reasoning effor t "
75. Review and fix the blockers/majors. (I asked the model to go and fix the specs according to the suggested resolution)
76. The agent decided to rewrite the initial specs
77. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt Ready to generate the task list!
78. # Role You are an AI coding agent creating an implementation plan from a specification. # Input • Specification document: @file:proposal.md • Requirements: @file:requirements.md • Acceptance criteria: @file:acceptance_criteria.md * Technical constaints: @file:constraints.md # Task Analyze the specification and produce an EXECUTION PLAN with: 1. Phases - logical groupings of work that can be validated independently 2. Tasks - atomic units of work within each phase 3. Dependencies - what must complete before each task can start 4. Validation criteria - how to verify each task is complete 5. Checkpoints - points where human review is recommended # Plan Requirements ## Task Granularity • Each task should be completable in a single focused effort • Tasks should produce a verifiable artifact (file, test passing, etc.) • Tasks should be small enough to rollback if wrong ## Dependency Rules • No circular dependencies • Minimize cross-phase dependencies • Infrastructure before business logic • Interfaces before implementations ## Checkpoint Placement Place checkpoints after: • Project structure creation • Core domain model completion • Each major component integration • Test suite completion • Final integration # Output Format ```yaml plan: name: "{feature name}" phases: - id: phase-1 name: "{phase name}" description: "{what this phase accomplishes}" tasks: - id: task-1.1 name: "{task name}" description: "{what to do}" artifact: "{file path or outcome}" depends_on: [] validation: "{how to verify completion}" - id: task-1.2 ... checkpoint: description: "{what to review}" criteria: ["{criterion 1}", "{criterion 2}"] ``` # Constraints • Maximum 5 phases • Maximum 7 tasks per phase • Every task must have a validation criterion • Every phase must end with a checkpoint • Report if the result does not fit the constrants IMPORTANT: do not start implementing the tasks, only output the task list # Output File Write the result to spec/plan.yaml file Finally, generate the task list The output doesn't have to be in *.md
80. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt
81. Go to IDE The AGENTS.md only describes how to work with the spec and the task list
82. Progress tracking in a separate file
83. Breaking changes in Spring Batch 5.x- > 6.x The agent needed additional information how to deal with Spring Batch 5.x- > 6.x changes. I created a skill for this purpose
84. The agent repor t ed that its in trouble with Spring Batch Reading the agent skill Correct new impor t s for Spring Batch 6.x
85. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt 1. Refine the initial high- level idea 2. Review and verify the spec 3. Execute task. Use AGENTS.md to steer the agent IMPORTANT: the process and format is not set in stone, you can adjust everything!
86. https://www.softwareseni.com/spec-driven-development-in-2025-the-complete-guide-to-using-ai-to-write-production-code/ https://www.epam.com/insights/ai/blogs/using-spec-kit-for-brown fi eld-codebase https://www.infoq.com/articles/spec-driven-development/ https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html
87. Learn from SDD principles (better planning, structured speci fi cations, architectural thinking) but don't treat it as dogma.
88. speakerdeck.com/antonarhipov @antonarhipov github.com/antonarhipov