创建或扩展 Apache Airflow DAG 时…

需要新建、编写或扩展现有 Apache Airflow DAG 时，用 `af` CLI 先发现环境和代码库，再规划、实现、校验、测试并迭代。

适用场景

解决思路

1. 使用 `af` CLI 编写和验证 Airflow DAG；若尚未可用，通过 `astro otto` 自动获得，或用 `uv tool install astro-airflow-mcp` 独立安装。
2. 配置 Stop hook：运行 `echo 'Remember to test your DAG with the testing-dags skill'`，提醒使用 testing-dags 技能测试 DAG。
3. 按 6 阶段流程推进：DISCOVER -> PLAN -> IMPLEMENT -> VALIDATE -> TEST -> ITERATE；每阶段完成后进入下一阶段。
4. Phase 1 DISCOVER：写代码前先理解代码库与环境。
5. 用 Glob 查找 `**/dags/**/*.py` 定位现有 DAG。
6. 用 Read 阅读相似 DAG，理解项目约定。
7. 查看 `requirements.txt`，确认可用包。
8. 用 `af config connections` 查询已配置的外部系统。
9. 用 `af config variables` 查询已有配置值。
10. 用 `af config providers` 查询已安装的 operator 包。
11. 用 `af config version` 查询 Airflow 版本约束和可用特性。
12. 用 `af dags list` 查询现有 DAG 和命名约定。
13. 用 `af config pools` 查询用于并发控制的资源池。
14. 当要确认是否有 Snowflake 连接时，运行 `af config connections`。
15. 当要确认 Airflow 版本时，运行 `af config version`。
16. 当要确认是否有 S3 operators 时，运行 `af config providers`。
17. Phase 2 PLAN：基于发现结果提出方案。
18. 提出 DAG 结构：tasks、dependencies、schedule。
19. 根据可用 providers 提出要使用的 operators。
20. 列出需要的 connections，区分已有的和需要创建的。
21. 列出需要的 variables，区分已有的和需要创建的。
22. 列出需要的 packages，以及 `requirements.txt` 中要新增的内容。
23. 在实现前获得用户批准。
24. Phase 3 IMPLEMENT：按最佳实践编写 DAG。
25. 在合适位置创建 DAG 文件。
26. 如需要，更新 `requirements.txt`。
27. 保存文件。
28. Phase 4 VALIDATE：用 `af` CLI 作为反馈循环验证 DAG。
29. 保存后运行 `af dags errors` 检查解析错误，Airflow 已解析文件。
30. 如果 `af dags errors` 输出中出现你的文件，修复后重试。
31. 如果 `af dags errors` 无错误，继续下一步。
32. 常见错误原因：缺失 imports、语法错误、缺失 packages。
33. 运行 `af dags get <dag_id>` 验证 DAG 是否存在。
34. 检查 DAG 是否存在、schedule 是否正确、tags 是否设置、paused 状态。
35. 运行 `af dags warnings` 检查警告。
36. 关注 deprecation warnings 或配置问题。
37. 运行 `af dags explore <dag_id>` 探索 DAG 结构。
38. 该命令一次返回 metadata、tasks、dependencies、source code。
39. 如果运行在 Astro 上，可在部署前本地验证。
40. 在 Astro 上运行 `astro dev parse` 捕获 import errors 和 DAG 级问题，无需启动完整 Airflow 环境。
41. 在 Astro 上验证后，使用 `astro deploy --dags` 进行快速 DAG-only 部署，跳过 Docker image 构建，适合迭代 DAG 代码。
42. Phase 5 TEST：验证通过后，按 testing-dags 技能测试 DAG。
43. 触发前始终先获得用户同意。
44. 运行 `af runs trigger-wait <dag_id> --timeout 300` 触发并等待。
45. 分析运行结果，检查成功/失败状态。
46. 如需调试，运行 `af runs diagnose <dag_id> <run_id>`，并运行 `af tasks logs <dag_id> <run_id> <task_id>` 查看任务日志。
47. 快速测试最小流程：先询问用户，然后运行 `af runs trigger-wait <dag_id> --timeout 300`。
48. 完整 test -> debug -> fix -> retest 循环参考 testing-dags。
49. Phase 6 ITERATE：如果发现问题，修复代码。
50. 修复后运行 `af dags errors` 检查 import errors。
51. 重新执行 Phase 4 验证。
52. 按 testing-dags 工作流重新测试，即 Phase 5。
53. CLI Quick Reference：Discover 阶段使用 `af config connections`、`af config variables`、`af config providers`、`af config version`。
54. CLI Quick Reference：Validate 阶段使用 `af dags errors`、`af dags get <dag_id>`、`af dags warnings`、`af dags explore <dag_id>`。
55. 测试命令参考 testing-dags 技能，包括 `af runs trigger-wait`、`af runs diagnose`、`af tasks logs` 等。
56. 编写新 DAG 或审查现有 DAG 时，阅读 `reference/best-practices.md`。
57. 该参考覆盖正确模式，包括 Airflow 3 特定行为，以及应避免的反模式。
58. 相关技能：测试 DAG、调试失败和 test -> fix -> retest 循环使用 testing-dags。
59. 相关技能：排查失败 DAG 使用 debugging-dags。
60. 相关技能：将 DAG 部署到生产，Astro 或 open-source，使用 deploying-airflow。
61. 相关技能：将 DAG 迁移到 Airflow 3 使用 migrating-airflow-2-to-3。

适用边界 · 注意事项

• 不适用于测试、调试或排查失败 DAG；这些应改用 testing-dags 或 debugging-dags 技能。
• 环境未安装或未配置 Apache Airflow、`af` CLI，且无法使用 `astro otto` 或 `uv tool install astro-airflow-mcp` 时，不应直接按本技能验证或测试。
• 仅做 Airflow 2 到 3 迁移或生产部署时，使用 migrating-airflow-2-to-3 或 deploying-airflow，而不是本技能。