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](references/project-structure.md)

- Bicep, Terraform, parameters, outputs, or environments: [references/iac-and-environments.md](references/iac-and-environments.md)

- Secrets, hooks, CI/CD, deployment, or troubleshooting: [references/security-cicd-operations.md](references/security-cicd-operations.md)

- Product details that may have changed: [references/official-docs.md](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 no