Son las diez de la mañana. Llevas quince minutos refinando un prompt para que tu AI tool genere un servicio Angular que siga las convenciones del equipo. El resultado usa BehaviorSubject cuando vosotros usáis signals. Pone el archivo en src/services/ cuando vuestro monorepo tiene una estructura completamente diferente. El naming es genérico — NotificationService — cuando vuestra convención es UserNotificationFacadeService.
Borras. Reescribes el prompt. Añades más detalle. Tercer intento. Cuarto.
En otro equipo — o en el mismo equipo tres meses después — la misma petición produce un resultado que pasa code review sin cambios. Mismo modelo. Mismo tipo de prompt. ¿La diferencia? No fue el prompt.
El problema no es cómo preguntas. Es qué sabe la IA sobre tu proyecto antes de que preguntes.
El problema real
Hay una desconexión fundamental entre cómo funcionan las AI tools y cómo funcionan los proyectos enterprise reales.
En un equipo de ocho personas trabajando sobre un monorepo Angular con doce microfrontends, existen decenas de decisiones arquitectónicas que viven en las cabezas de la gente. El patrón de servicios facade, la convención de carpetas por dominio, los patterns prohibidos, las razones por las que se descartó NgRx global en favor de SignalStore local. Nada de eso está escrito. Todo el mundo lo sabe. Los nuevos lo aprenden por ósmosis en semanas.
La IA no tiene semanas. La IA no pregunta. La IA no aprende por ósmosis.
Lo que no está escrito no existe para la IA.
Esto explica por qué las demos son espectaculares y tu día a día no lo es. Las demos usan proyectos vacíos sin historia, sin convenciones acumuladas, sin decisiones previas. Ahí no hace falta contexto porque no hay contexto específico. Tu proyecto de tres años con 200K líneas y convenciones de un equipo de quince personas es un animal diferente.
Y aquí es donde entra la trampa del prompt engineering.
La industria ha generado un mercado enorme de "prompt libraries", "mega prompts" y cursos sobre "cómo preguntar mejor a la IA". Todos asumen implícitamente que el contexto del proyecto ya está disponible. En enterprise, rara vez lo está. Puedes escribir el prompt más elaborado del mundo — si la IA no sabe que tu equipo usa facade services, no va a generar facade services.
La asimetría es brutal: un prompt mejor mejora un resultado una vez. Contexto documentado mejora todos los resultados todas las veces.
La tesis: contexto es más importante que prompts
Si el cuello de botella no es el prompt sino la ausencia de contexto, la solución no es escribir prompts más creativos. Es proporcionar contexto estructurado. Y la forma más directa de hacerlo es un archivo que yo llamo architecture.md.
No es documentación genérica. No es un README con instrucciones de instalación. Es un archivo diseñado para que cualquier LLM — Copilot, Cursor, Claude, ChatGPT — entienda tu proyecto sin que tengas que explicárselo cada vez. Contiene lo que un senior de tu equipo tiene en la cabeza: stack, convenciones, estructura, patterns, decisiones clave.
¿Por qué funciona? Porque los LLMs generan basándose en patrones estadísticos más el contexto que les proporcionas. Si el contexto dice "en este proyecto usamos signals, no BehaviorSubject", el output usa signals. Sin esa información, usa lo estadísticamente más común — que en el caso de Angular anterior a 2024 significa BehaviorSubject. Y tu equipo lleva un año usando signals exclusivamente.
Piénsalo así: un prompt sin contexto de proyecto es como decirle a un taxista "llévame a la oficina" sin darle la dirección. El taxista puede ser excelente, el coche puede ser potente, pero sin dirección no va a ningún sitio útil. Un architecture.md es darle la dirección, decirle qué calles evitar por obras, y por qué entrada se accede al parking. Misma petición. Resultado radicalmente diferente.
Y hay un efecto compuesto que los prompts no tienen. Escribir un architecture.md cuesta unas pocas horas. Pero ese archivo mejora miles de interacciones futuras, con cualquier herramienta, para cualquier miembro del equipo. Eso es leverage real — no la optimización de un prompt individual que resuelve un problema una vez.
Un caso práctico
Para que esto deje de ser abstracto, veamos un caso real.
Proyecto: aplicación Angular enterprise para un cliente del sector financiero. Monorepo Nx con ocho librerías. Equipo de ocho personas. Convenciones propias desarrolladas durante dos años.
Petición al LLM: "Genera un servicio Angular para gestionar el estado de notificaciones del usuario."
Sin architecture.md
El modelo genera algo así:
@Injectable({ providedIn: 'root' })
export class NotificationService {
private notifications$ = new BehaviorSubject<Notification[]>([]);
getNotifications(): Observable<Notification[]> {
return this.notifications$.asObservable();
}
addNotification(notification: Notification): void {
const current = this.notifications$.value;
this.notifications$.next([...current, notification]);
}
}
Técnicamente funcional. Y completamente inutilizable en nuestro proyecto. El naming está mal. Usa BehaviorSubject cuando nosotros usamos signals. No sigue el patrón facade. El archivo se crearía en un path incorrecto. No pasaría code review.
El fragmento de architecture.md relevante
## Convenciones de servicios
- Patrón: Facade services como interfaz pública. Domain services internos.
- Naming: {Feature}{Tipo}Service (ej: UserNotificationFacadeService)
- Estado: signals (WritableSignal) para estado reactivo. No BehaviorSubject.
- Ubicación: libs/{domain}/{feature}/services/
- Tests: describe por método público, mocks con ng-mocks.
## Patterns prohibidos
- No subscribe() manual. Usar toSignal() o async pipe.
- No servicios god (>300 líneas). Dividir en facade + domain services.
Con architecture.md en contexto
Mismo prompt exacto. El modelo genera:
@Injectable({ providedIn: 'root' })
export class UserNotificationFacadeService {
private readonly notificationDomainService = inject(UserNotificationDomainService);
readonly notifications = this.notificationDomainService.notifications;
readonly unreadCount = computed(() =>
this.notifications().filter(n => !n.read).length
);
markAsRead(id: string): void {
this.notificationDomainService.markAsRead(id);
}
}
Naming correcto. Signals. Patrón facade. Inyección con inject(). Separación facade/domain. Listo para commit.
El prompt fue idéntico. La única diferencia fue el contexto.
Esto no es exclusivo de Angular. Lo he visto igual con pipelines de Azure DevOps donde sin documentar las convenciones de stages y naming de templates el YAML generado nunca pasa validación. Lo he visto con APIM policies donde el XML generado usa patrones genéricos que no encajan con la estructura real de backends. Lo he visto con Nginx configs para reverse proxy de microfrontends donde los location blocks no reflejan el routing real de la aplicación.
En todos los casos, mismo patrón: sin contexto explícito, resultado genérico e inutilizable. Con contexto, resultado adaptado y funcional.
Objeciones legítimas
Sería intelectualmente deshonesto no abordar las objeciones evidentes.
"Un buen prompt sí importa."
Sí. Un prompt bien escrito sobre un buen contexto es la combinación ideal. Pero la prioridad es clara: primero contexto, después prompt. Un prompt excelente sobre contexto vacío tiene un techo mucho más bajo que un prompt mediocre sobre contexto rico. Si solo puedes invertir en una cosa, invierte en contexto.
"Documentar lleva tiempo que no tenemos."
Un architecture.md básico se escribe en dos horas. Si un developer interactúa con AI tools veinte veces al día y cada interacción sin contexto requiere tres minutos extra de corrección, son sesenta minutos perdidos al día. En un equipo de ocho, son ocho horas diarias. La inversión se recupera en la primera semana. Y esa documentación no solo sirve para AI — sirve para onboarding, para decisiones futuras, para code reviews.
"Los modelos mejorarán y esto será innecesario."
Llevan tres años diciendo esto. Los modelos han mejorado enormemente y siguen sin poder adivinar que tu equipo eligió facade services en vez de servicios planos, o que vuestra pipeline usa templates reutilizables con naming específico. Los modelos mejoran en generalización. Tu proyecto no es general. El contexto explícito siempre ganará al contexto inferido porque las decisiones de TU equipo no existen en los datos de entrenamiento de ningún modelo.
"Es que nuestro proyecto es demasiado complejo."
No necesitas documentar todo. Treinta líneas con cinco convenciones principales y tres patterns prohibidos ya marcan una diferencia medible. El 80/20 aplica perfectamente aquí. Un architecture.md no es un libro — es una página.
Un matiz importante: prompting y context engineering no son enemigos. Son capas. El contexto es la base. El prompt es el acabado. Pero sin base sólida, no hay acabado que salve el resultado.
Conclusión
En un mercado donde todo el mundo tiene acceso a los mismos modelos, la ventaja competitiva de tu equipo con AI no está en qué herramienta usáis ni en quién escribe mejores prompts. Está en quién proporciona mejor contexto.
Un architecture.md no es burocracia. No es documentación por documentar. Es infraestructura — como tu pipeline de CI, como tu linter, como tus tests. Se escribe una vez, se mantiene con esfuerzo mínimo, y multiplica la calidad de todas las interacciones futuras con cualquier AI tool que aparezca.
La IA no ha creado un problema nuevo. Ha hecho visible uno que siempre existió: el conocimiento implícito que vive en las cabezas de las personas no escala. Antes el coste era onboarding lento y decisiones inconsistentes. Ahora el coste es outputs de AI que no sirven y tiempo perdido corrigiéndolos. Mismo problema, diferente manifestación. Y misma solución: hacer explícito lo implícito.
Los equipos que hoy invierten en contexto estructurado tendrán ventaja compuesta durante años. Cada modelo nuevo que aparezca les beneficiará más. Cada herramienta nueva será más útil. Cada miembro nuevo del equipo será productivo antes.
Coleccionar cien prompts mágicos optimiza cien preguntas.
Un architecture.md optimiza todas las respuestas.
Siguiente paso
Si este artículo te ha parecido útil, cada semana publico análisis prácticos sobre arquitectura enterprise e IA aplicada. Pragmático. Sin hype. Para seniors que construyen sistemas reales.
He creado un template de architecture.md que puedes adaptar a tu proyecto en treinta minutos. Incluye secciones para stack, convenciones, decisiones y reglas específicas para AI tools.
Publicado: Mayo 2026