Créer le premier feature flag

Le SDK est connecté. Aidez maintenant l'utilisateur à créer son premier feature flag et à le voir fonctionner de bout en bout.

Cette compétence est imbriquée sous Onboarding LaunchDarkly ; l'étape parent Step 6 est first flag. Avant : Appliquer les modifications de code.

Optionnel -- Compétence Flag Create déjà installée : Si la compétence launchdarkly-flag-create de github.com/launchdarkly/ai-tooling est disponible dans la session (installer avec npx skills add launchdarkly/ai-tooling --skill launchdarkly-flag-create -y --agent <agent>), vous pouvez l'utiliser pour créer le flag et choisir le code d'évaluation qui correspond au dépôt. Vous devez toujours terminer désactiver par défaut → vérifier OFF → activer → vérifier ON (étapes 3-5 ci-dessous). Ne requérez pas cette compétence : cette page reste le recours complet en cas d'absence ou de conflits de flux MCP uniquement avec la configuration de l'utilisateur.

Sécurité : Gestion des identifiants

Ne substituez jamais les valeurs de jeton littérales dans les commandes. Utilisez plutôt des références aux variables d'environnement :

• Commandes shell : $LAUNCHDARKLY_ACCESS_TOKEN (développée par le shell, non visible dans la sortie ps)
• Définir la variable dans votre session : export LAUNCHDARKLY_ACCESS_TOKEN=<your-token>

Cela empêche les jetons d'apparaître dans les listes de processus, l'historique shell et les enregistrements d'écran.

Étape 0 : Consulter les conseils sur la clé de flag du SDK

Avant de créer le flag ou d'implémenter le code d'évaluation, consultez le tableau Comportement de la clé de flag par SDK ci-dessous. Certains SDK transforment les clés de flag avant de les exposer dans le code d'application (par exemple, le SDK React change les clés kebab-case en camelCase). La clé de flag que vous créez dans LaunchDarkly, la configuration du SDK/framework et la clé que vous référencez dans le code doivent tous être alignés.

• Si le SDK transforme les clés (par exemple, React useFlags() change my-first-flag en camelCase → myFirstFlag) : générez le code d'évaluation en utilisant la clé transformée. La clé de flag dans LaunchDarkly reste telle quelle (kebab-case est conventionnel).
• Si le SDK conserve les clés telles quelles (la plupart des SDK côté serveur) : utilisez la chaîne de clé de flag LaunchDarkly exacte dans le code.
• Si le SDK prend en charge les deux modes (par exemple, React permet de désactiver camelCase via les options du fournisseur) : décidez quel mode le projet utilise (vérifiez le code existant ou la config du fournisseur), puis générez du code qui correspond.

Comportement de la clé de flag par SDK

Lors du câblage du code d'évaluation à l'étape 2 ci-dessous, utilisez la valeur de la colonne Clé de code, pas la clé LaunchDarkly brute, chaque fois que le SDK applique une transformation.

Étape 1 : Créer le flag

Auth REST / curl : Utilisez $LAUNCHDARKLY_ACCESS_TOKEN comme valeur d'en-tête Authorization (LaunchDarkly utilise le jeton brut, pas de préfixe Bearer). Le shell développe la variable mais ne la consigne pas.

Via MCP (préféré)

