Spec-Driven Development Analysis
Specifications are the product. Code is the derivative.
The core insight behind HDIM's delivery velocity is that AI assistants produce dramatically better output when given complete architectural specifications rather than ad-hoc prompts. This page documents the specification structure, the AI workflow it enables, and the success factors that made it work for a 51-service healthcare platform.
Specification Structure
Every HDIM service was generated from a specification document containing six mandatory sections. This structure was designed to provide AI assistants with complete context while fitting within context window limits.
1. Purpose & Scope
Defines what the service does, which domain it belongs to, and its boundaries. Includes the service name, port assignment, database name, and upstream/downstream dependencies. This section prevents AI from generating features outside the service's responsibility.
2. API Contracts
Complete REST endpoint definitions including HTTP method, path, request/response schemas, status codes, and required headers. Specifies X-Tenant-ID and authentication requirements per endpoint. AI generates controller classes, request validation, and OpenAPI annotations directly from these contracts.
3. Data Models
Entity definitions with column names, types, constraints, and relationships. Includes the Liquibase migration structure so database schema and JPA entities are generated in lockstep. Specifies tenant isolation columns and audit fields (created_at, updated_at, tenant_id).
4. Integration Points
Defines how the service communicates with other services: Feign client interfaces, Kafka topic names and event schemas, Redis cache keys and TTL values. This section is critical for cross-service consistency. When two services share a Kafka topic, both specifications reference the same topic name and event schema.
5. Security Requirements
Role-based access control matrix per endpoint. Specifies which roles (SUPER_ADMIN, ADMIN, EVALUATOR, ANALYST, VIEWER) can access each operation. Includes HIPAA-specific requirements: PHI cache TTL limits, audit logging directives, and no-cache response headers for sensitive endpoints.
6. Testing Requirements
Defines required test categories: unit tests for service methods, integration tests for API endpoints, entity-migration validation tests, multi-tenant isolation tests, and RBAC permission tests. Includes specific test scenarios that must pass before the service is considered complete.
AI Assistant Workflow
The specification structure enables a four-step workflow that produces production-quality code with minimal manual intervention.
The AI assistant receives the complete specification document. The six-section structure fits within context windows while providing full architectural context. The AI understands not just what to build, but how it fits into the broader system.
From a single specification, the AI generates: JPA entities, Liquibase migrations, repository interfaces, service classes, REST controllers, Feign clients, Kafka producers/consumers, configuration files, and test classes. All artifacts conform to the patterns defined in the spec.
The architect reviews generated code against the specification. Review focuses on architectural conformance, not syntactic correctness. Common review items: cross-service contract alignment, security annotation completeness, and migration rollback coverage.
When review reveals gaps, the architect updates the specification rather than manually editing generated code. The AI regenerates from the updated spec. This keeps the specification as the single source of truth and prevents spec-code drift.
Success Factors
Spec-driven development with AI is not automatic. Several factors determined whether the approach produced maintainable production code or generated plausible-looking artifacts that failed under real conditions.
- Specification completeness matters more than specification length. A concise spec with all six sections outperforms a verbose spec missing security or testing requirements.
- Cross-service contracts must be synchronized. When the patient-service spec defines an event schema, the care-gap-service spec must reference the identical schema.
- The architect must understand the generated code deeply enough to review it. Spec-driven development does not eliminate the need for engineering expertise. It amplifies it.
- Migration files must never be regenerated. Once a Liquibase migration is committed, it is immutable. New changes require new migration files. This was enforced by convention and CI validation.
- Test requirements in specs must be specific. Saying "add unit tests" produces generic tests. Saying "test that tenant A cannot access tenant B's patients" produces meaningful validation.
- Context window management is a skill. Specifications were structured to provide maximum architectural context within token limits, with cross-references to related specs rather than inline duplication.
Methodology Comparison
| Dimension | Prompt-Driven | Spec-Driven |
|---|---|---|
| Input to AI | Natural language prompt | Structured specification document |
| Output scope | Single file or function | Complete service (10-20 files) |
| Architectural coherence | Depends on prompt quality | Enforced by spec structure |
| Reproducibility | Low — prompts are informal | High — specs are versioned documents |
| Review efficiency | Line-by-line code review | Spec-conformance review |
| Iteration cost | Manual editing of generated code | Update spec, regenerate |
| Cross-service consistency | Manual coordination | Shared contract definitions |
| Onboarding value | Prompts are ephemeral | Specs serve as living documentation |
Results by the Numbers
See How It Compares
Explore the methodology differences and real-world delivery outcomes.