{"slug": "spec-driven-development-with-ai-a-new-approach-and-a-journey-into-the-past", "title": "Spec-Driven Development with AI: A New Approach and a Journey into the Past", "summary": "A software development methodology that makes requirements the single source of truth and uses AI tools such as Claude Code to generate downstream artifacts has produced better business alignment, maintainable code, and complete traceability from business needs to implementation, according to its developer. The approach combines Rational Unified Process (RUP) ideas with modern AI tooling, storing all specifications as Markdown and PlantUML diagrams in Git alongside application code, and organizes systems into independent epics such as UC-EVENT-001, UC-USER-001, and UC-ORG-001 with no cross-epic dependencies. The developer argues code-centric AI coding tools like Claude Code, Windsurf, and JetBrains Junie accelerate the same maintenance problems by generating code faster without keeping requirements current.", "body_md": "The software development world is buzzing about AI-assisted coding. Tools like Claude Code, Windsurf, and JetBrains Junie promise to make us more productive. But most approaches focus on generating code faster – they’re still **code-centric**.\n\nWhat if we took a different approach? What if we made **requirements** the source of truth and let AI do the work downstream, with us reviewing it?\n\nAfter years of building business applications, I started to develop a methodology that combines ideas of the [Rational Unified Process](https://en.wikipedia.org/wiki/Rational_unified_process) (RUP) with modern AI tooling. The results are remarkable: better business alignment, maintainable code, and complete traceability from business needs to implementation.\n\n## The Problem with Code-Centric Development\n\nTraditional development follows this pattern:\n\n1. Write requirements documents\n2. Code the application\n3. Add tests (maybe)\n4. Update documentation (rarely)\n\nThe problem? Code becomes the source of truth. Requirements documents get outdated. When bugs appear or features need changes, we dig through the code to understand what the system was supposed to do. It even gets worse if we must modernize the application a few years later.\n\nAI coding tools make this worse by generating code faster. We’re accelerating toward the same maintenance problems we’ve always had.\n\n## Requirements as the Single Source of Truth\n\nMy approach flips this around. Requirements stay at the center, and everything else follows from them:\n\n### The Complete Workflow\n\n1. **Business Requirements Catalog** (manual, with business stakeholders)\n2. **Business Use Case Diagrams** (AI-generated, then reviewed with business stakeholders)\n3. **Entity Models** (AI-derived from requirements catalog, reviewd by the business)\n4. **System Use Case Diagrams** (AI-generated and revised by the developer and/or business)\n5. **System Use Case Specifications** (AI-generated, detailed markdown, revised by the developer and/or business)\n6. **Application Code** (AI-generated, reviewed by developer)\n\nThe key: **Every step gets reviewed and revised by the business team.** They validate not just the business artifacts, but also the entity models and system use cases. This catches domain modeling errors before they become expensive code problems.\n\n### Everything is Code, Everything is Versioned\n\nAll specifications are written in Markdown and stored in Git alongside the application code. Use case diagrams are generated as PlantUML source code. This gives us:\n\n- **Visual diffs** : See exactly what changed in diagrams\n- **Complete audit trails** : Track every change from requirements to code\n- **Version control** : Branch specifications alongside code\n- **Collaborative editing** : Business stakeholders can request specific changes\n\n### AI as the Consistency Engine\n\nWhen requirements change, AI tools like Claude Code update all downstream artifacts automatically:\n\n- Update the affected use case diagrams\n- Update entity models\n- Modify system specifications\n- Update the application code\n- Maintain traceability links\n\nNo manual synchronization. No outdated documentation. No guessing what the system should do.\n\n## The Structure: Independent Epics\n\nBusiness applications are complex, but that doesn’t mean they have to be complicated. I organize everything into independent epics:\n\n- **Event Management** : UC-EVENT-001, UC-EVENT-002, etc.\n- **User Management** : UC-USER-001, UC-USER-002, etc.\n- **Organization Management** : UC-ORG-001, UC-ORG-002, etc.\n\nNo cross-epic dependencies. Each epic is a bounded context that can be developed, tested, and deployed independently. This simplifies both the AI generation process and the overall system architecture.\n\n## A Real Example: System Use Case Specification\n\nHere’s how a system use case looks in practice:\n\n```\n# Use Case: Create Events\n\n**Use Case ID:** UC-EVENT-001  \n**Primary Actor:** Manager  \n**Goal:** Allow managers to create new events for their organization\n\n## Main Success Scenario\n1. Manager navigates to \"Events\" section\n2. Manager clicks \"Create New Event\" button\n3. System displays event creation form\n...\n\n## Business Rules\n### BR-EVENT-001: Event Date Validation\n- End date must be equal to or after start date\n- Events cannot be created with start dates in the past\n\n## Technical Notes\n### Validation Rules\n- Title: Required, 3-200 characters\n- Start Date: Required, must be future date\n- End Date: Required, must be >= start date\n```\n\nThis level of detail gives AI tools everything they need to generate correct, complete implementations. Business stakeholders can understand the main flow, while developers get precise technical requirements.\n\n## The Results\n\nThis approach has transformed how I build business applications:\n\n**Better Business Alignment**: Business stakeholders review every artifact, ensuring the system matches their actual needs.\n\n**Maintainable Code**: When requirements change, everything downstream updates consistently. No drift between documentation and implementation.\n\n**Faster Development**: AI handles the tedious work of generating diagrams, specifications, and code. Business stakeholders concentrate on providing the requirements and reviewing the specification. Developers focus on business logic and architecture.\n\n**Complete Traceability**: From a business requirement to a line of code, every connection is maintained and visible.\n\n**Quality Assurance**: Generated code includes comprehensive tests based on the use case specifications.\n\n## Why This Works for Business Applications\n\nBusiness applications have predictable technical patterns but more or less complex domain logic. Frameworks like Vaadin, Spring Boot, and jOOQ provide stable foundations (see [the Simon Martinelli Stack](https://martinelli.ch/the-simon-martinelli-stack-a-pragmatic-approach-to-full-stack-java-development/)). The real complexity lies in understanding and modeling the business domain correctly.\n\nThis methodology plays to both strengths:\n\n- Human expertise handles business domain complexity\n- AI handles consistent technical implementation\n\n## Getting Started\n\nIf you want to try this approach:\n\n1. **Start with requirements** : Don’t jump to code. Invest time in understanding and documenting business needs.\n2. **Make everything code** : Use markdown for specifications, PlantUML for diagrams. Version everything in Git.\n3. **Review with business** : Get stakeholders to validate not just business artifacts, but also entity models and system use cases.\n4. **Use AI as your consistency engine** : Let tools like Claude Code handle generation and updates.\n5. **Keep epics independent** : Avoid cross-dependencies to simplify both development and AI generation.\n\n## The Future of Business Application Development\n\nWe’re at an inflection point. AI can generate high-quality code, but only if we give it high-quality specifications. The organizations that invest in better requirements processes will build better software faster.\n\nThis isn’t about replacing developers with AI. It’s about using AI to eliminate the tedious, error-prone work so we can focus on what matters: understanding business needs and designing systems that serve them well.\n\nThe code is the easy part. Getting the requirements right is where the real value lies.\n\nRead more: [https://unifiedprocess.ai](https://unifiedprocess.ai)", "url": "https://wpnews.pro/news/spec-driven-development-with-ai-a-new-approach-and-a-journey-into-the-past", "canonical_source": "https://martinelli.ch/spec-driven-development-with-ai-a-new-approach-and-a-journey-into-the-past/", "published_at": "2026-10-09 18:09:26+00:00", "updated_at": "2026-10-09 18:23:44.233016+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["Claude Code", "Windsurf", "JetBrains Junie", "Rational Unified Process", "Git", "PlantUML"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/spec-driven-development-with-ai-a-new-approach-and-a-journey-into-the-past", "markdown": "https://wpnews.pro/news/spec-driven-development-with-ai-a-new-approach-and-a-journey-into-the-past.md", "text": "https://wpnews.pro/news/spec-driven-development-with-ai-a-new-approach-and-a-journey-into-the-past.txt", "jsonld": "https://wpnews.pro/news/spec-driven-development-with-ai-a-new-approach-and-a-journey-into-the-past.jsonld"}}