williamlimasilva/azure-developer-cli

Azure Developer CLI best practices

Use this skill to produce maintainable, secure, environment-aware azd projects. Prefer repository conventions when they are already coherent, and make the smallest complete change that improves the project.

Start with repository discovery

Before editing:

1. Find azure.yaml, the configured infra.path, source projects, deployment scripts, .gitignore, and pipeline definitions.
2. Read azure.yaml before inferring services or the IaC provider.
3. Identify whether the task is to create, migrate, review, deploy, or troubleshoot.
4. Identify the active environment only when an environment-specific operation is required.
5. Read the relevant reference:
   • Repository layout or azure.yaml: references/project-structure.md
   • Bicep, Terraform, parameters, outputs, or environments: references/iac-and-environments.md
   • Secrets, hooks, CI/CD, deployment, or troubleshooting: references/security-cicd-operations.md
   • Product details that may have changed: references/official-docs.md

Do not assume the default infra path, the default Bicep provider, or a single service when azure.yaml says otherwise.

Apply safety guardrails

• Never commit .azure, environment .env files, credentials, deployment outputs containing secrets, local Terraform state, or generated deployment artifacts.
• Never put literal secrets in azure.yaml, IaC parameter files, hooks, source control, command arguments that will be logged, or IaC outputs.
• Prefer managed identities and RBAC. Use Key Vault references and azd env set-secret when a secret is unavoidable.
• Before a command that can create, modify, or delete Azure resources, confirm the target environment, subscription, tenant, region, and expected scope.
• Treat an explicit user request to deploy, provision, destroy, or configure a pipeline as approval for that named action. Otherwise, ask before running azd up, azd provision, azd deploy, azd down, or azd pipeline config.
• Do not replace Bicep with Terraform, Terraform with Bicep, or an established hosting service unless the user requests that architectural change.
• Preserve resources and state owned outside the current azd project.

Use these defaults

| Concern | Preferred default | | --- | --- | | Project manifest | One azure.yaml at the repository root | | Application code | src/<service-name> per independently deployable service | | Infrastructure | infra with a thin entry point and reusable modules | | IaC provider | Bicep unless the repository or user chooses Terraform | | Deployment environments | Separate named environments for dev, test, staging, and production | | Local AZD state | .azure/<environment-name> and excluded from source control | | Shared environment state | AZD remote environments backed by Azure Blob Storage | | Secrets | Managed identity/RBAC first, then Key Vault references | | Automation scripts | Short, idempotent scripts under scripts/azd | | CI authentication | Workload identity federation/OIDC where supported | | Routine development | azd up for simple workflows; separate phases for controlled workflows |

Implementation workflow

1. Model the application

• Define one services entry for each independently deployable component.
• Keep service keys stable because they participate in resource discovery and deployment.
• Map each service to its actual project, language, and host.
• Keep shared infrastructure in IaC rather than inventing a fake deployable service.
• Declare dependencies with supported azure.yaml fields instead of relying on file order.

2. Model infrastructure

• Keep main.bicep or main.tf as the orchestration entry point.
• Split reusable or independently understandable infrastructure into modules.
• Parameterize environment-specific values; do not fork the IaC tree per environment.
• Output only stable, nonsecret values required by deployment or application configuration.
• Use deterministic naming and consistent tags that include the project and environment.
• Add role assignments to identities rather than distributing service keys.
• Use infrastructure layers only when separate scopes or lifecycle dependencies justify them.

3. Model environments

• Use predictable names such as <project>-dev for shared environments and <alias>-dev for personal environments.
• Use azd env set, azd env unset, and azd env set-secret rather than editing .env directly.
• Use -e or --environment in scripts and automation so the target is explicit.
• Use azd env refresh to synchronize deployment outputs after another actor changes an environment.
• Configure AZD remote state when a team shares environment state.

4. Add hooks only for lifecycle gaps

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

5. Build CI/CD deliberately

• Keep the pipeline definition with the template and review generated changes from azd pipeline config.
• Use short-lived federated credentials where the provider supports them.
• Run tests and IaC validation before provisioning.
• Use explicit environments and --no-prompt in automation.
• Add protected production environments and approval gates.
• For Terraform, configure protected remote state before pipeline setup and account for current AZD authentication limitations.

Validate before finishing

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. These checks can authenticate to Azure or read remote state, so follow the safety guardrails.

Verify that:

• azure.yaml paths exist and service settings match the source projects.
• The IaC entry point and provider agree with azure.yaml.
• Required deployment outputs match the 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.
• Documentation explains prerequisites, environment creation, deployment, verification, and cleanup.

Report the result

State:

• The files and behavior changed.
• The IaC provider and environment assumptions.
• The checks performed.
• Any cloud-changing command deliberately not run.
• Any beta or preview feature the solution relies on.

Do not claim deployment success unless the target environment was actually deployed and verified.