Prompting para devs: cómo pedirle a la IA código decente (sin sufrir)

Anoche, 11:47 pm. Te falta un endpoint y el deploy es mañana temprano. Le pides a la IA: “haz un login en Node”. Te responde con 300 líneas, usa librerías que no tienes, mete JWT sin refresh tokens, guarda passwords en texto plano (sí, pasa), y de paso inventa rutas que ni existen en tu repo.

Y ahí estás tú: con la laptop ya dando el viejazo, el Wi‑Fi del depa fallando, y el PM preguntando por Slack: “¿sí sale hoy?”.

La neta: muchas veces no es que la IA “sea mala”. Es que le pedimos como si fuera un junior telepático… pero sin onboarding, sin constraints y sin Definition of Done. Resultado: código de tutorial que se rompe en production.

Qué te vas a llevar

• Cómo armar prompts para que la IA te devuelva código compatible con tu stack y tus decisiones.
• Un template práctico (copiable) para features, refactors, bugfixes y tests.
• Cómo pedir alternativas con tradeoffs sin que te aviente un ensayo.
• Qué info mínima darle para evitar “funciona en mi máquina”.
• Cómo revisar lo que te da sin convertirte en auditor 40 minutos por respuesta.

Contexto real: la IA no adivina tu repo

Cuando trabajas con banda del equipo, das contexto sin pensarlo:

• “Estamos en Next.js 14 con App Router.”
• “Usamos Prisma, no Sequelize.”
• “En este monolito no metemos nuevas libs sin aprobación.”
• “El backend corre en Docker, Node 20, y production es Linux.”

La IA no trae ese mapa. Si no lo dices, te va a contestar con lo más probable “en promedio”:

• Versiones viejas.
• Librerías populares que no están en tu proyecto.
• Soluciones a medias (sin manejo de errores, logs decentes, rate limit, seguridad básica).

Decisión práctica: si quieres código decente, tu prompt tiene que funcionar como mini‑onboarding. En corto.

La guía principal: el prompt que sí jala (y por qué)

Piensa en 6 piezas. No siempre ocupas todas, pero entre más riesgo tenga el cambio (auth, pagos, permisos), más vale meterlas.

1) Rol + objetivo (qué quieres que entregue)

No es “escribe código”. Es “entrégame algo que yo podría convertir en un pull request sin llorar”.

Ejemplo (bien):

Actúa como dev backend senior. Necesito implementar un endpoint POST /api/login.

Por qué sirve: amarra el nivel de detalle y el estándar de calidad.

2) Contexto del sistema (stack, versiones, restricciones reales)

Aquí se mueren la mayoría de prompts flojos.

Incluye:

• Lenguaje y versión (Node 20, Python 3.11)
• Framework (Express, FastAPI)
• Auth (JWT, session cookies)
• DB + ORM
• Estándares del repo (eslint/prettier, arquitectura)
• Restricciones (sin nuevas dependencias, o “sí se vale usar Zod”)

Ejemplo:

Stack: Node 20 + Express 4, TypeScript. ORM: Prisma. DB: Postgres. Ya existe middleware de requestId y logger pino. No podemos agregar nuevas dependencias.

Si no lo pones, te sueltan un setup con Passport, o una lib random, y luego andas haciendo rollback porque el build tronó con el deadline encima.

3) Definición de “done” (criterios de aceptación)

Si no defines el “done”, te va a dar “algo que compila”… no lo que tu equipo considera correcto.

Ejemplo:

Done = valida input, rate limit básico (si no hay lib, al menos un TODO), responde errores consistentes ({ error: { code, message } }), y agrega tests.

4) Inputs/outputs concretos (contratos)

Esto evita endpoints “creativos” que no embonan con el frontend o con tu API gateway.

Ejemplo:

Request body: { "email": string, "password": string }.

200: { "token": string, "user": { "id": string, "email": string } }

401: { error: { code: "INVALID_CREDENTIALS", message: string } }

5) Ejemplos + edge cases (lo que rompe en la vida real)

Aquí es donde metes la realidad: datos sucios, usuarios necios, y flows incompletos.

• correos con mayúsculas y espacios
• usuarios que intentan 50 veces porque el teclado del cel falla
• perfiles incompletos (nulls) que nadie contempló

Ejemplo:

Edge cases: email con espacios al inicio/fin, password vacío, usuario no existe, usuario bloqueado por 5 intentos.

6) Formato de respuesta (para no pelearte con el output)

Pídelo como lo vas a consumir. Si no, te lo da todo revuelto y tú armas el rompecabezas.

Ejemplo:

Entrega:

1. explicación corta (5-8 bullets)
2. cambios por archivo (paths)
3. snippets listos para pegar
4. tests con Jest

Prompt template (copiar/pegar)

Guárdalo como snippet en tu editor o en Notion. Úsalo cuando quieras “código decente” y no fanfic.

Actúa como [rol: dev backend/frontend/mobile] senior.

Objetivo:
Quiero implementar: [feature/bugfix/refactor] en [módulo/servicio].

Contexto:
- Stack: [lenguaje+version], [framework], [runtime]
- Librerías permitidas/no permitidas: [...]
- DB/ORM: [...]
- Estándares del repo: [lint, patterns, arquitectura]
- Restricciones: [tiempo, performance, seguridad, compatibilidad]

Contrato:
- Input:
- Output:
- Errores:

Criterios de aceptación (Definition of Done):
- [...]

Edge cases:
- [...]

Entrega el resultado así:
1) Resumen en bullets
2) Cambios por archivo con paths
3) Código
4) Tests
5) Riesgos/Tradeoffs

Antes de escribir código, hazme 5 preguntas si te falta info.

