Calidad de código: testing, refactor y revisión

Refactoring seguro

Tests primero, refactor después — siempre acotado

Tests completos

Edge cases, errores y assertions específicas

Documentación técnica

OpenAPI, TSDoc y diagramas generados por el agente

Cultura de MR review

El Reviewer como primer filtro antes del merge

---

Conceptos clave

Atacar deuda técnica con el agente

El agente como herramienta de refactoring sobre código legacy real. La estrategia es segura y acotada:

1. Añadir tests primero — antes de tocar nada, el agente genera tests del código actual

2. Refactor de un fichero a la vez — nunca refactors masivos sin supervisión

3. Revisión humana del diff — el dev valida cada cambio antes del commit

Casos prácticos sobre el código del equipo:

Angular → Signals

Refactoriza el componente UserListComponent:
- Reemplaza los BehaviorSubject por signal()
- Reemplaza los Observable derivados por computed()
- Reemplaza las suscripciones en ngOnInit por effect()
- Mantén la misma interfaz pública del componente
- NO cambies los tests existentes — primero verifica que pasan

Laravel → separar

El método OrderController@store tiene 150 líneas con validación,
lógica de negocio, envío de emails y logging mezclados.

Refactoriza:
1. Extrae la validación a un StoreOrderRequest
2. Extrae la lógica de negocio a OrderService
3. Extrae el envío de emails a un Event/Listener
4. El controller solo coordina — máximo 20 líneas

Código sin tests

El fichero app/Services/PaymentService.php no tiene tests.
Antes de cualquier cambio:
1. Genera tests PHPUnit que cubran el comportamiento actual
2. Ejecuta los tests — deben pasar SIN modificar el código
3. Solo entonces propón el refactor

Testing generado por el agente

El agente genera la suite de tests completa. La clave: instruirle para que cubra edge cases, no solo el happy path.

Cómo instruir al agente para tests completos:

Genera tests para UserService.getById():
- Happy path: usuario existe, devuelve datos completos
- Error: usuario no existe → lanza NotFoundException
- Error: ID inválido (null, undefined, negativo, string)
- Edge: usuario existe pero tiene campos null (nombre, email)
- Edge: múltiples llamadas concurrentes
- Seguridad: no devuelve el password hash en la respuesta

Revisión crítica del test generado — qué validar:

• ¿Los assertions son específicos o son genéricos (toBeTruthy)?
• ¿Los mocks simulan la realidad o simplifican demasiado?
• ¿Cubre los errores que pueden ocurrir en producción?
• ¿El test fallaría si el código tiene un bug? (test que siempre pasa = test inútil)

Stack del equipo:

• Angular: Karma + Jasmine con TestBed.configureTestingModule
• Laravel: PHPUnit con factories y DatabaseTransactions

Documentación técnica generada y mantenida

El agente no solo genera documentación — puede detectar documentación desactualizada y proponer actualizaciones.

Tipos de documentación a generar:

Tipo	Herramienta	Dónde
API REST	OpenAPI/Swagger	Endpoints Laravel
Servicios Angular	JSDoc/TSDoc	Clases y métodos públicos
Componentes	README.md	Por componente o por feature
Arquitectura	Diagramas Mermaid	docs/ del repo

Cómo integrarlo como tarea recurrente:

• Prompt file /actualizar-docs que el Reviewer ejecuta en cada pre-review
• Hook PostToolUse que recuerda generar docs cuando se crea un endpoint nuevo
• Tarea del sprint: “el agente revisa si la documentación está al día”

Ejemplo de prompt para OpenAPI:

Analiza todos los controllers en app/Http/Controllers/ y genera
un fichero OpenAPI 3.0 en docs/api-spec.yaml.

Para cada endpoint incluye:
- Path, método HTTP, parámetros
- Request body (usando los Form Requests existentes)
- Responses (200, 401, 403, 404, 422)
- Descripción breve basada en los comentarios del controller

Cultura de MR review — el Reviewer como primer filtro

El equipo no tiene cultura de revisión de Merge Requests. Esta sesión aborda dos cosas:

1. Por qué hacer review antes del merge No es burocracia. Es la forma más barata de:

• Detectar bugs antes de que lleguen a producción
• Compartir conocimiento entre el equipo (el que revisa aprende)
• Reducir deuda técnica (lo que no se revisa, se acumula)

2. Cómo el Reviewer elimina la fricción El Reviewer corre localmente antes de abrir el MR — genera un informe en segundos. No requiere cambiar el proceso en GitLab, solo añadir un paso previo que no cuesta:

Flujo actual

código → push → MR → (nadie revisa) → merge

Flujo con Reviewer

código → Reviewer → fix → push → MR → review humano ligero → merge

Tip

El Reviewer detecta los problemas obvios (naming, patrones, seguridad básica). El review humano se centra en lógica de negocio y decisiones de diseño — lo que realmente requiere un cerebro humano.

---

Tarea individual (entre sesiones)

Tiempo: 45–55 min · Entregable: fichero refactorizado + suite de tests + OpenAPI

1. Elegir un componente Angular con BehaviorSubject o un controller Laravel con lógica mezclada

2. Aplicar el proceso completo: tests primero (sin tocar el código) → ejecutar y verificar que pasan → refactor → ejecutar tests de nuevo

3. Generar una suite de tests completa para una función o servicio sin tests: happy path, al menos 3 casos de error, al menos 2 edge cases. Verificar que las assertions son específicas

4. Generar documentación OpenAPI 3.0 de al menos 3 endpoints Laravel

5. Ejecutar el Reviewer sobre los cambios y leer el informe: ¿detectó algo que no habías visto?

6. Medir: anotar tiempo invertido con agente vs estimación sin él — dato para la sesión de métricas