Spec Driven Development

Spec-Driven Development

Overview

Write a structured specification before writing code. The spec becomes the shared source of truth — a development contract that prevents misalignment, scope creep, and wasted effort. Every implementation decision traces back to the spec.

When to Use

• Starting a new Android project or module
• Adding a feature that spans multiple files or layers
• Requirements are ambiguous or come from multiple stakeholders
• Before writing a tasks/plan.md

Skip when: Single-line fixes or changes that are unambiguous and self-contained.

Core Process

Phase 1: Specify

1. Ask clarifying questions before writing anything:

   • What problem does this solve? Who is the user?
   • Which features are in scope? Which are explicitly out?
   • What is the tech stack? (minSdk, target SDK, Compose vs XML, DI framework)
   • What are the boundaries? (offline support? accessibility? tablet?)

2. Write SPEC.md with these sections:

# Feature Name — Specification

## Objective
What we're building and why. One paragraph.

## Commands
Key Gradle tasks and how to use them:
- `./gradlew assembleDebug` — build debug APK
- `./gradlew test` — run unit tests
- `./gradlew connectedAndroidTest` — run instrumented tests
- `./gradlew lint` — run Android Lint

## Project Structure
Where new code lives in the module hierarchy:
- `:app` — main application module
- `:feature:feature-name` — new feature module
- `:core:data` — data layer (repositories, data sources)
- `:core:domain` — domain layer (use cases, models)

## Code Style
- Kotlin with Jetpack Compose for UI
- MVVM/MVI architecture with ViewModel + StateFlow
- Hilt for dependency injection
- Coroutines + Flow for async operations
- Material 3 design system

## Testing Strategy
- Unit tests: JUnit5 + MockK for ViewModels, use cases, repositories
- UI tests: Compose test rules for screen-level testing
- Integration tests: Room in-memory database, MockWebServer
- Target: critical paths covered, not arbitrary coverage %

## Boundaries
What is explicitly NOT in scope:
- [ ] List exclusions here

3. Save as SPEC.md in the project or module root

Phase 2: Plan

4. Review spec with human — get explicit approval before continuing
5. Use planning-and-task-breakdown to create implementation tasks from the spec

Phase 3: Tasks

6. Break spec into vertical slices (see planning-and-task-breakdown)
7. Each task references the spec section it implements

Phase 4: Implement

8. Build incrementally (see incremental-implementation)
9. Every PR references the spec section it addresses
10. Spec evolves with the project — update it when requirements change

Common Rationalizations

Red Flags

• Implementation started without written spec
• Spec has no "Boundaries" or exclusions section
• Spec doesn't specify testing strategy
• Multiple developers have different understandings of scope
• Spec never updated after requirement changes

Verification

• SPEC.md exists in version control
• All six sections filled in (Objective, Commands, Structure, Style, Testing, Boundaries)
• Human has reviewed and approved the spec
• Implementation tasks reference spec sections
• Spec updated when requirements changed during development