featurevisor/featurevisor

Was macht featurevisor?

Sie helfen dem Nutzer mit Featurevisor, Feature-Management über Git. Ein Featurevisor-Projekt ist ein Repository mit YAML- (Standard) oder JSON-Definitionen. Die CLI lintet und testet sie und erstellt statische JSON-Datafiles, die Anwendungen lokal über SDKs auswerten. Jede Aufgabe befindet sich auf einer von zwei Seiten:

• Projektseite: Erstellen und Abfragen von Definitionen (Features, Segmente, Attribute, globale Variablen, Tests) und Ausführen der featurevisor-CLI.
• Anwendungsseite: Laden von Datafiles und deren Auswertung über ein SDK (@featurevisor/sdk, React, Vue oder eine andere Sprache).

Dieses Skill deckt beide Seiten ab, für Featurevisor v4. Das Dokumentationsverzeichnis befindet sich unter https://featurevisor.com/llms.txt, mit dem vollständigen Text unter https://featurevisor.com/llms-full.txt. Rufen Sie diese ab, wenn ein Thema nicht durch die folgenden Referenzen abgedeckt wird.

Kennen Sie Ihr Publikum

Ingenieure, Produktmanager, Vermarkter und Personen, die beschreiben, was sie wollen, ohne das YAML zu kennen, verwenden alle Featurevisor. Kalibrieren Sie:

• Absicht übersetzen. „Schalten Sie das Banner für 10 % der niederländischen Benutzer ein“ ist eine Rollout-Regel. Führen Sie die Zuordnung selbst durch und berichten Sie das Ergebnis in ihren Worten: was geändert wurde, wer betroffen ist und was als nächstes passiert.
• Routineänderungen: Erhöhen eines Prozentsatzes, Hinzufügen einer Regel über dem Catch-All, Hinzufügen eines Features, Erzwingen eines Features für QA. Führen Sie diese selbstbewusst durch.
• Riskante Änderungen: Umbenennen eines Regelschlüssels, Ändern von bucketBy, Ändern von Variationsgewichten, Senken eines Prozentsatzes, Archivieren von etwas, auf das noch verwiesen wird. Diese verschieben Benutzer zwischen Ergebnissen. Sagen Sie dies klar („einige Benutzer würden das Feature mitten in der Sitzung verlieren“) und bestätigen Sie, bevor Sie fortfahren.
• Den Kreis schließen. Sagen Sie nach einer Änderung in ein oder zwei Sätzen, was passiert, sobald sie ausgeliefert wird. Zum Beispiel: „Sobald dies zusammengeführt wird und CI das Datafile bereitstellt, sehen etwa 10 % der Benutzer in den Niederlanden das Banner, alle anderen sehen nichts.“
• Bieten Sie den Katalog an für jeden, der das Projekt sehen möchte, anstatt YAML zu lesen (Visuelle Überprüfung mit dem Katalog).

Orientieren Sie sich zuerst

Beispiele in diesem Skill verwenden das Standard-Scaffold, das keine Umgebungen hat. Wenn das Projekt Umgebungen konfiguriert, fügen Sie --environment=<name> zu evaluate, benchmark, assess-distribution und build --print hinzu. Ein normaler Datei-Build deckt jede Umgebung ab.

Noch kein Projekt? Befragen, dann Gerüst

Ohne eine featurevisor.config.js im Arbeitsverzeichnis gibt es kein Featurevisor-Projekt. Wenn der Benutzer in einem Anwendungs-Repository ist, handelt es sich um SDK-Arbeit: siehe Anwendungsintegration (SDKs), und verfassen Sie Definitionen im Projekt-Repository, nicht hier. Wenn sie ein neues Projekt möchten, fragen Sie zuerst diese, da jede danach geschriebene Datei davon abhängt:

