ATLAS + GOTCHA -- Parte 3

GOTCHA: Las 6 capas que hacen pensar a la IA

#ai #gotcha #prompts #framework

El problema

En el Articulo 2, aprendiste ATLAS — la checklist que estructura tu pensamiento antes de hablar con la IA. Completaste las cinco fases. Sabes que vas a construir, como fluyen los datos, como se conectan los componentes, en que orden construir y como validar.

Y ahora que?

Tienes un cuaderno lleno de decisiones. Pero la IA no lee cuadernos. Lee prompts. Y aqui esta el problema: la mayoria de developers cogen su trabajo de ATLAS y lo comprimen en un solo parrafo. “Construye un servicio de notificaciones que escuche eventos de Service Bus y envie emails y SMS usando Azure Communication Services, con logica de reintentos e idempotencia.”

Eso es mejor que “construye un servicio de notificaciones.” Pero sigue siendo un bloque de texto. La IA tiene que adivinar que es un objetivo, que es una restriccion, que es una herramienta y que es una regla. Tiene que adivinar prioridades. Y adivinar es donde las cosas salen mal.

GOTCHA resuelve esto. Coge tus decisiones de ATLAS y las organiza en seis capas que encajan con la forma en que los modelos de IA procesan la informacion. Cada capa responde a una pregunta diferente. Cada capa le da a la IA un tipo especifico de instruccion.

Piensalo asi: ATLAS son los deberes que haces. GOTCHA es el formato que usas para entregarlos.

La solucion

GOTCHA tiene seis capas. El orden sigue el acronimo, y cada capa se construye sobre la anterior.

G — Goals

Lo que la IA debe conseguir.

Goals es la declaracion de mision. Le dice a la IA como se ve el exito. No como llegar — solo a donde llegar.

Una buena seccion de Goals es corta, especifica y medible. La IA deberia poder leerla y responder: “Se como es el resultado final?” Si la respuesta es no, tu seccion de Goals necesita trabajo.

Goals malo:

Build a notification service.

Demasiado vago. Que tipo de notificaciones? Que las dispara? Que significa “terminado”?

Goals bueno:

Build a .NET 10 worker service that:
- Listens for OrderConfirmed and ShipmentDispatched events from Azure Service Bus
- Sends email and SMS notifications to users via Azure Communication Services
- Sends push notifications via Azure Notification Hubs
- Processes each event within 30 seconds of receipt
- Guarantees at-least-once delivery (no lost notifications)

Cinco puntos. Cada uno es testeable. La IA sabe exactamente que significa “terminado.”

La regla clave para Goals: no pongas detalles de implementacion aqui. “Usa el repository pattern” no es un goal — es una heuristica. “Enviar notificaciones en menos de 30 segundos” es un goal. Mantenlos separados.

O — Orchestration

Como se coordinan los componentes y en que orden.

Orchestration le dice a la IA la secuencia. Que pasa primero, que pasa despues, que depende de que. Sin esto, la IA elige su propio orden — y podria construir el tejado antes que los cimientos.

Orchestration es donde tu fase Assemble de ATLAS se convierte en instrucciones:

Build in this order:

1. Event schemas (shared contract library)
2. Service Bus consumer (event listener + deserialization)
3. User preference service (PostgreSQL lookup)
4. Template engine (render notification content)
5. Channel dispatcher (route to email, SMS, or push provider)
6. Provider implementations:
   a. Azure Communication Services Email
   b. Azure Communication Services SMS
   c. Azure Notification Hubs (can return mock response initially)
7. Retry logic with exponential backoff
8. Idempotency guard (check notification_log before sending)
9. Dead letter handling
10. Health check endpoint and Prometheus metrics

Diez pasos. Cada uno es claro. La IA no intentara construir la logica de reintentos antes de que existan los providers. No conectara las metricas antes de que el servicio principal funcione.

La regla clave para Orchestration: se explicito con las dependencias. Si el paso 5 depende del paso 3, dilo. La IA respeta la secuencia cuando le das una secuencia.

T — Tools

Lo que la IA puede usar.

Tools es la lista de la compra. Le dice a la IA que frameworks, librerias, APIs y plataformas usar. Sin ella, la IA elige lo que mas vio durante su entrenamiento — que podria ser la version equivocada, la libreria equivocada, o algo que no quieres en tu proyecto.

- .NET 10 (worker service template)
- Azure.Messaging.ServiceBus (NuGet)
- Azure.Communication.Email (NuGet)
- Azure.Communication.Sms (NuGet)
- Microsoft.Azure.NotificationHubs (NuGet)
- Entity Framework Core 10 with Npgsql provider
- PostgreSQL 16
- xUnit + Moq for testing
- Docker for local development
- Kubernetes for deployment

Se especifico con las versiones cuando importa. ”.NET 10” no solo ”.NET”. “PostgreSQL 16” no solo “PostgreSQL”. La IA conoce todas estas herramientas, pero al listarlas explicitamente te aseguras de que no sustituya algo distinto.

