featurevisor/featurevisor

¿Qué hace featurevisor?

Estás ayudando al usuario con Featurevisor, gestión de funcionalidades a través de Git. Un proyecto de Featurevisor es un repositorio de definiciones en YAML (por defecto) o JSON. La CLI las verifica (lint) y las prueba, y genera archivos de datos JSON estáticos, que las aplicaciones evalúan localmente mediante SDKs. Cada tarea se sitúa en uno de dos lados:

• Lado del proyecto: autoría y consulta de definiciones (funcionalidades, segmentos, atributos, variables globales, pruebas) y ejecución de la CLI featurevisor.
• Lado de la aplicación: carga de archivos de datos y evaluación a través de un SDK (@featurevisor/sdk, React, Vue u otro lenguaje).

Este skill cubre ambos, para Featurevisor v4. El índice de documentación está en https://featurevisor.com/llms.txt, con el texto completo en https://featurevisor.com/llms-full.txt. Recupéralos cuando un tema no esté cubierto por las referencias a continuación.

Conoce a tu audiencia

Ingenieros, gerentes de producto, especialistas en marketing y personas que describen lo que quieren sin conocer YAML utilizan Featurevisor. Adáptate:

• Traduce la intención. "Activar el banner para el 10% de los usuarios holandeses" es una regla de despliegue. Haz la traducción tú mismo, luego informa el resultado en sus palabras: qué cambió, a quién afecta y qué sucede después.
• Cambios rutinarios: aumentar un porcentaje, agregar una regla por encima del comodín ((catch-all), añadir una funcionalidad, forzar una funcionalidad para QA. Hazlos con confianza.
• Cambios riesgosos: renombrar una clave de regla, cambiar bucketBy, modificar pesos de variación, reducir un porcentaje, archivar algo que todavía se referencia. Estos mueven usuarios entre resultados. Dilo claramente ("algunos usuarios perderían la funcionalidad a mitad de sesión") y confirma antes de proceder.
• Cierra el ciclo. Después de un cambio, di en una o dos oraciones qué sucede una vez que se implementa. Por ejemplo: "una vez que esto se fusione y CI despliegue el archivo de datos, aproximadamente el 10% de los usuarios en los Países Bajos verán el banner, el resto no verá nada."
• Ofrece el Catálogo a cualquiera que quiera ver el proyecto en lugar de leer YAML (Revisión visual con el Catálogo).

Oriéntate primero

Los ejemplos en este skill usan la plantilla predeterminada, que no tiene entornos. Cuando el proyecto configura entornos, agrega --environment=<nombre> a evaluate, benchmark, assess-distribution y build --print. Una compilación de archivos normal cubre todos los entornos.

¿Aún no hay proyecto? Entrevista, luego crea la plantilla

Sin un featurevisor.config.js en el árbol de trabajo no hay un proyecto Featurevisor. Si el usuario está en un repositorio de aplicación, esto es trabajo del SDK: consulta Integración de aplicaciones (SDKs), y las definiciones se escriben en el repositorio del proyecto, no aquí. Si quieren un proyecto nuevo, pregunta primero lo siguiente, porque cada archivo que se escriba después depende de ello:

1. ¿Entornos? El predeterminado no tiene ninguno, y las reglas son listas directas. --example=with-environments da staging y production explícitos.
2. ¿Sets? Predeterminado no. Ofrece Sets solo para árboles revisados de forma independiente: canales de lanzamiento promovidos de dev a staging a producción, o superficies no relacionadas como una tienda y un administrador. Lee sets-promotions.md primero.
3. ¿Consumidores? Una aplicación puede usar el objetivo all predeterminado, que no tiene selectores e incluye cada definición activa. Varias superficies generalmente reciben etiquetas como web, ios y android, y un objetivo por superficie.
4. ¿Formato de archivo? YAML (predeterminado) o JSON.
5. ¿Qué identifica a un usuario? userId, deviceId o ambos (bucketBy: { or: [userId, deviceId] }). Lint requiere bucketBy en cada funcionalidad, así que esto decide qué declara cada funcionalidad y qué atributos vienen primero.

Crea la plantilla en un directorio vacío, en su propio repositorio, separado del código de la aplicación:

npx @featurevisor/cli@latest init
npm install

--example=with-environments da reglas con clave de entorno, --example=environments da Sets como canales de lanzamiento, y --example=sets da superficies independientes. La tabla de configuración de la CLI enumera todos los ejemplos. Luego ajusta featurevisor.config.js según las respuestas de la entrevista. templates/example-project/ es un proyecto v4 completo que pasa lint y pruebas, útil como referencia de cómo encajan las piezas.

¿Proyecto existente? Detecta la versión y la forma antes de tocar nada

Confirma que el proyecto tenga un @featurevisor/cli instalado en su manifiesto de paquete y archivo de bloqueo, y con npm ls @featurevisor/cli. Luego ejecuta la CLI instalada desde el proyecto:

npx featurevisor --version

Debe resolver el binario del propio proyecto. Si falta o npx ofrece descargar un paquete, detente y pregunta sobre restaurar las dependencias bloqueadas del proyecto. No instales una CLI remota ni actualices dependencias solo para detectar una versión.

• 4.x: todo en este skill aplica.
• 3.x: la sintaxis de v3 difiere. Usa segments en reglas y requiredFeatures en lugar de conditions unificadas, y carece de condiciones de variables, composiciones, continue, checks de pruebas, escenarios y varios operadores. No escribas sintaxis v4 en un proyecto v3. Mantente dentro de lo que upgrading-to-v4.md enumera como sintaxis v3, y ofrece la actualización cuando la solicitud necesite v4.
• 2.x: formas como scopes:, un directorio environments/ o createInstance en el código de la aplicación. Ofrece upgrading-to-v3.md primero.

Los consumidores deciden lo que puedes publicar. Los archivos de datos v4 necesitan SDKs v4: los SDKs v3 no entienden conditions unificadas, por lo que las reglas dejan de coincidir. El schemaVersion del archivo de datos es informativo y no hace que un SDK antiguo rechace el archivo. Antes de introducir una capacidad en tiempo de ejecución, como la acumulación de anulaciones o un operador más nuevo, confirma la versión del SDK de cada aplicación que consuma ese archivo de datos. Pregunta al usuario cuando esto sea desconocido. Verifica cada una contra la matriz de compatibilidad de SDKs. Los números de versión nativos difieren, así que no asumas que cada SDK compatible tiene la versión 4.x. El éxito de lint de la CLI por sí solo no establece el soporte en tiempo de ejecución. Las comprobaciones de pruebas y escenarios requieren ejecutores de CLI compatibles, lo cual es una pregunta separada de lo que soportan los consumidores.

Luego lee la configuración:

npx featurevisor config --json --pretty
npx featurevisor info

Cuatro valores cambian la forma de todo lo que escribes:

• sets: cuando es true, cada definición vive bajo sets/<set>/ y los comandos toman --set. Lee sets-promotions.md primero.
• environments: cuando se declara, las rules de funcionalidad, force y expose, y las overrides de variables globales, son mapas con clave de entorno. Sin ello, son listas directas, y expose es un booleano o lista de etiquetas.
• parser: autoría JSON para "json", YAML para "yml" (predeterminado) o el formato personalizado configurado (custom-parsers.md).
• namespaceCharacter: separador para claves de subdirectorios. Predeterminado ., por lo que features/checkout/promo.yml es checkout.promo. Algunos proyectos usan /. Cada referencia debe usar el separador del proyecto. Confírmalo contra claves reales con npx featurevisor list --segments --json.

También ten en cuenta tags (cada etiqueta que uses debe ser declarada), disallowOperators, allowedConditions y anulaciones de directorio como featuresDirectoryPath. Luego lee una o dos definiciones existentes para igualar el estilo local antes de agregar nuevas.

Cómo encaja Featurevisor

Definición	Ruta	Propósito
Atributo	attributes/<clave>.yml	Declara una clave de contexto y su tipo. Nunca tiene espacio de nombres.
Segmento	segments/<clave>.yml	Nombra una audiencia a través de conditions.
Funcionalidad	features/<clave>.yml	Un indicador, variaciones opcionales y variables de funcionalidad, con reglas de despliegue. Con partición (bucketed).
Variable global	variables/<clave>.yml	Un valor tipado con anulaciones ordenadas, o una compose de otros valores. Nunca tiene partición.
Esquema	schemas/<clave>.yml	Una forma de variable reutilizable.
Objetivo	targets/<clave>.yml	Qué definiciones van en un archivo de datos.
Especificación de prueba	tests/**/*.spec.yml	Afirmaciones de funcionalidades, segmentos y variables, y escenarios independientes.

Conditions son una gramática utilizada en todas partes donde una definición selecciona o restringe: segmentos, reglas, entradas de fuerza, restricciones raíz y anulaciones. Una hoja compara un atributo, nombra un segmento con una cadena simple, requiere una funcionalidad o compara el valor de una variable. Una lista significa AND, y los grupos and, or y not se anidan. '*' coincide con todos, pero solo como toda la expresión.

conditions:
  - attribute: country
    operator: equals
    value: nl
  - payingAccounts # una cadena simple siempre es una clave de segmento
  - feature: liveChat # requiere que liveChat esté habilitado
  - variable: maintenanceMode
    operator: equals
    value: false

Orden de evaluación. El indicador de una funcionalidad verifica un valor fijo (sticky), luego si la funcionalidad está en el archivo de datos, luego la primera entrada de fuerza que coincida, luego las conditions raíz, luego la primera regla cuyas condiciones coincidan, y finalmente el porcentaje de esa regla contra el bucket del usuario. Una falta de porcentaje no pasa a la siguiente regla. Una variable global verifica un valor fijo, luego las conditions raíz, luego las fuentes de composición si las hay, luego la primera anulación que coincida (y las siguientes también cuando una anulación establece continue: true), y finalmente su valor predeterminado. Detalles: features.md y global-variables.md.

Reglas principales de autoría

Las referencias agregan profundidad, pero nunca anulan estas reglas.

1. La partición (bucketing) y las claves de regla son contratos

• bucketBy mantiene estable el resultado de cada usuario mientras los porcentajes cambian. Elígelo una vez y nunca lo cambies en silencio.
• Las superficies con sesión iniciada hacen partición por userId, las anónimas por deviceId, las mixtas por { or: [userId, deviceId] }. Los nombres de atributos varían entre proyectos: lee attributes/ y pregunta cuál usar cuando no sea obvio. Nunca inventes nombres de atributos.
• Las claves de regla deben ser únicas por lista (por entorno cuando está configurado) y no deben cambiar una vez que los usuarios están en buckets. Los archivos de estado almacenan los rangos de variación de cada regla por clave, por lo que un renombramiento los reasigna. Agrega una nueva regla en lugar de renombrar.

2. La primera regla que coincide gana

Las reglas se ejecutan de arriba a abajo. Coloca reglas estrechas, como un país al 100%, por encima de la regla comodín conditions: '*'. Una vez que una regla coincide, su porcentaje decide, y los usuarios por encima de él no pasan a reglas posteriores.

3. Referencia solo lo que existe

Confirma que cada atributo, segmento, funcionalidad y variable que referencias exista, o créalo. Verifica también allowedConditions en featurevisor.config.js: puede limitar qué tipos de condición acepta cada ubicación, por ejemplo, reglas que solo nombran segmentos (conditions.md). Lint rechaza referencias desconocidas. También rechaza, con archived_reference, cualquier referencia a una definición archivada desde una definición o especificación que no esté archivada. Una definición archivada se elimina de los archivos de datos, por lo que una referencia a ella dejaría de coincidir silenciosamente, y bajo not coincidiría con todos. Lint verifica las definiciones archivadas solo por su forma, por lo que lo que usaban puede cambiar o desaparecer más tarde. Una referencia a una definición obsoleta es una advertencia deprecated_reference. Ejecuta npx featurevisor find-usage antes de archivar, renombrar o eliminar algo, y prefiere archivar a eliminar: el archivo archivado reserva la clave.

4. Los pesos de variación suman 100

Cada valor es único. control y treatment son solo convenciones. Lint rechaza pesos que no sumen 100. Con CLI 4.0.0 no lo hacía, así que verifica la suma tú mismo allí: una división corta se construye una vez, luego cada construcción posterior falla con Invalid saved variation allocation. Para experimentos mutuamente excluyentes, consulta mutual-exclusion.md.

5. Las condiciones se mantienen portátiles entre SDKs

Cada SDK evalúa el mismo archivo de datos, por lo que lint aplica un subconjunto portátil:

• Fechas (before, after) toman una marca de tiempo ISO 8601 completa con zona horaria, entrecomillada: '2026-11-27T00:00:00Z'. Los valores solo de fecha y sin zona horaria fallan lint. Ambos operadores son estrictos.
• Versiones (semver*) son cadenas entrecomilladas como '5.5' o '5.5.0', por lo que YAML las mantiene como texto.
• Expresiones regulares (matches, notMatches) solo permiten las banderas g, i, m y s, y rechazan toda construcción (?, incluidos los grupos no capturadores (?:…), las referencias inversas y los cuantificadores posesivos.
• Los operadores se verifican contra los tipos declarados. Un atributo type: string con format: date-time solo toma los operadores before, after y de presencia, y in toma una lista de cadenas.

Detalles y mensajes de lint: operators.md.

6. Coincide con la forma del proyecto

Los entornos, Sets, el analizador y el separador de espacio de nombres cambian cómo se escribe la misma solicitud. Las plantillas usan la forma predeterminada sin entornos. En un proyecto con entornos, coloca cada lista de rules, force o overrides globales bajo su clave de entorno, y agrega environment a las pruebas.

Definición de terminado

Ejecuta este bucle después de cada cambio. Es cómo demuestras que un cambio hace lo que el usuario pidió, y te da la evidencia para informar.

1. Lint. npx featurevisor lint debe pasar. Con --json, cada error tiene filePath, path, message y code, por lo que puedes corregir el campo exacto. Vuelve a ejecutar después de corregir: algunos errores solo aparecen una vez que se corrigen los anteriores en la…

… [truncado por límite de tokens]