1. Umgebungen? Der Standard hat keine, und Regeln sind direkte Listen. --example=with-environments ergibt explizite staging und production.
2. Sets? Standard nein. Bieten Sie Sets nur für unabhängig überprüfte Bäume an: Release-Lanes, die von dev über staging nach production hochgestuft werden, oder unzusammenhängende Oberflächen wie eine Storefront und ein Admin. Lesen Sie zuerst sets-promotions.md.
3. Konsumenten? Eine Anwendung kann das Standard-all-Target verwenden, das keine Selektoren hat und jede aktive Definition einschließt. Mehrere Oberflächen erhalten normalerweise Tags wie web, ios und android, und ein Target pro Oberfläche.
4. Dateiformat? YAML (Standard) oder JSON.
5. Was identifiziert einen Benutzer? userId, deviceId oder beides (bucketBy: { or: [userId, deviceId] }). Lint erfordert bucketBy für jedes Feature, also bestimmt dies, was jedes Feature deklariert und welche Attribute zuerst kommen.

Gerüst in einem leeren Verzeichnis, in einem eigenen Repository, getrennt vom Anwendungscode:

npx @featurevisor/cli@latest init
npm install

--example=with-environments ergibt umgebungsschlüsselgebundene Regeln, --example=environments ergibt Sets als Release-Lanes, und --example=sets ergibt unabhängige Oberflächen. Die CLI-Setup-Tabelle listet jedes Beispiel auf. Passen Sie dann featurevisor.config.js an die Antworten der Befragung an. templates/example-project/ ist ein komplettes v4-Projekt, das Lint und Test besteht, nützlich als Referenz, wie die Teile zusammenpassen.

Bestehendes Projekt? Erkennen Sie die Version und Form, bevor Sie etwas anfassen

Bestätigen Sie, dass das Projekt ein installiertes @featurevisor/cli in seinem Package-Manifest und der Lockdatei hat, und mit npm ls @featurevisor/cli. Führen Sie dann die installierte CLI aus dem Projekt aus:

npx featurevisor --version

Es muss das eigene Binärprogramm des Projekts auflösen. Wenn es fehlt oder npx anbietet, ein Paket herunterzuladen, stoppen Sie und fragen Sie nach der Wiederherstellung der gesperrten Abhängigkeiten des Projekts. Installieren Sie keine entfernte CLI oder aktualisieren Sie Abhängigkeiten, nur um eine Version zu erkennen.

• 4.x: Alles in diesem Skill gilt.
• 3.x: Die v3-Syntax unterscheidet sich. Sie verwendet segments in Regeln und requiredFeatures anstelle von einheitlichen conditions, und es fehlen variable Bedingungen, Kompositionen, continue, Test checks, Szenarien und mehrere Operatoren. Schreiben Sie keine v4-Syntax in ein v3-Projekt. Bleiben Sie innerhalb dessen, was upgrading-to-v4.md als v3-Syntax auflistet, und bieten Sie das Upgrade an, wenn die Anfrage v4 benötigt.
• 2.x: Formen wie scopes:, ein environments/-Verzeichnis oder createInstance im Anwendungscode. Bieten Sie zuerst upgrading-to-v3.md an.

Konsumenten bestimmen, was Sie veröffentlichen können. v4-Datafiles benötigen v4-SDKs: v3-SDKs verstehen einheitliche conditions nicht, daher hören Regeln auf zu matchen. Das Datafile schemaVersion ist informativ und führt nicht dazu, dass ein altes SDK die Datei ablehnt. Bevor Sie eine Laufzeitfunktion wie das Akkumulieren von Überschreibungen oder einen neueren Operator einführen, bestätigen Sie die SDK-Version jeder Anwendung, die dieses Datafile konsumiert. Fragen Sie den Benutzer, wenn dies unbekannt ist. Überprüfen Sie jede gegen die SDK-Kompatibilitätsmatrix. Native Versionsnummern unterscheiden sich, gehen Sie also nicht davon aus, dass jedes kompatible SDK mit 4.x nummeriert ist. Der CLI-Lint-Erfolg allein etabliert keine Laufzeitunterstützung. Test-Checks und Szenarien erfordern kompatible CLI-Runner, was eine separate Frage davon ist, was Konsumenten unterstützen.

Lesen Sie dann die Konfiguration:

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

Vier Werte ändern die Form von allem, was Sie schreiben:

• sets: wenn true, lebt jede Definition unter sets/<set>/ und Befehle verwenden --set. Lesen Sie zuerst sets-promotions.md.
• environments: wenn deklariert, sind Feature rules, force und expose sowie globale Variable overrides Maps, die nach Umgebung verschlüsselt sind. Ohne sie sind es direkte Listen, und expose ist ein Boolean oder eine Tag-Liste.
• parser: Autor JSON für "json", YAML für "yml" (Standard) oder das konfigurierte benutzerdefinierte Format (custom-parsers.md).
• namespaceCharacter: Trennzeichen für Schlüssel aus Unterverzeichnissen. Standard ., also ist features/checkout/promo.yml checkout.promo. Einige Projekte verwenden /. Jede Referenz muss das Trennzeichen des Projekts verwenden. Bestätigen Sie anhand echter Schlüssel mit npx featurevisor list --segments --json.

Beachten Sie auch tags (jedes Tag, das Sie verwenden, muss deklariert sein), disallowOperators, allowedConditions und Verzeichnisüberschreibungen wie featuresDirectoryPath. Lesen Sie dann eine oder zwei bestehende Definitionen, um den lokalen Stil zu treffen, bevor Sie neue hinzufügen.

Wie Featurevisor zusammenhängt

Definition	Pfad	Zweck
Attribut	attributes/<key>.yml	Deklariert einen Kontextschlüssel und seinen Typ. Nie namensräumig.
Segment	segments/<key>.yml	Benennt eine Zielgruppe durch conditions.
Feature	features/<key>.yml	Ein Flag, optionale Variationen und Feature-Variablen, mit Rollout-Regeln. Gebucketet.
Globale Variable	variables/<key>.yml	Ein typisierter Wert mit geordneten Überschreibungen oder eine compose anderer Werte. Nie gebucketet.
Schema	schemas/<key>.yml	Eine wiederverwendbare Variablenform.
Target	targets/<key>.yml	Welche Definitionen in ein Datafile aufgenommen werden.
Test-Spezifikation	tests/**/*.spec.yml	Feature-, Segment- und Variablen-Assertions sowie eigenständige Szenarien.

Bedingungen sind eine Grammatik, die überall dort verwendet wird, wo eine Definition auswählt oder sperrt: Segmente, Regeln, Force-Einträge, Root-Gates und Überschreibungen. Ein Blatt vergleicht ein Attribut, benennt ein Segment mit einem bloßen String, erfordert ein Feature oder vergleicht den Wert einer Variablen. Eine Liste bedeutet UND, und and-, or- und not-Gruppen verschachteln sich. '*' matched jeden, aber nur als gesamter Ausdruck.

conditions:
  - attribute: country
    operator: equals
    value: nl
  - payingAccounts # ein bloßer String ist immer ein Segment-Schlüssel
  - feature: liveChat # erfordert, dass liveChat aktiviert ist
  - variable: maintenanceMode
    operator: equals
    value: false

Evaluierungsreihenfolge. Das Flag eines Features prüft einen sticky-Wert, dann ob das Feature im Datafile ist, dann den ersten passenden Force-Eintrag, dann Root-conditions, dann die erste Regel, deren Bedingungen passen, und schließlich den Prozentsatz dieser Regel gegen den Bucket des Benutzers. Ein Prozent-Fehlschlag fällt nicht zur nächsten Regel durch. Eine globale Variable prüft einen sticky-Wert, dann Root-conditions, dann Kompositionsquellen, falls vorhanden, dann die erste passende Überschreibung (und spätere auch, wenn eine Überschreibung continue: true setzt), dann ihren Standard. Details: features.md und global-variables.md.

Kern-Authoring-Regeln

Die Referenzen fügen Tiefe hinzu, aber sie überschreiben diese niemals.

1. Bucketing und Regelschlüssel sind Verträge

• bucketBy hält das Ergebnis jedes Benutzers stabil, während sich Prozentsätze ändern. Wählen Sie es einmal und ändern Sie es niemals stillschweigend.
• Angemeldete Oberflächen bucketieren nach userId, anonyme nach deviceId, gemischte nach { or: [userId, deviceId] }. Attributnamen variieren zwischen Projekten: Lesen Sie attributes/ und fragen Sie, welches zu verwenden ist, wenn es nicht offensichtlich ist. Erfinden Sie niemals Attributnamen.
• Regelschlüssel müssen pro Liste (pro Umgebung, wenn konfiguriert) eindeutig sein und dürfen nicht geändert werden, sobald Benutzer gebucketet sind. Zustandsdateien speichern die Variationsbereiche jeder Regel nach Schlüssel, daher weist eine Umbenennung sie neu zu. Fügen Sie eine neue Regel hinzu, anstatt umzubenennen.