La regla clave para Tools: si no lo listas, la IA podria elegir algo que no quieres. Si listas algo que contradice otra herramienta, la IA se liara. Se completo y consistente.

C — Context

Conocimiento de fondo, restricciones y patrones existentes.

Context es todo lo que la IA necesita saber sobre tu entorno pero no puede adivinar. Tu estructura de codigo existente. Tus convenciones de nombres. Tu destino de despliegue. Las reglas de tu equipo.

Esta es la capa mas infravalorada. La mayoria de developers la saltan porque piensan que la IA “simplemente lo sabe.” Pero la IA no conoce tu proyecto. No sabe que despliegas en Azure Kubernetes Service. No sabe que tu equipo usa una estructura de carpetas especifica. No sabe que tu empresa requiere que todos los servicios envien logs a una plataforma central.

- This service is part of an e-commerce microservices platform
- Other services: Order Service, Inventory Service, Payment Service, Shipment Service
- All services communicate via Azure Service Bus topics
- All services deploy to AKS (Azure Kubernetes Service) in West Europe
- Database per service pattern: this service owns user_preferences and notification_log tables
- Existing naming convention: PascalCase for C# classes, kebab-case for K8s resources
- All services use structured logging with Serilog → Azure Monitor
- Authentication between services uses managed identities, not connection strings
- Current environment: Development (local Docker Compose) and Production (AKS)

Nueve lineas. Cada una previene un error. Sin “managed identities, not connection strings,” la IA generaria codigo con connection strings hardcodeados. Sin “Serilog → Azure Monitor,” usaria Console.WriteLine.

La regla clave para Context: incluye cualquier cosa especifica de TU proyecto. Si otro developer que se une a tu equipo necesitaria saberlo, la IA tambien necesita saberlo.

H — Heuristics

Guardarrailes de comportamiento, reglas practicas y puertas de calidad.

Heuristics son las reglas que la IA debe seguir mientras construye. No que construir (Goals), no en que orden (Orchestration), sino COMO construirlo. Estilo de codigo, patrones, estrategias de manejo de errores, cosas que siempre hacer y cosas que nunca hacer.

DO:
- Use the repository pattern for all database access
- Use async/await for all I/O operations
- Return structured error responses (not exceptions to the caller)
- Log every notification attempt with correlation ID
- Make all provider calls idempotent (check notification_log first)
- Use dependency injection for all services
- Write unit tests for service layer, integration tests for repositories

DON'T:
- Don't put business logic in the event consumer (delegate to services)
- Don't catch and swallow exceptions silently
- Don't use static methods for anything that touches I/O
- Don't store secrets in code or config files (use Azure Key Vault)
- Don't create synchronous wrappers for async methods

El formato DO/DON’T funciona bien para Heuristics. Es claro, facil de escanear y no deja espacio para interpretacion.

Heuristics es donde los estandares de codigo de tu equipo se convierten en instrucciones para la IA. Cada “siempre hacemos X” y “nunca hacemos Y” va aqui. Cuanto mas especifico, mejor. “Escribe codigo limpio” es inutil. “Usa dependency injection para todos los servicios” es accionable.

La regla clave para Heuristics: se lo bastante especifico como para que la IA pueda comprobar su propio trabajo. Cada heuristica deberia ser una pregunta de si o no: “He usado el repository pattern?” Si o no. “El codigo esta limpio?” Eso no se puede comprobar.

A — Args

Parametros, inputs y configuracion para esta ejecucion especifica.

Args son los datos concretos. Todo lo demas en GOTCHA es estructural — podria aplicarse a muchos proyectos. Args es lo que lo hace especifico para ESTA ejecucion, ESTE entorno, ESTE despliegue.

Service Bus:
  Connection: from environment variable SERVICEBUS_CONNECTION
  Topic: order-events
  Subscription: notification-service
  Max concurrent calls: 10

PostgreSQL:
  Connection: from environment variable DB_CONNECTION
  Schema: notifications
  Tables: user_preferences, notification_log

Azure Communication Services:
  Connection: from environment variable ACS_CONNECTION
  Email sender: notifications@contoso.com

Azure Notification Hubs:
  Connection: from environment variable NH_CONNECTION
  Hub name: ecommerce-notifications

Kubernetes:
  Namespace: ecommerce
  Replicas: 2 (minimum)
  CPU request: 250m, limit: 500m
  Memory request: 256Mi, limit: 512Mi
  Health check: /healthz on port 8080

Estos son los valores que la IA mete en el codigo que genera. Sin ellos, se inventa connection strings, adivina numeros de puerto y usa valores placeholder que tendras que reemplazar despues.

La regla clave para Args: cada valor que la IA necesita para generar codigo funcional deberia estar aqui. Si quieres que la IA use variables de entorno en vez de valores hardcodeados, dilo explicitamente.

Execute

