Spec-Driven Development with AI Agents. Java Day Istanbul 2026

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"
5. Tools Methods Context window
6. Tools Methods Prompt and commands Agent skills Subagents MCP AGENTS.md Context window
7. Tools Methods Prompt and commands Agent skills Subagents MCP AGENTS.md Context window SDD?
8. 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
9. The intuition for SDD Get the thinking right, and any tool becomes your instrument.
10. Implement batch job with Spring Batch and JDBC to import temperature data from CSV files into MySQL database.
11. 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
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 Why not just ...
21. plan.md "Make no mistakes!" Why not just ...
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 AGENTS.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. 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
47. Par t 2 : Custom SDD process
48. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt
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
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 Previously:
51. # 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
52. # 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
55. For the demo: assume the LLM can choose the best option (don't try this at home!)
64. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt
65. # 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`
66. Looks like a good input for generating the tests
67. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt
68. # 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
74. Is this all part of the speci fi cation, or could these be agent skills?
75. # 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
76. "Apply more reasoning effor t "
77. Review and fix the blockers/majors. (I asked the model to go and fix the specs according to the suggested resolution)
78. The agent decided to rewrite the initial specs
79. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt Ready to generate the task list!
80. # 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
82. proposal.md requirements.md prompt acceptance_criteria.md constraints.md plan/tasks prompt
83. Go to IDE The AGENTS.md only describes how to work with the spec and the task list
84. Progress tracking in a separate file
86. Breaking changes in Spring Batch 5.x- > 6.x
87. The agent needed additional information how to deal with Spring Batch 5.x- > 6.x changes. I created a skill for this purpose
88. 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
89. 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!
90. Learn from SDD principles (better planning, structured speci fi cations, architectural thinking) but don't treat it as dogma.
91. Learn from SDD principles (better planning, structured speci fi cations, architectural thinking) but don't treat it as dogma. And please read the code
92. A free course on SDD with AI agents
93. speakerdeck.com/antonarhipov @antonarhipov github.com/antonarhipov learn.deeplearning.ai/courses/spec-driven-development-with-coding-agents