1. Modelo mental
La IA de código es multiplicador de contexto. Si le das un problema bien delimitado, interfaces claras y tests, puede acelerar mucho. Si le das un repositorio sin mapa y le permites cambiar todo, acelera también la deuda técnica.
El objetivo no es “que escriba el código”, sino reducir el tiempo desde intención hasta cambio verificado. Eso incluye leer, proponer, implementar, probar, revisar y documentar.
Mantén el bucle corto: cambio pequeño → test → diff → revisión. Los grandes parches generados de una vez son difíciles de entender y aún más difíciles de mantener.
2. Conceptos que debes dominar
Archivos, arquitectura, convenciones y restricciones que el asistente debe conocer.
Unidad de revisión: qué cambió y por qué.
Contrato ejecutable que detecta regresiones.
Lint, type checking y seguridad como barreras deterministas.
Entorno donde ejecutar código sin dañar producción.
Paquetes inventados, desactualizados o inseguros.
Credenciales o datos sensibles expuestos al modelo o logs.
La persona/equipo debe poder explicar y mantener el cambio.
Cambio estructural que conserva comportamiento; necesita tests antes.
Agente que modifica varios archivos y ejecuta herramientas; requiere permisos y checkpoints.
3. Workflow paso a paso
Explica arquitectura
Da mapa mínimo del repo y objetivo.
El asistente no adivina frameworks.
Delimita cambio
Archivos y comportamiento esperado.
El diff previsto es pequeño.
Pide plan
Antes de editar, lista pasos y riesgos.
Puedes corregir enfoque barato.
Escribe tests
Primero o junto al cambio.
El comportamiento está especificado.
Implementa pequeño
Una unidad coherente.
Diff revisable.
Ejecuta herramientas
Tests, lint, types, security.
No confías sólo en lectura.
Revisa diff
Comprende cada línea significativa.
Podrías mantenerlo mañana.
Integra
Commit claro, rollback y observación.
Sabes revertir si aparece regresión.
4. Ejemplo completo
Bug:un parser acepta fechas inválidas.
En lugar de “arregla el parser”, aporta archivo, función, ejemplos válidos e inválidos y comportamiento esperado. Pide primero tests que reproduzcan el bug. Después implementa el cambio mínimo. Ejecuta test suite y revisa si la solución altera timezone o formatos colindantes.
Si no puedes explicar el diff, aún no está listo para merge.
5. Matriz de decisión
| Decisión | Qué mirar | Señal buena | Señal de riesgo |
|---|---|---|---|
| Autocomplete | Código local y claro | Acelera boilerplate | Aceptas sin leer |
| Chat de repo | Necesitas comprensión | Cita archivos y contexto | Indexación incompleta |
| Agente | Cambio multiarchivo | Tests + sandbox | Permisos amplios |
| Refactor | Tests sólidos | Mejora estructura | Sin baseline |
| Security fix | Alto impacto | Revisión especializada | Modelo decide solo |
6. Fallos y límites
Una guía útil también debe decir cuándo detenerse. Estos son los fallos que más cambian la calidad del resultado:
- Aceptar paquetes o APIs que no existen.
- Pegar secretos o datos de clientes.
- Permitir comandos destructivos sin sandbox.
- Generar grandes refactors sin tests.
- No revisar licencias/dependencias.
- Confundir código compilable con código correcto.
- Dejar comentarios o tests que sólo reflejan implementación.
- Usar IA para saltarse comprensión del sistema.
7. Cómo medirlo
No midas sólo si “parece bueno”. Define una señal observable antes de escalar.
| Métrica | Qué mide | Cómo observarla | Umbral/alerta |
|---|---|---|---|
| Lead time | Velocidad a cambio aprobado | Tiempo issue→merge | No baja |
| Review time | Carga de revisión | Minutos/diff | Crece por parches grandes |
| Regression rate | Calidad | Bugs post-merge | Sube |
| Test coverage useful | Contrato | Casos críticos cubiertos | Tests triviales |
| Diff size | Revisabilidad | Líneas/cambio | Parches enormes |
| Security findings | Riesgo | SAST/review | Nuevos hallazgos |
8. Checklist de producción
9. Ejercicios para convertir lectura en habilidad
- Da a una IA un bug y exige primero un test que falle.
- Pide dos soluciones y compara trade-offs antes de implementar.
- Revisa un diff generado y marca cada línea que no entiendas.
- Crea un prompt de repositorio con arquitectura y convenciones.
- Simula un paquete inventado y comprueba cómo lo detectarías.
10. Qué estudiar después
No intentes memorizar toda la IA. Encadena la siguiente pieza cuando resuelva una duda que ya has encontrado en la práctica.
Apéndice A · Preguntas que deberías poder responder
- ¿Qué parte del problema es determinista y cuál necesita juicio probabilístico?
- ¿Qué dato o ejemplo cambiaría tu decisión actual?
- ¿Cómo distinguirás una mejora real de una respuesta simplemente más convincente?
- ¿Qué ocurre cuando faltan datos, la herramienta falla o la respuesta es incierta?
- ¿Qué parte del proceso debe seguir bajo responsabilidad humana?
- ¿Qué coste operativo aparece después del primer prototipo?
- ¿Qué revisarías dentro de 30, 90 y 180 días para evitar que el sistema envejezca?
Si no puedes responder todavía a varias de estas preguntas, no significa que el proyecto esté mal: significa que has encontrado exactamente los huecos que la siguiente iteración debe cerrar. Ese es uno de los usos más valiosos de una guía técnica: convertir incertidumbre difusa en decisiones explícitas.
Apéndice B · Cuatro escenarios para practicar la decisión
Pregunta:Código local y claro.Señal favorable:Acelera boilerplate.Alerta:Aceptas sin leer.
Pregunta:Necesitas comprensión.Señal favorable:Cita archivos y contexto.Alerta:Indexación incompleta.
Pregunta:Cambio multiarchivo.Señal favorable:Tests + sandbox.Alerta:Permisos amplios.
Pregunta:Tests sólidos.Señal favorable:Mejora estructura.Alerta:Sin baseline.
No memorices la tabla como si fuera una regla universal. Cambia volumen, riesgo, disponibilidad, privacidad o coste y vuelve a recorrer la decisión. Un sistema robusto documenta qué variables sostienen la elección y cuáles podrían invalidarla.
Apéndice C · Cuaderno de campo para tu propio caso
Copia estas preguntas en un documento y complétalas con un caso real. El objetivo es que el conocimiento deje de estar en la página y pase a tu proceso.
- Problema¿Qué trabajo concreto intentas mejorar y para quién?
- Baseline¿Cómo se hace hoy, cuánto tarda y qué errores aparecen?
- Datos¿Qué entra, de dónde viene, quién puede verlo y qué no debería salir del entorno?
- Salida¿Qué formato y criterios convierten el resultado en usable?
- Prueba¿Qué 20–50 casos representarían el trabajo real?
- Riesgo¿Cuál es el fallo más costoso y cómo se detecta?
- Operación¿Quién observa, corrige, actualiza y puede detener el sistema?
- Revisión¿Qué evento o fecha obligará a reevaluar esta decisión?
Guarda también dos ejemplos que funcionaron y dos que fallaron. Con el tiempo, esos ejemplos se convierten en un pequeño dataset de evaluación mucho más útil que cualquier memoria informal de “esto parecía ir bien”.
Apéndice D · De prototipo a producción
Una demo responde a la pregunta “¿puede funcionar?”. Producción responde a otras: “¿funciona de forma repetible?”, “¿qué pasa cuando falla?”, “¿quién lo mantiene?”, “¿cómo sabemos que sigue siendo bueno dentro de tres meses?” y “¿podemos revertirlo?”. El salto entre ambas fases suele ser mayor que el salto entre dos modelos.
Antes de escalar, separa cuatro planos.Calidad:casos y métricas.Operación:latencia, cuotas, errores y costes.Gobernanza:permisos, datos, revisión y responsables.Cambio:versiones, fuentes y fechas de reevaluación. Si uno de estos planos no tiene dueño, el riesgo aparecerá precisamente cuando el uso crezca.
- Define un SLO de calidad y uno operativo.
- Registra versión de modelo, prompt, fuentes y configuración.
- Mantén una muestra estable para detectar regresiones.
- Añade un fallback para proveedor, herramienta o dato ausente.
- Decide qué errores se reintentan y cuáles se escalan.
- Presupuesta revisión humana, no sólo tokens.
- Evita permisos permanentes que sólo necesitabas para una prueba.
- Programa una revisión tras cambios de modelo, precio, política o dataset.
Finalmente, observa el sistema con tráfico real. Una mejora offline puede empeorar experiencia, coste o tasa de escalado. Las métricas de esta guía son el comienzo; adáptalas al impacto de tu caso y conserva siempre ejemplos concretos detrás de cada porcentaje.
Programación asistida: velocidad sin renunciar a ingeniería
La IA acelera código cuando el problema está bien delimitado. Entrega arquitectura relevante, archivos concretos, convenciones y criterio de aceptación. Pedir “mejora todo” favorece cambios grandes y difíciles de revisar. El tamaño del diff es una variable de calidad: cuanto más pequeño, más fácil entender causalidad y revertir.
Para bugs, pide primero una reproducción o un test que falle. Esa secuencia obliga a formalizar el comportamiento esperado antes de editar implementación. Después solicita el cambio mínimo y vuelve a ejecutar el test. Si el modelo modifica el test para que pase sin resolver el contrato, la revisión debe detectarlo.
No confíes en nombres de paquetes, métodos o APIs sin comprobar documentación. Los modelos pueden proponer dependencias plausibles pero inexistentes o APIs obsoletas. Bloquea versiones cuando corresponda, revisa licencias y usa compilador, type checker, linter y tests como verificadores deterministas.
Protege secretos. Nunca pegues claves, credenciales o datos de producción en un contexto por comodidad. Para agentes de código, limita acceso a repositorios y comandos; ejecuta en ramas o entornos aislados; pide confirmación antes de operaciones destructivas.
Mide lead time hasta cambio aprobado y regresiones posteriores. Generar código rápido no es productividad si la revisión, depuración y mantenimiento aumentan. El objetivo es acortar el ciclo completo sin degradar comprensibilidad ni seguridad.
Una escala de madurez para programación asistida: velocidad sin renunciar a ingeniería
Resuelve un caso real de principio a fin. Conserva entrada, salida y correcciones. Aquí buscas descubrir fallos, no automatizar.
La entrada y la salida ya tienen contrato, existen ejemplos límite y puedes medir calidad, tiempo y coste con el mismo criterio.
Hay observabilidad, permisos, fallback, responsable, revisión de cambios y un mecanismo para detectar regresiones antes de afectar al usuario.
La transición entre niveles debe estar motivada por evidencia. No pases a integración o autonomía sólo porque una demo salió bien. Pasa cuando hayas repetido la tarea con casos representativos, sepas dónde falla y el ahorro neto siga siendo positivo después de incluir revisión y operación.
Para los primeros 30 días, reúne ejemplos y construye el baseline. Entre 30 y 60 días, estabiliza el contrato de entrada/salida y convierte los fallos recurrentes en tests, checklist o reglas. Entre 60 y 90 días, si el volumen lo justifica, añade automatización, monitorización y revisión de costes. Si una etapa no supera sus propios criterios, mantén el sistema en la etapa anterior.
Documenta también las condiciones de salida: qué cambio de proveedor, política, precio, modelo, volumen o riesgo obligaría a reevaluar el diseño. Una arquitectura madura no pretende ser definitiva; hace explícito cuándo deja de ser válida.
Antes de considerar el trabajo terminado, realiza una revisión adversarial: busca deliberadamente entradas ambiguas, datos faltantes, instrucciones contradictorias, límites de cuota y resultados que parezcan correctos pero no puedan verificarse. El objetivo no es demostrar que el sistema funciona, sino descubrir bajo qué condiciones deja de funcionar y comprobar que esos fallos tienen una respuesta segura. Registra cada hallazgo y conviértelo en una prueba futura.
- Guarda al menos 20 casos reales, incluidos fallos.
- Define un criterio de aprobación que otra persona pueda aplicar.
- Separa métricas de calidad, coste y operación.
- Establece quién puede detener o revertir el sistema.
- Programa una fecha de revisión aunque nada parezca haber cambiado.
Documentación que sostiene y actualiza esta guía
Las capacidades y políticas cambian. Usa estas referencias para comprobar los puntos que dependan de un proveedor o de una versión concreta.