From 3bf1d2642f63ad2da05181cac20f3acebb2113c7 Mon Sep 17 00:00:00 2001 From: Lennart Kats Date: Fri, 12 Jun 2026 14:35:28 +0200 Subject: [PATCH 1/7] Add AGENTS.md and CLAUDE.md to bundle templates Generated DAB projects now include an AGENTS.md with project layout, the common bundle CLI workflow (validate/deploy/run/summary), and conventions, plus a CLAUDE.md that imports it via @AGENTS.md so Claude Code and tools using the AGENTS.md convention share one source of truth. Added to the default, default-sql, default-scala, and dbt-sql template bodies, which covers all built-in templates (default-python, default-minimal, lakeflow-pipelines, and pydabs share the default body). Co-authored-by: Isaac --- .../dbt-sql/output/my_dbt_sql/AGENTS.md | 39 ++++++++++++++++ .../dbt-sql/output/my_dbt_sql/CLAUDE.md | 6 +++ .../output/my_default_minimal/AGENTS.md | 34 ++++++++++++++ .../output/my_default_minimal/CLAUDE.md | 6 +++ .../output/my_default_python/AGENTS.md | 37 +++++++++++++++ .../output/my_default_python/CLAUDE.md | 6 +++ .../output/my_default_python/AGENTS.md | 37 +++++++++++++++ .../output/my_default_python/CLAUDE.md | 6 +++ .../output/my_default_scala/AGENTS.md | 35 +++++++++++++++ .../output/my_default_scala/CLAUDE.md | 6 +++ .../output/my_default_sql/AGENTS.md | 35 +++++++++++++++ .../output/my_default_sql/CLAUDE.md | 6 +++ .../output/my_lakeflow_pipelines/AGENTS.md | 34 ++++++++++++++ .../output/my_lakeflow_pipelines/CLAUDE.md | 6 +++ .../output/my_lakeflow_pipelines/AGENTS.md | 34 ++++++++++++++ .../output/my_lakeflow_pipelines/CLAUDE.md | 6 +++ .../template/{{.project_name}}/AGENTS.md.tmpl | 39 ++++++++++++++++ .../template/{{.project_name}}/CLAUDE.md.tmpl | 6 +++ .../template/{{.project_name}}/AGENTS.md.tmpl | 35 +++++++++++++++ .../template/{{.project_name}}/CLAUDE.md.tmpl | 6 +++ .../template/{{.project_name}}/AGENTS.md.tmpl | 35 +++++++++++++++ .../template/{{.project_name}}/CLAUDE.md.tmpl | 6 +++ .../template/{{.project_name}}/AGENTS.md.tmpl | 45 +++++++++++++++++++ .../template/{{.project_name}}/CLAUDE.md.tmpl | 6 +++ 24 files changed, 511 insertions(+) create mode 100644 acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md create mode 100644 acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/CLAUDE.md create mode 100644 acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md create mode 100644 acceptance/bundle/templates/default-minimal/output/my_default_minimal/CLAUDE.md create mode 100644 acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md create mode 100644 acceptance/bundle/templates/default-python/classic/output/my_default_python/CLAUDE.md create mode 100644 acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md create mode 100644 acceptance/bundle/templates/default-python/serverless/output/my_default_python/CLAUDE.md create mode 100644 acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md create mode 100644 acceptance/bundle/templates/default-scala/output/my_default_scala/CLAUDE.md create mode 100644 acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md create mode 100644 acceptance/bundle/templates/default-sql/output/my_default_sql/CLAUDE.md create mode 100644 acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md create mode 100644 acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/CLAUDE.md create mode 100644 acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md create mode 100644 acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/CLAUDE.md create mode 100644 libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl create mode 100644 libs/template/templates/dbt-sql/template/{{.project_name}}/CLAUDE.md.tmpl create mode 100644 libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl create mode 100644 libs/template/templates/default-scala/template/{{.project_name}}/CLAUDE.md.tmpl create mode 100644 libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl create mode 100644 libs/template/templates/default-sql/template/{{.project_name}}/CLAUDE.md.tmpl create mode 100644 libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl create mode 100644 libs/template/templates/default/template/{{.project_name}}/CLAUDE.md.tmpl diff --git a/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md new file mode 100644 index 00000000000..9bfb3f19c2a --- /dev/null +++ b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md @@ -0,0 +1,39 @@ +# AGENTS.md + +Guidance for AI coding agents working in the **my_dbt_sql** project. This +is a dbt project deployed with a Declarative Automation Bundle (DAB): the dbt +models run as a Databricks job defined as code in `databricks.yml` and +`resources/`. + +This file follows the cross-tool AGENTS.md convention and is also loaded by +Claude Code via CLAUDE.md. + +## Project layout + +- `databricks.yml` — the bundle definition: targets, variables, and `include`s. +- `resources/` — one file per resource (the job that runs dbt). +- `dbt_project.yml` — the dbt project configuration. +- `src/` — dbt models and other dbt sources. + +## Working with the bundle + +Use the Databricks CLI (the `databricks` skill has the current guidance): + +- `databricks bundle validate` — type-check the configuration. Run this after + every edit to `databricks.yml` or anything under `resources/`, and report the + exact CLI error if it fails. +- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is + the default target and deploys in development mode (paused schedules, resources + prefixed with your username). +- `databricks bundle run ` — run the job that executes the dbt models. +- `databricks bundle summary` — inspect the resolved configuration. + +Use `dbt` directly (e.g. `dbt run`, `dbt test`) for local model development; see +the project README for connection setup. + +## Conventions + +- Define each new resource as its own file under `resources/`; don't inline + resources into `databricks.yml`. +- Never deploy to the `prod` target unless explicitly asked. +- If a CLI command fails, report the exact error rather than guessing. diff --git a/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/CLAUDE.md b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/CLAUDE.md new file mode 100644 index 00000000000..6dc3692c2b7 --- /dev/null +++ b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Claude Code loads it via the import below. + +@AGENTS.md diff --git a/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md new file mode 100644 index 00000000000..517c97b2149 --- /dev/null +++ b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md @@ -0,0 +1,34 @@ +# AGENTS.md + +Guidance for AI coding agents working in the **my_default_minimal** project. This +is a Declarative Automation Bundle (DAB): Databricks resources defined as code in +`databricks.yml` and `resources/`, deployed with the Databricks CLI. + +This file follows the cross-tool AGENTS.md convention and is also loaded by +Claude Code via CLAUDE.md. + +## Project layout + +- `databricks.yml` — the bundle definition: targets, variables, and `include`s. +- `resources/` — one file per resource (jobs, pipelines, ...). +- `src/` — SQL source for the jobs and pipelines. + +## Working with the bundle + +Use the Databricks CLI (the `databricks` skill has the current guidance): + +- `databricks bundle validate` — type-check the configuration. Run this after + every edit to `databricks.yml` or anything under `resources/`, and report the + exact CLI error if it fails. +- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is + the default target and deploys in development mode (paused schedules, resources + prefixed with your username). +- `databricks bundle run ` — run a job or pipeline. +- `databricks bundle summary` — inspect the resolved configuration. + +## Conventions + +- Define each new resource as its own file under `resources/`; don't inline + resources into `databricks.yml`. +- Never deploy to the `prod` target unless explicitly asked. +- If a CLI command fails, report the exact error rather than guessing. diff --git a/acceptance/bundle/templates/default-minimal/output/my_default_minimal/CLAUDE.md b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/CLAUDE.md new file mode 100644 index 00000000000..6dc3692c2b7 --- /dev/null +++ b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Claude Code loads it via the import below. + +@AGENTS.md diff --git a/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md b/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md new file mode 100644 index 00000000000..5c3d7dc16cb --- /dev/null +++ b/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md @@ -0,0 +1,37 @@ +# AGENTS.md + +Guidance for AI coding agents working in the **my_default_python** project. This +is a Declarative Automation Bundle (DAB): Databricks resources defined as code in +`databricks.yml` and `resources/`, deployed with the Databricks CLI. + +This file follows the cross-tool AGENTS.md convention and is also loaded by +Claude Code via CLAUDE.md. + +## Project layout + +- `databricks.yml` — the bundle definition: targets, variables, and `include`s. +- `resources/` — one file per resource (jobs, pipelines, ...). +- `src/` — Python source for the jobs and pipelines. + - `src/my_default_python/` — shared Python code used by jobs and pipelines. +- `tests/`, `fixtures/` — unit tests and test data. + +## Working with the bundle + +Use the Databricks CLI (the `databricks` skill has the current guidance): + +- `databricks bundle validate` — type-check the configuration. Run this after + every edit to `databricks.yml` or anything under `resources/`, and report the + exact CLI error if it fails. +- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is + the default target and deploys in development mode (paused schedules, resources + prefixed with your username). +- `databricks bundle run ` — run a job or pipeline. +- `databricks bundle summary` — inspect the resolved configuration. +- `uv run pytest` — run the unit tests after changing Python under `src/`. + +## Conventions + +- Define each new resource as its own file under `resources/`; don't inline + resources into `databricks.yml`. +- Never deploy to the `prod` target unless explicitly asked. +- If a CLI command fails, report the exact error rather than guessing. diff --git a/acceptance/bundle/templates/default-python/classic/output/my_default_python/CLAUDE.md b/acceptance/bundle/templates/default-python/classic/output/my_default_python/CLAUDE.md new file mode 100644 index 00000000000..6dc3692c2b7 --- /dev/null +++ b/acceptance/bundle/templates/default-python/classic/output/my_default_python/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Claude Code loads it via the import below. + +@AGENTS.md diff --git a/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md new file mode 100644 index 00000000000..5c3d7dc16cb --- /dev/null +++ b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md @@ -0,0 +1,37 @@ +# AGENTS.md + +Guidance for AI coding agents working in the **my_default_python** project. This +is a Declarative Automation Bundle (DAB): Databricks resources defined as code in +`databricks.yml` and `resources/`, deployed with the Databricks CLI. + +This file follows the cross-tool AGENTS.md convention and is also loaded by +Claude Code via CLAUDE.md. + +## Project layout + +- `databricks.yml` — the bundle definition: targets, variables, and `include`s. +- `resources/` — one file per resource (jobs, pipelines, ...). +- `src/` — Python source for the jobs and pipelines. + - `src/my_default_python/` — shared Python code used by jobs and pipelines. +- `tests/`, `fixtures/` — unit tests and test data. + +## Working with the bundle + +Use the Databricks CLI (the `databricks` skill has the current guidance): + +- `databricks bundle validate` — type-check the configuration. Run this after + every edit to `databricks.yml` or anything under `resources/`, and report the + exact CLI error if it fails. +- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is + the default target and deploys in development mode (paused schedules, resources + prefixed with your username). +- `databricks bundle run ` — run a job or pipeline. +- `databricks bundle summary` — inspect the resolved configuration. +- `uv run pytest` — run the unit tests after changing Python under `src/`. + +## Conventions + +- Define each new resource as its own file under `resources/`; don't inline + resources into `databricks.yml`. +- Never deploy to the `prod` target unless explicitly asked. +- If a CLI command fails, report the exact error rather than guessing. diff --git a/acceptance/bundle/templates/default-python/serverless/output/my_default_python/CLAUDE.md b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/CLAUDE.md new file mode 100644 index 00000000000..6dc3692c2b7 --- /dev/null +++ b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Claude Code loads it via the import below. + +@AGENTS.md diff --git a/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md b/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md new file mode 100644 index 00000000000..ca0af37e76a --- /dev/null +++ b/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md @@ -0,0 +1,35 @@ +# AGENTS.md + +Guidance for AI coding agents working in the **my_default_scala** project. This +is a Declarative Automation Bundle (DAB): Databricks resources defined as code in +`databricks.yml` and `resources/`, deployed with the Databricks CLI. + +This file follows the cross-tool AGENTS.md convention and is also loaded by +Claude Code via CLAUDE.md. + +## Project layout + +- `databricks.yml` — the bundle definition: targets, variables, and `include`s. +- `resources/` — one file per resource (jobs, pipelines, ...). +- `build.sbt`, `project/` — the sbt build for the Scala sources; `sbt package` + produces the JAR that the jobs run. + +## Working with the bundle + +Use the Databricks CLI (the `databricks` skill has the current guidance): + +- `databricks bundle validate` — type-check the configuration. Run this after + every edit to `databricks.yml` or anything under `resources/`, and report the + exact CLI error if it fails. +- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is + the default target and deploys in development mode (paused schedules, resources + prefixed with your username). +- `databricks bundle run ` — run a job. +- `databricks bundle summary` — inspect the resolved configuration. + +## Conventions + +- Define each new resource as its own file under `resources/`; don't inline + resources into `databricks.yml`. +- Never deploy to the `prod` target unless explicitly asked. +- If a CLI command fails, report the exact error rather than guessing. diff --git a/acceptance/bundle/templates/default-scala/output/my_default_scala/CLAUDE.md b/acceptance/bundle/templates/default-scala/output/my_default_scala/CLAUDE.md new file mode 100644 index 00000000000..6dc3692c2b7 --- /dev/null +++ b/acceptance/bundle/templates/default-scala/output/my_default_scala/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Claude Code loads it via the import below. + +@AGENTS.md diff --git a/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md b/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md new file mode 100644 index 00000000000..01dcb0b6471 --- /dev/null +++ b/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md @@ -0,0 +1,35 @@ +# AGENTS.md + +Guidance for AI coding agents working in the **my_default_sql** project. This +is a Declarative Automation Bundle (DAB): Databricks resources defined as code in +`databricks.yml` and `resources/`, deployed with the Databricks CLI. + +This file follows the cross-tool AGENTS.md convention and is also loaded by +Claude Code via CLAUDE.md. + +## Project layout + +- `databricks.yml` — the bundle definition: targets, variables, and `include`s. +- `resources/` — one file per resource (jobs, pipelines, ...). +- `src/` — SQL source for the jobs. +- `scratch/` — a place for exploratory notebooks; not deployed by default. + +## Working with the bundle + +Use the Databricks CLI (the `databricks` skill has the current guidance): + +- `databricks bundle validate` — type-check the configuration. Run this after + every edit to `databricks.yml` or anything under `resources/`, and report the + exact CLI error if it fails. +- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is + the default target and deploys in development mode (paused schedules, resources + prefixed with your username). +- `databricks bundle run ` — run a job. +- `databricks bundle summary` — inspect the resolved configuration. + +## Conventions + +- Define each new resource as its own file under `resources/`; don't inline + resources into `databricks.yml`. +- Never deploy to the `prod` target unless explicitly asked. +- If a CLI command fails, report the exact error rather than guessing. diff --git a/acceptance/bundle/templates/default-sql/output/my_default_sql/CLAUDE.md b/acceptance/bundle/templates/default-sql/output/my_default_sql/CLAUDE.md new file mode 100644 index 00000000000..6dc3692c2b7 --- /dev/null +++ b/acceptance/bundle/templates/default-sql/output/my_default_sql/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Claude Code loads it via the import below. + +@AGENTS.md diff --git a/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md new file mode 100644 index 00000000000..8fd9a8061a2 --- /dev/null +++ b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md @@ -0,0 +1,34 @@ +# AGENTS.md + +Guidance for AI coding agents working in the **my_lakeflow_pipelines** project. This +is a Declarative Automation Bundle (DAB): Databricks resources defined as code in +`databricks.yml` and `resources/`, deployed with the Databricks CLI. + +This file follows the cross-tool AGENTS.md convention and is also loaded by +Claude Code via CLAUDE.md. + +## Project layout + +- `databricks.yml` — the bundle definition: targets, variables, and `include`s. +- `resources/` — one file per resource (jobs, pipelines, ...). +- `src/` — Python source for the jobs and pipelines. + +## Working with the bundle + +Use the Databricks CLI (the `databricks` skill has the current guidance): + +- `databricks bundle validate` — type-check the configuration. Run this after + every edit to `databricks.yml` or anything under `resources/`, and report the + exact CLI error if it fails. +- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is + the default target and deploys in development mode (paused schedules, resources + prefixed with your username). +- `databricks bundle run ` — run a job or pipeline. +- `databricks bundle summary` — inspect the resolved configuration. + +## Conventions + +- Define each new resource as its own file under `resources/`; don't inline + resources into `databricks.yml`. +- Never deploy to the `prod` target unless explicitly asked. +- If a CLI command fails, report the exact error rather than guessing. diff --git a/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/CLAUDE.md b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/CLAUDE.md new file mode 100644 index 00000000000..6dc3692c2b7 --- /dev/null +++ b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Claude Code loads it via the import below. + +@AGENTS.md diff --git a/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md new file mode 100644 index 00000000000..e8b0d55fc5d --- /dev/null +++ b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md @@ -0,0 +1,34 @@ +# AGENTS.md + +Guidance for AI coding agents working in the **my_lakeflow_pipelines** project. This +is a Declarative Automation Bundle (DAB): Databricks resources defined as code in +`databricks.yml` and `resources/`, deployed with the Databricks CLI. + +This file follows the cross-tool AGENTS.md convention and is also loaded by +Claude Code via CLAUDE.md. + +## Project layout + +- `databricks.yml` — the bundle definition: targets, variables, and `include`s. +- `resources/` — one file per resource (jobs, pipelines, ...). +- `src/` — SQL source for the jobs and pipelines. + +## Working with the bundle + +Use the Databricks CLI (the `databricks` skill has the current guidance): + +- `databricks bundle validate` — type-check the configuration. Run this after + every edit to `databricks.yml` or anything under `resources/`, and report the + exact CLI error if it fails. +- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is + the default target and deploys in development mode (paused schedules, resources + prefixed with your username). +- `databricks bundle run ` — run a job or pipeline. +- `databricks bundle summary` — inspect the resolved configuration. + +## Conventions + +- Define each new resource as its own file under `resources/`; don't inline + resources into `databricks.yml`. +- Never deploy to the `prod` target unless explicitly asked. +- If a CLI command fails, report the exact error rather than guessing. diff --git a/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/CLAUDE.md b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/CLAUDE.md new file mode 100644 index 00000000000..6dc3692c2b7 --- /dev/null +++ b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Claude Code loads it via the import below. + +@AGENTS.md diff --git a/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl new file mode 100644 index 00000000000..8fe609f5fd6 --- /dev/null +++ b/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl @@ -0,0 +1,39 @@ +# AGENTS.md + +Guidance for AI coding agents working in the **{{.project_name}}** project. This +is a dbt project deployed with a Declarative Automation Bundle (DAB): the dbt +models run as a Databricks job defined as code in `databricks.yml` and +`resources/`. + +This file follows the cross-tool AGENTS.md convention and is also loaded by +Claude Code via CLAUDE.md. + +## Project layout + +- `databricks.yml` — the bundle definition: targets, variables, and `include`s. +- `resources/` — one file per resource (the job that runs dbt). +- `dbt_project.yml` — the dbt project configuration. +- `src/` — dbt models and other dbt sources. + +## Working with the bundle + +Use the Databricks CLI (the `databricks` skill has the current guidance): + +- `databricks bundle validate` — type-check the configuration. Run this after + every edit to `databricks.yml` or anything under `resources/`, and report the + exact CLI error if it fails. +- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is + the default target and deploys in development mode (paused schedules, resources + prefixed with your username). +- `databricks bundle run ` — run the job that executes the dbt models. +- `databricks bundle summary` — inspect the resolved configuration. + +Use `dbt` directly (e.g. `dbt run`, `dbt test`) for local model development; see +the project README for connection setup. + +## Conventions + +- Define each new resource as its own file under `resources/`; don't inline + resources into `databricks.yml`. +- Never deploy to the `prod` target unless explicitly asked. +- If a CLI command fails, report the exact error rather than guessing. diff --git a/libs/template/templates/dbt-sql/template/{{.project_name}}/CLAUDE.md.tmpl b/libs/template/templates/dbt-sql/template/{{.project_name}}/CLAUDE.md.tmpl new file mode 100644 index 00000000000..6dc3692c2b7 --- /dev/null +++ b/libs/template/templates/dbt-sql/template/{{.project_name}}/CLAUDE.md.tmpl @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Claude Code loads it via the import below. + +@AGENTS.md diff --git a/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl new file mode 100644 index 00000000000..768f505ef02 --- /dev/null +++ b/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl @@ -0,0 +1,35 @@ +# AGENTS.md + +Guidance for AI coding agents working in the **{{.project_name}}** project. This +is a Declarative Automation Bundle (DAB): Databricks resources defined as code in +`databricks.yml` and `resources/`, deployed with the Databricks CLI. + +This file follows the cross-tool AGENTS.md convention and is also loaded by +Claude Code via CLAUDE.md. + +## Project layout + +- `databricks.yml` — the bundle definition: targets, variables, and `include`s. +- `resources/` — one file per resource (jobs, pipelines, ...). +- `build.sbt`, `project/` — the sbt build for the Scala sources; `sbt package` + produces the JAR that the jobs run. + +## Working with the bundle + +Use the Databricks CLI (the `databricks` skill has the current guidance): + +- `databricks bundle validate` — type-check the configuration. Run this after + every edit to `databricks.yml` or anything under `resources/`, and report the + exact CLI error if it fails. +- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is + the default target and deploys in development mode (paused schedules, resources + prefixed with your username). +- `databricks bundle run ` — run a job. +- `databricks bundle summary` — inspect the resolved configuration. + +## Conventions + +- Define each new resource as its own file under `resources/`; don't inline + resources into `databricks.yml`. +- Never deploy to the `prod` target unless explicitly asked. +- If a CLI command fails, report the exact error rather than guessing. diff --git a/libs/template/templates/default-scala/template/{{.project_name}}/CLAUDE.md.tmpl b/libs/template/templates/default-scala/template/{{.project_name}}/CLAUDE.md.tmpl new file mode 100644 index 00000000000..6dc3692c2b7 --- /dev/null +++ b/libs/template/templates/default-scala/template/{{.project_name}}/CLAUDE.md.tmpl @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Claude Code loads it via the import below. + +@AGENTS.md diff --git a/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl new file mode 100644 index 00000000000..034c9a0971a --- /dev/null +++ b/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl @@ -0,0 +1,35 @@ +# AGENTS.md + +Guidance for AI coding agents working in the **{{.project_name}}** project. This +is a Declarative Automation Bundle (DAB): Databricks resources defined as code in +`databricks.yml` and `resources/`, deployed with the Databricks CLI. + +This file follows the cross-tool AGENTS.md convention and is also loaded by +Claude Code via CLAUDE.md. + +## Project layout + +- `databricks.yml` — the bundle definition: targets, variables, and `include`s. +- `resources/` — one file per resource (jobs, pipelines, ...). +- `src/` — SQL source for the jobs. +- `scratch/` — a place for exploratory notebooks; not deployed by default. + +## Working with the bundle + +Use the Databricks CLI (the `databricks` skill has the current guidance): + +- `databricks bundle validate` — type-check the configuration. Run this after + every edit to `databricks.yml` or anything under `resources/`, and report the + exact CLI error if it fails. +- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is + the default target and deploys in development mode (paused schedules, resources + prefixed with your username). +- `databricks bundle run ` — run a job. +- `databricks bundle summary` — inspect the resolved configuration. + +## Conventions + +- Define each new resource as its own file under `resources/`; don't inline + resources into `databricks.yml`. +- Never deploy to the `prod` target unless explicitly asked. +- If a CLI command fails, report the exact error rather than guessing. diff --git a/libs/template/templates/default-sql/template/{{.project_name}}/CLAUDE.md.tmpl b/libs/template/templates/default-sql/template/{{.project_name}}/CLAUDE.md.tmpl new file mode 100644 index 00000000000..6dc3692c2b7 --- /dev/null +++ b/libs/template/templates/default-sql/template/{{.project_name}}/CLAUDE.md.tmpl @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Claude Code loads it via the import below. + +@AGENTS.md diff --git a/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl new file mode 100644 index 00000000000..b9030f37ca3 --- /dev/null +++ b/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl @@ -0,0 +1,45 @@ +# AGENTS.md +{{- $skip_tests := or (eq .language "sql") (eq .lakeflow_only "yes")}} +{{- $has_python_package_dir := and (or (eq .include_python "yes") (eq .include_job "yes") (eq .include_pipeline "yes")) (not (eq .lakeflow_only "yes"))}} + +Guidance for AI coding agents working in the **{{.project_name}}** project. This +is a Declarative Automation Bundle (DAB): Databricks resources defined as code in +`databricks.yml` and `resources/`, deployed with the Databricks CLI. + +This file follows the cross-tool AGENTS.md convention and is also loaded by +Claude Code via CLAUDE.md. + +## Project layout + +- `databricks.yml` — the bundle definition: targets, variables, and `include`s. +- `resources/` — one file per resource (jobs, pipelines, ...). +- `src/` — {{if eq .language "sql"}}SQL{{else}}Python{{end}} source for the jobs and pipelines. +{{- if $has_python_package_dir}} + - `src/{{.project_name}}/` — shared Python code used by jobs and pipelines. +{{- end}} +{{- if not $skip_tests}} +- `tests/`, `fixtures/` — unit tests and test data. +{{- end}} + +## Working with the bundle + +Use the Databricks CLI (the `databricks` skill has the current guidance): + +- `databricks bundle validate` — type-check the configuration. Run this after + every edit to `databricks.yml` or anything under `resources/`, and report the + exact CLI error if it fails. +- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is + the default target and deploys in development mode (paused schedules, resources + prefixed with your username). +- `databricks bundle run ` — run a job or pipeline. +- `databricks bundle summary` — inspect the resolved configuration. +{{- if not $skip_tests}} +- `uv run pytest` — run the unit tests after changing Python under `src/`. +{{- end}} + +## Conventions + +- Define each new resource as its own file under `resources/`; don't inline + resources into `databricks.yml`. +- Never deploy to the `prod` target unless explicitly asked. +- If a CLI command fails, report the exact error rather than guessing. diff --git a/libs/template/templates/default/template/{{.project_name}}/CLAUDE.md.tmpl b/libs/template/templates/default/template/{{.project_name}}/CLAUDE.md.tmpl new file mode 100644 index 00000000000..6dc3692c2b7 --- /dev/null +++ b/libs/template/templates/default/template/{{.project_name}}/CLAUDE.md.tmpl @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Claude Code loads it via the import below. + +@AGENTS.md From 07855865b036d52b2d3a33fda07ad7bc9c5a87d1 Mon Sep 17 00:00:00 2001 From: Lennart Kats Date: Fri, 12 Jun 2026 14:35:28 +0200 Subject: [PATCH 2/7] Rename Databricks Asset Bundles to Declarative Automation Bundles in templates Update the remaining template files that referred to the product by its former name: the databricks.yml header comments (default, default-sql, default-scala bodies), the dbt_project.yml comment, and the default-minimal welcome message. Co-authored-by: Isaac --- .../bundle/templates/dbt-sql/output/my_dbt_sql/dbt_project.yml | 2 +- acceptance/bundle/templates/default-minimal/output.txt | 2 +- .../default-minimal/output/my_default_minimal/databricks.yml | 2 +- .../classic/output/my_default_python/databricks.yml | 2 +- .../serverless/output/my_default_python/databricks.yml | 2 +- .../default-scala/output/my_default_scala/databricks.yml | 2 +- .../templates/default-sql/output/my_default_sql/databricks.yml | 2 +- .../python/output/my_lakeflow_pipelines/databricks.yml | 2 +- .../sql/output/my_lakeflow_pipelines/databricks.yml | 2 +- .../pydabs/init-classic/output/my_pydabs/databricks.yml | 2 +- .../templates/telemetry/default-python/out.databricks.yml | 2 +- .../bundle/templates/telemetry/default-sql/out.databricks.yml | 2 +- .../dbt-sql/template/{{.project_name}}/dbt_project.yml.tmpl | 2 +- .../templates/default-minimal/databricks_template_schema.json | 2 +- .../template/{{.project_name}}/databricks.yml.tmpl | 2 +- .../default-sql/template/{{.project_name}}/databricks.yml.tmpl | 2 +- .../default/template/{{.project_name}}/databricks.yml.tmpl | 2 +- 17 files changed, 17 insertions(+), 17 deletions(-) diff --git a/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/dbt_project.yml b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/dbt_project.yml index 74044e47b74..4a472241985 100644 --- a/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/dbt_project.yml +++ b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/dbt_project.yml @@ -6,7 +6,7 @@ config-version: 2 profile: 'my_dbt_sql' # These configurations specify where dbt should look for different types of files. -# For Databricks asset bundles, we put everything in src, as you may have +# For Declarative Automation Bundles, we put everything in src, as you may have # non-dbt resources in your project. model-paths: ["src/models"] analysis-paths: ["src/analyses"] diff --git a/acceptance/bundle/templates/default-minimal/output.txt b/acceptance/bundle/templates/default-minimal/output.txt index 5d0538b0382..2b4d56eaf77 100644 --- a/acceptance/bundle/templates/default-minimal/output.txt +++ b/acceptance/bundle/templates/default-minimal/output.txt @@ -1,6 +1,6 @@ >>> [CLI] bundle init default-minimal --config-file ./input.json --output-dir output -Welcome to the minimal Databricks Asset Bundle template! +Welcome to the minimal Declarative Automation Bundles template! This template creates a minimal project structure without sample code, ideal for advanced users. (For getting started with Python or SQL code, use the default-python or default-sql templates instead.) diff --git a/acceptance/bundle/templates/default-minimal/output/my_default_minimal/databricks.yml b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/databricks.yml index c10c7416920..c829ab7d25f 100644 --- a/acceptance/bundle/templates/default-minimal/output/my_default_minimal/databricks.yml +++ b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/databricks.yml @@ -1,4 +1,4 @@ -# This is a Databricks asset bundle definition for my_default_minimal. +# This is a Declarative Automation Bundles definition for my_default_minimal. # See https://docs.databricks.com/dev-tools/bundles/index.html for documentation. bundle: name: my_default_minimal diff --git a/acceptance/bundle/templates/default-python/classic/output/my_default_python/databricks.yml b/acceptance/bundle/templates/default-python/classic/output/my_default_python/databricks.yml index fe79065310e..0d5ba92e390 100644 --- a/acceptance/bundle/templates/default-python/classic/output/my_default_python/databricks.yml +++ b/acceptance/bundle/templates/default-python/classic/output/my_default_python/databricks.yml @@ -1,4 +1,4 @@ -# This is a Databricks asset bundle definition for my_default_python. +# This is a Declarative Automation Bundles definition for my_default_python. # See https://docs.databricks.com/dev-tools/bundles/index.html for documentation. bundle: name: my_default_python diff --git a/acceptance/bundle/templates/default-python/serverless/output/my_default_python/databricks.yml b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/databricks.yml index 2683348b94f..a9e370c66dc 100644 --- a/acceptance/bundle/templates/default-python/serverless/output/my_default_python/databricks.yml +++ b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/databricks.yml @@ -1,4 +1,4 @@ -# This is a Databricks asset bundle definition for my_default_python. +# This is a Declarative Automation Bundles definition for my_default_python. # See https://docs.databricks.com/dev-tools/bundles/index.html for documentation. bundle: name: my_default_python diff --git a/acceptance/bundle/templates/default-scala/output/my_default_scala/databricks.yml b/acceptance/bundle/templates/default-scala/output/my_default_scala/databricks.yml index fa88835b65a..0cd8c293ed9 100644 --- a/acceptance/bundle/templates/default-scala/output/my_default_scala/databricks.yml +++ b/acceptance/bundle/templates/default-scala/output/my_default_scala/databricks.yml @@ -1,4 +1,4 @@ -# This is a Databricks asset bundle definition for my_default_scala. +# This is a Declarative Automation Bundles definition for my_default_scala. # See https://docs.databricks.com/dev-tools/bundles/index.html for documentation. bundle: name: my_default_scala diff --git a/acceptance/bundle/templates/default-sql/output/my_default_sql/databricks.yml b/acceptance/bundle/templates/default-sql/output/my_default_sql/databricks.yml index 07562ce7ad1..018d582be3e 100644 --- a/acceptance/bundle/templates/default-sql/output/my_default_sql/databricks.yml +++ b/acceptance/bundle/templates/default-sql/output/my_default_sql/databricks.yml @@ -1,4 +1,4 @@ -# This is a Databricks asset bundle definition for my_default_sql. +# This is a Declarative Automation Bundles definition for my_default_sql. # See https://docs.databricks.com/dev-tools/bundles/index.html for documentation. bundle: name: my_default_sql diff --git a/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/databricks.yml b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/databricks.yml index 9df14beed6c..8d0715c60ef 100644 --- a/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/databricks.yml +++ b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/databricks.yml @@ -1,4 +1,4 @@ -# This is a Databricks asset bundle definition for my_lakeflow_pipelines. +# This is a Declarative Automation Bundles definition for my_lakeflow_pipelines. # See https://docs.databricks.com/dev-tools/bundles/index.html for documentation. bundle: name: my_lakeflow_pipelines diff --git a/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/databricks.yml b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/databricks.yml index 9df14beed6c..8d0715c60ef 100644 --- a/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/databricks.yml +++ b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/databricks.yml @@ -1,4 +1,4 @@ -# This is a Databricks asset bundle definition for my_lakeflow_pipelines. +# This is a Declarative Automation Bundles definition for my_lakeflow_pipelines. # See https://docs.databricks.com/dev-tools/bundles/index.html for documentation. bundle: name: my_lakeflow_pipelines diff --git a/acceptance/bundle/templates/pydabs/init-classic/output/my_pydabs/databricks.yml b/acceptance/bundle/templates/pydabs/init-classic/output/my_pydabs/databricks.yml index 8bb7b985107..2a794ba9719 100644 --- a/acceptance/bundle/templates/pydabs/init-classic/output/my_pydabs/databricks.yml +++ b/acceptance/bundle/templates/pydabs/init-classic/output/my_pydabs/databricks.yml @@ -1,4 +1,4 @@ -# This is a Databricks asset bundle definition for my_pydabs. +# This is a Declarative Automation Bundles definition for my_pydabs. # See https://docs.databricks.com/dev-tools/bundles/index.html for documentation. bundle: name: my_pydabs diff --git a/acceptance/bundle/templates/telemetry/default-python/out.databricks.yml b/acceptance/bundle/templates/telemetry/default-python/out.databricks.yml index 2e00b00b9e4..8371742b307 100644 --- a/acceptance/bundle/templates/telemetry/default-python/out.databricks.yml +++ b/acceptance/bundle/templates/telemetry/default-python/out.databricks.yml @@ -1,4 +1,4 @@ -# This is a Databricks asset bundle definition for my_default_python. +# This is a Declarative Automation Bundles definition for my_default_python. # See https://docs.databricks.com/dev-tools/bundles/index.html for documentation. bundle: name: my_default_python diff --git a/acceptance/bundle/templates/telemetry/default-sql/out.databricks.yml b/acceptance/bundle/templates/telemetry/default-sql/out.databricks.yml index 49704391ea6..881672205b7 100644 --- a/acceptance/bundle/templates/telemetry/default-sql/out.databricks.yml +++ b/acceptance/bundle/templates/telemetry/default-sql/out.databricks.yml @@ -1,4 +1,4 @@ -# This is a Databricks asset bundle definition for my_default_sql. +# This is a Declarative Automation Bundles definition for my_default_sql. # See https://docs.databricks.com/dev-tools/bundles/index.html for documentation. bundle: name: my_default_sql diff --git a/libs/template/templates/dbt-sql/template/{{.project_name}}/dbt_project.yml.tmpl b/libs/template/templates/dbt-sql/template/{{.project_name}}/dbt_project.yml.tmpl index 91fb1be1b53..4d6fdbdcb92 100644 --- a/libs/template/templates/dbt-sql/template/{{.project_name}}/dbt_project.yml.tmpl +++ b/libs/template/templates/dbt-sql/template/{{.project_name}}/dbt_project.yml.tmpl @@ -6,7 +6,7 @@ config-version: 2 profile: '{{.project_name}}' # These configurations specify where dbt should look for different types of files. -# For Databricks asset bundles, we put everything in src, as you may have +# For Declarative Automation Bundles, we put everything in src, as you may have # non-dbt resources in your project. model-paths: ["src/models"] analysis-paths: ["src/analyses"] diff --git a/libs/template/templates/default-minimal/databricks_template_schema.json b/libs/template/templates/default-minimal/databricks_template_schema.json index c6f5badc23a..5f4aa082943 100644 --- a/libs/template/templates/default-minimal/databricks_template_schema.json +++ b/libs/template/templates/default-minimal/databricks_template_schema.json @@ -1,6 +1,6 @@ { "template_dir": "../default", - "welcome_message": "Welcome to the minimal Databricks Asset Bundle template!\n\nThis template creates a minimal project structure without sample code, ideal for advanced users.\n(For getting started with Python or SQL code, use the default-python or default-sql templates instead.)\n\nYour workspace at {{workspace_host}} is used for initialization.\n(See https://docs.databricks.com/dev-tools/cli/profiles.html for how to change your profile.)", + "welcome_message": "Welcome to the minimal Declarative Automation Bundles template!\n\nThis template creates a minimal project structure without sample code, ideal for advanced users.\n(For getting started with Python or SQL code, use the default-python or default-sql templates instead.)\n\nYour workspace at {{workspace_host}} is used for initialization.\n(See https://docs.databricks.com/dev-tools/cli/profiles.html for how to change your profile.)", "properties": { "template_name": { "//": "This property is always set to 'default-minimal'", diff --git a/libs/template/templates/default-scala/template/{{.project_name}}/databricks.yml.tmpl b/libs/template/templates/default-scala/template/{{.project_name}}/databricks.yml.tmpl index bfd50a1052d..18fb5f4db45 100644 --- a/libs/template/templates/default-scala/template/{{.project_name}}/databricks.yml.tmpl +++ b/libs/template/templates/default-scala/template/{{.project_name}}/databricks.yml.tmpl @@ -1,4 +1,4 @@ -# This is a Databricks asset bundle definition for {{.project_name}}. +# This is a Declarative Automation Bundles definition for {{.project_name}}. # See https://docs.databricks.com/dev-tools/bundles/index.html for documentation. bundle: name: {{.project_name}} diff --git a/libs/template/templates/default-sql/template/{{.project_name}}/databricks.yml.tmpl b/libs/template/templates/default-sql/template/{{.project_name}}/databricks.yml.tmpl index 6acdf40e78e..16ffa0c5377 100644 --- a/libs/template/templates/default-sql/template/{{.project_name}}/databricks.yml.tmpl +++ b/libs/template/templates/default-sql/template/{{.project_name}}/databricks.yml.tmpl @@ -1,4 +1,4 @@ -# This is a Databricks asset bundle definition for {{.project_name}}. +# This is a Declarative Automation Bundles definition for {{.project_name}}. # See https://docs.databricks.com/dev-tools/bundles/index.html for documentation. bundle: name: {{.project_name}} diff --git a/libs/template/templates/default/template/{{.project_name}}/databricks.yml.tmpl b/libs/template/templates/default/template/{{.project_name}}/databricks.yml.tmpl index 5849ae7a39a..af17977fc94 100644 --- a/libs/template/templates/default/template/{{.project_name}}/databricks.yml.tmpl +++ b/libs/template/templates/default/template/{{.project_name}}/databricks.yml.tmpl @@ -1,7 +1,7 @@ {{$with_classic := (ne .serverless "yes") -}} {{$with_python := (eq .include_python "yes") -}} {{$with_pydabs := (eq .enable_pydabs "yes") -}} -# This is a Databricks asset bundle definition for {{.project_name}}. +# This is a Declarative Automation Bundles definition for {{.project_name}}. # See https://docs.databricks.com/dev-tools/bundles/index.html for documentation. bundle: name: {{.project_name}} From d855f4ee917ff049bd9aec3ae77413df8aabd1eb Mon Sep 17 00:00:00 2001 From: Lennart Kats Date: Fri, 12 Jun 2026 16:41:07 +0200 Subject: [PATCH 3/7] Shorten template AGENTS.md to point at the databricks skill Replace the verbose per-template AGENTS.md with the short version originally used in experimental/aitools (removed in c8d825c66): point agents at the databricks skill, explain how to install agent skills (databricks aitools install), and leave a placeholder for project-specific instructions. Inlining all instructions is a non-goal. Co-authored-by: Isaac --- .../dbt-sql/output/my_dbt_sql/AGENTS.md | 47 +++++------ .../output/my_default_minimal/AGENTS.md | 44 +++++----- .../output/my_default_python/AGENTS.md | 47 +++++------ .../output/my_default_python/AGENTS.md | 47 +++++------ .../output/my_default_scala/AGENTS.md | 45 +++++------ .../output/my_default_sql/AGENTS.md | 45 +++++------ .../output/my_lakeflow_pipelines/AGENTS.md | 44 +++++----- .../output/my_lakeflow_pipelines/AGENTS.md | 44 +++++----- .../template/{{.project_name}}/AGENTS.md.tmpl | 55 ++++++------- .../template/{{.project_name}}/AGENTS.md.tmpl | 53 ++++++------ .../template/{{.project_name}}/AGENTS.md.tmpl | 53 ++++++------ .../template/{{.project_name}}/AGENTS.md.tmpl | 81 +++++++++---------- 12 files changed, 267 insertions(+), 338 deletions(-) diff --git a/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md index 9bfb3f19c2a..1188efc0f66 100644 --- a/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md +++ b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md @@ -1,39 +1,28 @@ -# AGENTS.md +# Declarative Automation Bundles Project -Guidance for AI coding agents working in the **my_dbt_sql** project. This -is a dbt project deployed with a Declarative Automation Bundle (DAB): the dbt -models run as a Databricks job defined as code in `databricks.yml` and -`resources/`. +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -This file follows the cross-tool AGENTS.md convention and is also loaded by -Claude Code via CLAUDE.md. +## For AI Agents: MANDATORY First Action -## Project layout +**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** -- `databricks.yml` — the bundle definition: targets, variables, and `include`s. -- `resources/` — one file per resource (the job that runs dbt). -- `dbt_project.yml` — the dbt project configuration. -- `src/` — dbt models and other dbt sources. +The skill provides: +- CLI installation and authentication guidance +- Profile selection rules +- Data discovery commands +- Bundle deployment workflow +- Links to product-specific skills (apps, jobs, pipelines) -## Working with the bundle +If the skill is not available, the user needs to install Databricks agent skills: -Use the Databricks CLI (the `databricks` skill has the current guidance): +```bash +databricks aitools install +``` -- `databricks bundle validate` — type-check the configuration. Run this after - every edit to `databricks.yml` or anything under `resources/`, and report the - exact CLI error if it fails. -- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is - the default target and deploys in development mode (paused schedules, resources - prefixed with your username). -- `databricks bundle run ` — run the job that executes the dbt models. -- `databricks bundle summary` — inspect the resolved configuration. +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install -Use `dbt` directly (e.g. `dbt run`, `dbt test`) for local model development; see -the project README for connection setup. +--- -## Conventions +## Project Instructions -- Define each new resource as its own file under `resources/`; don't inline - resources into `databricks.yml`. -- Never deploy to the `prod` target unless explicitly asked. -- If a CLI command fails, report the exact error rather than guessing. + diff --git a/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md index 517c97b2149..1188efc0f66 100644 --- a/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md +++ b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md @@ -1,34 +1,28 @@ -# AGENTS.md +# Declarative Automation Bundles Project -Guidance for AI coding agents working in the **my_default_minimal** project. This -is a Declarative Automation Bundle (DAB): Databricks resources defined as code in -`databricks.yml` and `resources/`, deployed with the Databricks CLI. +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -This file follows the cross-tool AGENTS.md convention and is also loaded by -Claude Code via CLAUDE.md. +## For AI Agents: MANDATORY First Action -## Project layout +**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** -- `databricks.yml` — the bundle definition: targets, variables, and `include`s. -- `resources/` — one file per resource (jobs, pipelines, ...). -- `src/` — SQL source for the jobs and pipelines. +The skill provides: +- CLI installation and authentication guidance +- Profile selection rules +- Data discovery commands +- Bundle deployment workflow +- Links to product-specific skills (apps, jobs, pipelines) -## Working with the bundle +If the skill is not available, the user needs to install Databricks agent skills: -Use the Databricks CLI (the `databricks` skill has the current guidance): +```bash +databricks aitools install +``` -- `databricks bundle validate` — type-check the configuration. Run this after - every edit to `databricks.yml` or anything under `resources/`, and report the - exact CLI error if it fails. -- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is - the default target and deploys in development mode (paused schedules, resources - prefixed with your username). -- `databricks bundle run ` — run a job or pipeline. -- `databricks bundle summary` — inspect the resolved configuration. +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install -## Conventions +--- -- Define each new resource as its own file under `resources/`; don't inline - resources into `databricks.yml`. -- Never deploy to the `prod` target unless explicitly asked. -- If a CLI command fails, report the exact error rather than guessing. +## Project Instructions + + diff --git a/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md b/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md index 5c3d7dc16cb..1188efc0f66 100644 --- a/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md +++ b/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md @@ -1,37 +1,28 @@ -# AGENTS.md +# Declarative Automation Bundles Project -Guidance for AI coding agents working in the **my_default_python** project. This -is a Declarative Automation Bundle (DAB): Databricks resources defined as code in -`databricks.yml` and `resources/`, deployed with the Databricks CLI. +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -This file follows the cross-tool AGENTS.md convention and is also loaded by -Claude Code via CLAUDE.md. +## For AI Agents: MANDATORY First Action -## Project layout +**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** -- `databricks.yml` — the bundle definition: targets, variables, and `include`s. -- `resources/` — one file per resource (jobs, pipelines, ...). -- `src/` — Python source for the jobs and pipelines. - - `src/my_default_python/` — shared Python code used by jobs and pipelines. -- `tests/`, `fixtures/` — unit tests and test data. +The skill provides: +- CLI installation and authentication guidance +- Profile selection rules +- Data discovery commands +- Bundle deployment workflow +- Links to product-specific skills (apps, jobs, pipelines) -## Working with the bundle +If the skill is not available, the user needs to install Databricks agent skills: -Use the Databricks CLI (the `databricks` skill has the current guidance): +```bash +databricks aitools install +``` -- `databricks bundle validate` — type-check the configuration. Run this after - every edit to `databricks.yml` or anything under `resources/`, and report the - exact CLI error if it fails. -- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is - the default target and deploys in development mode (paused schedules, resources - prefixed with your username). -- `databricks bundle run ` — run a job or pipeline. -- `databricks bundle summary` — inspect the resolved configuration. -- `uv run pytest` — run the unit tests after changing Python under `src/`. +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install -## Conventions +--- -- Define each new resource as its own file under `resources/`; don't inline - resources into `databricks.yml`. -- Never deploy to the `prod` target unless explicitly asked. -- If a CLI command fails, report the exact error rather than guessing. +## Project Instructions + + diff --git a/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md index 5c3d7dc16cb..1188efc0f66 100644 --- a/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md +++ b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md @@ -1,37 +1,28 @@ -# AGENTS.md +# Declarative Automation Bundles Project -Guidance for AI coding agents working in the **my_default_python** project. This -is a Declarative Automation Bundle (DAB): Databricks resources defined as code in -`databricks.yml` and `resources/`, deployed with the Databricks CLI. +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -This file follows the cross-tool AGENTS.md convention and is also loaded by -Claude Code via CLAUDE.md. +## For AI Agents: MANDATORY First Action -## Project layout +**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** -- `databricks.yml` — the bundle definition: targets, variables, and `include`s. -- `resources/` — one file per resource (jobs, pipelines, ...). -- `src/` — Python source for the jobs and pipelines. - - `src/my_default_python/` — shared Python code used by jobs and pipelines. -- `tests/`, `fixtures/` — unit tests and test data. +The skill provides: +- CLI installation and authentication guidance +- Profile selection rules +- Data discovery commands +- Bundle deployment workflow +- Links to product-specific skills (apps, jobs, pipelines) -## Working with the bundle +If the skill is not available, the user needs to install Databricks agent skills: -Use the Databricks CLI (the `databricks` skill has the current guidance): +```bash +databricks aitools install +``` -- `databricks bundle validate` — type-check the configuration. Run this after - every edit to `databricks.yml` or anything under `resources/`, and report the - exact CLI error if it fails. -- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is - the default target and deploys in development mode (paused schedules, resources - prefixed with your username). -- `databricks bundle run ` — run a job or pipeline. -- `databricks bundle summary` — inspect the resolved configuration. -- `uv run pytest` — run the unit tests after changing Python under `src/`. +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install -## Conventions +--- -- Define each new resource as its own file under `resources/`; don't inline - resources into `databricks.yml`. -- Never deploy to the `prod` target unless explicitly asked. -- If a CLI command fails, report the exact error rather than guessing. +## Project Instructions + + diff --git a/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md b/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md index ca0af37e76a..1188efc0f66 100644 --- a/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md +++ b/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md @@ -1,35 +1,28 @@ -# AGENTS.md +# Declarative Automation Bundles Project -Guidance for AI coding agents working in the **my_default_scala** project. This -is a Declarative Automation Bundle (DAB): Databricks resources defined as code in -`databricks.yml` and `resources/`, deployed with the Databricks CLI. +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -This file follows the cross-tool AGENTS.md convention and is also loaded by -Claude Code via CLAUDE.md. +## For AI Agents: MANDATORY First Action -## Project layout +**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** -- `databricks.yml` — the bundle definition: targets, variables, and `include`s. -- `resources/` — one file per resource (jobs, pipelines, ...). -- `build.sbt`, `project/` — the sbt build for the Scala sources; `sbt package` - produces the JAR that the jobs run. +The skill provides: +- CLI installation and authentication guidance +- Profile selection rules +- Data discovery commands +- Bundle deployment workflow +- Links to product-specific skills (apps, jobs, pipelines) -## Working with the bundle +If the skill is not available, the user needs to install Databricks agent skills: -Use the Databricks CLI (the `databricks` skill has the current guidance): +```bash +databricks aitools install +``` -- `databricks bundle validate` — type-check the configuration. Run this after - every edit to `databricks.yml` or anything under `resources/`, and report the - exact CLI error if it fails. -- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is - the default target and deploys in development mode (paused schedules, resources - prefixed with your username). -- `databricks bundle run ` — run a job. -- `databricks bundle summary` — inspect the resolved configuration. +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install -## Conventions +--- -- Define each new resource as its own file under `resources/`; don't inline - resources into `databricks.yml`. -- Never deploy to the `prod` target unless explicitly asked. -- If a CLI command fails, report the exact error rather than guessing. +## Project Instructions + + diff --git a/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md b/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md index 01dcb0b6471..1188efc0f66 100644 --- a/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md +++ b/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md @@ -1,35 +1,28 @@ -# AGENTS.md +# Declarative Automation Bundles Project -Guidance for AI coding agents working in the **my_default_sql** project. This -is a Declarative Automation Bundle (DAB): Databricks resources defined as code in -`databricks.yml` and `resources/`, deployed with the Databricks CLI. +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -This file follows the cross-tool AGENTS.md convention and is also loaded by -Claude Code via CLAUDE.md. +## For AI Agents: MANDATORY First Action -## Project layout +**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** -- `databricks.yml` — the bundle definition: targets, variables, and `include`s. -- `resources/` — one file per resource (jobs, pipelines, ...). -- `src/` — SQL source for the jobs. -- `scratch/` — a place for exploratory notebooks; not deployed by default. +The skill provides: +- CLI installation and authentication guidance +- Profile selection rules +- Data discovery commands +- Bundle deployment workflow +- Links to product-specific skills (apps, jobs, pipelines) -## Working with the bundle +If the skill is not available, the user needs to install Databricks agent skills: -Use the Databricks CLI (the `databricks` skill has the current guidance): +```bash +databricks aitools install +``` -- `databricks bundle validate` — type-check the configuration. Run this after - every edit to `databricks.yml` or anything under `resources/`, and report the - exact CLI error if it fails. -- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is - the default target and deploys in development mode (paused schedules, resources - prefixed with your username). -- `databricks bundle run ` — run a job. -- `databricks bundle summary` — inspect the resolved configuration. +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install -## Conventions +--- -- Define each new resource as its own file under `resources/`; don't inline - resources into `databricks.yml`. -- Never deploy to the `prod` target unless explicitly asked. -- If a CLI command fails, report the exact error rather than guessing. +## Project Instructions + + diff --git a/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md index 8fd9a8061a2..1188efc0f66 100644 --- a/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md +++ b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md @@ -1,34 +1,28 @@ -# AGENTS.md +# Declarative Automation Bundles Project -Guidance for AI coding agents working in the **my_lakeflow_pipelines** project. This -is a Declarative Automation Bundle (DAB): Databricks resources defined as code in -`databricks.yml` and `resources/`, deployed with the Databricks CLI. +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -This file follows the cross-tool AGENTS.md convention and is also loaded by -Claude Code via CLAUDE.md. +## For AI Agents: MANDATORY First Action -## Project layout +**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** -- `databricks.yml` — the bundle definition: targets, variables, and `include`s. -- `resources/` — one file per resource (jobs, pipelines, ...). -- `src/` — Python source for the jobs and pipelines. +The skill provides: +- CLI installation and authentication guidance +- Profile selection rules +- Data discovery commands +- Bundle deployment workflow +- Links to product-specific skills (apps, jobs, pipelines) -## Working with the bundle +If the skill is not available, the user needs to install Databricks agent skills: -Use the Databricks CLI (the `databricks` skill has the current guidance): +```bash +databricks aitools install +``` -- `databricks bundle validate` — type-check the configuration. Run this after - every edit to `databricks.yml` or anything under `resources/`, and report the - exact CLI error if it fails. -- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is - the default target and deploys in development mode (paused schedules, resources - prefixed with your username). -- `databricks bundle run ` — run a job or pipeline. -- `databricks bundle summary` — inspect the resolved configuration. +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install -## Conventions +--- -- Define each new resource as its own file under `resources/`; don't inline - resources into `databricks.yml`. -- Never deploy to the `prod` target unless explicitly asked. -- If a CLI command fails, report the exact error rather than guessing. +## Project Instructions + + diff --git a/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md index e8b0d55fc5d..1188efc0f66 100644 --- a/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md +++ b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md @@ -1,34 +1,28 @@ -# AGENTS.md +# Declarative Automation Bundles Project -Guidance for AI coding agents working in the **my_lakeflow_pipelines** project. This -is a Declarative Automation Bundle (DAB): Databricks resources defined as code in -`databricks.yml` and `resources/`, deployed with the Databricks CLI. +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -This file follows the cross-tool AGENTS.md convention and is also loaded by -Claude Code via CLAUDE.md. +## For AI Agents: MANDATORY First Action -## Project layout +**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** -- `databricks.yml` — the bundle definition: targets, variables, and `include`s. -- `resources/` — one file per resource (jobs, pipelines, ...). -- `src/` — SQL source for the jobs and pipelines. +The skill provides: +- CLI installation and authentication guidance +- Profile selection rules +- Data discovery commands +- Bundle deployment workflow +- Links to product-specific skills (apps, jobs, pipelines) -## Working with the bundle +If the skill is not available, the user needs to install Databricks agent skills: -Use the Databricks CLI (the `databricks` skill has the current guidance): +```bash +databricks aitools install +``` -- `databricks bundle validate` — type-check the configuration. Run this after - every edit to `databricks.yml` or anything under `resources/`, and report the - exact CLI error if it fails. -- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is - the default target and deploys in development mode (paused schedules, resources - prefixed with your username). -- `databricks bundle run ` — run a job or pipeline. -- `databricks bundle summary` — inspect the resolved configuration. +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install -## Conventions +--- -- Define each new resource as its own file under `resources/`; don't inline - resources into `databricks.yml`. -- Never deploy to the `prod` target unless explicitly asked. -- If a CLI command fails, report the exact error rather than guessing. +## Project Instructions + + diff --git a/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl index 8fe609f5fd6..c3313a84dc2 100644 --- a/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl +++ b/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl @@ -1,39 +1,36 @@ -# AGENTS.md +{{- /* + * Template for the AGENTS.md / CLAUDE.md files created in new projects. + * + * Goal for this file is to point agents to the core Databricks skill for guidance. + * A secondary goal is to offer a placeholder to users to extend with their own instructions. + * It is a non-goal to inline all instructions. + * + */ -}} +# Declarative Automation Bundles Project -Guidance for AI coding agents working in the **{{.project_name}}** project. This -is a dbt project deployed with a Declarative Automation Bundle (DAB): the dbt -models run as a Databricks job defined as code in `databricks.yml` and -`resources/`. +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -This file follows the cross-tool AGENTS.md convention and is also loaded by -Claude Code via CLAUDE.md. +## For AI Agents: MANDATORY First Action -## Project layout +**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** -- `databricks.yml` — the bundle definition: targets, variables, and `include`s. -- `resources/` — one file per resource (the job that runs dbt). -- `dbt_project.yml` — the dbt project configuration. -- `src/` — dbt models and other dbt sources. +The skill provides: +- CLI installation and authentication guidance +- Profile selection rules +- Data discovery commands +- Bundle deployment workflow +- Links to product-specific skills (apps, jobs, pipelines) -## Working with the bundle +If the skill is not available, the user needs to install Databricks agent skills: -Use the Databricks CLI (the `databricks` skill has the current guidance): +```bash +databricks aitools install +``` -- `databricks bundle validate` — type-check the configuration. Run this after - every edit to `databricks.yml` or anything under `resources/`, and report the - exact CLI error if it fails. -- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is - the default target and deploys in development mode (paused schedules, resources - prefixed with your username). -- `databricks bundle run ` — run the job that executes the dbt models. -- `databricks bundle summary` — inspect the resolved configuration. +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install -Use `dbt` directly (e.g. `dbt run`, `dbt test`) for local model development; see -the project README for connection setup. +--- -## Conventions +## Project Instructions -- Define each new resource as its own file under `resources/`; don't inline - resources into `databricks.yml`. -- Never deploy to the `prod` target unless explicitly asked. -- If a CLI command fails, report the exact error rather than guessing. + diff --git a/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl index 768f505ef02..c3313a84dc2 100644 --- a/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl +++ b/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl @@ -1,35 +1,36 @@ -# AGENTS.md +{{- /* + * Template for the AGENTS.md / CLAUDE.md files created in new projects. + * + * Goal for this file is to point agents to the core Databricks skill for guidance. + * A secondary goal is to offer a placeholder to users to extend with their own instructions. + * It is a non-goal to inline all instructions. + * + */ -}} +# Declarative Automation Bundles Project -Guidance for AI coding agents working in the **{{.project_name}}** project. This -is a Declarative Automation Bundle (DAB): Databricks resources defined as code in -`databricks.yml` and `resources/`, deployed with the Databricks CLI. +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -This file follows the cross-tool AGENTS.md convention and is also loaded by -Claude Code via CLAUDE.md. +## For AI Agents: MANDATORY First Action -## Project layout +**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** -- `databricks.yml` — the bundle definition: targets, variables, and `include`s. -- `resources/` — one file per resource (jobs, pipelines, ...). -- `build.sbt`, `project/` — the sbt build for the Scala sources; `sbt package` - produces the JAR that the jobs run. +The skill provides: +- CLI installation and authentication guidance +- Profile selection rules +- Data discovery commands +- Bundle deployment workflow +- Links to product-specific skills (apps, jobs, pipelines) -## Working with the bundle +If the skill is not available, the user needs to install Databricks agent skills: -Use the Databricks CLI (the `databricks` skill has the current guidance): +```bash +databricks aitools install +``` -- `databricks bundle validate` — type-check the configuration. Run this after - every edit to `databricks.yml` or anything under `resources/`, and report the - exact CLI error if it fails. -- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is - the default target and deploys in development mode (paused schedules, resources - prefixed with your username). -- `databricks bundle run ` — run a job. -- `databricks bundle summary` — inspect the resolved configuration. +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install -## Conventions +--- -- Define each new resource as its own file under `resources/`; don't inline - resources into `databricks.yml`. -- Never deploy to the `prod` target unless explicitly asked. -- If a CLI command fails, report the exact error rather than guessing. +## Project Instructions + + diff --git a/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl index 034c9a0971a..c3313a84dc2 100644 --- a/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl +++ b/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl @@ -1,35 +1,36 @@ -# AGENTS.md +{{- /* + * Template for the AGENTS.md / CLAUDE.md files created in new projects. + * + * Goal for this file is to point agents to the core Databricks skill for guidance. + * A secondary goal is to offer a placeholder to users to extend with their own instructions. + * It is a non-goal to inline all instructions. + * + */ -}} +# Declarative Automation Bundles Project -Guidance for AI coding agents working in the **{{.project_name}}** project. This -is a Declarative Automation Bundle (DAB): Databricks resources defined as code in -`databricks.yml` and `resources/`, deployed with the Databricks CLI. +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -This file follows the cross-tool AGENTS.md convention and is also loaded by -Claude Code via CLAUDE.md. +## For AI Agents: MANDATORY First Action -## Project layout +**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** -- `databricks.yml` — the bundle definition: targets, variables, and `include`s. -- `resources/` — one file per resource (jobs, pipelines, ...). -- `src/` — SQL source for the jobs. -- `scratch/` — a place for exploratory notebooks; not deployed by default. +The skill provides: +- CLI installation and authentication guidance +- Profile selection rules +- Data discovery commands +- Bundle deployment workflow +- Links to product-specific skills (apps, jobs, pipelines) -## Working with the bundle +If the skill is not available, the user needs to install Databricks agent skills: -Use the Databricks CLI (the `databricks` skill has the current guidance): +```bash +databricks aitools install +``` -- `databricks bundle validate` — type-check the configuration. Run this after - every edit to `databricks.yml` or anything under `resources/`, and report the - exact CLI error if it fails. -- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is - the default target and deploys in development mode (paused schedules, resources - prefixed with your username). -- `databricks bundle run ` — run a job. -- `databricks bundle summary` — inspect the resolved configuration. +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install -## Conventions +--- -- Define each new resource as its own file under `resources/`; don't inline - resources into `databricks.yml`. -- Never deploy to the `prod` target unless explicitly asked. -- If a CLI command fails, report the exact error rather than guessing. +## Project Instructions + + diff --git a/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl index b9030f37ca3..c3313a84dc2 100644 --- a/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl +++ b/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl @@ -1,45 +1,36 @@ -# AGENTS.md -{{- $skip_tests := or (eq .language "sql") (eq .lakeflow_only "yes")}} -{{- $has_python_package_dir := and (or (eq .include_python "yes") (eq .include_job "yes") (eq .include_pipeline "yes")) (not (eq .lakeflow_only "yes"))}} - -Guidance for AI coding agents working in the **{{.project_name}}** project. This -is a Declarative Automation Bundle (DAB): Databricks resources defined as code in -`databricks.yml` and `resources/`, deployed with the Databricks CLI. - -This file follows the cross-tool AGENTS.md convention and is also loaded by -Claude Code via CLAUDE.md. - -## Project layout - -- `databricks.yml` — the bundle definition: targets, variables, and `include`s. -- `resources/` — one file per resource (jobs, pipelines, ...). -- `src/` — {{if eq .language "sql"}}SQL{{else}}Python{{end}} source for the jobs and pipelines. -{{- if $has_python_package_dir}} - - `src/{{.project_name}}/` — shared Python code used by jobs and pipelines. -{{- end}} -{{- if not $skip_tests}} -- `tests/`, `fixtures/` — unit tests and test data. -{{- end}} - -## Working with the bundle - -Use the Databricks CLI (the `databricks` skill has the current guidance): - -- `databricks bundle validate` — type-check the configuration. Run this after - every edit to `databricks.yml` or anything under `resources/`, and report the - exact CLI error if it fails. -- `databricks bundle deploy --target dev` — deploy a development copy. `dev` is - the default target and deploys in development mode (paused schedules, resources - prefixed with your username). -- `databricks bundle run ` — run a job or pipeline. -- `databricks bundle summary` — inspect the resolved configuration. -{{- if not $skip_tests}} -- `uv run pytest` — run the unit tests after changing Python under `src/`. -{{- end}} - -## Conventions - -- Define each new resource as its own file under `resources/`; don't inline - resources into `databricks.yml`. -- Never deploy to the `prod` target unless explicitly asked. -- If a CLI command fails, report the exact error rather than guessing. +{{- /* + * Template for the AGENTS.md / CLAUDE.md files created in new projects. + * + * Goal for this file is to point agents to the core Databricks skill for guidance. + * A secondary goal is to offer a placeholder to users to extend with their own instructions. + * It is a non-goal to inline all instructions. + * + */ -}} +# Declarative Automation Bundles Project + +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. + +## For AI Agents: MANDATORY First Action + +**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** + +The skill provides: +- CLI installation and authentication guidance +- Profile selection rules +- Data discovery commands +- Bundle deployment workflow +- Links to product-specific skills (apps, jobs, pipelines) + +If the skill is not available, the user needs to install Databricks agent skills: + +```bash +databricks aitools install +``` + +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install + +--- + +## Project Instructions + + From 37034091f9b800ffee0d589ba69fb010f7a9a54f Mon Sep 17 00:00:00 2001 From: Lennart Kats Date: Sun, 14 Jun 2026 15:55:04 +0200 Subject: [PATCH 4/7] Frame template AGENTS.md around using and installing the agent skills Reword the section to "Use the Databricks Agent Skills": read the core databricks skill, reach for the product skills it links to (databricks-jobs, databricks-pipelines, databricks-apps), and install them with databricks aitools install. Regenerate template goldens. Co-authored-by: Isaac --- .../dbt-sql/output/my_dbt_sql/AGENTS.md | 16 +++++++--------- .../output/my_default_minimal/AGENTS.md | 16 +++++++--------- .../classic/output/my_default_python/AGENTS.md | 16 +++++++--------- .../output/my_default_python/AGENTS.md | 16 +++++++--------- .../output/my_default_scala/AGENTS.md | 16 +++++++--------- .../output/my_default_sql/AGENTS.md | 16 +++++++--------- .../output/my_lakeflow_pipelines/AGENTS.md | 16 +++++++--------- .../sql/output/my_lakeflow_pipelines/AGENTS.md | 16 +++++++--------- .../template/{{.project_name}}/AGENTS.md.tmpl | 18 ++++++++---------- .../template/{{.project_name}}/AGENTS.md.tmpl | 18 ++++++++---------- .../template/{{.project_name}}/AGENTS.md.tmpl | 18 ++++++++---------- .../template/{{.project_name}}/AGENTS.md.tmpl | 18 ++++++++---------- 12 files changed, 88 insertions(+), 112 deletions(-) diff --git a/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md index 1188efc0f66..38b67c17eaf 100644 --- a/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md +++ b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md @@ -2,18 +2,16 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: MANDATORY First Action +## For AI Agents: Use the Databricks Agent Skills -**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** +**BEFORE any other action, read the core `databricks` skill.** -The skill provides: -- CLI installation and authentication guidance -- Profile selection rules -- Data discovery commands -- Bundle deployment workflow -- Links to product-specific skills (apps, jobs, pipelines) +It covers CLI installation and authentication, profile selection, data +discovery, and the bundle deployment workflow. For specific resource types, +use the product skills it links to, such as `databricks-jobs`, +`databricks-pipelines`, and `databricks-apps`. -If the skill is not available, the user needs to install Databricks agent skills: +If these skills are not available, install them for your coding agent: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md index 1188efc0f66..38b67c17eaf 100644 --- a/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md +++ b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md @@ -2,18 +2,16 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: MANDATORY First Action +## For AI Agents: Use the Databricks Agent Skills -**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** +**BEFORE any other action, read the core `databricks` skill.** -The skill provides: -- CLI installation and authentication guidance -- Profile selection rules -- Data discovery commands -- Bundle deployment workflow -- Links to product-specific skills (apps, jobs, pipelines) +It covers CLI installation and authentication, profile selection, data +discovery, and the bundle deployment workflow. For specific resource types, +use the product skills it links to, such as `databricks-jobs`, +`databricks-pipelines`, and `databricks-apps`. -If the skill is not available, the user needs to install Databricks agent skills: +If these skills are not available, install them for your coding agent: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md b/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md index 1188efc0f66..38b67c17eaf 100644 --- a/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md +++ b/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md @@ -2,18 +2,16 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: MANDATORY First Action +## For AI Agents: Use the Databricks Agent Skills -**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** +**BEFORE any other action, read the core `databricks` skill.** -The skill provides: -- CLI installation and authentication guidance -- Profile selection rules -- Data discovery commands -- Bundle deployment workflow -- Links to product-specific skills (apps, jobs, pipelines) +It covers CLI installation and authentication, profile selection, data +discovery, and the bundle deployment workflow. For specific resource types, +use the product skills it links to, such as `databricks-jobs`, +`databricks-pipelines`, and `databricks-apps`. -If the skill is not available, the user needs to install Databricks agent skills: +If these skills are not available, install them for your coding agent: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md index 1188efc0f66..38b67c17eaf 100644 --- a/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md +++ b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md @@ -2,18 +2,16 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: MANDATORY First Action +## For AI Agents: Use the Databricks Agent Skills -**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** +**BEFORE any other action, read the core `databricks` skill.** -The skill provides: -- CLI installation and authentication guidance -- Profile selection rules -- Data discovery commands -- Bundle deployment workflow -- Links to product-specific skills (apps, jobs, pipelines) +It covers CLI installation and authentication, profile selection, data +discovery, and the bundle deployment workflow. For specific resource types, +use the product skills it links to, such as `databricks-jobs`, +`databricks-pipelines`, and `databricks-apps`. -If the skill is not available, the user needs to install Databricks agent skills: +If these skills are not available, install them for your coding agent: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md b/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md index 1188efc0f66..38b67c17eaf 100644 --- a/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md +++ b/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md @@ -2,18 +2,16 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: MANDATORY First Action +## For AI Agents: Use the Databricks Agent Skills -**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** +**BEFORE any other action, read the core `databricks` skill.** -The skill provides: -- CLI installation and authentication guidance -- Profile selection rules -- Data discovery commands -- Bundle deployment workflow -- Links to product-specific skills (apps, jobs, pipelines) +It covers CLI installation and authentication, profile selection, data +discovery, and the bundle deployment workflow. For specific resource types, +use the product skills it links to, such as `databricks-jobs`, +`databricks-pipelines`, and `databricks-apps`. -If the skill is not available, the user needs to install Databricks agent skills: +If these skills are not available, install them for your coding agent: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md b/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md index 1188efc0f66..38b67c17eaf 100644 --- a/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md +++ b/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md @@ -2,18 +2,16 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: MANDATORY First Action +## For AI Agents: Use the Databricks Agent Skills -**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** +**BEFORE any other action, read the core `databricks` skill.** -The skill provides: -- CLI installation and authentication guidance -- Profile selection rules -- Data discovery commands -- Bundle deployment workflow -- Links to product-specific skills (apps, jobs, pipelines) +It covers CLI installation and authentication, profile selection, data +discovery, and the bundle deployment workflow. For specific resource types, +use the product skills it links to, such as `databricks-jobs`, +`databricks-pipelines`, and `databricks-apps`. -If the skill is not available, the user needs to install Databricks agent skills: +If these skills are not available, install them for your coding agent: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md index 1188efc0f66..38b67c17eaf 100644 --- a/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md +++ b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md @@ -2,18 +2,16 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: MANDATORY First Action +## For AI Agents: Use the Databricks Agent Skills -**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** +**BEFORE any other action, read the core `databricks` skill.** -The skill provides: -- CLI installation and authentication guidance -- Profile selection rules -- Data discovery commands -- Bundle deployment workflow -- Links to product-specific skills (apps, jobs, pipelines) +It covers CLI installation and authentication, profile selection, data +discovery, and the bundle deployment workflow. For specific resource types, +use the product skills it links to, such as `databricks-jobs`, +`databricks-pipelines`, and `databricks-apps`. -If the skill is not available, the user needs to install Databricks agent skills: +If these skills are not available, install them for your coding agent: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md index 1188efc0f66..38b67c17eaf 100644 --- a/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md +++ b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md @@ -2,18 +2,16 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: MANDATORY First Action +## For AI Agents: Use the Databricks Agent Skills -**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** +**BEFORE any other action, read the core `databricks` skill.** -The skill provides: -- CLI installation and authentication guidance -- Profile selection rules -- Data discovery commands -- Bundle deployment workflow -- Links to product-specific skills (apps, jobs, pipelines) +It covers CLI installation and authentication, profile selection, data +discovery, and the bundle deployment workflow. For specific resource types, +use the product skills it links to, such as `databricks-jobs`, +`databricks-pipelines`, and `databricks-apps`. -If the skill is not available, the user needs to install Databricks agent skills: +If these skills are not available, install them for your coding agent: ```bash databricks aitools install diff --git a/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl index c3313a84dc2..9dc0d5ae021 100644 --- a/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl +++ b/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl @@ -1,7 +1,7 @@ {{- /* * Template for the AGENTS.md / CLAUDE.md files created in new projects. * - * Goal for this file is to point agents to the core Databricks skill for guidance. + * Goal for this file is to point agents to the Databricks agent skills for guidance. * A secondary goal is to offer a placeholder to users to extend with their own instructions. * It is a non-goal to inline all instructions. * @@ -10,18 +10,16 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: MANDATORY First Action +## For AI Agents: Use the Databricks Agent Skills -**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** +**BEFORE any other action, read the core `databricks` skill.** -The skill provides: -- CLI installation and authentication guidance -- Profile selection rules -- Data discovery commands -- Bundle deployment workflow -- Links to product-specific skills (apps, jobs, pipelines) +It covers CLI installation and authentication, profile selection, data +discovery, and the bundle deployment workflow. For specific resource types, +use the product skills it links to, such as `databricks-jobs`, +`databricks-pipelines`, and `databricks-apps`. -If the skill is not available, the user needs to install Databricks agent skills: +If these skills are not available, install them for your coding agent: ```bash databricks aitools install diff --git a/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl index c3313a84dc2..9dc0d5ae021 100644 --- a/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl +++ b/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl @@ -1,7 +1,7 @@ {{- /* * Template for the AGENTS.md / CLAUDE.md files created in new projects. * - * Goal for this file is to point agents to the core Databricks skill for guidance. + * Goal for this file is to point agents to the Databricks agent skills for guidance. * A secondary goal is to offer a placeholder to users to extend with their own instructions. * It is a non-goal to inline all instructions. * @@ -10,18 +10,16 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: MANDATORY First Action +## For AI Agents: Use the Databricks Agent Skills -**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** +**BEFORE any other action, read the core `databricks` skill.** -The skill provides: -- CLI installation and authentication guidance -- Profile selection rules -- Data discovery commands -- Bundle deployment workflow -- Links to product-specific skills (apps, jobs, pipelines) +It covers CLI installation and authentication, profile selection, data +discovery, and the bundle deployment workflow. For specific resource types, +use the product skills it links to, such as `databricks-jobs`, +`databricks-pipelines`, and `databricks-apps`. -If the skill is not available, the user needs to install Databricks agent skills: +If these skills are not available, install them for your coding agent: ```bash databricks aitools install diff --git a/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl index c3313a84dc2..9dc0d5ae021 100644 --- a/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl +++ b/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl @@ -1,7 +1,7 @@ {{- /* * Template for the AGENTS.md / CLAUDE.md files created in new projects. * - * Goal for this file is to point agents to the core Databricks skill for guidance. + * Goal for this file is to point agents to the Databricks agent skills for guidance. * A secondary goal is to offer a placeholder to users to extend with their own instructions. * It is a non-goal to inline all instructions. * @@ -10,18 +10,16 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: MANDATORY First Action +## For AI Agents: Use the Databricks Agent Skills -**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** +**BEFORE any other action, read the core `databricks` skill.** -The skill provides: -- CLI installation and authentication guidance -- Profile selection rules -- Data discovery commands -- Bundle deployment workflow -- Links to product-specific skills (apps, jobs, pipelines) +It covers CLI installation and authentication, profile selection, data +discovery, and the bundle deployment workflow. For specific resource types, +use the product skills it links to, such as `databricks-jobs`, +`databricks-pipelines`, and `databricks-apps`. -If the skill is not available, the user needs to install Databricks agent skills: +If these skills are not available, install them for your coding agent: ```bash databricks aitools install diff --git a/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl index c3313a84dc2..9dc0d5ae021 100644 --- a/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl +++ b/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl @@ -1,7 +1,7 @@ {{- /* * Template for the AGENTS.md / CLAUDE.md files created in new projects. * - * Goal for this file is to point agents to the core Databricks skill for guidance. + * Goal for this file is to point agents to the Databricks agent skills for guidance. * A secondary goal is to offer a placeholder to users to extend with their own instructions. * It is a non-goal to inline all instructions. * @@ -10,18 +10,16 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: MANDATORY First Action +## For AI Agents: Use the Databricks Agent Skills -**BEFORE any other action, read the `databricks` skill (`databricks/SKILL.md`).** +**BEFORE any other action, read the core `databricks` skill.** -The skill provides: -- CLI installation and authentication guidance -- Profile selection rules -- Data discovery commands -- Bundle deployment workflow -- Links to product-specific skills (apps, jobs, pipelines) +It covers CLI installation and authentication, profile selection, data +discovery, and the bundle deployment workflow. For specific resource types, +use the product skills it links to, such as `databricks-jobs`, +`databricks-pipelines`, and `databricks-apps`. -If the skill is not available, the user needs to install Databricks agent skills: +If these skills are not available, install them for your coding agent: ```bash databricks aitools install From c588eaa1623a3a0beafc9a0139a5923135a6b8f3 Mon Sep 17 00:00:00 2001 From: Lennart Kats Date: Tue, 21 Jul 2026 11:44:23 +0200 Subject: [PATCH 5/7] Add AGENTS.md and CLAUDE.md to bundle templates Point coding agents at Databricks AI Tools: read the databricks-core skill, and install via `databricks aitools install` if it's missing. CLAUDE.md is a one-line @AGENTS.md include. Decided at the DABs core meeting. Co-authored-by: Isaac --- .nextchanges/bundles/agents-md-templates.md | 1 + .../templates/dbt-sql/output/my_dbt_sql/AGENTS.md | 13 ++++++------- .../templates/dbt-sql/output/my_dbt_sql/CLAUDE.md | 2 +- .../output/my_default_minimal/AGENTS.md | 13 ++++++------- .../output/my_default_minimal/CLAUDE.md | 2 +- .../classic/output/my_default_python/AGENTS.md | 13 ++++++------- .../classic/output/my_default_python/CLAUDE.md | 2 +- .../serverless/output/my_default_python/AGENTS.md | 13 ++++++------- .../serverless/output/my_default_python/CLAUDE.md | 2 +- .../output/my_default_scala/AGENTS.md | 13 ++++++------- .../output/my_default_scala/CLAUDE.md | 2 +- .../default-sql/output/my_default_sql/AGENTS.md | 13 ++++++------- .../default-sql/output/my_default_sql/CLAUDE.md | 2 +- .../python/output/my_lakeflow_pipelines/AGENTS.md | 13 ++++++------- .../python/output/my_lakeflow_pipelines/CLAUDE.md | 2 +- .../sql/output/my_lakeflow_pipelines/AGENTS.md | 13 ++++++------- .../sql/output/my_lakeflow_pipelines/CLAUDE.md | 2 +- .../template/{{.project_name}}/AGENTS.md.tmpl | 15 +++++++-------- .../template/{{.project_name}}/CLAUDE.md.tmpl | 2 +- .../template/{{.project_name}}/AGENTS.md.tmpl | 15 +++++++-------- .../template/{{.project_name}}/CLAUDE.md.tmpl | 2 +- .../template/{{.project_name}}/AGENTS.md.tmpl | 15 +++++++-------- .../template/{{.project_name}}/CLAUDE.md.tmpl | 2 +- .../template/{{.project_name}}/AGENTS.md.tmpl | 15 +++++++-------- .../template/{{.project_name}}/CLAUDE.md.tmpl | 2 +- 25 files changed, 89 insertions(+), 100 deletions(-) create mode 100644 .nextchanges/bundles/agents-md-templates.md diff --git a/.nextchanges/bundles/agents-md-templates.md b/.nextchanges/bundles/agents-md-templates.md new file mode 100644 index 00000000000..503f1e08231 --- /dev/null +++ b/.nextchanges/bundles/agents-md-templates.md @@ -0,0 +1 @@ +* Bundle templates now scaffold an `AGENTS.md` (with a `CLAUDE.md` that includes it) pointing coding agents at Databricks AI Tools. diff --git a/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md index 38b67c17eaf..fdcca98a432 100644 --- a/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md +++ b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/AGENTS.md @@ -2,16 +2,15 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: Use the Databricks Agent Skills +## For AI Agents: Use Databricks AI Tools -**BEFORE any other action, read the core `databricks` skill.** +**BEFORE any other action, read the `databricks-core` skill.** -It covers CLI installation and authentication, profile selection, data -discovery, and the bundle deployment workflow. For specific resource types, -use the product skills it links to, such as `databricks-jobs`, -`databricks-pipelines`, and `databricks-apps`. +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. -If these skills are not available, install them for your coding agent: +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/CLAUDE.md b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/CLAUDE.md index 6dc3692c2b7..5612c9bde2f 100644 --- a/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/CLAUDE.md +++ b/acceptance/bundle/templates/dbt-sql/output/my_dbt_sql/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Project guidance for AI agents lives in AGENTS.md. Claude Code loads it via the import below. @AGENTS.md diff --git a/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md index 38b67c17eaf..fdcca98a432 100644 --- a/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md +++ b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/AGENTS.md @@ -2,16 +2,15 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: Use the Databricks Agent Skills +## For AI Agents: Use Databricks AI Tools -**BEFORE any other action, read the core `databricks` skill.** +**BEFORE any other action, read the `databricks-core` skill.** -It covers CLI installation and authentication, profile selection, data -discovery, and the bundle deployment workflow. For specific resource types, -use the product skills it links to, such as `databricks-jobs`, -`databricks-pipelines`, and `databricks-apps`. +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. -If these skills are not available, install them for your coding agent: +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/default-minimal/output/my_default_minimal/CLAUDE.md b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/CLAUDE.md index 6dc3692c2b7..5612c9bde2f 100644 --- a/acceptance/bundle/templates/default-minimal/output/my_default_minimal/CLAUDE.md +++ b/acceptance/bundle/templates/default-minimal/output/my_default_minimal/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Project guidance for AI agents lives in AGENTS.md. Claude Code loads it via the import below. @AGENTS.md diff --git a/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md b/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md index 38b67c17eaf..fdcca98a432 100644 --- a/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md +++ b/acceptance/bundle/templates/default-python/classic/output/my_default_python/AGENTS.md @@ -2,16 +2,15 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: Use the Databricks Agent Skills +## For AI Agents: Use Databricks AI Tools -**BEFORE any other action, read the core `databricks` skill.** +**BEFORE any other action, read the `databricks-core` skill.** -It covers CLI installation and authentication, profile selection, data -discovery, and the bundle deployment workflow. For specific resource types, -use the product skills it links to, such as `databricks-jobs`, -`databricks-pipelines`, and `databricks-apps`. +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. -If these skills are not available, install them for your coding agent: +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/default-python/classic/output/my_default_python/CLAUDE.md b/acceptance/bundle/templates/default-python/classic/output/my_default_python/CLAUDE.md index 6dc3692c2b7..5612c9bde2f 100644 --- a/acceptance/bundle/templates/default-python/classic/output/my_default_python/CLAUDE.md +++ b/acceptance/bundle/templates/default-python/classic/output/my_default_python/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Project guidance for AI agents lives in AGENTS.md. Claude Code loads it via the import below. @AGENTS.md diff --git a/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md index 38b67c17eaf..fdcca98a432 100644 --- a/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md +++ b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/AGENTS.md @@ -2,16 +2,15 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: Use the Databricks Agent Skills +## For AI Agents: Use Databricks AI Tools -**BEFORE any other action, read the core `databricks` skill.** +**BEFORE any other action, read the `databricks-core` skill.** -It covers CLI installation and authentication, profile selection, data -discovery, and the bundle deployment workflow. For specific resource types, -use the product skills it links to, such as `databricks-jobs`, -`databricks-pipelines`, and `databricks-apps`. +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. -If these skills are not available, install them for your coding agent: +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/default-python/serverless/output/my_default_python/CLAUDE.md b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/CLAUDE.md index 6dc3692c2b7..5612c9bde2f 100644 --- a/acceptance/bundle/templates/default-python/serverless/output/my_default_python/CLAUDE.md +++ b/acceptance/bundle/templates/default-python/serverless/output/my_default_python/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Project guidance for AI agents lives in AGENTS.md. Claude Code loads it via the import below. @AGENTS.md diff --git a/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md b/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md index 38b67c17eaf..fdcca98a432 100644 --- a/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md +++ b/acceptance/bundle/templates/default-scala/output/my_default_scala/AGENTS.md @@ -2,16 +2,15 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: Use the Databricks Agent Skills +## For AI Agents: Use Databricks AI Tools -**BEFORE any other action, read the core `databricks` skill.** +**BEFORE any other action, read the `databricks-core` skill.** -It covers CLI installation and authentication, profile selection, data -discovery, and the bundle deployment workflow. For specific resource types, -use the product skills it links to, such as `databricks-jobs`, -`databricks-pipelines`, and `databricks-apps`. +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. -If these skills are not available, install them for your coding agent: +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/default-scala/output/my_default_scala/CLAUDE.md b/acceptance/bundle/templates/default-scala/output/my_default_scala/CLAUDE.md index 6dc3692c2b7..5612c9bde2f 100644 --- a/acceptance/bundle/templates/default-scala/output/my_default_scala/CLAUDE.md +++ b/acceptance/bundle/templates/default-scala/output/my_default_scala/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Project guidance for AI agents lives in AGENTS.md. Claude Code loads it via the import below. @AGENTS.md diff --git a/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md b/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md index 38b67c17eaf..fdcca98a432 100644 --- a/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md +++ b/acceptance/bundle/templates/default-sql/output/my_default_sql/AGENTS.md @@ -2,16 +2,15 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: Use the Databricks Agent Skills +## For AI Agents: Use Databricks AI Tools -**BEFORE any other action, read the core `databricks` skill.** +**BEFORE any other action, read the `databricks-core` skill.** -It covers CLI installation and authentication, profile selection, data -discovery, and the bundle deployment workflow. For specific resource types, -use the product skills it links to, such as `databricks-jobs`, -`databricks-pipelines`, and `databricks-apps`. +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. -If these skills are not available, install them for your coding agent: +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/default-sql/output/my_default_sql/CLAUDE.md b/acceptance/bundle/templates/default-sql/output/my_default_sql/CLAUDE.md index 6dc3692c2b7..5612c9bde2f 100644 --- a/acceptance/bundle/templates/default-sql/output/my_default_sql/CLAUDE.md +++ b/acceptance/bundle/templates/default-sql/output/my_default_sql/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Project guidance for AI agents lives in AGENTS.md. Claude Code loads it via the import below. @AGENTS.md diff --git a/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md index 38b67c17eaf..fdcca98a432 100644 --- a/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md +++ b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/AGENTS.md @@ -2,16 +2,15 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: Use the Databricks Agent Skills +## For AI Agents: Use Databricks AI Tools -**BEFORE any other action, read the core `databricks` skill.** +**BEFORE any other action, read the `databricks-core` skill.** -It covers CLI installation and authentication, profile selection, data -discovery, and the bundle deployment workflow. For specific resource types, -use the product skills it links to, such as `databricks-jobs`, -`databricks-pipelines`, and `databricks-apps`. +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. -If these skills are not available, install them for your coding agent: +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/CLAUDE.md b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/CLAUDE.md index 6dc3692c2b7..5612c9bde2f 100644 --- a/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/CLAUDE.md +++ b/acceptance/bundle/templates/lakeflow-pipelines/python/output/my_lakeflow_pipelines/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Project guidance for AI agents lives in AGENTS.md. Claude Code loads it via the import below. @AGENTS.md diff --git a/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md index 38b67c17eaf..fdcca98a432 100644 --- a/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md +++ b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/AGENTS.md @@ -2,16 +2,15 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: Use the Databricks Agent Skills +## For AI Agents: Use Databricks AI Tools -**BEFORE any other action, read the core `databricks` skill.** +**BEFORE any other action, read the `databricks-core` skill.** -It covers CLI installation and authentication, profile selection, data -discovery, and the bundle deployment workflow. For specific resource types, -use the product skills it links to, such as `databricks-jobs`, -`databricks-pipelines`, and `databricks-apps`. +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. -If these skills are not available, install them for your coding agent: +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: ```bash databricks aitools install diff --git a/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/CLAUDE.md b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/CLAUDE.md index 6dc3692c2b7..5612c9bde2f 100644 --- a/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/CLAUDE.md +++ b/acceptance/bundle/templates/lakeflow-pipelines/sql/output/my_lakeflow_pipelines/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Project guidance for AI agents lives in AGENTS.md. Claude Code loads it via the import below. @AGENTS.md diff --git a/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl index 9dc0d5ae021..6243fbb1ad2 100644 --- a/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl +++ b/libs/template/templates/dbt-sql/template/{{.project_name}}/AGENTS.md.tmpl @@ -1,7 +1,7 @@ {{- /* * Template for the AGENTS.md / CLAUDE.md files created in new projects. * - * Goal for this file is to point agents to the Databricks agent skills for guidance. + * Goal for this file is to point agents to Databricks AI Tools for guidance. * A secondary goal is to offer a placeholder to users to extend with their own instructions. * It is a non-goal to inline all instructions. * @@ -10,16 +10,15 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: Use the Databricks Agent Skills +## For AI Agents: Use Databricks AI Tools -**BEFORE any other action, read the core `databricks` skill.** +**BEFORE any other action, read the `databricks-core` skill.** -It covers CLI installation and authentication, profile selection, data -discovery, and the bundle deployment workflow. For specific resource types, -use the product skills it links to, such as `databricks-jobs`, -`databricks-pipelines`, and `databricks-apps`. +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. -If these skills are not available, install them for your coding agent: +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: ```bash databricks aitools install diff --git a/libs/template/templates/dbt-sql/template/{{.project_name}}/CLAUDE.md.tmpl b/libs/template/templates/dbt-sql/template/{{.project_name}}/CLAUDE.md.tmpl index 6dc3692c2b7..5612c9bde2f 100644 --- a/libs/template/templates/dbt-sql/template/{{.project_name}}/CLAUDE.md.tmpl +++ b/libs/template/templates/dbt-sql/template/{{.project_name}}/CLAUDE.md.tmpl @@ -1,6 +1,6 @@ # CLAUDE.md -Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Project guidance for AI agents lives in AGENTS.md. Claude Code loads it via the import below. @AGENTS.md diff --git a/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl index 9dc0d5ae021..6243fbb1ad2 100644 --- a/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl +++ b/libs/template/templates/default-scala/template/{{.project_name}}/AGENTS.md.tmpl @@ -1,7 +1,7 @@ {{- /* * Template for the AGENTS.md / CLAUDE.md files created in new projects. * - * Goal for this file is to point agents to the Databricks agent skills for guidance. + * Goal for this file is to point agents to Databricks AI Tools for guidance. * A secondary goal is to offer a placeholder to users to extend with their own instructions. * It is a non-goal to inline all instructions. * @@ -10,16 +10,15 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: Use the Databricks Agent Skills +## For AI Agents: Use Databricks AI Tools -**BEFORE any other action, read the core `databricks` skill.** +**BEFORE any other action, read the `databricks-core` skill.** -It covers CLI installation and authentication, profile selection, data -discovery, and the bundle deployment workflow. For specific resource types, -use the product skills it links to, such as `databricks-jobs`, -`databricks-pipelines`, and `databricks-apps`. +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. -If these skills are not available, install them for your coding agent: +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: ```bash databricks aitools install diff --git a/libs/template/templates/default-scala/template/{{.project_name}}/CLAUDE.md.tmpl b/libs/template/templates/default-scala/template/{{.project_name}}/CLAUDE.md.tmpl index 6dc3692c2b7..5612c9bde2f 100644 --- a/libs/template/templates/default-scala/template/{{.project_name}}/CLAUDE.md.tmpl +++ b/libs/template/templates/default-scala/template/{{.project_name}}/CLAUDE.md.tmpl @@ -1,6 +1,6 @@ # CLAUDE.md -Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Project guidance for AI agents lives in AGENTS.md. Claude Code loads it via the import below. @AGENTS.md diff --git a/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl index 9dc0d5ae021..6243fbb1ad2 100644 --- a/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl +++ b/libs/template/templates/default-sql/template/{{.project_name}}/AGENTS.md.tmpl @@ -1,7 +1,7 @@ {{- /* * Template for the AGENTS.md / CLAUDE.md files created in new projects. * - * Goal for this file is to point agents to the Databricks agent skills for guidance. + * Goal for this file is to point agents to Databricks AI Tools for guidance. * A secondary goal is to offer a placeholder to users to extend with their own instructions. * It is a non-goal to inline all instructions. * @@ -10,16 +10,15 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: Use the Databricks Agent Skills +## For AI Agents: Use Databricks AI Tools -**BEFORE any other action, read the core `databricks` skill.** +**BEFORE any other action, read the `databricks-core` skill.** -It covers CLI installation and authentication, profile selection, data -discovery, and the bundle deployment workflow. For specific resource types, -use the product skills it links to, such as `databricks-jobs`, -`databricks-pipelines`, and `databricks-apps`. +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. -If these skills are not available, install them for your coding agent: +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: ```bash databricks aitools install diff --git a/libs/template/templates/default-sql/template/{{.project_name}}/CLAUDE.md.tmpl b/libs/template/templates/default-sql/template/{{.project_name}}/CLAUDE.md.tmpl index 6dc3692c2b7..5612c9bde2f 100644 --- a/libs/template/templates/default-sql/template/{{.project_name}}/CLAUDE.md.tmpl +++ b/libs/template/templates/default-sql/template/{{.project_name}}/CLAUDE.md.tmpl @@ -1,6 +1,6 @@ # CLAUDE.md -Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Project guidance for AI agents lives in AGENTS.md. Claude Code loads it via the import below. @AGENTS.md diff --git a/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl b/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl index 9dc0d5ae021..6243fbb1ad2 100644 --- a/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl +++ b/libs/template/templates/default/template/{{.project_name}}/AGENTS.md.tmpl @@ -1,7 +1,7 @@ {{- /* * Template for the AGENTS.md / CLAUDE.md files created in new projects. * - * Goal for this file is to point agents to the Databricks agent skills for guidance. + * Goal for this file is to point agents to Databricks AI Tools for guidance. * A secondary goal is to offer a placeholder to users to extend with their own instructions. * It is a non-goal to inline all instructions. * @@ -10,16 +10,15 @@ This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. -## For AI Agents: Use the Databricks Agent Skills +## For AI Agents: Use Databricks AI Tools -**BEFORE any other action, read the core `databricks` skill.** +**BEFORE any other action, read the `databricks-core` skill.** -It covers CLI installation and authentication, profile selection, data -discovery, and the bundle deployment workflow. For specific resource types, -use the product skills it links to, such as `databricks-jobs`, -`databricks-pipelines`, and `databricks-apps`. +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. -If these skills are not available, install them for your coding agent: +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: ```bash databricks aitools install diff --git a/libs/template/templates/default/template/{{.project_name}}/CLAUDE.md.tmpl b/libs/template/templates/default/template/{{.project_name}}/CLAUDE.md.tmpl index 6dc3692c2b7..5612c9bde2f 100644 --- a/libs/template/templates/default/template/{{.project_name}}/CLAUDE.md.tmpl +++ b/libs/template/templates/default/template/{{.project_name}}/CLAUDE.md.tmpl @@ -1,6 +1,6 @@ # CLAUDE.md -Project guidance for AI agents lives in AGENTS.md (the cross-tool convention). +Project guidance for AI agents lives in AGENTS.md. Claude Code loads it via the import below. @AGENTS.md From 109d675372d37559e9032084bf1f843fa9863176 Mon Sep 17 00:00:00 2001 From: Lennart Kats Date: Tue, 21 Jul 2026 12:45:14 +0200 Subject: [PATCH 6/7] Add PR link to the AGENTS.md changelog fragment Co-authored-by: Isaac --- .nextchanges/bundles/agents-md-templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.nextchanges/bundles/agents-md-templates.md b/.nextchanges/bundles/agents-md-templates.md index 503f1e08231..52b6c8d47e1 100644 --- a/.nextchanges/bundles/agents-md-templates.md +++ b/.nextchanges/bundles/agents-md-templates.md @@ -1 +1 @@ -* Bundle templates now scaffold an `AGENTS.md` (with a `CLAUDE.md` that includes it) pointing coding agents at Databricks AI Tools. +Bundle templates now scaffold an `AGENTS.md` that points coding agents at Databricks AI Tools, alongside a one-line `CLAUDE.md` that includes it via `@AGENTS.md` ([#5996](https://github.com/databricks/cli/pull/5996)). From b0d8254faedaa7265a412be8c6a92da0932d641c Mon Sep 17 00:00:00 2001 From: Lennart Kats Date: Tue, 21 Jul 2026 20:53:29 +0200 Subject: [PATCH 7/7] Regenerate pipelines template goldens for AGENTS.md and CLAUDE.md The lakeflow-pipelines template reuses default via template_dir, so projects initialized by the pipelines/{init,e2e} acceptance tests now emit AGENTS.md and CLAUDE.md; add them to those tests' goldens. Co-authored-by: Isaac --- .../e2e/output/lakeflow_project/AGENTS.md | 25 +++++++++++++++++++ .../e2e/output/lakeflow_project/CLAUDE.md | 6 +++++ .../python/output/my_python_project/AGENTS.md | 25 +++++++++++++++++++ .../python/output/my_python_project/CLAUDE.md | 6 +++++ .../init/sql/output/my_sql_project/AGENTS.md | 25 +++++++++++++++++++ .../init/sql/output/my_sql_project/CLAUDE.md | 6 +++++ 6 files changed, 93 insertions(+) create mode 100644 acceptance/pipelines/e2e/output/lakeflow_project/AGENTS.md create mode 100644 acceptance/pipelines/e2e/output/lakeflow_project/CLAUDE.md create mode 100644 acceptance/pipelines/init/python/output/my_python_project/AGENTS.md create mode 100644 acceptance/pipelines/init/python/output/my_python_project/CLAUDE.md create mode 100644 acceptance/pipelines/init/sql/output/my_sql_project/AGENTS.md create mode 100644 acceptance/pipelines/init/sql/output/my_sql_project/CLAUDE.md diff --git a/acceptance/pipelines/e2e/output/lakeflow_project/AGENTS.md b/acceptance/pipelines/e2e/output/lakeflow_project/AGENTS.md new file mode 100644 index 00000000000..fdcca98a432 --- /dev/null +++ b/acceptance/pipelines/e2e/output/lakeflow_project/AGENTS.md @@ -0,0 +1,25 @@ +# Declarative Automation Bundles Project + +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. + +## For AI Agents: Use Databricks AI Tools + +**BEFORE any other action, read the `databricks-core` skill.** + +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. + +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: + +```bash +databricks aitools install +``` + +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install + +--- + +## Project Instructions + + diff --git a/acceptance/pipelines/e2e/output/lakeflow_project/CLAUDE.md b/acceptance/pipelines/e2e/output/lakeflow_project/CLAUDE.md new file mode 100644 index 00000000000..5612c9bde2f --- /dev/null +++ b/acceptance/pipelines/e2e/output/lakeflow_project/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md. +Claude Code loads it via the import below. + +@AGENTS.md diff --git a/acceptance/pipelines/init/python/output/my_python_project/AGENTS.md b/acceptance/pipelines/init/python/output/my_python_project/AGENTS.md new file mode 100644 index 00000000000..fdcca98a432 --- /dev/null +++ b/acceptance/pipelines/init/python/output/my_python_project/AGENTS.md @@ -0,0 +1,25 @@ +# Declarative Automation Bundles Project + +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. + +## For AI Agents: Use Databricks AI Tools + +**BEFORE any other action, read the `databricks-core` skill.** + +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. + +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: + +```bash +databricks aitools install +``` + +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install + +--- + +## Project Instructions + + diff --git a/acceptance/pipelines/init/python/output/my_python_project/CLAUDE.md b/acceptance/pipelines/init/python/output/my_python_project/CLAUDE.md new file mode 100644 index 00000000000..5612c9bde2f --- /dev/null +++ b/acceptance/pipelines/init/python/output/my_python_project/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md. +Claude Code loads it via the import below. + +@AGENTS.md diff --git a/acceptance/pipelines/init/sql/output/my_sql_project/AGENTS.md b/acceptance/pipelines/init/sql/output/my_sql_project/AGENTS.md new file mode 100644 index 00000000000..fdcca98a432 --- /dev/null +++ b/acceptance/pipelines/init/sql/output/my_sql_project/AGENTS.md @@ -0,0 +1,25 @@ +# Declarative Automation Bundles Project + +This project uses Declarative Automation Bundles (DABs) for deployment. Add project-specific instructions below. + +## For AI Agents: Use Databricks AI Tools + +**BEFORE any other action, read the `databricks-core` skill.** + +It sets you up to work with this project reliably: CLI authentication, profile +selection, data discovery, and the bundle deployment workflow. Without it, +results are often slower and less accurate. + +If this skill is not available (Databricks AI Tools are not installed), you can install them for your coding agent in seconds: + +```bash +databricks aitools install +``` + +If the CLI is not installed, see: https://docs.databricks.com/dev-tools/cli/install + +--- + +## Project Instructions + + diff --git a/acceptance/pipelines/init/sql/output/my_sql_project/CLAUDE.md b/acceptance/pipelines/init/sql/output/my_sql_project/CLAUDE.md new file mode 100644 index 00000000000..5612c9bde2f --- /dev/null +++ b/acceptance/pipelines/init/sql/output/my_sql_project/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +Project guidance for AI agents lives in AGENTS.md. +Claude Code loads it via the import below. + +@AGENTS.md