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
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?)
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
- Save as
SPEC.mdin the project or module root
Phase 2: Plan
- Review spec with human — get explicit approval before continuing
- Use
planning-and-task-breakdownto create implementation tasks from the spec
Phase 3: Tasks
- Break spec into vertical slices (see
planning-and-task-breakdown) - Each task references the spec section it implements
Phase 4: Implement
- Build incrementally (see
incremental-implementation) - Every PR references the spec section it addresses
- Spec evolves with the project — update it when requirements change
Common Rationalizations
| Shortcut | Why It Fails |
|---|---|
| "The feature is simple, no spec needed" | Simple features have hidden edge cases (configuration changes, process death, deep links). A brief spec still beats none. |
| "We'll figure it out as we go" | Without a spec, each developer builds a different mental model. Alignment costs compound. |
| "The ticket/issue IS the spec" | Tickets describe what to build. Specs describe how it fits into the system, what's excluded, and how to verify. |
| "Writing specs slows us down" | Rework from misalignment costs 3–10x more than a spec. |
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