Si le serveur MCP LaunchDarkly est disponible, utilisez create-feature-flag (ou l'outil équivalent de création de flag que votre serveur expose) :

• Key : my-first-flag (ou un nom pertinent pour le projet de l'utilisateur)
• Name : "My First Flag"
• Kind : boolean
• Variations : true / false
• Temporary : true

Via l'API LaunchDarkly

curl -s -X POST \
  "https://app.launchdarkly.com/api/v2/flags/PROJECT_KEY" \
  -H "Authorization: $LAUNCHDARKLY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Flag",
    "key": "my-first-flag",
    "kind": "boolean",
    "variations": [
      {"value": true},
      {"value": false}
    ],
    "temporary": true
  }'

Via ldcli

ldcli flags create \
  --access-token "$LAUNCHDARKLY_ACCESS_TOKEN" \
  --project PROJECT_KEY \
  --data '{"name": "My First Flag", "key": "my-first-flag", "kind": "boolean", "temporary": true}'

Après la création, le flag commence avec ciblage OFF, servant la variation off (false) à tout le monde. Quand la clé du projet est connue, liez l'utilisateur à la page du tableau de bord du flag : https://app.launchdarkly.com/projects/{projectKey}/flags/my-first-flag (remplacez la clé du projet réelle).

Étape 2 : Ajouter le code d'évaluation du flag

Ajoutez du code pour évaluer le flag dans l'application. Placez-le là où cela a du sens pour la fonctionnalité de l'utilisateur.

Exemples côté serveur

// Node.js (@launchdarkly/node-server-sdk) -- ldClient est votre client serveur initialisé après waitForInitialization
const context = { kind: 'user', key: 'example-user-key', name: 'Example User' };
const showFeature = await ldClient.boolVariation('my-first-flag', context, false);

if (showFeature) {
  console.log('Feature is ON');
} else {
  console.log('Feature is OFF');
}

# Python (launchdarkly-server-sdk) -- client est ldclient.get() après set_config
from ldclient import Context

context = Context.builder("example-user-key").name("Example User").build()
show_feature = client.variation("my-first-flag", context, False)

if show_feature:
    print("Feature is ON")
else:
    print("Feature is OFF")

// Go
context := ldcontext.NewBuilder("example-user-key").Name("Example User").Build()
showFeature, _ := ldClient.BoolVariation("my-first-flag", context, false)

if showFeature {
    fmt.Println("Feature is ON")
} else {
    fmt.Println("Feature is OFF")
}

Exemples côté client

// React — useFlags() change les clés en camelCase : "my-first-flag" → myFirstFlag (voir tableau étape 0)
import { useFlags } from 'launchdarkly-react-client-sdk';

function MyComponent() {
  const { myFirstFlag } = useFlags();

  return (
    <div>
      {myFirstFlag ? <p>Feature is ON</p> : <p>Feature is OFF</p>}
    </div>
  );
}

Le hook useFlags() du SDK React change les clés de flag kebab-case en camelCase par défaut, donc my-first-flag devient myFirstFlag. Si le projet désactive ceci via reactOptions: { useCamelCaseFlagKeys: false } sur le fournisseur, utilisez la chaîne de clé originale à la place. Vérifiez toujours la configuration du fournisseur du projet avant de choisir quelle forme utiliser — voir le tableau Comportement de la clé de flag ci-dessus.

Étape 3 : Vérifier la valeur par défaut

Avec le ciblage OFF, le flag devrait s'évaluer à false. Exécutez l'application et confirmez :

Feature is OFF

Étape 4 : Activer le flag

Via MCP

Le serveur MCP LaunchDarkly expose update-feature-flag (JSON Patch), pas un outil nommé toggle-flag -- utilisez les noms d'outils que votre serveur MCP liste.

Chemin le plus simple : Préférez ldcli ou le bloc API LaunchDarkly ci-dessous quand vous avez juste besoin d'activer le flag une fois.

Si vous utilisez update-feature-flag : Appelez-le avec projectKey, featureFlagKey et PatchWithComment.patch comme un tableau JSON Patch. Activer le flag on pour un environnement utilise généralement une opération replace sur le champ on de cet environnement (confirmez le chemin exact depuis get-feature-flag pour votre compte si nécessaire) :

{
  "projectKey": "PROJECT_KEY",
  "featureFlagKey": "my-first-flag",
  "PatchWithComment": {
    "patch": [
      {
        "op": "replace",
        "path": "/environments/ENVIRONMENT_KEY/on",
        "value": true
      }
    ],
    "comment": "Onboarding: turn on my-first-flag"
  }
}

Remplacez ENVIRONMENT_KEY par la clé d'environnement pour l'environnement que vous ciblez (par exemple test, production).

Via l'API LaunchDarkly

curl -s -X PATCH \
  "https://app.launchdarkly.com/api/v2/flags/PROJECT_KEY/my-first-flag" \
  -H "Authorization: $LAUNCHDARKLY_ACCESS_TOKEN" \
  -H "Content-Type: application/json; domain-model=launchdarkly.semanticpatch" \
  -d '{
    "environmentKey": "ENVIRONMENT_KEY",
    "instructions": [
      {"kind": "turnFlagOn"}
    ]
  }'

