Spec-Driven Development with AI Agents (Workshop, May 2026)

Transcript

1. From Spec to Screen Spec-Driven Development with AI Agents @antonarhipov
2. From Spec to Screen Spec-Driven Development with AI Agents @antonarhipov Context
3. Expectations management github.com/antonarhipov/sdd-workshop gist.github.com/antonarhipov
4. Expectations management * Application: CSV -> DB -> Web -> UI github.com/antonarhipov/sdd-workshop gist.github.com/antonarhipov
5. Expectations management * Application: CSV -> DB -> Web -> UI * Use: AI agents github.com/antonarhipov/sdd-workshop gist.github.com/antonarhipov
6. Expectations management * Application: CSV -> DB -> Web -> UI * Use: AI agents * Learn: Spec-Driven Development github.com/antonarhipov/sdd-workshop gist.github.com/antonarhipov
7. Expectations management * Application: CSV -> DB -> Web -> UI * Use: AI agents * Learn: Spec-Driven Development * Side effect: explore Intell iJ IDEA github.com/antonarhipov/sdd-workshop gist.github.com/antonarhipov
8. Spec-Driven Development (SDD)
9. Spec-Driven Development (SDD) * Distill requirements * Generate plan * Breakdown to tasks * Implement What people generally mean by "SDD"
10. Tools Methods Context window
11. Tools Methods Prompt and commands Agent skills Subagents MCP AGENTS.md Context window
12. Tools Methods Prompt and commands Agent skills Subagents MCP AGENTS.md Context window SDD?
13. Tools Methods Prompt and commands Agent skills Subagents MCP AGENTS.md Context window SDD? BMAD spec-kit Kiro openspec agent-os intent-integrity-chain Toolkits
14. The intuition for SDD Get the thinking right, and any tool becomes your instrument.
15. Implement batch job with Spring Batch and JDBC to import temperature data from CSV files into MySQL database. How many clarifying questions can you ask?
16. Implement batch job with Spring Batch and 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 Is this detailed enough now?
17. Par t 1 : The naive process
18. proposal.md Model: GPT-5
19. proposal.md Model: Sonnet 4.5
20. proposal.md Model: Sonnet 4.5 Model: GPT-5
21. plan.md
22. plan.md
23. plan.md
24. plan.md
25. plan.md Why not just ...
26. plan.md "Make no mistakes!" Why not just ...
27. plan.md It is not possible to track the "plan". Let's create an ordered task list that we could track
28. plan.md prompt
29. plan.md prompt GPT-5
30. plan.md prompt GPT-5 Sonnet 4.5
31. plan.md prompt GPT-5 Sonnet 4.5
32. plan.md AGENTS.md
33. Naturally tracking the progress Done Next task
34. proposal.md
35. proposal.md plan.md REVIEW! prompt
36. proposal.md plan.md prompt tasks.md REVIEW! REVIEW! prompt
37. plan.md prompt tasks.md REVIEW! REVIEW! prompt
46. It looks like the naive process could work pretty well!
47. github.com/antonarhipov/eshop Let's try doing something very conventional, a CRUD app with Spring ... and let the team mates to review the result
48. github.com/antonarhipov/eshop Terrible layered architecture, it's easier to rewrite than to refactor
49. github.com/antonarhipov/eshop Terrible layered architecture, it's easier to rewrite than to refactor Should use @Transaction(readOnly=true) for read-only operations
50. 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
51. 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
52. 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
53. Implement batch job with Spring Batch and 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 github.com/antonarhipov/sdd-workshop gist.github.com/antonarhipov
54. Par t 2 : Custom SDD process
55. github.com/antonarhipov/sdd-workshop See the specification ar t efacts and the commands and/or skills in .claude and .junie directories
57. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt
58. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt This is just a custom process that demonstrates the idea of refining the vague proposal into detailed specification and implementation plan
59. # 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 /clarify
60. # 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: /clarify
61. # 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 Make the LLM find what's missing from the initial proposal /clarify
62. # 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 /clarify
63. The LLM star t s asking questions to clarify the task
65. For the demo: assume the LLM can choose the best option (don't try this at home!)
74. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt This is the first ar t efact for the spec, describing what we are going to build /clarify
75. # 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` /analyze
76. Looks like a good input for generating the tests
77. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt /analyze
78. # 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 /constrain
84. Is this all part of the speci fi cation, or could these be agent skills?
85. # 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. What if we make the LLM to review the specs /validate
86. "Apply more reasoning effor t "
87. Review and fix the blockers/majors. (I asked the model to fix the specs according to the suggested resolution)
88. The agent decided to rewrite the initial specs
89. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt Ready to generate the task list! /validate
90. # 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
91. The LLM decided to validate if the plan is a valid YAML file
92. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt /generate-plan
93. Go to IDE The AGENTS.md only describes how to work with the spec and the task list
94. Progress tracking in a separate file
96. Breaking changes in Spring Batch 5.x- > 6.x
97. The agent needed additional information how to deal with Spring Batch 5.x- > 6.x changes. I created a skill for this purpose
98. 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
99. 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!
100. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt DISCUSSION POINT: do you need all these artefacts or is it an overkill?
101. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt DISCUSSION POINT: do you need all these artefacts or is it an overkill? For instance, the technical constraints could be replaced with a reusable agent skill that enforces the style and the technology decisions of your organization
102. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt DISCUSSION POINT: do you need all these artefacts or is it an overkill? 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?
103. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt DISCUSSION POINT: do you need all these artefacts or is it an overkill? 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?
104. Learn from SDD principles (better planning, structured speci fi cations, architectural thinking) but don't treat it as dogma.
105. github.com/antonarhipov/sdd-workshop speci fi cation artefacts Implementation of the initial spec: CSV fi le to DB import UI implementation using superpowers plugin UI implementation using superpowers plugin initial state
106. speakerdeck.com/antonarhipov @antonarhipov github.com/antonarhipov learn.deeplearning.ai/courses/spec-driven-development-with-coding-agents