Esa última línea (“hazme 5 preguntas…”) es oro. En equipos reales, lo que más cuesta no es teclear: es alinear supuestos antes de que el cambio caiga en QA.

Cómo usar prompting según el tipo de tarea

Feature nueva (ej. endpoint)

• Pide contrato + criterios de aceptación + tests.
• Pide que se adapte a tu estructura de carpetas.

Mini prompt:

Tenemos esta estructura:
- src/routes/auth.ts
- src/services/authService.ts
- src/lib/errors.ts

Implementa login con ese patrón. No inventes nuevas carpetas.

Bugfix (cuando ya duele)

Dale síntomas, logs, versión y cómo reproducir. Si no, te van a contestar “podría ser X” y te quedas igual.

Mini prompt:

Bug: a veces devuelve 500 en /api/login.
Log: "TypeError: cannot read properties of undefined (reading 'id')" en authService.ts:72
Repro: usuario sin registro de profile.
Necesito fix + test que lo cubra.

Refactor (sin romper todo)

Pide “cambios mínimos” y “mantener API”. Eso reduce el diff, baja el riesgo, y hace más fácil el review.

Mini prompt:

Refactor: extrae validación a funciones puras.
No cambies firmas públicas. Mantén responses iguales. Prioriza diff pequeño.

Tests (para que no te dé tests de adorno)

Dile qué runner usas, cómo se mockea DB, y qué nivel quieres. Si no, te sueltan unit tests que no cubren el bug real.

Mini prompt:

Usamos Jest + supertest. DB se mockea con Prisma sqlite in-memory.
Dame tests de integración para 200/401/422.

Screenshots sugeridos

• Captura del prompt template en tu herramienta (ChatGPT/Claude/Copilot Chat) con el bloque “Contexto / Contrato / Done”.
• Captura del diff en el IDE (VS Code) mostrando “cambios por archivo” como lo entregó la IA.
• Captura de ejecución de tests (terminal) con jest pasando.
• Captura de un ejemplo de error response JSON consistente.

Errores comunes (y cómo arreglarlos en corto)

1) “Hazme un login” (demasiado abierto)

Síntoma: te da una solución genérica, mete dependencias nuevas, o no coincide con tu repo.

Arreglo: agrega stack + restricciones + estructura de archivos.

2) No pedir versión / no pedir compatibilidad

Síntoma: te sugiere APIs viejas (o experimentales) y te truena el build.

Arreglo: especifica versiones y pide “no uses features experimentales”.

3) No pedir tests

Síntoma: terminas validando “a ojo” a las 2am, y el bug sale en QA (o peor: en production).

Arreglo: agrega Definition of Done con “tests mínimos” + casos.

4) Pedir “mejor práctica” sin tradeoffs

Síntoma: te sermonea, te da 6 opciones y no decide.

Arreglo: pídele 2 opciones máximo y que recomiende una con razones.

Prompt:

Dame 2 opciones (A/B) y recomiéndame una.
Incluye tradeoffs: seguridad, complejidad, mantenimiento.

5) Copiar/pegar sin revisar (la trampa clásica)

Síntoma: funciona en local, se rompe en production con datos reales (nulos, encoding, timezone, permisos).

Arreglo: pídele que liste supuestos y puntos de riesgo. Y tú valida esos supuestos contra tu repo.

Prompt:

Antes del código, lista supuestos y riesgos. Si algo depende de mi repo, pregúntame.

Checklist final (antes de hacer merge)

• El prompt incluía stack, versiones y restricciones (sin nuevas deps si aplica).
• El output respeta la estructura de carpetas del repo (no “inventó” arquitectura).
• Hay contrato claro: inputs, outputs, errores.
• Maneja edge cases reales (nulos, espacios, intentos, usuarios incompletos).
• Incluye tests que fallan si rompes el comportamiento.
• No guarda secretos ni credenciales en logs.
• El código tiene manejo de errores consistente.
• Revisaste supuestos: ¿de dónde sale user.profile? ¿puede ser null?
• Corriste lint + tests local (aunque sea en la laptop cansada).
• Si es auth: revisaste hashing, expiración de tokens y políticas básicas.

FAQ

1) ¿Cuál es la diferencia entre un prompt “bonito” y uno útil?

Que el útil trae restricciones y contrato. Un prompt bonito suena bien, pero no evita que la IA meta libs raras o te cambie el estilo del repo.

2) ¿Cuánto contexto es demasiado contexto?

Si el cambio es pequeño (un helper), con stack + firma + ejemplo basta. Si es auth/pagos/datos sensibles, el contexto extra te ahorra horas y sustos.

3) ¿Qué hago si la IA se inventa funciones o archivos?

Dile explícitamente: “no inventes módulos; usa estos archivos” y pega la estructura real. Si puedes, pásale el snippet del archivo existente para que se acople al estilo del repo.

4) ¿Conviene pedirle que pregunte antes de codear?

Sí, sobre todo cuando hay ambigüedad. Es como cuando un senior te dice: “antes de moverle, dime cómo está el flujo de auth”. Te ahorra re‑trabajo.

5) ¿Cómo le pido que no me entregue código inseguro?

Incluye en Done: hashing, manejo de sesiones/tokens, validación de input, no exponer PII, y “no logs de password/token”. También pide que marque riesgos.

Siguiente episodio

Ya lograste que la IA te entregue código decente… ahora falta lo que de verdad te salva: que sea confiable.

Nos vamos a meter a la parte incómoda: tests, fixtures y cómo usar la IA para encontrar esos casos raros que QA te va a reclamar el viernes a las 6 pm, justo cuando ya querías cerrar la laptop.