authoring-dags

DAG 作成スキル

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

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

---

CLI の実行

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

---

ワークフローの概要

+-----------------------------------------+
| 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              |
+-----------------------------------------+

---

フェーズ 1：調査

コードを書く前に、状況を把握してください。

コードベースを調べる

ファイルツールを使って既存のパターンを探します。

• **/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：計画

調査結果に基づいて、以下を提案します。

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

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

---

フェーズ 3：実装

ベストプラクティスに従って DAG を記述します（以下を参照）。主な手順は次のとおりです。

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

---

フェーズ 4：検証

af CLI をフィードバックループとして使用し、DAG を検証してください。

ステップ 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：テスト

テストに関する詳細なガイダンスは、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>

クイックテスト（最小構成）

# Ask user first, then:
af runs trigger-wait <dag_id> --timeout 300

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

---

フェーズ 6：反復

問題が見つかった場合：

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

---

CLI クイックリファレンス

フェーズ	コマンド	目的
検出	af config connections	利用可能な接続
検出	af config variables	設定値
検出	af config providers	インストール済みのオペレーター
検出	af config version	バージョン情報
検証	af dags errors	解析エラー（最初に確認してください！）
検証	af dags get <dag_id>	DAG 設定の検証
検証	af dags warnings	設定に関する警告
検証	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 への移行について