Glosario
Términos clave de Blueprint AI-First. Cada entrada incluye una definición concisa y el capítulo donde se explica en detalle.
A
AGENTS.md Archivo markdown en la raíz del proyecto que contiene el contexto completo para AI coding agents: descripción del proyecto, stack, comandos, reglas críticas, documentación referenciada, y anti-patrones. Es la fuente de verdad cross-tool — funciona con Claude Code, Antigravity, Cursor, y cualquier herramienta que lea archivos de contexto. Máximo recomendado: ~150 líneas. → Cap 4 AI-First (enfoque) Enfoque de desarrollo donde la AI es el builder principal del código (80-90%) y el humano actúa como arquitecto, director, curador, y validador. Se diferencia del vibe coding (sin estructura) y del desarrollo tradicional (el humano escribe todo). → Cap 2 Anti-patrón Error recurrente descubierto durante la implementación con AI. Se documenta en la sección “What NOT to Do” del AGENTS.md para que la AI no lo repita. Cada anti-patrón existe porque la AI ya cometió ese error al menos una vez. → Cap 4 Artefacto Documento producido en la cadena de artefactos: PRD, arquitectura, schema, AGENTS.md, GUIA_DISEÑO.md, o documentación post-implementación. Cada artefacto alimenta al siguiente eslabón de la cadena. → Cap 3B
Blueprint AI-First Metodología para equipos mixtos (diseño + desarrollo) que construyen productos con AI coding agents. Define una cadena de artefactos, 4 protocolos operativos, y templates reutilizables. Agnóstica de herramienta. → Toda la metodología BYOM (Bring Your Own Model) Categoría de herramientas de AI coding (Aider, OpenCode, Cline) que son gratuitas pero requieren que el usuario pague por el uso de API del modelo LLM que elija. El costo varía según el modelo y la intensidad de uso. → Cap 12C
Cadena de artefactos El flujo completo desde la idea hasta el código: Idea → PRD → Arquitectura → Schema → Contexto AI → Implementación → Documentación post-implementación. Cada eslabón produce un artefacto que el siguiente consume. Romper la cadena significa que la AI trabaja con información incompleta. → Cap 3 Capa 1 (principios agnósticos) La capa de documentación de UX que contiene principios universales — navegación por capas, patrones de interacción, estados de UI. No cambia entre proyectos ni stacks. Vive en UX_PATTERNS_PROTOCOL.md. → Cap 5, Cap 7 Capa 2 (specs de proyecto) La capa de documentación de UX que contiene especificaciones técnicas concretas — tokens de color, tipografía, componentes específicos, gotchas del framework. Es única por proyecto. Vive en GUIA_DISEÑO.md. → Cap 5 CHANGE_LOG.md Registro permanente de todos los cambios implementados en un proyecto. Cada entrada incluye fecha, tipo, archivos afectados, y lecciones aprendidas. No se borra. Los documentos temporales enpending/ se eliminan después de migrar su resumen aquí. → Cap 8
CHG-XXX
Documento individual de cambio con formato numerado (CHG-001, CHG-002). Documenta qué cambia, por qué, análisis de impacto, plan de implementación, y verificación. Vive en docs/changes/pending/ mientras está activo y se elimina al cerrarse. → Cap 8
CLAUDE.md
Archivo específico de Claude Code que se lee al inicio de cada sesión. En Blueprint AI-First, contiene únicamente la referencia @AGENTS.md, actuando como puntero liviano. La fuente de verdad es el AGENTS.md. → Cap 4
Compactación (/compact)
Técnica de gestión de contexto que resume la conversación previa manteniendo lo esencial. Se aplica cuando la sesión alcanza ~50% del contexto disponible. Se puede especificar qué preservar. → Cap 6
Contexto como producto
Concepto central de Blueprint AI-First: en desarrollo AI-First, el contexto (documentación, reglas, patrones) es el producto principal — el código es el subproducto. La AI genera código a velocidades que ningún humano iguala, pero la calidad depende enteramente del contexto que recibe. → Cap 1
Curador (rol)
Uno de los 4 roles del developer AI-First. Mantiene el contexto del proyecto vivo y actualizado: AGENTS.md, guía de diseño, anti-patrones, gotchas. Sin el curador, cada sesión empieza un poco más perdida que la anterior. → Cap 2
D
DEV AI First El enfoque de desarrollo dentro de Blueprint AI-First. Significa diseñar todo el flujo de desarrollo asumiendo que la AI es el builder principal. La documentación se escribe para que la AI la entienda, la arquitectura se define antes del código, y las convenciones se codifican explícitamente. → Cap 2 Director (rol) Uno de los 4 roles del developer AI-First. Define qué se construye en cada sesión, en qué orden, con qué restricciones. Prepara los prompts de implementación y detiene la sesión cuando la AI va por mal camino. → Cap 2 Documentación evolutiva Patrón donde la guía de diseño crece orgánicamente con el proyecto. No se escribe completa al inicio — se empieza con las secciones obligatorias y se agregan componentes, patrones, y gotchas conforme se implementa. Demostrado por la GUIA_DISEÑO.md de Virso (1134 líneas). → Cap 5F
Flujo corto Proceso simplificado de gestión de cambios para correcciones menores que tocan 1-2 archivos y no modifican schema de BD. Documentar → Implementar → Verificar → Actualizar docs. → Cap 8 Flujo completo Proceso completo de gestión de cambios para cambios de medio-alto riesgo. Documentar → Analizar impacto → Planificar → Implementar por pasos → Verificar → Actualizar docs → Cerrar. → Cap 8G
Gotcha Bug, comportamiento inesperado, o incompatibilidad descubiertos durante la implementación real con AI. Se documentan en la sección de gotchas de la GUIA_DISEÑO.md o en “What NOT to Do” del AGENTS.md. Tienen alto valor porque previenen que la AI (o el equipo) repita el mismo error. → Cap 5, Cap 6 GUIA_DISEÑO.md Documento de especificaciones visuales y técnicas de un proyecto. Incluye paleta de colores, tipografía, espaciado, componentes, patrones de página, gotchas del framework CSS, y checklist. Es la Capa 2 (específica por proyecto) que complementa al UX_PATTERNS_PROTOCOL (Capa 1, agnóstico). → Cap 5H
Hook Script que se ejecuta automáticamente cuando ocurre un evento específico en el AI coding agent. A diferencia del AGENTS.md (advisory), los hooks son deterministas — se ejecutan siempre. Tipos: PreToolUse, PostToolUse, Stop. → Cap 6N
Navegación por capas Patrón de UX donde la aplicación tiene tres layouts contextuales. Capa 1 (Browse): layout con sidenav para explorar. Capa 2 (Create): layout limpio sin sidenav para flujos de creación. Capa 3 (Detail): layout limpio sin sidenav para ver detalle. → Cap 7P
Plan mode Técnica donde la AI presenta un plan de implementación antes de ejecutar. El humano revisa, edita, y aprueba antes de que se escriba código. Útil para features complejos. En Claude Code: Shift+Tab ×2. → Cap 6 PRD (Product Requirements Document) Documento que describe el producto desde la perspectiva del usuario. Qué hace, para quién, qué problema resuelve, y cuáles son los límites. Es el eslabón más crítico de la cadena — el único que no debería saltarse nunca. → Cap 3 Protocolo de cierre de sesión Proceso de 3 fases al terminar una sesión de implementación: la AI documenta (SESSION_LOG, docs actualizados, anti-patrones) → el humano verifica (5 puntos de checklist) → el humano cierra (commit, sync Notion, cerrar CHG-XXX). → Cap 9 Protocolo de desarrollo de features Proceso de 6 pasos antes de implementar un feature: asegurar spec → leer diseño → validar UX → verificar dependencias → preparar contexto AI → definir secuencia de implementación. → Cap 10 Protocolo de gestión de cambios Proceso para modificar requerimientos post-implementación sin romper lo existente. Incluye clasificación de cambios, documento CHG-XXX, análisis de impacto, implementación por pasos, y patrones anti-regresión. → Cap 8 Protocolo de consistencia UX Documento con los patrones de experiencia de usuario que toda implementación debe respetar. Navegación por capas, separación negocio vs admin, interacciones en tablas, formularios, modales, y estados de UI. → Cap 7R
Restart Momento donde un proyecto se vuelve tan inconsistente que la única opción es empezar de cero. Causado típicamente por falta de contexto persistente. Blueprint AI-First existe para que los restarts no sean necesarios. → Cap 1, Cap 3S
Sesión limpia Técnica de gestión de contexto donde cada tarea significativa se ejecuta en una sesión nueva con contexto fresco. La sesión anterior produce un artefacto (spec, SESSION_LOG) que la nueva sesión consume. Previene degradación de contexto. → Cap 6 SESSION_LOG.md Registro cronológico de sesiones de implementación. Cada entrada documenta qué se implementó, qué archivos se modificaron, anti-patrones descubiertos, y pendientes para la siguiente sesión. Sesión más reciente arriba. → Cap 9 Skill Archivo markdown con conocimiento especializado que la AI carga on-demand, solo cuando es relevante para la tarea actual. Vive en.claude/skills/{nombre}/SKILL.md. Permite mantener el AGENTS.md ligero sin perder conocimiento especializado. → Cap 6
Spec mínima viable
El documento más corto que todavía le da a la AI suficiente contexto para implementar: qué hace el feature, criterios de aceptación, alcance (incluye/no incluye), y dependencias. Se usa cuando no hay PRD formal. → Cap 10