Promptes delimitados: Impidiendo que los asistentes de IA inventen una pila paralela

Pide a un asistente de programación que “construya una página de configuración del usuario” y por lo general obtendrás algo que se compila, se renderiza y parece terminado. Si lo observas más de cerca, el diferencial suele incluir su propio almacén de estado, sus propios auxiliares para realizar solicitudes y una biblioteca de validación que tu repositorio nunca ha utilizado. Nada falla, y ese es precisamente el motivo por el cual el problema pasa desapercibido durante la revisión. Este artículo explica por qué las solicitudes vagas fracasan de esta manera, por qué añadir adjetivos no ayuda y cómo redactar una instrucción precisa, además de una lista de verificación reutilizable que mantiene el código generado dentro de tu arquitectura existente.

Cómo fracasan suavemente las solicitudes vagas

Imagínese un equipo trabajando en una aplicación de administración para clientes desarrollada con React y TypeScript. La base de código ya cuenta con primitivas de formularios, un cliente API compartido y un gancho para notificaciones. Alguien pide al asistente una página de configuraciones en una sola oración breve. El resultado incluye pestañas, formularios, mensajes emergentes, elementos de carga temporal y un pequeño almacén de estado. Sin embargo, este cambio discrepaba en silencio con la base de código:

• El estado de los formularios es gestionado por una biblioteca que el proyecto no utiliza.
• Nuevos envoltorios para fetch se encuentran junto al cliente API compartido.
• Los mensajes emergentes se generan directamente en el código en lugar de pasar por el gancho de notificaciones del proyecto.
• Los esquemas de validación ignoran las estructuras ya definidas en types/.
• Un “almacén de configuraciones” del lado del cliente alberga tres campos que en realidad pertenecen al servidor.
• Los elementos de carga temporal no coinciden con el resto del panel de control.

Nada de esto genera un error, y podría sobrevivir a una revisión rápida a menos que alguien abra package.json. Ese es el peligro: las instrucciones vagas fallan de forma sutil. Introducen una segunda forma de hacer algo que el equipo ya resolvió, y todo futuro mantenedor hereda ambas. El asistente es bueno con el código que puede ver; los archivos que nunca abrió son los que deciden si la función realmente pertenece a tu aplicación.

Por qué una instrucción más larga no es la solución

El consejo habitual es ser más específico. Un segundo intento natural solicita una página de configuración “perfeccionada y lista para producción” con “una UX limpia, buen TypeScript y un manejo sólido de errores”.

Eso genera la misma arquitectura paralela, solo que con mayor seguridad. Las palabras describen el gusto, y el gusto deja al modelo completamente libre para inventar la estructura. Lo que faltaba nunca fue elocuencia, sino límites: declaraciones explícitas sobre qué puede usar el modelo, qué no debe añadir y qué se considera completado.

Escribiendo la versión limitada

La instrucción limitada a continuación solicita la misma función, pero se lee como una descripción de puesto. Menciona los componentes exactos, el hook, el cliente API y el archivo de esquema a reutilizar, enumera el comportamiento en las pestañas y al enviar, define las pruebas y termina con prohibiciones explícitas.

Build a user settings page in React and TypeScript.
Use ONLY these existing pieces:
- `src/components/FormField.tsx`
- `src/components/Button.tsx`
- `src/hooks/useNotify.ts`
- `src/api/client.ts` (no new fetch wrappers)
- validation schemas from `src/types/userSettings.ts`
Behavior:
- Tabs: Profile, Notifications, Security
- Preserve unsaved edits when switching tabs
- Show server field errors beside the matching inputs
- Disable submit while in flight
- Ignore duplicate submits
Tests:
- loading, success, server error, duplicate click
- empty required fields
Do NOT:
- add a state-management library
- add a toast library
- create a new API client
- invent types that duplicate `src/types/userSettings.ts`

Esto es menos una instrucción amigable que una nota de arquitectura que el modelo debe seguir. En comparación con la versión breve, comunica siete aspectos que anteriormente quedaban al azar:

1. Qué componentes existentes reutilizar.

Dónde se encuentra la fuente de verdad para la validación.

Reglas de interacción, como mantener las ediciones no guardadas entre pestañas.

Dónde deben aparecer los errores.

Comportamiento de concurrencia: el estado en proceso y los envíos duplicados.

Pruebas que definen qué significa “listo”.

Detenciones estrictas ante nuevas dependencias.

