Azure Developer CLI

Azure Developer CLI best practices

Produce maintainable, secure, environment-aware azd projects by reading the repository manifest first, preserving the chosen IaC provider, and validating only the checks that apply.

When to invoke

• "Review this azd project."
• "Create or fix azure.yaml for this app."
• "How should this Azure Developer CLI template be structured?"
• "Troubleshoot azd provision, deploy, or pipeline config."
• "Migrate this app to an azd template with Bicep or Terraform."

Prerequisites and context

• Read azure.yaml before inferring services, paths, IaC provider, or deployment behavior.
• Find the configured infra.path, source projects, deployment scripts, .gitignore, and pipeline definitions before editing.
• Identify whether the task is create, migrate, review, deploy, or troubleshoot.
• Identify the active environment only when an environment-specific operation is required.
• Read bundled references on demand: references/project-structure.md, references/iac-and-environments.md, references/security-cicd-operations.md, and references/official-docs.md.

Safety guardrails

Project defaults

Modeling rules

For environments, use predictable names such as <project>-dev for shared environments and <alias>-dev for personal environments. Use azd env set, azd env unset, azd env set-secret, azd env refresh, -e, and --environment rather than hand-editing .env files or relying on implicit context.

Hooks and CI/CD

Prefer declarative IaC and native service configuration over hooks. Use root hooks for project-wide behavior, service hooks for service-specific behavior, and versioned scripts under scripts/azd for nontrivial logic. Set shell explicitly, provide windows and posix variants when necessary, keep hooks idempotent and noninteractive in CI, fail on errors unless intentionally nonblocking, and test with azd hooks run <hook-name>.

For CI/CD, keep the pipeline definition with the template, review generated changes from azd pipeline config, use short-lived federated credentials, run tests and IaC validation before provisioning, use explicit environments and --no-prompt, add production approval gates, and configure protected remote state before Terraform pipeline setup.

Validation commands

Run only checks applicable to the repository:

Application: existing formatter, linter, type-check, build, and tests
Bicep:      az bicep build --file infra/main.bicep
Terraform:  terraform fmt -check -recursive
            terraform init -backend=false
            terraform validate
AZD hooks:  azd hooks run <hook-name>
Packaging:  azd package

For a Bicep what-if or Terraform plan, choose the correct deployment scope and environment because the command can authenticate to Azure or read remote state.

Progressive disclosure and bundled resources

• references/project-structure.md: repository layout and azure.yaml guidance.
• references/iac-and-environments.md: Bicep, Terraform, parameters, outputs, layers, and environments.
• references/security-cicd-operations.md: secrets, hooks, CI/CD, deployment, and troubleshooting.
• references/official-docs.md: current Microsoft product documentation links.
• examples/azure.yaml: example manifest shape.

Output template

## Azure Developer CLI result — <project or task>

**Status:** changed | reviewed | blocked
**IaC provider:** Bicep | Terraform | unknown
**Environment assumptions:** <environment, subscription, tenant, region, or none>

| Area | Finding or change | Evidence | Follow-up |
| --- | --- | --- | --- |
| azure.yaml | <service/path/provider result> | `<file/path>` | <next action> |
| infra | <Bicep/Terraform result> | `<file/path>` | <next action> |
| security | <secret/state/identity result> | `<evidence>` | <next action> |
| validation | <command> | pass | fail | not run | <why> |

**Cloud-changing commands not run:** <azd up/provision/deploy/down/pipeline config or none>
**Preview or beta features:** <feature or none>

Quality gate

• azure.yaml was read before service, provider, or path conclusions were made.
• azure.yaml paths exist and service settings match source projects.
• The IaC entry point and provider agree with azure.yaml.
• Required deployment outputs match variables consumed by services, hooks, and pipelines.
• .gitignore excludes .azure, secrets, local state, and generated artifacts.
• No secret appears in tracked content or command output.
• Applicable Bicep, Terraform, hook, package, application, or pipeline checks were run or explicitly deferred.
• Documentation explains prerequisites, environment creation, deployment, verification, and cleanup when this skill changes template behavior.