Skill de création de DAG

Cette skill te guide dans la création et la validation de DAGs Airflow en suivant les meilleures pratiques et les commandes CLI af.

Pour tester et déboguer les DAGs, consulte la skill testing-dags qui couvre le workflow complet test → débogage → correction → nouvel essai.

Exécuter la CLI

Ces commandes supposent que af est dans PATH. Exécute via astro otto pour l'obtenir automatiquement, ou installe de manière autonome avec uv tool install astro-airflow-mcp.

Vue d'ensemble du workflow

+-----------------------------------------+
| 1. DISCOVER                             |
|    Understand codebase & environment    |
+-----------------------------------------+
                 |
+-----------------------------------------+
| 2. PLAN                                 |
|    Propose structure, get approval      |
+-----------------------------------------+
                 |
+-----------------------------------------+
| 3. IMPLEMENT                            |
|    Write DAG following patterns         |
+-----------------------------------------+
                 |
+-----------------------------------------+
| 4. VALIDATE                             |
|    Check import errors, warnings        |
+-----------------------------------------+
                 |
+-----------------------------------------+
| 5. TEST (with user consent)             |
|    Trigger, monitor, check logs         |
+-----------------------------------------+
                 |
+-----------------------------------------+
| 6. ITERATE                              |
|    Fix issues, re-validate              |
+-----------------------------------------+

Phase 1 : Découverte

Avant d'écrire le code, comprends le contexte.

Explorer la base de code

Utilise les outils de fichiers pour trouver les patterns existants :

• Glob pour **/dags/**/*.py pour trouver les DAGs existants
• Read des DAGs similaires pour comprendre les conventions
• Vérifie requirements.txt pour les packages disponibles

Interroger l'environnement Airflow

Utilise les commandes CLI af pour comprendre ce qui est disponible :

Exemples de questions pour la découverte :

• « Y a-t-il une connexion Snowflake ? » -> af config connections
• « Quelle version d'Airflow ? » -> af config version
• « Les opérateurs S3 sont-ils disponibles ? » -> af config providers

Phase 2 : Planification

Sur la base de la découverte, propose :

1. Structure du DAG - Tâches, dépendances, planning
2. Opérateurs à utiliser - Basés sur les providers disponibles
3. Connexions nécessaires - Existantes ou à créer
4. Variables nécessaires - Existantes ou à créer
5. Packages nécessaires - Ajouts à requirements.txt

Obtiens l'approbation de l'utilisateur avant de mettre en œuvre.

Phase 3 : Implémentation

Écris le DAG en suivant les meilleures pratiques (voir ci-dessous). Étapes clés :

1. Crée le fichier DAG à l'emplacement approprié
2. Mets à jour requirements.txt si nécessaire
3. Enregistre le fichier

Phase 4 : Validation

Utilise la CLI af comme boucle de rétroaction pour valider ton DAG.

Étape 1 : Vérifier les erreurs d'import

Après l'enregistrement, vérifie les erreurs d'analyse (Airflow aura déjà analysé le fichier) :

af dags errors

• Si ton fichier apparaît -> corrige et réessaye
• Si pas d'erreurs -> continue

Causes courantes : imports manquants, erreurs de syntaxe, packages manquants.

Étape 2 : Vérifier que le DAG existe

af dags get <dag_id>

Vérifie : DAG existe, planning correct, tags définis, statut de pause.

Étape 3 : Vérifier les avertissements

af dags warnings

Cherche les avertissements de dépéciation ou les problèmes de configuration.

Étape 4 : Explorer la structure du DAG

af dags explore <dag_id>

Retourne en un seul appel : métadonnées, tâches, dépendances, code source.

Sur Astro

Si tu exécutes sur Astro, tu peux aussi valider localement avant le déploiement :

• Vérification d'analyse : Exécute astro dev parse pour détecter les erreurs d'import et les problèmes au niveau du DAG sans démarrer un environnement Airflow complet
• Déploiement DAG uniquement : Une fois validé, utilise astro deploy --dags pour des déploiements rapides DAG uniquement qui sautent la construction de l'image Docker — idéal pour itérer sur le code du DAG

Phase 5 : Test

Consulte la skill testing-dags pour des conseils de test complets.

Une fois la validation réussie, teste le DAG en utilisant le workflow dans la skill testing-dags :

1. Obtenir le consentement de l'utilisateur -- Demande toujours avant de déclencher
2. Déclencher et attendre -- af runs trigger-wait <dag_id> --timeout 300
3. Analyser les résultats -- Vérifie le statut de succès/échec
4. Déboguer si nécessaire -- af runs diagnose <dag_id> <run_id> et af tasks logs <dag_id> <run_id> <task_id>

Test rapide (minimal)

# Demande d'abord à l'utilisateur, puis :
af runs trigger-wait <dag_id> --timeout 300

Pour la boucle complète test → débogage → correction → nouvel essai, consulte testing-dags.

Phase 6 : Itération

Si des problèmes sont trouvés :

1. Corrige le code
2. Vérifie les erreurs d'import : af dags errors
3. Re-valide (Phase 4)
4. Re-teste en utilisant le workflow de la skill testing-dags (Phase 5)

Référence rapide de la CLI

Commandes de test -- Consulte la skill testing-dags pour af runs trigger-wait, af runs diagnose, af tasks logs, etc.

Meilleures pratiques et anti-patterns

Pour les patterns de code et les anti-patterns, consulte reference/best-practices.md.

Lis cette référence lors de l'écriture de nouveaux DAGs ou de la révision de DAGs existants. Elle couvre les patterns corrects (y compris le comportement spécifique à Airflow 3) et ce qu'il faut éviter.

Skills connexes

• testing-dags : Pour tester les DAGs, déboguer les échecs et la boucle test → correction → nouvel essai
• debugging-dags : Pour dépanner les DAGs défaillants
• deploying-airflow : Pour déployer les DAGs en production (Astro ou open-source)
• migrating-airflow-2-to-3 : Pour migrer les DAGs vers Airflow 3