Ejemplo Práctico

Vamos a crear una API de gestión de tareas usando Spec-Kit de principio a fin.

Paso 1: Crear Constitution

Iniciamos el agente AI y ejecutamos:

/speckit.constitution

Resultado: constitution.md

# Constitution: Todo API

## Stack Tecnológico
- Runtime: Bun
- Framework: Hono
- Database: SQLite
- Testing: Vitest

## Principios
- API REST
- Validación con Zod
- Responses JSON
- Códigos HTTP estándar

## Estructura
src/
├── domain/
├── application/
├── infrastructure/
└── index.ts

## Restricciones
- NO frameworks ORM pesados
- NO lógica en rutas
- Máximo 150 líneas por archivo

Paso 2: Especificar Feature

/speckit.specify "CRUD de tareas con título, descripción y estado"

Resultado: specs/todo-crud.md

# Spec: CRUD de Tareas

## Descripción
API REST para gestionar tareas personales.

## Entidades
### Todo
- id: string (UUID)
- title: string (1-100 chars)
- description: string (opcional, max 500)
- status: "pending" | "completed"
- createdAt: ISO date
- updatedAt: ISO date

## Endpoints

### POST /todos
Crear tarea nueva.
- Body: { title, description? }
- Response: 201 + Todo

### GET /todos
Listar todas las tareas.
- Query: ?status=pending|completed
- Response: 200 + Todo[]

### GET /todos/:id
Obtener tarea por ID.
- Response: 200 + Todo | 404

### PATCH /todos/:id
Actualizar tarea.
- Body: { title?, description?, status? }
- Response: 200 + Todo | 404

### DELETE /todos/:id
Eliminar tarea.
- Response: 204 | 404

Paso 3: Crear Plan Técnico

/speckit.plan "specs/todo-crud.md"

Resultado: plans/todo-crud-plan.md

# Plan: CRUD de Tareas

## Arquitectura

### Domain Layer
- Todo entity con factory method
- TodoRepository interface
- Validaciones en entity

### Application Layer
- CreateTodoUseCase
- ListTodosUseCase
- GetTodoUseCase
- UpdateTodoUseCase
- DeleteTodoUseCase

### Infrastructure Layer
- SQLiteTodoRepository
- Hono routes
- Zod schemas

## Contratos

### TodoRepository
- create(todo: Todo): Promise<Todo>
- findAll(filter?): Promise<Todo[]>
- findById(id): Promise<Todo | null>
- update(todo: Todo): Promise<Todo>
- delete(id): Promise<void>

## Testing
- Unit: entities y use cases
- Integration: repository + sqlite
- E2E: endpoints completos

Paso 4: Desglosar Tasks

/speckit.tasks "plans/todo-crud-plan.md"

Resultado: tasks/todo-crud-tasks.md

# Tasks: CRUD de Tareas

## 1. Setup
- [x] Inicializar proyecto Bun
- [x] Instalar dependencias
- [x] Configurar estructura carpetas

## 2. Domain
- [ ] Crear Todo entity
- [ ] Crear TodoRepository interface
- [ ] Tests unitarios entity

## 3. Application
- [ ] CreateTodoUseCase
- [ ] ListTodosUseCase
- [ ] GetTodoUseCase
- [ ] UpdateTodoUseCase
- [ ] DeleteTodoUseCase
- [ ] Tests use cases

## 4. Infrastructure
- [ ] SQLiteTodoRepository
- [ ] Zod validation schemas
- [ ] Hono routes
- [ ] Tests integración

## 5. Finalización
- [ ] Tests E2E
- [ ] Documentación API

Paso 5: Implementar

/speckit.implement "tasks/todo-crud-tasks.md"

El agente AI genera automáticamente:

src/domain/todo.ts

export interface Todo {
  id: string
  title: string
  description?: string
  status: 'pending' | 'completed'
  createdAt: Date
  updatedAt: Date
}

export function createTodo(
  title: string,
  description?: string
): Todo {
  return {
    id: crypto.randomUUID(),
    title,
    description,
    status: 'pending',
    createdAt: new Date(),
    updatedAt: new Date()
  }
}

src/application/create-todo.ts

import type { Todo } from '../domain/todo'
import type { TodoRepository } from '../domain/repository'
import { createTodo } from '../domain/todo'

export class CreateTodoUseCase {
  constructor(private repo: TodoRepository) {}

  async execute(
    title: string,
    description?: string
  ): Promise<Todo> {
    const todo = createTodo(title, description)
    return this.repo.create(todo)
  }
}

Resultado Final

Estructura generada:

src/
├── domain/
│   ├── todo.ts
│   └── repository.ts
├── application/
│   ├── create-todo.ts
│   ├── list-todos.ts
│   ├── get-todo.ts
│   ├── update-todo.ts
│   └── delete-todo.ts
├── infrastructure/
│   ├── sqlite-repository.ts
│   ├── schemas.ts
│   └── routes.ts
└── index.ts

Siguiente Paso

→ Capítulo 5: Mejores Prácticas