5. Proponer solución

6. ¿De qué va este tema?

La idea sería obtener, al final de este tema (y del módulo), un prototipo real que pueda simular la idea de solución que propones (para tu idea original, o uno de los tres ejemplos que propongo).

Usaremos OpenCode y un TUI (texto) con Python para desarrollar el prototipo. El interfaz de usuario sería lo más sencillo posible (TUI).

7. Clases

7.1. Del diseño al alcance comprobable

  1. Del dossier a una rebanada vertical:

    1. Elige un único flujo con valor, no toda la solución.

    2. Identifica la entrada, el procesamiento, la decisión y la salida visible.

    3. Comprueba que puedes demostrarlo en pocas horas con datos simulados.

    4. Conserva la relación con la arquitectura que escogiste

  2. Contrato del producto:

    Pregunta

    Decisión

    Ejemplo de riego

    Objetivo

    ¿Qué quieres mejorar?

    Decidir cuándo regar cada parcela.

    Área

    ¿Producción, ingresos/costes, …?

    Explotación y operación del riego.

    Entrada

    ¿Qué archivo, campos y frecuencia vas a simular?

    CSV con fecha, parcela, humedad y temperatura.

    Procesamiento

    ¿Qué validación, agrupación o indicador necesitas?

    Descartar valores imposibles y calcular la media por parcela.

    Decisión

    ¿Qué regla o recomendación produce el sistema?

    Regar si la media está por debajo del umbral.

    Salida

    ¿Qué verá el usuario?

    TUI con estado, decisión, datos rechazados e histórico.

  3. Esquema de datos de referencia:

    Campo

    Contenido

    Comentario

    fecha

    Fecha y hora de la lectura

    Permite agrupar por día, hora o ventana de decisión.

    entidad

    Objeto observado

    Parcela, máquina, pedido, usuario o cualquier unidad de tu proyecto.

    variable

    Magnitud medida

    Humedad, temperatura, importe, tiempo de espera, incidencias, etc.

    valor

    Valor numérico o textual

    Debe tener un rango o formato plausible.

    unidad

    Porcentaje, euros, grados, minutos

    Evita mezclar magnitudes distintas.

    origen

    Sensor simulado, formulario, API ficticia

    Recuerda que el dato es simulado o autorizado.

    Ejemplo de archivo CSV:

    fecha,entidad,variable,valor,unidad,origen
2026-03-01T08:00:00,parcela-01,humedad,42,porcentaje,sensor-simulado
2026-03-01T08:15:00,parcela-01,temperatura,18,grados,sensor-simulado
2026-03-01T08:15:00,parcela-02,humedad,-7,porcentaje,sensor-simulado

  4. Criterios de aceptación mínimos:

    1. Un comando ejecuta el prototipo.

    2. El prototipo carga un archivo de datos simulados.

    3. Valida los datos y registra los rechazos con motivo.

    4. Calcula al menos un indicador útil.

    5. Produce una decisión o recomendación con su motivo.

    6. Guarda un histórico consultable.

    7. La TUI muestra resumen, últimas lecturas, decisiones, alertas e histórico.

    8. Existen pruebas para caso normal, umbral y dato inválido.

    9. El README explica cómo ejecutar y demostrar el flujo.

  5. Fuera del alcance habitual de esta UD:

    1. Sensores físicos, hardware o infraestructura real.

    2. Despliegue en producción, dominio, base de datos empresarial o usuarios reales.

    3. Autenticación completa, pagos, mensajería real o integraciones externas no simuladas.

    4. Implementar todos los componentes de la arquitectura de UD2.

    5. Valorar la cantidad de código por sí misma.

Actividad

  1. Escribe el contrato del producto en una página: objetivo, área, entrada, procesamiento, decisión y salida.

  2. Define el esquema de datos y crea dos archivos: uno normal y otro con valores anómalos.

  3. Redacta los criterios de aceptación que comprobarás al final.

  4. Prepara cinco casos de prueba: normal, umbral, dato inválido, archivo ausente y ejecución repetida.

  5. Recorta explícitamente dos componentes de tu arquitectura y explica por qué no son necesarios para la demostración.