Via ldcli

ldcli flags toggle-on \
  --access-token "$LAUNCHDARKLY_ACCESS_TOKEN" \
  --project PROJECT_KEY \
  --environment ENVIRONMENT_KEY \
  --flag my-first-flag

Étape 5 : Vérifier l'activation

Après activation du flag, l'application devrait maintenant afficher :

Feature is ON

Pour les SDK côté serveur utilisant le streaming (par défaut), la modification devrait être reflétée en quelques secondes. Pour les SDK côté client, la modification apparaît au prochain chargement de page ou quand le SDK interroge les mises à jour.

Étape 6 : Ajouter une démo interactive

Maintenant que le flag fonctionne, ajoutez un élément visible et interactif pour que l'utilisateur voie le flag en action -- pas juste un log console. Cela crée un moment "wow" et donne à l'utilisateur une preuve tangible qu'il peut montrer à d'autres.

Choisissez la bonne démo en fonction de ce que vous avez détecté :

Exemple de démo frontend (React)

Ajoutez un composant ou élément qui est visuellement évident quand le flag est on :

// Ajouter à un composant de page existant
import { useFlags } from 'launchdarkly-react-client-sdk';

function FeatureFlagDemo() {
  const { myFirstFlag } = useFlags();

  if (!myFirstFlag) return null;

  return (
    <div style={{
      padding: '12px 20px',
      backgroundColor: '#405BFF',
      color: 'white',
      borderRadius: '8px',
      margin: '16px 0',
      fontWeight: 500
    }}>
      LaunchDarkly is working — this banner is controlled by a feature flag
    </div>
  );
}

Placez-le quelque part de visible (par exemple, en haut de la page principale ou dans une zone tableau de bord/en-tête).

Exemple de démo backend (Node.js/Express)

Ajoutez un endpoint qui retourne l'état du flag :

// Ajouter à votre app Express (ou équivalent pour d'autres frameworks)
app.get('/launchdarkly-demo', async (req, res) => {
  const context = { kind: 'user', key: 'demo-user' };
  const flagValue = await ldClient.boolVariation('my-first-flag', context, false);

  res.json({
    flag: 'my-first-flag',
    enabled: flagValue,
    message: flagValue 
      ? 'LaunchDarkly is working — the flag is ON'
      : 'LaunchDarkly is working — the flag is OFF'
  });
});

Dites à l'utilisateur de tester avec : curl http://localhost:PORT/launchdarkly-demo

Exemple de démo backend (Python/Flask)

@app.route('/launchdarkly-demo')
def launchdarkly_demo():
    context = Context.builder("demo-user").build()
    flag_value = ld_client.variation("my-first-flag", context, False)

    return jsonify({
        "flag": "my-first-flag",
        "enabled": flag_value,
        "message": "LaunchDarkly is working — the flag is ON" if flag_value 
                   else "LaunchDarkly is working — the flag is OFF"
    })

Démo full-stack

Pour les apps avec serveur et client (par exemple, Next.js, Remix, Rails avec frontend) :

1. Ajouter l'endpoint API (exemple backend ci-dessus)
2. Ajouter un composant UI qui appelle l'endpoint ou utilise le client SDK directement
3. L'utilisateur peut vérifier que les deux chemins fonctionnent

Recommandations

