Add AGENTS.md for dev/ and scripts/ci/prek/ (#64434)

* Add AGENTS.md guidelines for dev/ scripts

New scripts in dev/ should be standalone Python (not bash) with inline
script metadata so they can be run via `uv run`.

* Add AGENTS.md guidelines for dev/ and scripts/ci/prek/

Add coding guidelines for AI agents working in these directories:
- dev/AGENTS.md: new scripts must be standalone Python with inline
  script metadata (after the license header), run via `uv run`.
- scripts/ci/prek/AGENTS.md: use common_prek_utils.py helpers,
  breeze-dependent hooks go at the end of .pre-commit-config.yaml.

Author: potiuk

dev/AGENTS.md

@@ -0,0 +1,44 @@
+<!-- SPDX-License-Identifier: Apache-2.0
+      https://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [dev/ directory guidelines](#dev-directory-guidelines)
+  - [Scripts](#scripts)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# dev/ directory guidelines
+
+## Scripts
+
+New scripts in `dev/` must be standalone Python scripts (not bash). Each script must include
+[inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/)
+placed **after** the Apache License header, so that `uv run` can execute it without any prior
+installation:
+
+```python
+#!/usr/bin/env python3
+# Licensed to the Apache Software Foundation (ASF) ...
+#   http://www.apache.org/licenses/LICENSE-2.0
+# ...
+# /// script
+# requires-python = ">=3.9"
+# dependencies = [
+#     "some-package",
+# ]
+# ///
+```
+
+If the script only uses the standard library, omit the `dependencies` key but keep the
+`requires-python` line.
+
+Run scripts with:
+
+```shell
+uv run dev/my_script.py [args...]
+```
+
+Document `uv run` (not `python`) as the invocation method in READMEs and instructions.

scripts/ci/prek/AGENTS.md

@@ -0,0 +1,31 @@
+ <!-- SPDX-License-Identifier: Apache-2.0
+      https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# scripts/ci/prek/ guidelines
+
+## Overview
+
+This directory contains prek (pre-commit) hook scripts. Shared utilities live in
+`common_prek_utils.py` — always check there before duplicating logic.
+
+## Breeze CI image scripts
+
+Some prek scripts require the Breeze CI Docker image to run (e.g. mypy checks, OpenAPI spec
+generation, provider validation). These scripts use the `run_command_via_breeze_shell` helper
+from `common_prek_utils.py` to execute commands inside the container.
+
+When adding a new breeze-dependent hook:
+
+1. Import and use `run_command_via_breeze_shell` from `common_prek_utils` — do not shell out
+   to `breeze` directly.
+2. Register the hook at the **end** of the relevant `.pre-commit-config.yaml` file (breeze
+   hooks are slow and should run after fast, local checks).
+
+## Adding new hooks
+
+- Scripts must be Python (not bash).
+- Use helpers from `common_prek_utils.py` for path constants, console output, and breeze
+  execution.
+- Register the script in the appropriate `.pre-commit-config.yaml` (`/.pre-commit-config.yaml`
+  for repo-wide hooks, `/airflow-core/.pre-commit-config.yaml` for core-specific hooks, or a
+  provider-level config).