7.2. Del dossier al proyecto con agentes

  1. Estructura recomendada:

    proyecto/
  datos/
    lecturas.csv
    lecturas_anomalas.csv
    decisiones.jsonl
  app/
    __init__.py
    datos.py
    proceso.py
    reglas.py
    historial.py
    tui.py
  pruebas/
    __init__.py
    test_datos.py
    test_reglas.py
  docs/
    entrada/
    salida/
    cambios.md
    uso_ia.md
  README.md
  run.py

    decisiones.jsonl puede guardar un objeto json por línea. No necesitas una base de datos para el prototipo.

  2. Contexto permitido:

    Puedes compartir con OpenCode

    No compartas

    Objetivos, alcance, esquema de datos y reglas de decisión.

    Contraseñas, tokens, claves de API o archivos .env reales.

    Documentación propia de UD1 y UD2, sin datos sensibles.

    Datos personales o información empresarial confidencial.

    Datos ficticios, sintéticos o expresamente autorizados.

    Material con licencia restringida sin permiso.

    Pruebas, errores y resultados de comandos del proyecto.

    Archivos o directorios ajenos al proyecto.

  3. OpenCode como entorno supervisado:

    1. Inicia OpenCode en la carpeta del proyecto para que el contexto sea el repositorio del prototipo.

    2. Selecciona el proveedor y el modelo acordados; en UD2 ya viste el flujo entre agente, proveedor y LLM.

    3. Usa los Agentes incorporados: planificación o solo lectura antes de permitir cambios y construcción solo para incrementos pequeños.

    4. Configura permisos para preguntar antes de editar archivos, ejecutar comandos o consultar la web.

    5. Revisa cada diferencia y cada comando antes de aprobarlo.

    Un punto de partida prudente para opencode.json:

    {
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "webfetch": "ask"
  }
}

  4. Planificar antes de construir:

    1. Pide al agente que lea README.md, docs/entrada y el esquema de datos.

    2. Solicita una lista de tareas pequeñas, ordenadas y comprobables.

    3. Pide riesgos, dependencias y casos de prueba, sin modificar archivos.

    4. Convierte esa salida en tu plan de trabajo y descarta lo que no encaje.

    Instrucciones útiles:

    • Lee el contrato del producto y propón cinco incrementos mínimos.

    • No modifiques archivos; solo analiza y explica.

    • Indica qué pruebas harían falta antes de escribir el código.

    • Señala qué partes del diseño de UD2 quedan simuladas o fuera del prototipo.

  5. Primera iteración:

    1. Crea la estructura de carpetas y los dos archivos de datos.

    2. Implementa la lectura del CSV con csv.

    3. Valida campos obligatorios, fecha, tipo y rango.

    4. Devuelve registros válidos y rechazos con motivo.

    5. Añade pruebas con unittest.

    6. Ejecuta las pruebas y registra el resultado.

    Comando de referencia:

    python -m unittest discover pruebas

Actividad

  1. Crea la estructura del proyecto y los archivos de datos normal y anómalo.

  2. Escribe un README inicial con objetivo, comando de ejecución y límites.

  3. Configura OpenCode en la carpeta del proyecto y revisa los permisos.

  4. Usa un agente de planificación para obtener tareas, riesgos y pruebas; no aceptes cambios todavía.

  5. Implementa la carga y validación de datos en incrementos pequeños.

  6. Ejecuta las pruebas, corrige un fallo y anota en docs/cambios.md qué aceptaste, modificaste o rechazaste.

7.3. Completar y probar el prototipo

  1. Incrementos del flujo completo:

    1. Procesamiento: agrupa por entidad y ventana temporal, calcula medias, mínimos, máximos o conteos.

    2. Decisión: aplica reglas explícitas y genera una acción con su motivo.

    3. Histórico: guarda cada decisión en datos/decisiones.jsonl.

    4. Alertas: lista datos rechazados, valores fuera de rango o lecturas ausentes.

    5. Interfaz: construye una TUI de menú con argparse para los argumentos y entrada de consola para las vistas.

  2. Objeto de decisión de referencia:

    {
  "fecha": "2026-03-01T09:00:00",
  "entidad": "parcela-01",
  "indicador": "humedad_media_24h",
  "valor": 38.0,
  "umbral": 45.0,
  "accion": "REGAR",
  "motivo": "Media inferior al umbral en las últimas 24 horas.",
  "registros_rechazados": 1
}

  3. TUI mínima:

    Prototipo: riego asistido
1. Resumen
2. Últimas lecturas
3. Estado por parcela
4. Decisiones
5. Datos rechazados
0. Salir

Opción: 3

