Aprende patrones de prompting probados que guían a la IA hacia requisitos más claros, diseños modulares y código testeable—reduciendo refactors y ciclos de reescritura.
“Arquitectura más limpia” en este post no significa un framework concreto ni un diagrama perfecto. Significa que puedes explicar el sistema de forma simple, cambiarlo sin romper partes no relacionadas y verificar el comportamiento sin tests heroicos.
Claridad significa que el propósito y la forma del sistema son obvios desde una breve descripción: qué hace, quién lo usa, qué datos maneja y qué nunca debe hacer. En el trabajo asistido por IA, la claridad también significa que el modelo puede reformular los requisitos de vuelta a ti de una forma que aprobarías.
Modularidad significa que las responsabilidades tienen límites claros. Cada módulo tiene un trabajo, entradas/salidas y mínimo conocimiento de los internos de otros módulos. Cuando la IA genera código, la modularidad evita que esparza reglas de negocio por controladores, UI y acceso a datos.
Testeabilidad significa que la arquitectura hace que “probar que funciona” sea barato. Las reglas de negocio pueden testearse sin un sistema en ejecución completo, y las pruebas de integración se enfocan en unos pocos contratos en lugar de cada camino de código.
Las reescrituras normalmente no son causadas por “mal código”: son causadas por restricciones faltantes, alcance vago y suposiciones ocultas. Ejemplos:
La IA puede acelerar este modo de fallo al producir salidas convincentes rápido, lo que facilita construir sobre cimientos frágiles.
Los patrones que siguen son plantillas para adaptar, no prompts mágicos. Su objetivo real es forzar las conversaciones correctas temprano: aclarar restricciones, comparar opciones, documentar suposiciones y definir contratos. Si te saltas ese pensamiento, el modelo rellenará los huecos con gusto—y lo pagarás después.
Los usarás a lo largo de todo el ciclo de entrega:
Si usas un flujo de vibe-coding (donde el sistema se genera e itera vía chat), estos checkpoints importan aún más. Por ejemplo, en Koder.ai puedes ejecutar un bucle en “modo planificación” para cerrar requisitos y contratos antes de generar React/Go/PostgreSQL, y luego usar snapshots/rollback para iterar de forma segura cuando cambian las suposiciones—sin convertir cada cambio en una reescritura.
Los patrones de prompting son más valiosos cuando reducen la fricción en las decisiones. El truco es usarlos como checkpoints cortos y repetibles—antes de codificar, mientras diseñas y durante la revisión—para que la IA produzca artefactos reutilizables, no texto extra que tengas que filtrar.
Antes de codificar: ejecuta un bucle de “alineación” para confirmar objetivos, usuarios, restricciones y métricas de éxito.
Durante el diseño: usa patrones que fuerzan compensaciones explícitas (p. ej., alternativas, riesgos, límites de datos) antes de implementar.
Durante la revisión: usa un prompt estilo checklist para detectar huecos (casos límite, monitorización, seguridad, rendimiento) mientras los cambios aún son baratos.
Obtendrás mejor output con un paquete pequeño y consistente de entradas:
Si no sabes algo, dilo explícitamente y pide a la IA que liste suposiciones.
En lugar de “explica el diseño”, solicita artefactos que puedas pegar en docs o tickets:
Haz ciclos de 10–15 minutos: prompt → hojear → afinar. Siempre incluye criterios de aceptación (qué debe ser cierto para que el diseño sea aceptable), y pide a la IA que se auto-verifique contra ellos. Eso evita rediseños infinitos y hace que los patrones de las siguientes secciones sean rápidos de aplicar.
La mayoría de las “reescrituras de arquitectura” no son causadas por diagramas malos—son causadas por construir lo correcto para el problema equivocado (o incompleto). Cuando usas un LLM temprano, no pidas primero una arquitectura. Pídele que exponga la ambigüedad.
Usa el modelo como entrevistador de requisitos. Tu objetivo es una especificación corta y priorizada que puedas confirmar antes de que alguien diseñe componentes, elija bases de datos o se comprometa con APIs.
Aquí tienes una plantilla de copiar y pegar que puedes reutilizar:
You are my requirements analyst. Before proposing any architecture, do this:
1) Ask 10–15 clarifying questions about missing requirements and assumptions.
- Group questions by: users, workflows, data, integrations, security/compliance, scale, operations.
2) Produce a prioritized scope list:
- Must-have
- Nice-to-have
- Explicitly out-of-scope
3) List constraints I must confirm:
- Performance (latency/throughput targets)
- Cost limits
- Security/privacy
- Compliance (e.g., SOC2, HIPAA, GDPR)
- Timeline and team size
4) End with: “Restate the final spec in exactly 10 bullets for confirmation.”
Context:
- Product idea:
- Target users:
- Success metrics:
- Existing systems (if any):
Quieres preguntas que obliguen a tomar decisiones (no genéricos “cuéntame más”), además de una lista de must-have que realmente pueda cerrarse dentro de tu timeline.
Trata la reformulación de “10 viñetas” como un contrato: pégala en tu ticket/PRD, obtén un sí/no rápido de los stakeholders y solo entonces pasa a la arquitectura. Este paso evita la causa más común de refactors tardíos: construir características que nunca fueron realmente requeridas.
Cuando empiezas por herramientas (“¿Deberíamos usar event sourcing?”) a menudo terminas diseñando para la arquitectura en lugar del usuario. Un camino más rápido a una estructura limpia es pedirle a la IA que describa primero los recorridos de usuario en lenguaje claro y solo después traducir esos recorridos en componentes, datos y APIs.
Usa esto como punto de partida para copiar y pegar:
Luego pide:
“Describe the step-by-step flow for each action in plain language.”
“Provide a simple state diagram or state list (e.g., Draft → Submitted → Approved → Archived).”
“List non-happy-path scenarios: timeouts, retries, duplicate requests, cancellations, and invalid inputs.”
Una vez claros los flujos, puedes pedir a la IA que los mapee a decisiones técnicas:
Solo después pide un boceto de arquitectura (servicios/módulos, límites y responsabilidades) directamente vinculado a los pasos del flujo.
Finaliza pidiendo a la IA que convierta cada recorrido en criterios de aceptación que puedas probar:
Este patrón reduce reescrituras porque la arquitectura crece desde el comportamiento del usuario—no desde suposiciones sobre la tecnología.
La mayoría del rework de arquitectura no se debe a “mal diseño”—se debe a suposiciones ocultas que resultan ser falsas. Cuando pides una arquitectura a un LLM, a menudo rellenará los huecos con conjeturas plausibles. Un registro de suposiciones hace visibles esas conjeturas temprano, cuando los cambios son baratos.
Tu objetivo es forzar una separación clara entre hechos que proporcionaste y suposiciones que inventó.
Usa este patrón de prompt:
Template prompt “Before proposing any solution: list your assumptions. Mark each as validated (explicitly stated by me) or unknown (you inferred it). For each unknown assumption, propose a fast way to validate it (question to ask, metric to check, or quick experiment). Then design based only on validated assumptions, and call out where unknowns could change the design.”
Mantenlo corto para que la gente realmente lo use:
Añade una línea que obligue al modelo a decirte sus puntos de inflexión:
Este patrón convierte la arquitectura en un conjunto de decisiones condicionales. No solo obtienes un diagrama: obtienes un mapa de lo que debe confirmarse antes de comprometerte.
Las herramientas de IA son geniales produciendo un único “mejor” diseño—pero a menudo esa es solo la primera opción plausible. Una arquitectura más limpia suele aparecer cuando fuerzas una comparación temprano, mientras los cambios son baratos.
Usa un prompt que requiera múltiples arquitecturas y una tabla de compensaciones estructurada:
Propose 2–3 viable architectures for this project.
Compare them in a table with criteria: complexity, reliability, time-to-ship, scalability, cost.
Then recommend one option for our constraints and explain why it wins.
Finally, list “what we are NOT building” in this iteration to keep scope stable.
Context:
- Users and key journeys:
- Constraints (team size, deadlines, budget, compliance):
- Expected load and growth:
- Current systems we must integrate with:
Una comparación fuerza al modelo (y a ti) a sacar a la luz suposiciones ocultas: dónde vive el estado, cómo se comunican servicios, qué debe ser sincrónico y qué puede demorarse.
La tabla de criterios importa porque evita debates como “microservicios vs monolito” basados en opinión. Ancla la decisión a lo que realmente te importa: entregar rápido, reducir overhead operacional o mejorar fiabilidad.
No aceptes “depende.” Pide una recomendación clara y las restricciones específicas que optimiza.
También insiste en “qué NO construimos.” Ejemplos: “No multi-region failover”, “No plugin system”, “No notificaciones en tiempo real.” Esto evita que la arquitectura se expanda silenciosamente para soportar features no comprometidas aún—y previene reescrituras sorpresa cuando el alcance cambia.
La mayoría de las reescrituras ocurren porque los límites son vagos: todo “toca todo”, y un pequeño cambio se propaga por todo el código. Este patrón usa prompts que obligan a definir propiedad modular clara antes de debatir frameworks o diagramas de clases.
Pide a la IA que defina módulos y responsabilidades, además de qué explícitamente no pertenece a cada módulo. Luego solicita interfaces (entradas/salidas) y reglas de dependencia, no un plan de construcción o detalles de implementación.
Usa esto cuando estés esbozando una nueva feature o refactorizando un área desordenada:
Lista módulos con:
Para cada módulo, define solo interfaces:
Reglas de dependencia:
Prueba de cambio futuro: Dadas estos cambios probables: <list 3>, muestra qué módulo único debería absorber cada cambio y por qué.
Apuntas a módulos que puedas describir a un compañero en menos de un minuto. Si la IA propone un módulo “Utils” o pone reglas de negocio en controladores, empuja: “Mueve la toma de decisiones a un módulo de dominio y mantén los adaptadores delgados.”
Al terminar, tienes límites que sobreviven a nuevos requisitos—porque los cambios tienen un hogar claro y las reglas de dependencia previenen acoplamientos accidentales.
El retrabajo de integración a menudo no viene por “mal código”—viene por contratos poco claros. Si el modelo de datos y las formas de API se deciden tarde, cada equipo (o módulo) rellena los huecos de forma distinta, y pasas el siguiente sprint conciliando suposiciones desajustadas.
Comienza solicitando contratos antes de hablar de frameworks, bases de datos o microservicios. Un contrato claro se vuelve la referencia compartida que alinea UI, backend y pipelines de datos.
Usa este prompt temprano con tu asistente de IA:
Después sigue inmediatamente con:
Quieres artefactos concretos, no prosa. Por ejemplo:
Subscription
Y un boceto de API:
POST /v1/subscriptions
{
"customer_id": "cus_123",
"plan_id": "pro_monthly",
"start_date": "2026-01-01"
}
201 Created
{
"id": "sub_456",
"status": "active",
"current_period_end": "2026-02-01"
}
422 Unprocessable Entity
{
"error": {
"code": "VALIDATION_ERROR",
"message": "start_date must be today or later",
"fields": {"start_date": "in_past"}
}
}
Haz que la IA declare reglas como: “Los campos aditivos están permitidos sin bump de versión; renombrar requiere /v2; los clientes deben ignorar campos desconocidos.” Este paso evita cambios incompatibles silenciosos—y las reescrituras que siguen.
Las arquitecturas se reescriben cuando los diseños “happy path” se enfrentan al tráfico real, dependencias inestables y comportamiento de usuario inesperado. Este patrón convierte la fiabilidad en una salida de diseño explícita, no en un scramble post-lanzamiento.
Usa esto con tu descripción de arquitectura elegida:
List failure modes; propose mitigations; define observability signals.
Para cada modo de fallo:
- ¿Qué lo desencadena?
- Impacto en el usuario (qué experimenta el usuario)
- Mitigación (diseño + operacional)
- Retries, idempotency, rate limits, timeouts consideraciones
- Observabilidad: logs/metrics/traces + umbrales de alerta
Enfoca la respuesta nombrando las interfaces que pueden fallar: APIs externas, base de datos, colas, proveedor de auth y jobs en background. Luego exige decisiones concretas:
Termina el prompt con: “Devuelve un checklist simple que podamos revisar en 2 minutos.” Un buen checklist incluye ítems como: timeouts por dependencia, retries acotados, idempotencia para acciones create/charge, control de presión/backpressure, ruta de degradación elegante definida.
Solicita eventos alrededor de momentos de usuario (no solo internos): “user_signed_up”, “checkout_submitted”, “payment_confirmed”, “report_generated”. Para cada uno, pide:
Esto convierte la fiabilidad en un artefacto de diseño que puedes validar antes de que exista código.
Una forma común en que el diseño asistido por IA crea reescrituras es alentando arquitecturas “completas” demasiado pronto. La solución es simple: fuerza el plan a empezar por la porción más pequeña usable—una que entregue valor, pruebe el diseño y mantenga abiertas las opciones futuras.
Usa esto cuando sientas que la solución se expande más rápido que los requisitos:
Template: “Propose the smallest usable slice; define success metrics; list follow-ups.”
Pide al modelo que responda con:
Añade: “Da una hoja de ruta por fases: MVP → v1 → v2, y explica qué riesgo reduce cada fase.” Esto mantiene ideas posteriores visibles sin forzarlas en la primera entrega.
Resultados de ejemplo que buscas:
La línea más poderosa en este patrón es: “Lista qué está explícitamente fuera del alcance para el MVP.” Las exclusiones protegen decisiones de arquitectura de complejidad prematura.
Buenas exclusiones:
Finalmente: “Convierte el MVP en tickets, cada uno con criterios de aceptación y dependencias.” Esto obliga a claridad y revela acoplamientos ocultos.
Un buen desglose de tickets suele incluir:
Si quieres, enlaza esto directamente a tu flujo pidiendo al modelo salida en el formato de tu equipo (p. ej., campos estilo Jira) y mantén fases posteriores como backlog separado.
Una forma simple de evitar que la arquitectura se desvíe es forzar claridad mediante tests antes de pedir un diseño. Cuando pides a un LLM que comience con tests de aceptación, debe nombrar comportamientos, inputs, outputs y casos límite. Eso expone requisitos faltantes y empuja la implementación hacia límites modulares limpios.
Usa esto como prompt “puerta” cuando vayas a diseñar un componente:
Sigue con: “Agrupa las pruebas por responsabilidad de módulo (capa API, lógica de dominio, persistencia, integraciones externas). Para cada grupo, especifica qué se mockea y qué es real.”
Esto empuja al LLM lejos de diseños enmarañados donde todo toca todo. Si no puede explicar dónde empiezan las pruebas de integración, probablemente tu arquitectura aún no está clara.
Pide: “Propón un plan de datos de prueba: fixtures vs factories, cómo generar casos límite y cómo mantener tests deterministas. Lista qué dependencias pueden usar fakes en memoria y cuáles requieren servicio real en CI.”
A menudo descubrirás que una feature “simple” necesita un contrato, un dataset semilla o IDs estables—mejor detectarlo ahora que durante una reescritura.
Termina con un checklist ligero:
Las revisiones de diseño no deben ocurrir solo después de que exista código. Con IA, puedes ejecutar una “revisión pre-mortem” sobre tu borrador de arquitectura (aunque sea solo unos párrafos y un diagrama en palabras) y obtener una lista concreta de debilidades antes de que se conviertan en reescrituras.
Comienza con una postura de revisor directo y fuerza especificidad:
Prompt: “Act as a reviewer; list risks, inconsistencies, and missing details in this design. Be concrete. If you can’t evaluate something, say what information is missing.”
Pega tu resumen de diseño, restricciones (presupuesto, timeline, habilidades del equipo) y requisitos no funcionales (latencia, disponibilidad, cumplimiento).
Las revisiones fallan cuando el feedback es vago. Pide una lista priorizada de arreglos:
Prompt: “Give me a prioritized punch list. For each item: severity (Blocker/High/Medium/Low), why it matters, suggested fix, and the smallest validation step.”
Esto produce tareas listas para decisión en vez de un debate.
Un mecanismo útil es un puntaje simple:
Prompt: “Assign a rewrite risk score from 1–10. Explain the top 3 drivers. What would reduce the score by 2 points with minimal effort?”
No buscas precisión; buscas surfacear las suposiciones más propensas a reescribir.
Finalmente, evita que la revisión expanda alcance:
Prompt: “Provide a diff plan: minimal changes needed to reach the target design. List what stays the same, what changes, and any breaking impacts.”
Si repites este patrón en cada iteración, tu arquitectura evoluciona mediante pasos pequeños y reversibles—mientras los grandes problemas se detectan temprano.
Usa este pack como un flujo ligero que repites en cada feature. La idea es encadenar prompts para que cada paso produzca un artefacto que el siguiente puede reutilizar—reduciendo “contexto perdido” y reescrituras sorpresa.
En la práctica, los equipos suelen implementar esta cadena como una “receta de feature” repetible. Si construyes con Koder.ai, la misma estructura se mapea bien a un proceso de build guiado por chat: captura los artefactos en un lugar, genera la primera slice funcional y luego itera con snapshots para que los experimentos sean reversibles. Cuando el MVP esté listo, puedes exportar código fuente o desplegar/hostear con dominio personalizado—útil cuando quieres la velocidad de entrega asistida por IA sin bloquearte en un solo entorno.
SYSTEM (optional)
You are a software architecture assistant. Be practical and concise.
Guardrail: When you make a recommendation, cite the specific lines from *my input* you relied on by quoting them verbatim under “Input citations”. Do not cite external sources or general industry claims.
If something is unknown, ask targeted questions.
1) REQUIREMENTS CLARIFIER
Context: <product/system overview>
Feature: <feature name>
My notes: <paste bullets, tickets, constraints>
Task:
- Produce: (a) clarified requirements, (b) non-goals, (c) constraints, (d) open questions.
- Include “Input citations” quoting the exact parts of my notes you used.
2) ARCHITECTURE OPTIONS
Using the clarified requirements above, propose 3 architecture options.
For each: tradeoffs, complexity, risks, and when to choose it.
End with a recommendation + “Input citations”.
3) MODULAR BOUNDARIES
Chosen option: <option name>
Define modules/components and their responsibilities.
- What each module owns (and does NOT own)
- Key interfaces between modules
- “Input citations”
4) DATA & API CONTRACTS
For each interface, define a contract:
- Request/response schema (or events)
- Validation rules
- Versioning strategy
- Error shapes
- “Input citations”
5) TEST-FIRST ACCEPTANCE
Write:
- Acceptance criteria (Given/When/Then)
- 5–10 critical tests (unit/integration)
- What to mock vs not mock
- “Input citations”
6) RELIABILITY + DESIGN REVIEW
Create:
- Failure modes list (timeouts, partial failure, bad data, retries)
- Observability plan (logs/metrics/traces)
- Review checklist tailored to this feature
- “Input citations”
Si quieres un companion más profundo, ve a /blog/prompting-for-code-reviews. Si evaluas tooling o rollout en el equipo, /pricing es un siguiente paso práctico.
“Arquitectura más limpia” aquí significa que puedes:
En el trabajo asistido por IA, también significa que el modelo puede reformular los requisitos de una manera que firmarías.
La IA puede producir código y diseños convincentes rápidamente, lo que facilita construir sobre restricciones faltantes y suposiciones ocultas. Esa velocidad puede amplificar los disparadores de reescritura como:
La solución no es “menos IA”, sino usar prompts que obliguen a exponer restricciones, contratos y suposiciones desde el principio.
Usa los patrones como puntos de control cortos que produzcan artefactos reutilizables (no prosa extra):
Mantén las iteraciones en : prompt → hojear → ajustar → autoevaluación contra criterios de aceptación.
Lleva un paquete pequeño y consistente:
Si algo es desconocido, dilo y pide al modelo que explícitamente en vez de adivinar en silencio.
Pide artefactos que puedas pegar en docs, tickets y PRs:
Esto mantiene la salida de la IA accionable y reduce rehacer trabajo por “contexto perdido”.
Usa el modelo como entrevistador de requisitos. Haz que:
Empieza por roles y acciones, luego pide:
Solo después de que los flujos estén claros, mapea a decisiones como dónde termina la validación y dónde empiezan las reglas de negocio, dónde se necesita idempotencia y qué debe almacenarse vs derivarse. Luego convierte los flujos en criterios de aceptación Given/When/Then.
Porque los LLMs rellenarán huecos con conjeturas plausibles a menos que forces la separación entre:
Pide un registro de suposiciones que marque cada ítem como validado u desconocido, además de:
Obliga al modelo a proponer 2–3 arquitecturas viables y compáralas en una tabla (complejidad, fiabilidad, tiempo de entrega, escalabilidad, coste). Luego exige:
Esto evita que la primera opción plausible se convierta en la predeterminada y reduce la expansión silenciosa del alcance (causa común de reescritura).
El enfoque de contratos primero reduce el retrabajo de integración al hacer formas de datos y reglas de compatibilidad explícitas.
Pide:
/v2; clientes ignoran campos desconocidos)Trata esa reformulación de 10 viñetas como el contrato que validas con stakeholders antes de empezar el diseño.
También pide “¿qué cambiaría tu respuesta?” (p. ej., volumen, latencia, cumplimiento, retención) para hacer el diseño condicional y menos propenso a reescrituras.
Cuando UI, backend e integraciones comparten el mismo artefacto de contrato, se tarda menos en reconciliar suposiciones diferentes más tarde.