Composable, layered spec systems that scale with complexity
Single-document specifications work well for simple projects, but they become unwieldy bottlenecks as system complexity grows. Teams find themselves wrestling with massive specification documents that are difficult to maintain, impossible to navigate, and create coordination nightmares across multiple developers and domains.
In my previous article on how AI-DLC implements spec-driven development, I mentioned advanced techniques with adaptive specifications at different abstraction levels. This post explores those techniques in depth, focusing on two core principles that enable AI-DLC to scale beyond simple projects: composable specifications and horizontal versus vertical specification architecture.
These aren’t just theoretical concepts—they’re battle-tested approaches for teams ready to move beyond basic AI-assisted development into sophisticated specification architectures that can handle real-world complexity while maintaining the velocity benefits that make AI-DLC transformative.
Composable Specifications: Principles and Tenets Link to heading
Current spec-driven development relies on monolithic documents that attempt to capture everything about a system in one place. This approach breaks down quickly as systems grow in complexity, team size increases, or when multiple domains need to evolve independently.
Composable specifications flip this model: instead of one large document, you create modular building blocks that work together to describe complex systems. Each specification focuses on a specific responsibility while maintaining clear interfaces with other specifications.
Tenet 1: Single Responsibility Principle for Specifications Link to heading
Each spec file should declare information about one specific part of the system. A user authentication specification focuses solely on authentication concerns—login flows, token management, session handling—not database schemas or API endpoints for user management features.
This separation enables independent evolution. Authentication changes don’t require touching unrelated specifications. Multiple teams can work on different aspects without conflicts. Avoid mixing concerns: don’t combine API contracts with database schemas or bundle unrelated features just because they share data.
Tenet 2: Outcome-Driven Specification Design Link to heading
Focus on what the system should achieve, not how to achieve it. This gives AI agents flexibility to explore implementation alternatives while meeting specified outcomes.
Instead of “use JWT tokens with 24-hour expiration stored in Redis,” specify “users remain authenticated for their active session without requiring re-login, with automatic logout after extended inactivity for security.” AI agents can then evaluate JWT, session cookies, or other mechanisms based on system context.
Define clear success criteria and validation points. What does “successful authentication” look like? How do you measure “extended inactivity”? These outcome definitions guide AI implementation while preserving technical flexibility. During AI-DLC’s plan-execute-validate cycles, AI agents will ask clarifying questions to enhance outcome definitions.
Caveat: While focusing on “what” should be the norm, specifying “how” becomes important when creating guardrail or best practice specifications. Security standards, compliance requirements, or architectural constraints may require prescriptive implementation approaches to ensure consistency and safety across the system.
When specifications compose together, each defines its outcomes and interfaces, allowing AI agents to find optimal integration patterns rather than being locked into predetermined technical decisions.
Tenet 3: Specification-First Development Workflow Link to heading
In AI-DLC, specifications are updated before code to ensure consistency. This maintains specification authority throughout the development lifecycle.
When requirements change, teams update specifications first. These updated specs then guide AI-led design and code generation, ensuring implementation aligns with new requirements. Specifications drive code updates, not the reverse.
Specs evolve through the same branching strategies as code. Feature branches include both specification and code changes, maintaining traceability while enabling parallel development. Specification changes trigger validation workflows that verify consistency across composed specs and guide AI code generation.
This specification-first approach prevents specs from becoming outdated documentation. In AI-DLC, specifications remain the authoritative source of truth that actively guides development.
Tenet 4: Composition Through Explicit Interfaces Link to heading
Define clear integration points between specifications to enable independent development while maintaining system coherence.
Use explicit reference mechanisms like #[[file:]] syntax to create dependencies between specifications. An e-commerce checkout spec might reference #[[file:user-authentication.md]], #[[file:payment-processing.md]], and #[[file:inventory-management.md]]. Each referenced spec can evolve independently while maintaining interface awareness.
Define integration points explicitly: What data flows between specifications? What events trigger cross-specification interactions? What are the failure modes when one spec’s implementation affects another?
This explicit approach enables parallel team development while preventing integration surprises. Teams can own specifications aligned with their expertise—business analysts focus on user journeys, platform engineers maintain infrastructure specs, QA engineers create testing specifications that reference multiple implementation specs.
The next section will provide concrete examples of how these principles apply in practice through horizontal and vertical specification architectures.
Horizontal vs Vertical Specification Architecture Link to heading
Understanding when and how to structure specifications across different architectural dimensions is crucial for managing complex systems. The choice between horizontal and vertical specification approaches—or more commonly, the combination of both—determines how effectively your specifications can scale with system complexity.
Horizontal specifications focus on specific architectural layers: API contracts, database schemas, user interface components, or infrastructure configurations. Vertical specifications cut across these layers to describe complete business capabilities or user journeys. Most complex systems benefit from both approaches working together.
Horizontal Specifications: Layer-Focused Architecture Link to heading
Horizontal specifications organize around technical layers and architectural concerns. Each specification focuses on a specific layer of your system architecture, enabling technical standardization and reusable component definitions.
Consider an appointment booking service. The horizontal specification approach would create separate specifications for each architectural layer:
API Layer Specification defines all endpoints, request/response payloads, authentication requirements, and error handling patterns. This specification becomes the contract that both frontend and backend teams reference, ensuring consistent API behavior across all appointment-related features.
API Layer Specification Link to heading
Appointment Endpoints Link to heading
- POST /appointments - Create new appointment
- GET /appointments/{id} - Retrieve appointment details
- PUT /appointments/{id} - Update appointment
- DELETE /appointments/{id} - Cancel appointment
Authentication Requirements Link to heading
All endpoints require valid JWT token in Authorization header Token must include ‘appointments:read’ or ‘appointments:write’ scopes Database Schema Specification documents tables, relationships, constraints, and data access patterns. This specification guides database migrations and ensures data consistency across different features that interact with appointment data.
UI Component Specification defines reusable interface elements, user interaction patterns, validation rules, and accessibility requirements. This specification enables consistent user experience across different appointment-related screens and workflows.
Each horizontal specification can evolve independently based on layer-specific concerns. API specifications change when integration requirements evolve. Database specifications change when data modeling needs shift. UI specifications change when user experience requirements are updated.
Vertical Specifications: Business Capability Architecture Link to heading
Vertical specifications organize around business capabilities and user journeys that span multiple architectural layers. These specifications describe complete features or business processes from the user’s perspective.
The Complete Appointment Booking Flow specification would reference the horizontal specifications while defining the business logic and user journey:
Appointment Booking Flow Specification Link to heading
References: #[[file:api-layer.md]], #[[file:database-schema.md]], #[[file:ui-components.md]]
User Journey Link to heading
- User selects available time slot (UI: calendar component)
- System validates slot availability (API: GET /availability, DB: appointment_slots table)
- User provides appointment details (UI: booking form)
- System creates appointment (API: POST /appointments, DB: appointments table)
- User receives confirmation (UI: confirmation screen, API: notification service)
Business Rules Link to heading
- Appointments cannot be double-booked
- Cancellations allowed up to 24 hours before appointment
- Reminder notifications sent 24 hours and 1 hour before appointment This vertical specification defines how the horizontal layers work together to deliver the complete business capability. It specifies integration points, data flow between layers, and business rules that span multiple architectural concerns.
When to Use Each Approach Link to heading
Horizontal specifications work best for technical standardization and reusable component development. Use horizontal specs when you need to:
Establish consistent patterns across multiple features
Enable parallel development across different business capabilities
Create reusable technical components
Maintain architectural standards and technical debt management
Vertical specifications excel for feature development and business capability delivery. Use vertical specs when you need to:
Deliver complete user journeys and business processes
Coordinate across multiple technical layers
Validate business requirements against technical implementation
Enable end-to-end testing and business validation
Combined approaches handle complex systems requiring both perspectives. Most real-world systems benefit from horizontal specifications that establish technical foundations and vertical specifications that deliver business value on top of those foundations.
AI-DLC Phase Alignment Link to heading
The three-phase AI-DLC structure naturally aligns with different specification types:
Inception Phase focuses primarily on vertical specifications. Teams collaborate to understand business requirements and user journeys. The specifications created during Inception describe what the system should accomplish from the user’s perspective, establishing the business context that will guide technical decisions.
Construction Phase leverages both horizontal and vertical specifications. Teams create horizontal specifications for technical design and architecture while using vertical specifications to ensure business logic implementation. The interplay between these specification types enables both technical excellence and business value delivery.
Operation Phase emphasizes horizontal specifications for infrastructure and operational concerns. Deployment specifications, monitoring configurations, and operational runbooks focus on specific technical layers rather than business capabilities.
Composition Patterns Link to heading
Vertical specifications reference and coordinate horizontal specifications through explicit composition patterns. Rather than duplicating information, vertical specs define how horizontal specs work together to deliver business outcomes.
A vertical specification might reference multiple horizontal specifications while adding business-specific logic:
Reference API specification for technical contracts
Reference database specification for data requirements
Reference UI specification for user interaction patterns
Add business rules that govern how these layers interact
Define success criteria and validation points specific to the business capability
This composition approach prevents duplication while ensuring that business requirements drive technical implementation. Changes to horizontal specifications automatically propagate to vertical specifications through the reference mechanism, maintaining consistency across the specification architecture.
Trade-offs and Considerations Link to heading
Complexity vs. Flexibility: Multiple specifications increase architectural complexity but provide flexibility for independent evolution. Teams must balance the overhead of maintaining multiple specifications against the benefits of modular development.
Maintenance Overhead vs. Modularity: Composable specifications require more coordination and consistency checking than monolithic specifications. However, this overhead is typically offset by the ability to make focused changes without affecting unrelated system components.
The key is starting simple and evolving complexity as needed. Begin with vertical specifications for core business capabilities, then extract horizontal specifications as patterns emerge and reuse opportunities become clear.
Conclusion Link to heading
Composable specifications and horizontal versus vertical architecture work together to create specification architectures that scale with system complexity while maintaining AI-DLC’s velocity benefits.
Composable specifications provide modularity through four tenets: single responsibility, outcome-driven design, specification-first workflow, and explicit interfaces. Horizontal and vertical architecture enables both technical standardization and complete business capability delivery.
These techniques enhance AI-DLC’s Plan-Execute-Validate cycle by providing richer context for planning, focused guidance for execution, and clearer validation criteria. Start with simple composable specifications, then gradually introduce layered approaches as your team’s practices mature.