Apéndices
Términos clave de Falcux AI-First. Cada entrada incluye una definición concisa y el capítulo donde se explica en detalle.
ADR.md (registro de decisiones)
Registro de las decisiones difíciles de revertir: qué se eligió, qué se descartó y por qué. Una fila por decisión, que no se edita al cambiar de opinión: se agrega otra que la supera. ai-first init lo crea vacío en docs/ADR.md, y la verificación «Decisión sin fila en ADR» avisa cuando una decisión llega al código sin llegar al registro. → Cap 5
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
AI-FIRST.md
Archivo en la raíz del proyecto que declara qué lo gobierna —Zonas Prohibidas, superficies de decisión, alcance del cambio en curso y artefactos— en un frontmatter que ai-first audit verifica. Lo escribe ai-first init. A diferencia del AGENTS.md, no da órdenes al agente: es para las herramientas. → Cap 5
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 3
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 12
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 la skill protocolo-ux. → Cap 6, Cap 8
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 6
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 en pending/ se eliminan después de migrar su resumen aquí. → Cap 9
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 9
CLAUDE.md
Archivo específico de Claude Code que se lee al inicio de cada sesión. En Falcux 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 7
Contexto como producto Concepto central de Falcux 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
DEV AI First El enfoque de desarrollo dentro de Falcux 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 6
Entropía documental
La distancia entre lo que el proyecto documenta y lo que el proyecto es. ai-first audit la mide con cinco verificaciones y la resume en un puntaje de 0 a 100 donde más alto es peor: min(100, 40·P0 + 20·P1 + 8·P2). → Cap 5
Falcux AI-First
Metodología para equipos mixtos (diseño + desarrollo) que construyen productos con AI coding agents. Define una cadena de artefactos, protocolos operativos, templates reutilizables y un paquete que los instala. Agnóstica de herramienta. Hasta el 2026-09-21 se llamó «Blueprint AI-First»; el nombre vigente es éste, también en el paquete @falcux/ai-first. → Toda la metodología
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 9
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 9
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 6, Cap 7
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 a la skill protocolo-ux (Capa 1, agnóstico). → Cap 6
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 7
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 8
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 7
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
Punto de control
Los dos sitios donde ai-first init deja corriendo el detector: el hook de git .githooks/pre-push, que sólo interrumpe el push ante un P0, y el flujo .github/workflows/ai-first.yml, que corre con --estricto en cada pull request. Es un hook de git, no del agente. → Cap 5
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 10
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 11
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 9
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 8
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. Falcux AI-First existe para que los restarts no sean necesarios. → Cap 1, Cap 3
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 7
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 10
Skill
Archivo markdown con conocimiento especializado que la AI carga on-demand, solo cuando es relevante para la tarea actual. Vive en .agents/skills/{nombre}/SKILL.md, donde la deja ai-first init; Claude Code la lee por el enlace .claude/skills. Permite mantener el AGENTS.md ligero sin perder conocimiento especializado. → Cap 7
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 11
Superficie de decisión
Archivo o patrón donde un cambio se presume decisión arquitectónica: el esquema, los puntos de entrada de los paquetes, las configuraciones. Se declara en AI-FIRST.md; si se toca y el ADR no gana una fila, ai-first audit emite un P1. → Cap 5
Validador (rol) Uno de los 4 roles del developer AI-First. Revisa lo que la AI produce: verifica que cumple la spec, que los tests pasan, que el diseño es consistente, y que no se rompió nada existente. Ejecuta los checklists post-implementación. → Cap 2
Vibe coding Enfoque de desarrollo donde el humano describe una idea y la AI genera todo sin planificación previa. Funciona para prototipos desechables pero no para productos de producción. Se diferencia de AI-First por la ausencia de estructura y documentación. → Cap 2
“What NOT to Do” (sección) Sección del AGENTS.md que lista anti-patrones como prohibiciones explícitas. Cada línea existe porque la AI ya cometió ese error. Es una de las secciones de mayor valor del AGENTS.md — la AI atiende prohibiciones explícitas mejor que sugerencias implícitas. → Cap 4
Zona Prohibida
Ruta o patrón del repositorio que el agente no modifica sin aprobación explícita. El criterio es el costo de revertir un error ahí, no la importancia del archivo. No impide el cambio: lo hace visible, porque tocarla es un P0 en ai-first audit. Se declara en AI-FIRST.md y se enuncia como regla en el AGENTS.md. → Cap 5