Contexto para apps móviles: que tu agente IA no improvise.

Hice un experimento para entender lo útil que puede ser el contexto en el mundo de las apps. Desarrollé una app y la llevé a dos plataformas: la misma idea, el mismo desarrollador y un agente parecido en cada plataforma. Sobre el papel eran idénticas pero en la práctica salieron muy distintas, y la única diferencia entre ellas fue que una arrancó con su contexto escrito y la otra empezó sin él.

Una de las versiones arrancó con su contexto escrito desde el principio: una especificación y un archivo que le decía al agente cómo era el proyecto (arquitectura, convenciones, qué respetar). La otra empezó con poco más que un README de instalación, y así estuvo durante meses.

El resultado lo contaba el propio repositorio. La versión con contexto tenía una arquitectura limpia, coherente, sin cabos sueltos. La otra, decisiones tomadas sobre la marcha, gestión de errores a medias, varios TO-DOs abandonados en el código y un documento de arquitectura que apareció tarde, cuando el desorden ya estaba hecho. La variable que las separó fue solamente el contexto.

Continuando con el mensaje de lo importante que es especificar para que el modelo no divague, ya que un agente siempre va a rellenar los huecos de información con lo primero que le sirva, el contexto cobra mayor importancia porque es lo que decide si esos huecos se rellenan con información de tu proyecto o con invenciones que le encajen.

Para no hablar en abstracto, vamos a usar el mismo ejemplo que recorre toda la serie: una app de gastos compartidos. Ya sabes, esas para repartir la cuenta de un viaje o de una cena entre varias personas. Su MVP es modesto a propósito: crear un grupo por evento, añadir un gasto indicando quién pagó, repartirlo de forma configurable, ver una pantalla de balance que diga quién le debe a quién y liquidar.

Lo que no entra en la v1 también está decidido: nada de pagos reales dentro de la app, nada de multidivisa, nada de modo offline. Sobre esa app iremos colgando todo lo que sea relevante sobre el contexto, porque las ideas bonitas se entienden de verdad cuando chocan con una feature concreta.

¿Qué es “el contexto” de una app en realidad?

El contexto de una app es el contrato que el agente lee antes de tocar el código, los documentos que le dicen cómo funciona esta app en concreto. No es un README de instalación ni documentación de adorno, es lo que convierte un “hazme una pantalla” en “hazme una pantalla que encaje aquí”.

Merece la pena decirlo porque cuesta verlo. Es fácil pensar que el contexto era “contarle al agente qué hace la app” y no es eso, o no solo eso. El contexto es contarle qué decisiones ya están tomadas para que no las vuelva a tomar él. En la app de gastos compartidos, que el reparto pueda ser por partes iguales, por porcentajes o por importes fijos es una decisión de producto que el agente debe respetar, no reinventar cada vez que toca esa zona.

En nuestros proyectos, este contrato vive en tres capas a nivel de cada app:

Llevado a un archivo, el contrato de la app de gastos compartidos se parece a esto. Es el CONTEXTO.md que dejamos en la raíz del repo para que el agente lo lea antes que cualquier otra cosa:

# CONTEXTO — App de gastos compartidos

## Qué es
Repartir gastos de un evento (viaje, cena) entre varias personas.
MVP:
- Crear un grupo por evento.
- Añadir un gasto indicando quién pagó.
- Reparto configurable: partes iguales / porcentajes / importes fijos.
- Pantalla de balance: quién debe a quién.
- Liquidar.
Fuera de la v1 (NO implementar):
- Pagos reales dentro de la app.
- Multidivisa.
- Modo offline.

## Cómo está hecha
Clean Architecture. Capas: ui / domain / data.
- ui    → pantallas y estado, sin lógica de negocio.
- domain→ casos de uso y reglas (el reparto vive aquí).
- data  → repositorios y fuentes de datos.

## Persistencia
Base de datos local → fuente de verdad de los datos.
Backend → solo sincronización entre dispositivos.
PROHIBIDO llamar al backend desde la UI. La UI habla con domain;
domain habla con data; data decide local vs. backend.

## Convenciones
Estado de pantalla: loading / error / data.
Errores: nunca un TODO; siempre un manejo real.

Ninguna de estas especificaciones es exótica, la mitad del archivo describe cosas que la app no hace. Ese “fuera de la v1” pesa tanto como el MVP, porque es lo que evita que el agente, en cuanto huela un campo de importe, te monte la conversión de divisas que nadie le ha pedido. Lo decisivo no es qué pone, sino que esté escrito antes de que el agente empiece a decidir por su cuenta.