Con esas restricciones, la diferencia resultante se vuelve agradablemente aburrida. Utiliza el mismo FormField, el mismo useNotify, el mismo api/client. Las pestañas mantienen su estado no guardado sin necesidad de un almacén nuevo, y los envíos duplicados se gestionan mediante un botón deshabilitado y una prueba, en lugar de un comentario que diga “tratar esto más tarde”. Los conjuntos de código ya existentes contienen patrones; la tarea del prompt es señalarlos con tanta claridad que el modelo no pueda pasarlos por alto.

Esto también explica por qué los desarrolladores experimentados suelen obtener mejores resultados con los asistentes. Su ventaja no radica en la redacción, sino en saber de antemano qué detalles son importantes. Lo que importa es comunicar la arquitectura, no decorar el prompt.

Una prueba rápida de limitación

Si su prompt tendría sentido si se pegara en cualquier repositorio del mundo, aún no está limitado. Un buen prompt debería ser ligeramente inútil fuera de su propio árbol de fuentes, ya que hace referencia a sus rutas, tipos y convenciones.

Una lista de verificación reutilizable antes de comenzar

Mantener un plantilla por encima de cada solicitud de funcionalidad convierte este estilo estructurado en un hábito. La que se muestra a continuación agrupa las preguntas por contexto, invariantes, comportamiento, restricciones y una definición de terminación. La sección de invariantes es la que más a menudo se omite: decidir si los datos deben almacenarse en el servidor, en la URL o en el estado de la interfaz local evita que surja el problema de “almacenar tres campos” desde un principio.

CONTEXT
- Stack: React + TypeScript
- Relevant paths: ...
- Patterns to copy: ...

INVARIANTS
- Where does data live (server / URL / local UI state)?
- What must survive refresh?
- What is the source of truth for types/validation?

BEHAVIOR
- Happy path
- Empty / invalid input
- Server errors (field-level + form-level)
- Slow network / double submit
- Permission failure

CONSTRAINTS
- Do not add: ...
- Do not invent parallel: API client / store / toast / form lib
- Prefer editing: [files]

DONE
- Tests for: ...
- Manual checks: ...

Utilice la plantilla como umbral de preparación. Si no puede completar las restricciones y los caminos relevantes, aún no está listo para generar código; sigue en fase de diseño. Generar código mientras el diseño aún no está finalizado es precisamente cómo surge una segunda arquitectura. Las partes estables de esta lista de verificación pueden incluirse en un archivo de instrucciones del proyecto; consulte nuestra guía sobre cómo escribir un archivo CLAUDE.md eficaz.

Qué aún necesita revisión humana

Los prompts delimitados eliminan la mayor parte del ruido, pero no reemplazan el juicio. Al revisar las diferencias, sigue comprobando:

• Un nuevo paquete que nadie ha aprobado.
• Otra forma de llamar a la API.
• Tipos que se desvían del contrato del servidor.
• Estado en el lado del cliente para datos que debería gestionar el servidor.
• Pruebas que no prueban nada más allá del camino óptimo asumido por el modelo.

Escribir el prompt es la parte sencilla; saber qué límites son importantes en esta base de código es lo complicado, y ese conocimiento pertenece al equipo.

El cambio más pequeño que hacer hoy

Si una lista completa de verificación te parece abrumadora, agrega solo tres líneas a tu próxima solicitud de funcionalidad: qué rutas usar, qué bibliotecas no añadir y cómo se ve un resultado “completado”, incluyendo al menos una ruta de fallo.

Use only: [paths]
Do not add: [libs]
Done when: [2–3 behaviors + one failure path]

Conclusión

• Las instrucciones vagas rara vez causan fallos; crean infraestructura duplicada que parece terminada pero te cuesta caro más adelante.
• Más adjetivos cambian el tono del resultado, no su estructura. Las restricciones sí modifican la estructura.
• Una instrucción bien definida indica los nombres de los archivos a reutilizar, la fuente de verdad para los datos y tipos, el comportamiento en casos extremos, las pruebas y las dependencias que están prohibidas.
• Cuando el modelo inventa algo fuera de los límites establecidos, considéralo como una falta de delimitación: corrige la instrucción y regénerala en lugar de pulir la redacción.

Lecturas relacionadas

• Mantener los Hooks Headless: Separar el Comportamiento de las Alertas del Renderizado de Estas — Aprenda por qué un hook de React que devuelve JSX oculta parte del árbol de componentes, vincula el comportamiento con la presentación, y cómo refactorizarlo para exponer el estado en su lugar.
• Dirigir Agentes de Codificación AI con Cuatro Patrones de Arquitectura React Nombrados — Conozca cuatro patrones de React (composición por secciones, hooks personalizados, componentes polimórficos, reducers) y cómo nombrarlos en las instrucciones permite obtener código generado por IA más limpio.