Prompts para IA en Desarrollo de Software¶
Esta sección contiene una colección de prompts efectivos para trabajar con agentes de IA en diferentes aspectos del desarrollo de software.
¿Qué son los prompts?¶
Un prompt es una instrucción que le damos a un agente de IA para guiarlo en la generación de código, documentación o análisis. Un buen prompt debe ser claro, estructurado y contextual.
Los siguientes prompts están pensados para integrarse en tu flujo de trabajo y siempre generar resultados en la carpeta /context.
🔹 Prompt 1: Generar README a partir de requerimientos funcionales¶
Objetivo Transformar un documento de requerimientos funcionales en un README técnico.
Instrucción base
Analiza el documento de requerimientos funcionales que te paso.
Genera un archivo funcional.md en la carpeta /context que describa:
- Resumen del requerimiento
- Objetivos principales
- Entradas y salidas esperadas
- Casos de uso clave
- Restricciones y validaciones
- Checklist de criterios de aceptación
Ejemplo
Input: "El sistema debe permitir a los usuarios registrarse con email y contraseña,
enviar confirmación por correo y habilitar login con tokens JWT."
Output: README en /context/README.md con resumen del requerimiento de autenticación.
Consejo
Mantén los requerimientos claros y completos. Si falta información, el agente puede generar documentación ambigua o incompleta.
Formato recomendado
Usa encabezados (##), listas de viñetas y ejemplos de request/response en JSON para que la interpretación sea más precisa.
🔹 Prompt 2: Generar README con características de un proyecto¶
Objetivo Producir un README descriptivo con detalles clave del proyecto.
Instrucción base
Lee las características del proyecto que te paso y genera un archivo caracteristicas.md en /context.
El README debe incluir:
- Nombre y propósito del proyecto
- Tecnologías y frameworks utilizados
- Arquitectura general
- Dependencias externas
- Entornos soportados (local, test, prod)
- Guía de inicio rápido
- Buenas prácticas recomendadas
Ejemplo
Input: "Proyecto backend en Java 17 con Spring Boot, usa PostgreSQL, Kafka y Docker."
Output: README en /context/README.md con stack, arquitectura y pasos de ejecución.
Consejo
Incluye versiones exactas de dependencias y frameworks. Esto asegura reproducibilidad del entorno.
Formato recomendado
Agrega secciones de instalación paso a paso (bash, docker-compose) y un bloque de Getting Started.
🔹 Prompt 3: Generar README de un flujo funcional (ej. ejecución de un endpoint)¶
Objetivo
A partir de un punto de entrada (ejemplo: un endpoint), recorrer las clases involucradas y generar un README en /context documentando el flujo.
Instrucción base
Dado el punto de entrada [endpoint o clase], analiza todo el flujo funcional recorriendo las clases que intervienen.
Genera un archivo flujo.md en /context que incluya:
- Descripción del flujo paso a paso
- Capas involucradas (controller, service, repository, etc.)
- Entidades y DTOs que se utilizan
- Validaciones y reglas de negocio aplicadas
- Integraciones externas si existen
- Ejemplo de request/response
Ejemplo
Input: "GET /api/v1/users/{id}"
Output: README en /context/README.md con descripción:
UserController → UserService → UserRepository → DB, validaciones y DTO UserResponse.
Consejo
Documenta tanto el flujo principal como los escenarios de error. Esto evita malinterpretaciones.
Formato recomendado
Incluye diagramas simples en texto (Mermaid o listas) para visualizar el flujo de llamadas entre capas.
🔹 Prompt 4: Validador y Corrector OpenAPI¶
Objetivo Validar y corregir contratos OpenAPI 3.0.x con un asistente IA. Aplica buenas prácticas mínimas, sin ser demasiado estricto, y devuelve un documento YAML corregido junto con un reporte de correcciones.
Características principales
- Garantizar que cada operación incluya:
- Una respuesta 200.
- Al menos una respuesta de error (400, 404, o 500).
- Recomendar la presencia de todas las respuestas de error comunes (400, 404, 500).
- Declarar tipos (type) y formatos (format) en parámetros y schemas.
- Incluir descripciones (description) en:
- info
- tags
- operaciones (summary, description)
- respuestas
- components.schemas y sus properties
- Conservar la estructura original del contrato, corrigiendo solo lo necesario.
Instrucción base
Sos un asistente experto en OpenAPI 3.0.x.
Tu tarea es **validar y corregir** el contrato que voy a pegar, siguiendo estas reglas mínimas:
1. Cada operación debe incluir:
- Una respuesta **200**.
- Al menos una respuesta de error entre **400**, **404** o **500**.
- Si faltan **400**, **404** o **500**, agregarlas como recomendadas con un `ErrorResponseDTO` genérico.
2. Todos los parámetros, requestBody y schemas deben declarar un **type** (y **format** cuando corresponda).
3. Todo elemento importante (`info`, `tags`, `summary`, `description`, `responses`, `schemas`) debe tener una **description** clara.
4. No eliminar información: solo completar o corregir suavemente lo que falte.
5. Mantener el contrato válido en **OpenAPI 3.0.x**.
### Salida requerida (en este orden):
1. `### YAML corregido` → un único documento OpenAPI válido en **YAML**.
2. `### Reporte de correcciones` → listado breve de cambios aplicados.
### Entrada
Voy a pegar el contrato OpenAPI original entre triple comillas invertidas.
Ejemplo:
```yaml
<contenido del contrato>
Ejemplo de uso
Entrada completa:
openapi: 3.0.1
info:
title: OpenAPI definition
version: v0
description: API para ejecutar procesos batch de verificación y conciliación de checks y gestionar datos raw asociados.
servers:
- url: http://localhost:8080/msb-universal-co
description: Ambiente local para pruebas
- url: https://universalcopebatch.des-gke.financieraoh.local/msb-universal-co
description: Ambiente DES (desarrollo)
- url: https://universalcopebatch.stg-gke.financieraoh.local/msb-universal-co
description: Ambiente STG (staging)
- url: https://universalcopebatch.des-prod.financieraoh.local/msb-universal-co
description: Ambiente DES-PROD (preproducción)
tags:
- name: Batch Jobs
description: API para la ejecución de trabajos por lotes de conciliación
- name: Raw Data
description: API para la gestión de datos raw
paths:
/api/batch/checks:
post:
tags:
- Batch Jobs
summary: Ejecutar proceso de verificación y conciliación de checks
description: |
Inicia el proceso batch de verificación y conciliación de checks del día anterior.
El sistema automáticamente resta un día a la fecha proporcionada para consultar la tabla
`egestion.rpa_o017_consolidado` y procesar los checks del día hábil anterior.
Incluye:
- Ajuste automático de fecha
- Validación de rango (no futuro, últimos 90 días)
- Lectura de checks desde egestion
- Enriquecimiento desde FULXT01D
- Escritura en raw_data con tipo CHECKS
- Estadísticas detalladas
operationId: runChecksJobPreviousDay
parameters:
- name: date
in: query
required: true
description: Fecha base en formato `yyyy-MM-dd`. El sistema restará 1 día automáticamente.
schema:
type: string
format: date
example: "2025-07-31"
responses:
"200":
description: Proceso de checks completado correctamente.
content:
application/json:
schema:
$ref: "#/components/schemas/JobResponseDTO"
"400":
description: Parámetros inválidos en la solicitud (formato o rango de fecha).
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponseDTO"
"404":
description: No se encontraron registros para la fecha procesada.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponseDTO"
"500":
description: Error interno del servidor al ejecutar el proceso de checks.
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorResponseDTO"
components:
schemas:
JobResponseDTO:
type: object
description: Resultado de la ejecución del proceso batch, incluyendo identificadores y estado final.
properties:
jobId:
type: string
description: Identificador único del proceso batch.
example: "6e4ab7c2-9b41-4f0a-8c0f-2b0d1f9e12ab"
jobName:
type: string
description: Nombre del job ejecutado.
example: "checksJob"
status:
type: string
description: Estado final del job.
enum: [SUCCESS, ERROR, WARNING]
example: SUCCESS
code:
type: integer
format: int32
description: Código interno de resultado de la ejecución.
example: 0
message:
type: string
description: Mensaje informativo o de error asociado al resultado.
example: "Proceso finalizado sin errores."
timestamp:
type: string
format: date-time
description: Momento de finalización del job.
example: "2025-07-31T10:15:30Z"
parameters:
type: object
description: Parámetros de ejecución utilizados por el job.
additionalProperties: false
ErrorResponseDTO:
type: object
description: Objeto estándar de error para respuestas HTTP no exitosas.
properties:
code:
type: integer
format: int32
description: Código de estado HTTP.
example: 400
error:
type: string
description: Nombre del error.
example: Bad Request
message:
type: string
description: Descripción detallada del error.
example: "La fecha proporcionada no cumple con el formato yyyy-MM-dd"
timestamp:
type: string
format: date-time
description: Momento exacto en que ocurrió el error.
example: "2025-07-31T10:15:30Z"
path:
type: string
description: Endpoint donde ocurrió el error.
example: "/api/batch/checks"
required:
- code
- error
- message
- timestamp
- path
additionalProperties: false
Salida esperada: - Este contrato ya está bien estructurado, pero el validador verificaría: - ✅ Respuestas 200, 400, 404, 500 están presentes - ✅ Tipos y formatos declarados correctamente - ✅ Descripciones completas en todos los elementos - ✅ Schemas con propiedades bien documentadas - Reporte: "Contrato válido - cumple con todas las buenas prácticas mínimas"
Beneficios
- Asegura que todos los contratos tengan el mínimo de buenas prácticas.
- Estandariza las respuestas de error con ErrorResponseDTO.
- Evita revisiones manuales repetitivas.
- Se integra fácilmente con pipelines de validación (Spectral, CI/CD).
Consejo
Este prompt es especialmente útil para validar contratos API antes de su implementación o documentación final.
Formato recomendado
Usa este prompt cuando tengas un contrato OpenAPI que necesite ser estandarizado según buenas prácticas mínimas sin perder la estructura original.
🔹 Prompt 5: Generador de WireMock desde OpenAPI + Endpoint¶
Objetivo
Generar automáticamente la estructura de WireMock (mappings + __files) a partir de un YAML OpenAPI y el nombre de un endpoint, usando responses en archivos JSON y mocks + proxy fallback.
Características principales
- Produce una carpeta wiremock/ completa con:
- mappings/*.json (reglas WireMock)
- __files/*.json (payloads de respuesta)
- Mocks de respuestas (200, 400, 404, 500) referenciando bodyFileName
- Proxy de respaldo (fallback) a un backend real para casos no mockeados
- Estructura basada en mappings típicos de WireMock usando bodyFileName para separar payloads
Instrucción base
Sos un asistente experto en OpenAPI y WireMock. Quiero que GENERES una carpeta "wiremock" lista para usar (sin comentarios), a partir de:
1) Un contrato OpenAPI 3.0.x en YAML.
2) El nombre exacto de un endpoint objetivo (path + método), por ejemplo: POST /api/batch/checks.
3) Un proxy base de respaldo (opcional), por ejemplo: https://mi-backend.real.
### Reglas de generación
A. Estructura de archivos:
- Crear la carpeta `wiremock/`.
- Dentro, crear `wiremock/mappings/` y `wiremock/__files/`.
- Generar 1 mapping por cada status que figure en el YAML para el endpoint objetivo, al menos para: 200, y **al menos uno** entre 400/404/500. Si existen varios errores en el YAML, crear cada uno.
- Para cada mapping, usar `bodyFileName` que apunte a un JSON en `__files/`.
- Agregar un mapping de **proxy fallback** con `priority` menor precedencia (número más alto), que derive al `proxyBaseUrl` si se proporciona.
B. Contenido de mappings:
- `request`:
- `method`: según el YAML.
- Usar `urlPath` con el path exacto del endpoint.
- Incluir `queryParameters` si el YAML define parámetros de query (usar `matches` o `equalTo` razonables).
- `response`:
- `status`: 200, 400, 404, 500, etc. según corresponda.
- `headers`: `Content-Type: application/json`.
- `bodyFileName`: apuntar al archivo correspondiente en `__files`.
- Podés agregar `fixedDelayMilliseconds` de 50–150 ms para realismo (opcional).
- Prioridades:
- Los mocks deben tener `priority` **baja** (valor numérico chico, por ejemplo 1–3).
- El **proxy fallback** debe tener `priority` **alta** (valor numérico grande, por ejemplo 10).
- Usar `transformers: ["response-template"]` si necesitás interpolar datos de query en el body.
C. Contenido de `__files`:
- Para 200: construir un JSON que respete el schema referenciado por la respuesta 200 en el YAML (si hay `$ref`, ejemplificar campos clave; si no hay, derivar del schema inline).
- Para errores (400, 404, 500): usar el schema de error (por ejemplo `ErrorResponseDTO`) con campos de ejemplo coherentes con el endpoint y el status.
- Mantener claves y tipos fieles al contrato original.
D. Nombres de archivos:
- Mappings: `{tag-o-nombre-endpoint}_{method}_{status}.json` (kebab-case). Si no hay tag, basarse en el path.
- Bodies: en `__files/`: `{tag-o-nombre-endpoint}/{method}_{status}.json`.
- Crear subcarpetas si ayuda a la organización (por ejemplo `__files/batch-checks/`).
E. Salida:
- **Primero**: un árbol de carpetas y archivos.
- **Luego**: el contenido **completo** de cada archivo generado (mappings y bodies), sin texto adicional.
### Datos de entrada (reemplazá debajo)
- Endpoint objetivo: <METHOD> <PATH> (ej.: POST /api/batch/checks)
- Proxy de respaldo (opcional): <https://mi-backend.real>
- OpenAPI (YAML) original:
```yaml
<PEGAR AQUÍ EL YAML COMPLETO>
```
Ejemplo de uso
Aplicado al endpoint POST /api/batch/checks:
Árbol esperado:
wiremock/
mappings/
batch-jobs_post_200.json
batch-jobs_post_400.json
batch-jobs_post_404.json
batch-jobs_post_500.json
batch-jobs_post_proxy.json
__files/
batch-jobs/
post_200.json
post_400.json
post_404.json
post_500.json
Ejemplo de mapping (200):
{
"priority": 1,
"request": {
"method": "POST",
"urlPath": "/api/batch/checks",
"queryParameters": {
"date": {
"matches": "\\d{4}-\\d{2}-\\d{2}"
}
}
},
"response": {
"status": 200,
"headers": { "Content-Type": "application/json" },
"bodyFileName": "batch-jobs/post_200.json",
"fixedDelayMilliseconds": 80
}
}
Ejemplo de response body (200):
{
"jobId": "6e4ab7c2-9b41-4f0a-8c0f-2b0d1f9e12ab",
"jobName": "checksJob",
"status": "SUCCESS",
"code": 0,
"message": "Proceso finalizado sin errores.",
"timestamp": "2025-07-31T10:15:30Z",
"parameters": {
"date": "2025-07-31",
"adjustedDate": "2025-07-30"
}
}
Ejemplo de proxy fallback:
{
"priority": 10,
"request": {
"method": "POST",
"urlPath": "/api/batch/checks"
},
"response": {
"proxyBaseUrl": "https://universalcopebatch.stg-gke.financieraoh.local/msb-universal-co",
"headers": { "X-WireMock-Proxy": "true" }
}
}
Beneficios - Automatiza la creación completa de estructura WireMock desde contratos OpenAPI - Genera mocks realistas con responses separadas en archivos JSON - Incluye proxy fallback para casos no mockeados - Mantiene fidelidad al contrato original (schemas, tipos, ejemplos) - Estructura organizada por tags/endpoints para facilitar mantenimiento
Ejecución con Docker
docker run -it --rm \
-p 8089:8080 \
-v "$PWD/wiremock:/home/wiremock" \
--name wiremock \
wiremock/wiremock:3.8.0 --verbose
Prueba:
curl -i -X POST "http://localhost:8089/api/batch/checks?date=2025-07-31"
Consejo
Ajusta las priority si quieres que ciertos errores "ganen" sobre el 200. Puedes agregar scenarios de WireMock si necesitas flujos multi-estado.
Formato recomendado
Ideal para testing de integración y desarrollo frontend cuando el backend no está disponible o quieres simular diferentes escenarios de error.
🔹 Prompt 6: Generador de Documentación Gherkin desde Código y OpenAPI¶
Objetivo Generar documentación Gherkin/Cucumber en español a partir de tests existentes (Given/When/Then) y contratos OpenAPI, creando Features que documenten tanto reglas de dominio como contratos HTTP.
Características principales
- Dos enfoques complementarios:
- #1: Desde tests/casos de uso (dominio y reglas de negocio)
- #2: Desde contratos OpenAPI (flujos HTTP y validaciones de API)
- Mantiene sincronización entre código y documentación
- Genera .feature files en español (# language: es)
- Cobertura completa: dominio + API
Enfoque #1: Anotar Tests/UseCases con Given/When/Then¶
Instrucción base
Analizá los tests que te paso, que tienen bloques GWT (Given/When/Then) en Javadoc o @DisplayName.
Convertí cada bloque en un Escenario Gherkin válido, agrupando por Feature.
### Formato esperado en los tests:
```java
@DisplayName("Nombre del escenario")
/**
* Feature: Nombre de la característica
* Scenario: Descripción del escenario
* Given: precondición
* When: acción principal
* Then:
* - resultado esperado 1
* - resultado esperado 2
* - resultado esperado 3
*/
```
### Reglas de conversión:
- Agrupar por Feature y crear un solo archivo .feature
- Usar `# language: es`
- Convertir:
- Feature → Característica
- Scenario → Escenario
- Given → Dado
- When → Cuando
- Then → Entonces
- And → Y
- Mantener orden lógico de escenarios
- Usar nombres descriptivos para la Característica
### Salida:
1. Nombre del archivo .feature sugerido
2. Contenido completo del archivo .feature
Ejemplo de uso
Tests de entrada:
@DisplayName("Consultar razones de regularización disponibles para OHPAY")
/**
* Feature: Gestión de cuentas OpControl
* Scenario: Consultar razones de regularización disponibles para OHPAY
* Given: que el sistema tiene razones de regularización configuradas para el producto "OHPAY"
* When: solicito todas las razones de regularización para el producto "OHPAY"
* Then:
* - obtengo una lista con al menos una razón
* - cada razón tiene un identificador y una descripción
* - cada razón pertenece al productType "OHPAY"
*/
@Test
void should_list_reasons_for_ohpay() { /* ... */ }
@DisplayName("Regularizar cuenta en OpControl")
/**
* Feature: Gestión de cuentas OpControl
* Scenario: Regularizar cuenta con acción válida
* Given: que existe una cuenta en estado de control operacional
* When: ejecuto la acción de regularización con una razón válida
* Then:
* - la cuenta cambia a estado regularizado
* - se registra auditoría con usuario y timestamp
* - el endpoint responde 200 con el detalle de la regularización
*/
@Test
void should_regularize_account() { /* ... */ }
Salida esperada:
# language: es
Característica: Gestión de cuentas OpControl
Como usuario del sistema
Quiero gestionar cuentas en control operacional
Para mantener el control de regularizaciones
Escenario: Consultar razones de regularización disponibles para OHPAY
Dado que el sistema tiene razones de regularización configuradas para el producto "OHPAY"
Cuando solicito todas las razones de regularización para el producto "OHPAY"
Entonces obtengo una lista con al menos una razón
Y cada razón tiene un identificador y una descripción
Y cada razón pertenece al productType "OHPAY"
Escenario: Regularizar cuenta con acción válida
Dado que existe una cuenta en estado de control operacional
Cuando ejecuto la acción de regularización con una razón válida
Entonces la cuenta cambia a estado regularizado
Y se registra auditoría con usuario y timestamp
Y el endpoint responde 200 con el detalle de la regularización
Enfoque #2: Derivar Gherkin desde OpenAPI¶
Instrucción base
Con este contrato OpenAPI (JSON o YAML), generá Features en español.
### Reglas de generación:
- Agrupar por tag de OpenAPI
- Para cada operación, crear un Escenario con:
- Dado: precondición mínima del endpoint
- Cuando: método + path + parámetros de ejemplo del OpenAPI
- Entonces: status esperado (2xx) y validaciones esenciales del schema
- Y: validar al menos 2-3 campos clave del response según el schema
### Formato:
- Usar `# language: es`
- Nombrar la Característica con el tag principal
- Incluir descripción de valor de negocio
- Usar ejemplos reales del OpenAPI
### Salida:
1. Un archivo .feature por cada tag
2. Contenido completo de cada archivo .feature
### OpenAPI de entrada:
```yaml
<PEGAR AQUÍ EL YAML COMPLETO>
```
Ejemplo de uso
Para el endpoint anotado:
@Operation(
summary = "Listar razones de regularización por producto",
description = "Devuelve razones configuradas para un productType."
)
@ApiResponses({
@ApiResponse(responseCode = "200", description = "Listado obtenido"),
@ApiResponse(responseCode = "404", description = "Producto no encontrado"),
@ApiResponse(responseCode = "500", description = "Error interno")
})
@GetMapping("/opcontrol/reasons")
public ResponseEntity<List<ReasonDto>> getReasons(
@Parameter(description = "Código de producto", example = "OHPAY")
@RequestParam String productType) { /* ... */ }
Salida esperada:
# language: es
Característica: Raw Data / OpControl - Razones de regularización
Como consumidor de la API
Quiero consultar razones de regularización por producto
Para mostrar opciones válidas en el frontend
Escenario: Listar razones para OHPAY
Dado que existen razones de regularización configuradas para "OHPAY"
Cuando llamo GET /opcontrol/reasons con productType="OHPAY"
Entonces la respuesta es 200
Y el cuerpo contiene una lista
Y cada item tiene id (UUID), description (string) y productType="OHPAY"
Beneficios - Sincronización automática entre código y documentación - Cobertura completa: dominio (enfoque #1) + API (enfoque #2) - Lenguaje natural para stakeholders no técnicos - Testing BDD ejecutable con Cucumber - Documentación viva que evoluciona con el código
Uso combinado recomendado
- Dominio y reglas de negocio → Enfoque #1 (tests/usecases)
- Contratos HTTP y flujos de API → Enfoque #2 (OpenAPI)
- Publicar ambos .feature en src/test/resources/features/
- Ejecutar con RunCucumberTest.java
Definición de Hecho (DoD) sugerida
Para cada nuevo caso de uso:
- [ ] Test con bloque GWT (enfoque #1) actualizado
- [ ] .feature correspondiente actualizado
Para cada nuevo endpoint o cambio de contrato:
- [ ] Anotaciones OpenAPI completas (summary, description, responses, schemas)
- [ ] .feature derivado desde OpenAPI (enfoque #2) actualizado
Pipelines:
- [ ] Job que valida OpenAPI (Spectral) y ejecuta Cucumber
- [ ] Falla si falta .feature para endpoint o caso de uso crítico
Consejo
Combina ambos enfoques para documentación completa: usa #1 para lógica de dominio compleja y #2 para validaciones de contratos HTTP.
Formato recomendado
Ideal para equipos que practican BDD y quieren mantener documentación ejecutable sincronizada con el código fuente.