Vamos a ver las seis capas funcionando juntas. Aqui esta el prompt GOTCHA completo para el servicio de notificaciones que disenamos con ATLAS en el Articulo 2.

=== GOALS ===
Build a .NET 10 worker service that:
- Listens for OrderConfirmed and ShipmentDispatched events from Azure Service Bus
- Sends email and SMS notifications via Azure Communication Services
- Sends push notifications via Azure Notification Hubs
- Processes each event within 30 seconds of receipt
- Guarantees at-least-once delivery (no lost notifications)
- Respects user notification preferences (opt-out per channel)

=== ORCHESTRATION ===
Build in this order:
1. Event schemas (shared contract library, NuGet package)
2. Service Bus consumer (listener + JSON deserialization)
3. User preference service (EF Core repository → PostgreSQL)
4. Template engine (load + render per event type and channel)
5. Channel dispatcher (routes to correct provider based on preference)
6. Providers: ACS Email, ACS SMS, Notification Hubs
7. Retry logic (exponential backoff, 3 attempts per provider)
8. Idempotency guard (check notification_log before each send)
9. Dead letter handler (move poison messages, alert via log)
10. Health endpoint (/healthz) and Prometheus metrics

=== TOOLS ===
- .NET 10 worker service
- Azure.Messaging.ServiceBus
- Azure.Communication.Email + Azure.Communication.Sms
- Microsoft.Azure.NotificationHubs
- Entity Framework Core 10 + Npgsql
- PostgreSQL 16
- Serilog + Serilog.Sinks.AzureMonitor
- xUnit + Moq
- Docker + Kubernetes

=== CONTEXT ===
- Part of an e-commerce microservices platform on AKS (West Europe)
- Other services: Order, Inventory, Payment, Shipment
- All inter-service communication via Service Bus topics
- Database per service pattern (this service owns its tables)
- Managed identities for Azure resource access (no connection strings in code)
- Structured logging to Azure Monitor via Serilog
- Naming: PascalCase for C# classes, kebab-case for K8s resources

=== HEURISTICS ===
DO:
- Repository pattern for all database access
- Async/await for all I/O
- Dependency injection for all services
- Correlation ID on every log entry
- Check notification_log before sending (idempotency)
- Unit tests for services, integration tests for repositories

DON'T:
- No business logic in event consumer
- No silent exception swallowing
- No static I/O methods
- No secrets in code (Azure Key Vault only)
- No synchronous wrappers for async methods

=== ARGS ===
Service Bus: env SERVICEBUS_CONNECTION, topic order-events, sub notification-service
PostgreSQL: env DB_CONNECTION, schema notifications
ACS: env ACS_CONNECTION, sender notifications@contoso.com
Notification Hubs: env NH_CONNECTION, hub ecommerce-notifications
K8s: namespace ecommerce, 2 replicas, 250m/500m CPU, 256Mi/512Mi memory
Health: /healthz on port 8080

Eso es un prompt. Cada decision que tomaste en ATLAS esta ahora estructurada para la IA. Goals viene de Architect. Orchestration viene de Assemble. Tools viene de Link. Context viene de Trace y Link. Heuristics viene de Assemble. Args viene de Stress-test.

Sin adivinanzas. Sin “asumi que querias…” Sin el framework equivocado. Sin logica de reintentos olvidada.

Template

Aqui esta el template de GOTCHA que puedes copiar y rellenar para cualquier prompt:

=== GOTCHA PROMPT TEMPLATE ===

=== GOALS ===
(Que debe conseguir la IA? Solo resultados medibles.)

=== ORCHESTRATION ===
(En que orden? Que depende de que?)

=== TOOLS ===
(Frameworks, librerias, APIs, plataformas. Se especifico con las versiones.)

=== CONTEXT ===
(El entorno de tu proyecto, convenciones, restricciones.)

=== HEURISTICS ===
DO:
- (reglas a seguir)

DON'T:
- (reglas a evitar)

=== ARGS ===
(Valores concretos: connection strings, puertos, namespaces, limites.)

Usalo junto con la checklist de ATLAS del Articulo 2. ATLAS llena tu cabeza. GOTCHA llena el prompt.

Challenge

Antes del Articulo 4, prueba esto: coge la checklist de ATLAS que rellenaste en el challenge del Articulo 2 y traducela a un prompt GOTCHA. Usa el template de arriba. Mapea cada fase de ATLAS a su capa de GOTCHA.

No te preocupes si algunas capas quedan delgadas. Es normal. Goals y Heuristics suelen ser las mas largas. Args puede ser corto si tu proyecto es simple. Lo importante es separar las capas — no mezcles goals con heuristics, no pongas tools en el context.

En el Articulo 4, pondremos ATLAS y GOTCHA uno al lado del otro y mostraremos el mapeo exacto. Veras como cada decision humana tiene un lugar en las instrucciones de la IA — y construiremos un master prompt template que puedes usar en cualquier proyecto.

Si esta serie te ayuda, considera invitarme a un cafe.

Comments

Loading comments...