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

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

…