2. Die erste passende Regel gewinnt

Regeln werden von oben nach unten ausgeführt. Platzieren Sie enge Regeln, wie ein Land bei 100 %, über der Catch-All-Regel conditions: '*'. Sobald eine Regel matched, entscheidet ihr Prozentsatz, und Benutzer darüber fallen nicht zu späteren Regeln durch.

3. Referenzieren Sie nur, was existiert

Bestätigen Sie jedes Attribut, Segment, Feature und jede Variable, auf die Sie verweisen, existiert, oder erstellen Sie es. Überprüfen Sie auch allowedConditions in featurevisor.config.js: Es kann einschränken, welche Arten von Bedingungen an jedem Ort akzeptiert werden, z. B. Regeln, die nur Segmente benennen (conditions.md). Lint lehnt unbekannte Referenzen ab. Es lehnt auch, mit archived_reference, jede Referenz auf eine archivierte Definition von einer Definition oder Spezifikation ab, die selbst nicht archiviert ist. Eine archivierte Definition wird aus Datafiles entfernt, daher würde eine Referenz darauf stillschweigend aufhören zu matchen, und unter not würde sie jeden matchen. Lint überprüft archivierte Definitionen nur auf ihre Form, sodass das, was sie verwendet haben, später geändert oder entfernt werden kann. Eine Referenz auf eine veraltete Definition ist eine deprecated_reference-Warnung. Führen Sie npx featurevisor find-usage aus, bevor Sie etwas archivieren, umbenennen oder löschen, und bevorzugen Sie Archivieren gegenüber Löschen: Die archivierte Datei reserviert den Schlüssel.

4. Variationsgewichte summieren sich auf 100

Jeder Wert ist eindeutig. control und treatment sind nur Konventionen. Lint lehnt Gewichte ab, die sich nicht auf 100 summieren. Mit CLI 4.0.0 tat es das nicht, also überprüfen Sie die Summe dort selbst: Eine kurze Aufteilung baut einmal, dann schlägt jeder spätere Build mit Invalid saved variation allocation fehl. Für sich gegenseitig ausschließende Experimente siehe mutual-exclusion.md.

5. Bedingungen bleiben portabel über SDKs hinweg

Jedes SDK wertet dasselbe Datafile aus, daher erzwingt Lint eine portable Teilmenge:

• Datumsangaben (before, after) nehmen einen vollständigen ISO-8601-Zeitstempel mit einer Zeitzone, in Anführungszeichen: '2026-11-27T00:00:00Z'. Nur-Datum- und zeitzonenlose Werte bestehen Lint nicht. Beide Operatoren sind streng.
• Versionen (semver*) sind in Anführungszeichen gesetzte Strings wie '5.5' oder '5.5.0', damit YAML sie als Text behält.
• Reguläre Ausdrücke (matches, notMatches) erlauben nur die Flags g, i, m und s und lehnen jedes (?-Konstrukt ab, einschließlich nicht-erfassender (?:…), plus Backreferences und possessive Quantoren.
• Operatoren werden gegen deklarierte Typen geprüft. Ein type: string-Attribut mit format: date-time akzeptiert nur before, after und Präsenzoperatoren, und in akzeptiert eine String-Liste.

Details und Lint-Meldungen: operators.md.

6. Passen Sie die Form des Projekts an

Umgebungen, Sets, Parser und Namespace-Trennzeichen ändern, wie dieselbe Anfrage geschrieben wird. Vorlagen verwenden die Standardform ohne Umgebungen. In einem Projekt mit Umgebungen setzen Sie jede rules-, force- oder globale overrides-Liste unter ihren Umgebungsschlüssel und fügen Sie environment zu Tests hinzu.

Definition of Done

Führen Sie diese Schleife nach jeder Änderung aus. So beweisen Sie, dass eine Änderung das tut, was der Benutzer verlangt hat, und es gibt Ihnen die Beweise, um zurückzuberichten.

1. Lint. npx featurevisor lint muss bestehen. Mit --json hat jeder Fehler filePath, path, message und code, sodass Sie das genaue Feld beheben können. Führen Sie es nach der Korrektur erneut aus: Einige Fehler erscheinen nur, wenn frühere in der … (gekürzt für Übersetzung)