parcela-01  media 38 %  umbral 45 %  estado SECA
parcela-02  media 52 %  umbral 45 %  estado OK

    Comando de referencia:

    python run.py --datos datos/lecturas.csv --historial datos/decisiones.jsonl

  4. Pruebas que debe superar el prototipo:

    Caso

    Entrada

    Resultado esperado

    Normal

    Datos válidos con humedad baja

    Decisión REGAR y registro en el histórico.

    Umbral

    Valor exactamente igual al umbral

    Resultado estable y explicado por la regla.

    Dato inválido

    Humedad negativa, fecha imposible o campo vacío

    Rechazo con motivo y alerta visible.

    Archivo ausente

    Ruta de datos inexistente

    Mensaje claro, sin un fallo confuso para el usuario.

    Ejecución repetida

    Mismo archivo procesado dos veces

    Histórico coherente y sin perder decisiones anteriores.

  5. Diagnóstico con agentes:

    1. Reproduce el error con el comando y los datos exactos.

    2. Usa un agente solo lectura para analizar el traceback, los archivos y las pruebas.

    3. Pide hipótesis ordenadas y el cambio mínimo probable.

    4. Autoriza una edición pequeña o ejecuta tú el cambio.

    5. Vuelve a pasar las pruebas.

    6. Registra la causa, la corrección y la comprobación.

  6. Seguridad y autoría:

    1. No pegues credenciales ni datos personales en el contexto del agente.

    2. Revisa los comandos antes de aprobarlos y evita operaciones destructivas.

    3. Desconfía de instrucciones ocultas en documentos o datos; es un riesgo de inyección de prompt.

    4. Comprueba que las Herramientas usadas coinciden con la tarea.

    5. Si aceptas código generado, debes poder explicar qué hace y por qué encaja en tu diseño.

Actividad

  1. Implementa el procesamiento, la regla de decisión y el histórico en incrementos separados.

  2. Construye la TUI con resumen, últimas lecturas, decisiones y datos rechazados.

  3. Añade y ejecuta las cinco pruebas de la tabla anterior.

  4. Introduce el archivo anómalo y comprueba que la aplicación muestra el rechazo sin romperse.

  5. Usa un agente para diagnosticar un fallo real o provocado y aplica la corrección mínima.

  6. Anota la iteración en docs/cambios.md y docs/uso_ia.md.

7.4. Demostrar y defender la solución

  1. Trazabilidad del producto:

    Desde el problema

    Hasta el dato

    Hasta la decisión

    Hasta la demostración

    Objetivo de UD1 y área de UD2.

    Campos, origen simulado y validación.

    Regla, umbral, motivo y acción.

    Vista de la TUI, histórico y alertas.

  2. Guion de demostración:

    1. Explica el problema y la parte de la arquitectura que has concretado.

    2. Muestra el archivo de datos y su esquema.

    3. Ejecuta el prototipo con un comando.

    4. Enseña el estado, la decisión y su motivo en la TUI.

    5. Introduce datos anómalos y muestra el rechazo o la alerta.

    6. Consulta el histórico y un cambio documentado.

    7. Explica límites, riesgos y mejoras futuras sin presentarlas como implementadas.

  3. Documentación mínima:

    1. README: objetivo, instalación, ejecución, demo y límites.

    2. Esquema de datos y origen simulado.

    3. Reglas de decisión y umbrales.

    4. Pruebas ejecutadas y resultado.

    5. docs/cambios.md: iteraciones, correcciones y decisiones.

    6. docs/uso_ia.md: sugerencias aceptadas, modificadas y rechazadas.

    7. Riesgos de seguridad, privacidad y continuidad.

    8. Mejoras futuras y partes que siguen siendo conceptuales.

  4. Revisión final con agentes:

    1. Usa un agente solo lectura para comprobar la coherencia entre problema, diseño, datos, regla e interfaz.

    2. Usa otro pase para revisar privacidad, permisos, secretos y comandos peligrosos.

    3. Usa un tercer pase para detectar pruebas insuficientes o casos límite.

    4. No aceptes automáticamente ninguna sugerencia: clasifícala y justifica la decisión.

  5. Preguntas de autoría que deberías saber responder:

    1. ¿Por qué este flujo demuestra el objetivo empresarial?

    2. ¿Por qué elegiste esos campos y ese origen simulado?

    3. ¿Qué hace exactamente el procesamiento?

    4. ¿Por qué la regla toma esa decisión?

    5. ¿Qué ocurre con datos incompletos, imposibles o repetidos?

    6. ¿Qué sugerencia de IA rechazaste y por qué?

    7. ¿Qué sigue simulado respecto a la arquitectura completa?

Actividad

  1. Ejecuta la lista completa de criterios de aceptación.

  2. Graba o ensaya la demostración siguiendo el guion anterior.

  3. Completa README, docs/cambios.md y docs/uso_ia.md.

  4. Pasa las tres revisiones con agentes y registra qué cambias y qué no.

  5. Corrige al menos una incoherencia detectada antes del cierre.

  6. Autoevalúate con la rúbrica publicada y señala tus limitaciones.

Test de autoevaluación

Actividad final integradora

Entrega un prototipo operativo en Python con TUI que cargue datos simulados, los valide y procese, tome una decisión justificada, guarde histórico y permita consultar estado, decisiones, alertas e histórico. Incluye README, esquema de datos, reglas, pruebas, registro de cambios y uso supervisado de IA. Prepara una demostración reproducible y una defensa de tus decisiones. Es una única evidencia; el enunciado detallado y la rúbrica se publicarán aparte. No uses datos personales, credenciales ni despliegues en producción.