Sin contexto, el agente no se para. Improvisa

Un agente IA sin contexto no se para a preguntar, improvisa una arquitectura plausible y sigue adelante. Como nunca dice “no sé”, rellena cada decisión que no le dimos con lo que supone razonable, y lo que supone casi nunca coincide con lo que ya tenemos montado.

En la versión sin contexto, eso se tradujo en lo previsible: errores resueltos “para salir del paso” con un TO-DO en lugar de un manejo real, ninguna regla sobre cuándo usar la base de datos local y cuándo el backend y patrones que cambiaban de una pantalla a otra. El agente no se equivocó según su propia lógica, el problema es que no tenía la nuestra.

Se ve más claro bajándolo a una feature de la app de gastos. Imaginemos que le pedimos añadir el reparto por porcentajes a un grupo. Sin contexto, un encargo así:

Añade que un gasto se pueda repartir por porcentajes entre los miembros del grupo

El agente, que es servicial hasta el agobio, hace de todo a la vez: mete la lógica del reparto dentro del widget de la pantalla, llama directamente al backend para “guardar los porcentajes”, se inventa un modelo nuevo en lugar de tocar el gasto que ya existe y, de paso, deja un “//TO-DO: validar que sumen 100%” por si acaso.

Funciona en la demo pero el resultado fue el incumplimiento de tres principios fundamentales en una única funcionalidad: acabé con la lógica de negocio incrustada en la interfaz, una conexión al backend que vulneraba el contrato y código de dominio redundante.

No lo hizo de mala fe, le pedimos un reparto… sin decirle dónde vive el reparto en nuestra app. Y donde no hay regla, hay improvisación.

El agente no improvisa porque sea malo. Improvisa porque no le dimos la información que necesitaba y tuvo que improvisar.

Con el CONTEXTO.md delante, ni siquiera hace falta pedir lo mismo de otra forma. El mismo encargo, ahora interpretado a través del contrato, suena así:

Añade el reparto por porcentajes a un gasto. 
- La regla del reparto va en domain (caso de uso), nunca en la UI.
- Reutiliza el modelo de gasto que ya existe; no crees uno nuevo.
- Persiste en la BD local; el backend solo sincroniza (no lo llames desde aquí).
- Estado de pantalla: loading / error / data. Sin TO-DO: valida que sumen 100%.

La diferencia no está en que escribamos más, sino en que esas cuatro líneas ya estaban escritas una vez, en el contrato, y el agente las arrastra a cada tarea. La pieza encaja en lugar de aterrizar de cualquier manera. Y lo mejor: la próxima feature (el filtro de gastos por persona, pongamos) hereda exactamente las mismas reglas sin que las repitamos.

La trampa del contexto a posteriori

Documentar la arquitectura después de escribir el código no es montar el contexto, es hacerle la autopsia. En la versión que salió mal, ese documento llegó tarde, con el grueso del código ya escrito. No dirigió ni una sola de aquellas decisiones, sino que se limitó a describir, con buena letra, el desorden que ya existía.

Y ahí está el matiz que más gente se salta: un contrato que firmas después del trabajo no es un contrato, es un acta. El contexto solo cumple su función (evitar que el agente improvise) si existe antes que el código que se supone que debe guiar.

Lo digo por experiencia. En la versión que salió mal, llegamos a tener un documento de arquitectura con diagramas, capas bien nombradas, todo. Y no servía de nada porque describía un código que ya había decidido otra cosa.

Documentar a posteriori es hacer la autopsia porque aprendes qué mató al proyecto, pero el proyecto ya está en la camilla. La feature del balance, por ejemplo, en esa versión calculaba quién debe a quién en tres sitios distintos y ningún documento posterior iba a unificar eso por mí.

Cómo montar el contexto antes de empezar

El contexto se monta al principio, antes del código y en las tres capas que ya vimos: qué es, cómo está hecha y qué no se toca. No tiene por qué ser largo, tiene que existir antes que la primera línea. En nuestras apps mejor montadas, cada una arranca con su carpeta de documentación (especificación, decisiones, diseño) validada antes de programar nada.

En la práctica, para la app de gastos compartidos eso fue una sesión corta con el agente discutiendo el contrato, no escribiendo código. Algo tan tonto como esto antes del primer commit:

repo/
|–– CONTEXTO.md       <-- qué es, cómo está hecha, qué no se toca
|–– docs/
|   |–– spec.md       <-- el MVP detallado: grupos, gastos, reparto, balance
|   |__ decisiones.md <-- por qué BD local como fuente de verdad
|__ (todavía sin una sola línea de código)

