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

From Spec to Screen: AI-Driven Development with AI agents (Workshop)

AI coding agents can write code fast, but speed without a structure is just chaos at scale. This workshop gives you a framework that makes AI a reliable, auditable partner: Spec-Driven Development (SDD).

You'll learn to lead an AI agent from high-level requirements through a detailed plan, a task list, and all the way to working software, step by step, with you in control at every stage.

The session is built around a single evolving application:

1. We'll start with a batch application that imports CSV data into a database - simple enough to understand end-to-end, complex enough to feel real.
2. Next, we will add more functionality by turning the batch application into a Spring Boot web service.
3. To have more fun, we'll build a web UI to visualise the data.

While the agent does most of the work for writing code, we will review and discuss the results.

What you'll take away:

* A practical SDD workflow you can apply on your next project — with or without the exact tools shown
* Hands-on experience directing an AI agent in IntelliJ IDEA through structured artifacts
* The confidence to add AI to your process without losing ownership of your codebase

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 Different LLMs, different result - this is expected
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 Again, the result depends on the selected LLM.
32. plan.md prompt GPT-5 Sonnet 4.5
33. plan.md AGENTS.md The prompts are getting more specific to become LLM-agnostic
34. Naturally tracking the progress during the execution Done Next task
35. proposal.md Vague description of the application (or a feature) that we want to build
36. proposal.md plan.md REVIEW! prompt Make the implementation plan
37. proposal.md plan.md prompt tasks.md REVIEW! REVIEW! prompt Make a trackable task list
38. plan.md prompt tasks.md REVIEW! REVIEW! prompt
47. It looks like the naive process could work pretty well!
48. github.com/antonarhipov/eshop Let's try doing something very conventional, a CRUD app with Spring ... and let the teammates to review the result
49. github.com/antonarhipov/eshop Terrible layered architecture, it's easier to rewrite than to refactor
50. github.com/antonarhipov/eshop Terrible layered architecture, it's easier to rewrite than to refactor Should use @Transaction(readOnly=true) for read-only operations
51. 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
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. 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
54. 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
55. Par t 2 : Custom SDD process
56. 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 Let's try building an application, but spend more time planning: refine the proposal into more detailed requirements, acceptance criteria, constraints, etc Demo project
57. 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
58. Put the initial (vague) idea into the proposal.md
59. See the commands and skills in .junie and .claude folders
60. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt
61. 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
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 /clarify
63. # 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
64. # 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
65. # 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
66. The LLM star t s asking questions to clarify the task
68. For the demo: assume the LLM can choose the best option (don't try this at home!)
77. 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
78. # 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
79. Looks like a good input for generating the tests
80. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt /analyze
81. # 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
87. Is this all part of the speci fi cation, or could these be agent skills?
88. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt /constrain
89. # 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
90. "Apply more reasoning effor t "
91. Review and fix the blockers/majors. (I asked the model to fix the specs according to the suggested resolution)
92. The agent decided to rewrite the initial specs
93. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt The validation step will find inconsistencies and update the specs /validate prompt
94. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt Ready to generate the task list! /generate-plan
95. # 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
96. The LLM decided to validate if the plan is a valid YAML file
97. The tasks are grouped into phases
98. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt /generate-plan Now we have the task list; we can proceed with the implementation
99. The AGENTS.md contains the instructions how to work with the spec and the task list
100. Let's ask the agent to implement the tasks in batches, by phases This allows to scope session and keep the context window under control
101. Let's ask the agent to implement the tasks in batches, by phases This allows to scope session and keep the context window under control And we also stay in the loop by reviewing the results after each phase is complete. No vibes!
102. Progress tracking in a separate file, as instructed by AGENTS.md
104. Breaking changes in Spring Batch 5.x- > 6.x
105. The agent needed additional information how to deal with Spring Batch 5.x- > 6.x changes. I created a skill for this purpose
106. 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
107. Phase by phase, eventually, the implementation is complete
108. See the commits in the 'implementation' branch
109. 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
110. 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! /clarify /analyze /constrain /validate /generate-plan
111. 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?
112. 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
113. 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?
114. 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?
115. Spec-Driven Development (SDD) * Distill requirements * Generate plan * Breakdown to tasks * Implement
116. 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
117. Learn from SDD principles (better planning, structured speci fi cations, architectural thinking) but don't treat it as dogma.
118. speakerdeck.com/antonarhipov @antonarhipov github.com/antonarhipov learn.deeplearning.ai/courses/spec-driven-development-with-coding-agents