Skip to content

Specification-Driven Development

Quaestor uses specification-driven development to provide structure and clarity to AI-assisted development workflows.

What are Specifications?

Specifications are formal documents that define exactly what needs to be built. Each specification includes:

  • Contract: Precise inputs, outputs, and behavior rules
  • Acceptance Criteria: Measurable success conditions
  • Test Scenarios: Given/When/Then test cases
  • Implementation Tracking: Automatic progress monitoring

Why Use Specifications?

Clear Requirements

  • Forces detailed thinking before implementation
  • Prevents scope creep with defined contracts
  • Ensures all stakeholders understand the requirements

Better Testing

  • Test scenarios defined upfront
  • Systematic coverage of edge cases
  • Integration between requirements and tests

Automatic Tracking

  • Progress tracked through specification status
  • Branch-to-spec linking
  • Release readiness based on spec implementation

Specification Structure

Each specification contains:

id: feat-auth-001
title: User Authentication System
type: feature
priority: high
status: draft

contract:
  inputs:
    - username: string (required)
    - password: string (required, min 8 chars)
  outputs:
    - token: JWT string
    - user: User object
  behavior:
    - Validate credentials against database
    - Generate JWT with 24h expiration
    - Log authentication attempts

acceptance_criteria:
  - User can login with valid credentials
  - Invalid credentials return error message
  - JWT token expires after 24 hours
  - Failed attempts are logged

test_scenarios:
  - name: Valid login
    given: User exists with correct password
    when: Login request sent
    then: JWT token returned

Specification Lifecycle

  1. Draft: Initial specification created
  2. Approved: Contract and criteria reviewed and approved
  3. In Progress: Implementation started, linked to branch
  4. Implemented: Code complete according to contract
  5. Tested: All test scenarios pass
  6. Deployed: Feature live in production

Benefits

  • Structured Development: Clear process from requirements to implementation
  • Quality Assurance: Built-in testing and validation
  • Progress Visibility: Real-time tracking of implementation status
  • Team Coordination: Shared understanding of requirements
  • Documentation: Specifications serve as living documentation