Parece poca cosa, pero con media hora de definición nos estamos ahorrando semanas de pelear con un agente que tira para donde no quieres. Cuando luego le pedimos la pantalla de balance, no tuvimos que explicarle de nuevo que el cálculo de “quién debe a quién” vive en domain porque ya lo sabía.

Para que el contrato funcione:

• Escríbelo antes del primer commit, no a mitad de camino.
• Mantenlo corto: decisiones y reglas, no una enciclopedia.
• Actualízalo cuando una decisión cambie, no cuando ya rompió algo.

El contexto es un contrato vivo, no un documento de archivo.

Y una advertencia, porque el péndulo se va fácil al otro extremo: el contexto no es un volcado de todo lo que sabes. Si metes una enciclopedia, el agente se pierde igual que si no metes nada. El contexto es el contrato, las decisiones y las reglas que de verdad lo atan, no cada detalle de implementación. Lo que no condiciona una decisión, sobra.

El contexto no es solo para apps nuevas, también para una funcionalidad

La mayor parte del tiempo no construimos una app de cero, añadimos una funcionalidad a una que ya existe. Y ahí el contexto importa igual, o incluso es más importante. El agente necesita saber dónde encaja esa pieza, qué reutilizar y qué dejar en paz o reinventará lo que ya tenemos montado.

Un ejemplo de andar por casa en la app de gastos que podría funcionar es pedirle “añade un filtro de gastos por persona en la pantalla del grupo”. Sin contexto de la funcionalidad, el agente puede montarnos una capa de datos nueva, duplicar el repositorio de gastos que ya existe o resolver el filtro con un patrón distinto al del resto de la app. Funciona, pero acabamos con dos formas de hacer lo mismo. Es la bola de nieve otra vez, ahora a escala de feature.

Con contexto de la funcionalidad, el encargo cambia de naturaleza:

Añade un filtro de gastos por persona en la pantalla del grupo.
- Filtra usando el GastoRepository que ya existe; no crees otra fuente.
- Sigue el patrón de la pantalla de listado de gastos.
- El filtrado es lógica de dominio: resuélvelo en el caso de uso, no en el widget.
- No toques el modelo de gasto.

El agente deja de inventar y se limita a colocar la pieza en su sitio. Es el mismo salto que con el reparto por porcentajes, pero a una escala todavía más pequeña y por eso más fácil de olvidar darle contexto, que es justo cuando muerde.

El contexto de una funcionalidad:

• Dónde encaja: la pantalla o el módulo y el patrón que debe seguir.
• Qué reutilizar: los repositorios, componentes o utilidades que ya existen.
• Qué no tocar: lo que queda fuera del alcance de esta feature.

Es el mismo contrato, una talla más pequeña

Es la misma idea de “definir y acotar” del primer artículo de la serie, pero aplicada al contexto: cada tarea, por pequeña que sea, tiene su porción de contexto. Dársela antes de empezar es lo que evita que el agente, por ayudarte con una funcionalidad, nos ensucie las otras veinte.

Dolor o boost: cambia cómo le hablamos al agente

Montar el contexto cambia, sobre todo, tu forma de comunicarte con el agente. Sin contexto, en cada sesión repetimos las mismas reglas, corregimos los mismos desvíos y vigilamos cada salida por si se ha inventado algo. Con contexto, señalamos la tarea y el agente se mantiene en los raíles que escribimos una vez.

Con la app de gastos se nota en que dejamos de escribir mensajes de tres párrafos explicando la arquitectura cada vez. Pasamos de “monta esto, pero recuerda que la lógica va en domain, y no llames al backend, y reutiliza el repositorio, y por favor nada de TO-DOs…” a, simplemente, “añade el filtro por persona” y el contrato hacía el resto del trabajo en cada prompt.

Esa es la diferencia entre que la IA sea un dolor o un acelerador. No la marca el modelo que uses, sino si le dimos el contrato antes de pedirle que trabaje. Es, en el fondo, la diferencia entre dirigir y rezar.

En esta serie, el contexto nace de la fase de definición del primer artículo y prepara las siguientes: el diseño, el stack, la spec y el desarrollo. El paso inmediato es darle al agente capacidades reutilizables (las skills), que se apoyan precisamente en este contrato para saber cómo y dónde actuar. Pero el orden no cambia nunca: primero el contrato, después la primera línea de código.