Ceci est une série en 10 parties expliquant comment Apidog a développé Apidog CLI, un outil en ligne de commande pour les tests d'API et la gestion du cycle de vie des API. Lisez-les dans l'ordre ou sautez à n'importe quel article qui vous intéresse :
| Titre | Focus | |
|---|---|---|
| 1 | Nous avons créé 126 outils MCP. Mais ce n'est pas la meilleure solution pour l'Agent | Découverte du problème |
| 2 | Pourquoi nous avons développé le tout nouvel Apidog CLI | Développement de l'architecture |
| 3 | La règle d'or : le CLI produit des faits, le modèle agit sur les faits | Philosophie centrale |
| 4 | agentHints : Enseigner aux CLI à communiquer avec les Agents |
Sortie structurée |
| 5 | COMPÉTENCE : Fournir l'expérience opérationnelle sous forme de code | Expérience opérationnelle |
| 6 | Les chiffres ne mentent pas : 30 % d'appels d'outils en moins, 25 % de tokens en moins | Résultats quantitatifs |
| 7 | Du PRD à la boucle de test : un flux de travail complet d'Agent avec Apidog CLI | Tutoriel pratique |
| 8 | Pourquoi la compatibilité CI/CD est non négociable pour les outils d'Agent | Perspective DevOps |
| 9 | Branche AI : des modifications de projet plus sûres avec les Agents IA | Couche de sécurité |
| 10 | Spec-First, c'était hier. Bienvenue au Skill-First. | Vision et avenir |
Lorsqu'un Agent modifie des ressources de projet, la sécurité et la possibilité de révision sont importantes. La branche AI offre un environnement d'édition isolé – les modifications n'entrent dans la branche cible qu'après confirmation humaine.
Le défi de la sécurité
Lorsque les Agents IA participent au développement et aux tests d'API, ils peuvent créer, mettre à jour et supprimer des ressources de projet via des commandes CLI.
Ce pouvoir s'accompagne d'un risque.
| Risque | Ce qui pourrait arriver |
|---|---|
| Sorties imprévisibles | L'Agent écrit du contenu inattendu |
| Erreurs de champ | Assertions incorrectes, paramètres manquants |
| Dérive du périmètre | L'Agent modifie des ressources au-delà de la tâche |
| Pas de piste de révision | Les modifications apparaissent directement dans la branche principale |
| Interruption de l'équipe | Branche de collaboration partagée soudainement modifiée |
Comment laisser les Agents travailler sur des projets réels sans risquer la branche principale ?
Branche AI : La couche de sécurité
La branche AI est un type spécial de Branche de Sprint conçue spécifiquement pour les opérations externes d'IA et de CLI.
Concept clé :
Toutes les opérations d'édition initiées depuis Apidog CLI sont considérées par défaut comme initiées par l'IA / les Agents IA.
La branche AI fournit aux Agents IA une branche d'édition isolée. Les modifications restent dans la branche AI jusqu'à ce qu'un humain les examine et les fusionne.
L'Agent effectue des modifications via le CLI
↓
Modifications stockées dans la branche AI (isolée)
↓
L'utilisateur examine les différences
↓
L'utilisateur confirme le périmètre des ressources
↓
Fusionner vers la branche cible (directe ou demande de fusion)La branche principale reste intacte jusqu'à votre approbation.
Pourquoi la branche AI est nécessaire
Les modifications initiées par l'IA peuvent être imprévisibles. Apidog CLI offre un large éventail de capacités d'édition : points d'extrémité, schémas, scénarios de test, suites de test, et plus encore.
La branche AI est conçue pour ces opérations d'édition initiées par l'IA à plus haut risque.
Elle permet aux Agents IA de modifier les ressources du projet dans un périmètre contrôlé :
| Sans branche AI | Avec branche AI |
|---|---|
| L'Agent écrit directement dans la branche principale | L'Agent écrit dans une branche isolée |
| Les modifications apparaissent immédiatement | Les modifications attendent une révision |
| Pas de filet de sécurité | Confirmation humaine requise |
| Risque de modifications involontaires | Périmètre limité à des ressources spécifiques |
Qu'est-ce qu'une branche AI ?
Une branche AI est une branche de sprint spéciale avec des caractéristiques spécifiques :
Caractéristiques clés
| Caractéristique | Description |
|---|---|
| Édition isolée | Les modifications sont stockées dans la branche AI, n'affectant pas la branche principale ou source |
| Source claire | Ne peut pas être créée dans le client — doit provenir du CLI/MCP ; enregistre la branche source |
| Confirmation humaine | Les modifications doivent être confirmées avant fusion |
| Aucune limite de quantité | Créez autant de branches AI que nécessaire pour différentes tâches |
| Archivage automatique | Les branches sans différences sont archivées toutes les 24 heures |
Comment ça marche
| Opération | Où ça se passe |
|---|---|
| L'IA crée un point d'extrémité | Dans la branche AI |
| L'IA met à jour le scénario de test | Dans la branche AI |
| L'équipe examine les modifications | Dans le client ou la prévisualisation CLI |
| L'utilisateur approuve la fusion | Action de l'utilisateur, pas de l'IA |
| Les modifications entrent dans la branche cible | Après confirmation |
L'édition normale par les utilisateurs dans le client suit toujours les permissions des membres du projet et les règles de protection de branche.
Cas d'utilisation
La branche AI est appropriée lorsque l'IA doit participer à la maintenance du projet tout en préservant l'isolation des branches et la confirmation humaine.
| Scénario | Comment la branche AI aide |
|---|---|
| Générer des ébauches d'API à partir de code | L'IA crée des points d'extrémité dans la branche AI ; les utilisateurs confirment avant la fusion |
| Organiser les ressources API en masse | L'IA ajuste les dossiers, les descriptions, les modèles sans affecter la branche de collaboration |
| Générer des ébauches de tests automatisés | L'IA crée des scénarios/cas de test dans la branche AI pour la révision par le testeur |
| Combler les lacunes de la documentation API | L'IA complète les champs manquants en fonction des rapports de bogues ou de l'implémentation |
| Écriture par lot en CI/CD | Les flux de travail automatisés écrivent dans la branche AI, attendant la fusion par l'utilisateur |
Flux de travail de base
Un flux de travail typique de branche AI :
┌─────────────────────────────────────────────────────────────────┐
│ FLUX DE TRAVAIL DE LA BRANCHE AI │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Étape 1 : Créer une branche AI │
│ ┌───────────────────────────────────────────┐ │
│ │ apidog branch create --type ai │ │
│ │ --name "ai/20260312-from-main-feature" │ │
│ │ --from main │ │
│ └───────────────────────────────────────────┘ │
│ ↓ │
│ Étape 2 : Importer ou créer des ressources │
│ ┌───────────────────────────────────────────┐ │
│ │ apidog branch pick-to (importer existant) │ │
│ │ OU │ │
│ │ apidog endpoint create (créer nouveau) │ │
│ └───────────────────────────────────────────┘ │
│ ↓ │
│ Étape 3 : L'IA modifie les ressources │
│ ┌───────────────────────────────────────────┐ │
│ │ L'Agent utilise le CLI pour mettre à jour │ │
│ │ les points d'extrémité, les schémas, les │ │
│ │ scénarios de test, etc. │ │
│ │ (--branch spécifie la branche AI) │ │
│ └───────────────────────────────────────────┘ │
│ ↓ │
│ Étape 4 : L'utilisateur examine les différences │
│ ┌───────────────────────────────────────────┐ │
│ │ apidog merge-request preview │ │
│ │ OU │ │
│ │ Afficher dans le client Apidog │ │
│ └───────────────────────────────────────────┘ │
│ ↓ │
│ Étape 5 : Fusionner vers la branche cible │
│ ┌───────────────────────────────────────────┐ │
│ │ Fusion directe (branche non protégée) │ │
│ │ OU │ │
│ │ Demande de fusion (branche protégée) │ │
│ └───────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘Créer une branche AI
Utilisez branch create --type ai :
apidog branch create \
--project 123456 \
--type ai \
--name "ai/20260312-from-main-userRegister" \
--from mainRecommandation de nommage : ai/AAAAJJMM-from-brancheSource-fonctionnaliteOuModule
| Commande | But |
|---|---|
branch create --type ai |
Créer une branche AI |
branch list --type ai |
Afficher les branches AI dans le projet |
branch list --type all |
Afficher tous les types de branches |
branch get --type ai |
Afficher les détails de la branche AI |
Modifier des ressources dans une branche AI
Lorsque le CLI écrit des ressources de projet, utilisez le paramètre --branch pour écrire dans la branche AI :
| Ressource | Exemple de commande |
|---|---|
| Point d'extrémité HTTP | apidog endpoint create --project <id> --branch <nomBrancheAi> --file ./endpoint.json |
| Modèle de données | apidog schema update <schemaId> --project <id> --branch <nomBrancheAi> --file ./schema.json |
| Scénario de test | apidog test-scenario update <scenarioId> --project <id> --branch <nomBrancheAi> --file ./scenario.json |
| Suite de tests | apidog test-suite create --project <id> --branch <nomBrancheAi> --file ./suite.json |
Flux de travail recommandé :
# 1. Obtenir le schéma
apidog cli-schema get endpoint-create
# 2. Valider avant d'écrire
apidog cli-schema validate endpoint-create --file ./endpoint.json
# 3. Écrire dans la branche AI (pas la branche principale)
apidog endpoint create \
--project 123456 \
--branch "ai/20260312-from-main-userRegister" \
--file ./endpoint.jsonImporter des ressources existantes
Pour modifier des ressources existantes, importez-les d'abord depuis la branche source :
apidog branch pick-to \
--project 123456 \
--from main \
--to "ai/20260312-from-main-userRegister" \
--endpoint-ids 1001,1002Cela garantit que l'IA travaille avec la version de base correcte.
Examiner les modifications avant la fusion
Avant la fusion, prévisualisez les différences :
apidog merge-request preview \
--project 123456 \
--from "ai/20260312-from-main-userRegister" \
--to mainOu affichez le diff complet dans le client Apidog.
| Commande | But |
|---|---|
merge-request preview |
Scanner les modifications candidates |
branch get --type ai |
Afficher les informations de la branche AI |
Fusionner une branche AI
Après examen, fusionnez les modifications :
Fusion directe (branche non protégée)
apidog branch merge \
--project 123456 \
--from "ai/20260312-from-main-userRegister" \
--to main \
--endpoint-ids 1001,1002Demande de fusion (branche protégée)
apidog merge-request create \
--project 123456 \
--from "ai/20260312-from-main-userRegister" \
--to main \
--reviewer-ids 20001,20002 \
--endpoint-ids 1001,1002| Commande | But |
|---|---|
branch merge |
Fusion directe vers une branche non protégée |
merge-request create |
Créer une demande de fusion pour révision |
merge-request approve |
Approuver la demande de fusion |
merge-request reject |
Rejeter la demande de fusion |
Important : Les commandes de fusion ne traitent que la liste de ressources explicitement fournie. Confirmez les dépendances (répertoires, modèles, composants de réponse, tests) avant de fusionner.
Archiver et supprimer
Une fois les modifications fusionnées ou devenues inutiles :
# Archiver
apidog branch archive "ai/20260312-from-main-userRegister" \
--project 123456 --type ai
# Supprimer (après archivage)
apidog branch delete "ai/20260312-from-main-userRegister" \
--project 123456 --type aiPermissions d'édition AI externe
Par défaut, le CLI écrit dans la branche AI. Cela maintient les modifications générées par l'IA isolées jusqu'à la confirmation de l'utilisateur.
Pour permettre l'édition directe de la branche principale :
Paramètres du projet → Paramètres des fonctionnalités → Paramètres des fonctionnalités AI → Permissions d'édition AI externe| Permission | Ce qu'elle permet |
|---|---|
| Édition directe de la branche principale | Le CLI écrit directement dans la branche principale (contourne la branche AI) |
| Édition directe de la branche de sprint standard | Le CLI écrit directement dans les branches de sprint |
| Édition directe de la branche générale | Le CLI écrit directement dans les branches générales |
| Édition directe de la branche AI | Le CLI écrit dans les branches AI (généralement maintenu activé) |
Recommandation : Maintenez l'isolation de la branche AI activée. N'activez l'édition directe que lorsque les flux de travail d'automatisation en ont clairement besoin.
Bonnes pratiques
| Pratique | Pourquoi |
|---|---|
| Une branche AI par tâche | Périmètre clair : API d'enregistrement utilisateur, documentation du module de commande, tests de paiement |
| Importer avant d'éditer | Utilisez pick-to pour les ressources existantes — évitez la confusion de source |
| Valider avant d'écrire | Utilisez cli-schema validate pour détecter les erreurs avant la branche AI |
| Prévisualiser avant la fusion | Utilisez merge-request preview ou la vue diff du client |
| Périmètre de fusion explicite | Confirmez les points d'extrémité, les modèles, les répertoires, les tests ensemble |
| Maintenir la révision humaine | Les définitions d'API, les scripts de test doivent être examinés avant la fusion |
| Archiver rapidement | Gardez la liste des branches claire après la fusion ou l'abandon |
La branche AI dans le flux de travail CLI + SKILL
La branche AI s'intègre naturellement avec CLI + SKILL :
| Étape | CLI + SKILL + branche AI |
|---|---|
| Lire | endpoint get depuis n'importe quelle branche |
| Générer | L'Agent crée un JSON |
| Valider | cli-schema validate localement |
| Écrire | endpoint create --branch <nomBrancheAi> vers la branche AI |
| Examiner | merge-request preview |
| Fusionner | L'utilisateur confirme, puis branch merge |
| Vérifier | apidog run sur les ressources fusionnées |
Chaque écriture passe par la branche AI → révision humaine → fusion.
Résumé de la sécurité
| Couche | Protection |
|---|---|
cli-schema validate |
Détecte les erreurs structurelles avant l'écriture |
agentHints |
Guide l'Agent vers les prochaines étapes sûres |
| Branche AI | Isole les modifications de la branche principale |
| Révision humaine | Confirme le contenu avant la fusion |
| Périmètre de fusion | L'utilisateur sélectionne les ressources à fusionner |
Ensemble, ces couches créent une boucle plus sûre pour les modifications de projet pilotées par l'Agent.
Et ensuite ?
Avec la branche AI offrant la couche de sécurité, toutes les pièces sont en place :
- MCP pour la connexion des outils (Partie 1)
- CLI + SKILL pour l'exécution des flux de travail (Parties 2-5)
- Résultats de validation (Partie 6)
- Flux de travail pratiques (Partie 7)
- Base CI/CD (Partie 8)
- Branche AI pour la sécurité (Partie 9)
Il est maintenant temps pour la vision.
Dans la Partie 10, Spec-First, c'était hier. Bienvenue au Skill-First., nous décrirons comment le développement d'API évolue avec les Agents IA — et ce que les équipes devraient faire ensuite.
Points clés à retenir
- La branche AI offre une édition isolée pour les opérations AI/CLI
- Les modifications n'affectent pas la branche principale avant confirmation humaine
- Créez avec
branch create --type ai, écrivez avec le paramètre--branch - Importez les ressources existantes avec
branch pick-toavant d'éditer - Prévisualisez avec
merge-request preview, puis fusionnez ou créez une demande de fusion - Les permissions d'édition directe peuvent contourner la branche AI — utilisez-les avec prudence
- Meilleure pratique : une branche AI par tâche, validez avant d'écrire, révisez avant de fusionner
Téléchargez Apidog pour concevoir, simuler, tester, et documenter les API dans un seul espace de travail. En savoir plus sur Apidog CLI pour les tests d'API en ligne de commande, l'automatisation CI et les flux de travail des Agents IA.