DAG オーサリング スキル

このスキルは、ベストプラクティスと af CLI コマンドを使用して Airflow DAG を作成および検証するプロセスをガイドします。

DAG のテストとデバッグについては、テスト -> デバッグ -> 修正 -> 再テストワークフロー全体をカバーする testing-dags スキルを参照してください。

---

CLI の実行

これらのコマンドは af が PATH に存在することを前提としています。astro otto 経由で実行して自動的に取得するか、uv tool install astro-airflow-mcp でスタンドアロンインストールしてください。

---

ワークフロー概要

+-----------------------------------------+
| 1. DISCOVER                             |
|    コードベースと環境を理解              |
+-----------------------------------------+
                 |
+-----------------------------------------+
| 2. PLAN                                 |
|    構造を提案し、承認を取得              |
+-----------------------------------------+
                 |
+-----------------------------------------+
| 3. IMPLEMENT                            |
|    パターンに従って DAG を作成           |
+-----------------------------------------+
                 |
+-----------------------------------------+
| 4. VALIDATE                             |
|    インポートエラーと警告を確認          |
+-----------------------------------------+
                 |
+-----------------------------------------+
| 5. TEST (ユーザーの同意のもと)          |
|    トリガー、監視、ログ確認              |
+-----------------------------------------+
                 |
+-----------------------------------------+
| 6. ITERATE                              |
|    問題を修正し、再検証                  |
+-----------------------------------------+

---

フェーズ 1: Discover (発見)

コードを書く前に、コンテキストを理解します。

コードベースを探索

ファイルツールを使用して既存パターンを探します:

• **/dags/**/*.py に対して Glob を使用して既存 DAG を検索
• 同様の DAG を Read して規約を理解
• requirements.txt で利用可能なパッケージを確認

Airflow 環境をクエリ

af CLI コマンドを使用して何が利用可能かを理解します:

コマンド	目的
af config connections	設定されている外部システム
af config variables	存在する構成値
af config providers	インストールされているオペレータパッケージ
af config version	バージョン制約と機能
af dags list	既存 DAG と命名規約
af config pools	同時実行のリソースプール

例：発見質問:

• 「Snowflake コネクションはあるか？」 -> af config connections
• 「Airflow バージョンは？」 -> af config version
• 「S3 オペレータは利用可能か？」 -> af config providers

---

フェーズ 2: Plan (計画)

発見に基づいて以下を提案します:

1. DAG 構造 - タスク、依存関係、スケジュール
2. 使用するオペレータ - 利用可能なプロバイダーに基づいて
3. 必要なコネクション - 既存または作成が必要
4. 必要な変数 - 既存または作成が必要
5. 必要なパッケージ - requirements.txt への追加

実装する前にユーザーの承認を得てください。

---

フェーズ 3: Implement (実装)

ベストプラクティスに従って DAG を書きます（下記参照）。主要なステップ:

1. 適切な場所に DAG ファイルを作成
2. 必要に応じて requirements.txt を更新
3. ファイルを保存

---

フェーズ 4: Validate (検証)

DAG を検証するためのフィードバックループとして af CLI を使用します。

ステップ 1: インポートエラーを確認

保存後、パースエラーをチェックします（Airflow は既にファイルをパースしています）:

af dags errors

• ファイルが表示される場合 -> 修正して再試行
• エラーがない場合 -> 続行

一般的な原因: インポートの欠落、構文エラー、パッケージの欠落。

ステップ 2: DAG が存在することを確認

af dags get <dag_id>

確認内容: DAG が存在する、スケジュールが正しい、タグが設定されている、一時停止ステータス。

ステップ 3: 警告を確認

af dags warnings

非推奨警告または構成の問題を探します。

ステップ 4: DAG 構造を探索

af dags explore <dag_id>

1 回の呼び出しで返します: メタデータ、タスク、依存関係、ソースコード。

Astro での実行

Astro で実行している場合、デプロイ前にローカルで検証することもできます:

• パース確認: astro dev parse を実行して、完全な Airflow 環境を開始することなく、インポートエラーと DAG レベルの問題をキャッチ
• DAG のみのデプロイ: 検証後、astro deploy --dags を使用して、Docker イメージビルドをスキップする高速な DAG のみデプロイが可能 — DAG コードのイテレーションに最適

---

フェーズ 5: Test (テスト)

包括的なテストガイダンスについては testing-dags スキルを参照してください。

検証が完了したら、testing-dags スキルのワークフローを使用して DAG をテストします:

1. ユーザーの同意を取得 -- トリガーする前に常に確認
2. トリガーして待機 -- af runs trigger-wait <dag_id> --timeout 300
3. 結果を分析 -- 成功/失敗ステータスを確認
4. 必要に応じてデバッグ -- af runs diagnose <dag_id> <run_id> と af tasks logs <dag_id> <run_id> <task_id>

クイックテスト（最小限）

# まずユーザーに確認してから:
af runs trigger-wait <dag_id> --timeout 300

テスト -> デバッグ -> 修正 -> 再テストループの完全なフローについては、testing-dags を参照してください。

---

フェーズ 6: Iterate (反復)

問題が見つかった場合:

1. コードを修正
2. インポートエラーを確認: af dags errors
3. 再検証（フェーズ 4）
4. testing-dags スキルワークフロー（フェーズ 5）を使用して再テスト

---

CLI クイックリファレンス

フェーズ	コマンド	目的
Discover	af config connections	利用可能なコネクション
Discover	af config variables	構成値
Discover	af config providers	インストールされているオペレータ
Discover	af config version	バージョン情報
Validate	af dags errors	パースエラー（最初に確認！）
Validate	af dags get <dag_id>	DAG 構成を確認
Validate	af dags warnings	構成警告
Validate	af dags explore <dag_id>	DAG 全体のインスペクション

テストコマンド -- af runs trigger-wait、af runs diagnose、af tasks logs などについては testing-dags スキルを参照してください。

---

ベストプラクティス と アンチパターン

コードパターンとアンチパターンについては、reference/best-practices.md を参照してください。

新しい DAG を書く場合または既存の DAG を確認する場合は、このリファレンスを読んでください。 正しいパターン（Airflow 3 固有の動作を含む）と避けるべきことをカバーしています。

---

関連スキル

• testing-dags: DAG のテスト、障害のデバッグ、およびテスト -> 修正 -> 再テストループ
• debugging-dags: 失敗した DAG のトラブルシューティング
• deploying-airflow: DAG の本番環境へのデプロイ（Astro またはオープンソース）
• migrating-airflow-2-to-3: DAG を Airflow 3 に移行する