1. Suivre les motifs existants -- utilisez le même style de routing, les mêmes conventions de composants et le même style de code que le reste de l'app
2. Le rendre évident -- utilisez la couleur, la position ou le texte qui indique clairement qu'il s'agit de la démo LaunchDarkly
3. Le rendre supprimable -- ajoutez un bref commentaire comme // LaunchDarkly demo - safe to remove pour que l'utilisateur sache qu'il peut le supprimer plus tard (ou le garder comme modèle)
4. Ne pas sur-ingénier -- c'est une démo, pas une fonctionnalité de production ; quelques lignes de code c'est l'idéal

Guider l'utilisateur à travers

Après avoir ajouté l'élément de démo :

1. Dites à l'utilisateur où vous l'avez ajouté et comment le voir (URL, emplacement de la page, commande)
2. Demandez-lui de vérifier qu'il montre l'état actuel du flag
3. Demandez-lui d'activer le flag dans le tableau de bord (fournissez le lien profond : https://app.launchdarkly.com/projects/{projectKey}/flags/my-first-flag)
4. Demandez-lui de rafraîchir/réexécuter pour voir le changement
5. Célébrez l'intégration réussie

Félicitations

L'utilisateur a réussi à :

1. Installer le SDK LaunchDarkly
2. Le connecter à LaunchDarkly
3. Créer un feature flag
4. L'évaluer dans le code
5. L'activer et voir le résultat
6. Ajouter une démo interactive qu'il peut montrer à d'autres

C'est le moment du "proof point" -- l'utilisateur a un feature flag qui fonctionne et qu'il peut activer en temps réel. L'élément de démo le rend tangible et partageable.

Encourager la prochaine compétence : Suggérez-leur d'installer ou d'activer la compétence launchdarkly-flag-create de github.com/launchdarkly/ai-tooling (npx skills add launchdarkly/ai-tooling --skill launchdarkly-flag-create -y --agent <agent>) pour que le travail futur -- créer des flags qui correspondent aux conventions du dépôt, envelopper les fonctionnalités et vérifier le câblage -- ait un playbook dédié. Offrez de les aider à l'ajouter s'ils ne sont pas sûrs comment faire.

Gestion des erreurs

Erreurs d'autorisation

Si une étape retourne un 401 ou 403 :

D9 -- BLOQUANT : Appelez votre outil de question structurée maintenant.

• question: "I received an authorization error ([specific status code and message]). This requires your action to resolve -- I cannot retry automatically."
• options:
  • "I'll re-authenticate -- run ldcli login or refresh my token"
  • "Let me check my access token and try again"
  • "I don't have an account -- help me sign up"
  • "The project or environment doesn't exist -- help me create one"
• ARRÊTEZ. N'écrivez pas la question en tant que texte. Ne réessayez pas automatiquement les erreurs d'autorisation -- elles nécessitent toujours l'action de l'utilisateur. N'allez pas plus loin tant que l'utilisateur n'a pas sélectionné une option.

Autres erreurs

Pour les erreurs non-auth (échecs de création de flag, désaccords de clé SDK, flags retournant des valeurs fallback, etc.), diagnostiquez le problème à l'aide de la sortie d'erreur, des logs d'application et votre compréhension du projet.

Prochaines étapes à suggérer :

• Installer launchdarkly-flag-create de github.com/launchdarkly/ai-tooling s'il n'est pas déjà disponible -- ce flux d'onboarding couvre uniquement un premier flag booléen ; cette compétence guide la création de flags réelle alignée avec les motifs de code existants (nécessite MCP LaunchDarkly selon les prérequis de cette compétence).
• Utilisez launchdarkly-flag-targeting de la même distribution pour configurer les déploiements en pourcentage et les règles de ciblage
• Lisez la documentation LaunchDarkly pour les sujets avancés comme les contextes, l'expérimentation et les métriques

À la fin, continuez avec : Résumé d'onboarding et Règles d'éditeur et compétences (suivi par défaut dans la compétence d'onboarding parent -- pas la configuration MCP, qui est l'étape 4). Pour l'installation ou le dépannage MCP, utilisez mcp-configure et MCP Config Templates.