plan-forge bicep.instructions.md

Bicep Best Practices

File Structure

infra/
├── main.bicep                  ← entry point, orchestrates modules
├── main.bicepparam             ← deployment parameters (per environment)
├── abbreviations.json          ← resource type abbreviation lookup
├── bicepconfig.json            ← linter configuration
└── modules/
    ├── networking.bicep
    ├── compute.bicep
    ├── storage.bicep
    └── security.bicep

Parameters

// ✅ Always use @description — describe what and why
@description('The environment name, used for resource naming and tagging.')
@allowed(['dev', 'test', 'staging', 'prod'])
param environmentName string

// ✅ Enforce length constraints where naming rules apply
@description('Short workload name used in resource names. 2–8 chars.')
@minLength(2)
@maxLength(8)
param workloadName string

// ✅ @secure on all secret parameters — never surfaces in logs
@description('The admin password for the database.')
@secure()
param dbAdminPassword string

// ❌ NEVER provide a non-empty default for a @secure param
@secure()
param secret string = ''      // ← only empty string is acceptable

Naming

// ✅ Use uniqueString() with a prefix for globally unique names
var storageAccountName = 'st${workloadName}${environmentName}${uniqueString(resourceGroup().id)}'

// ✅ Use template expressions for all resource names
var keyVaultName = 'kv-${workloadName}-${environmentName}-${uniqueString(resourceGroup().id)}'

// ✅ camelCase for symbolic names — never include "Name" suffix
resource keyVault 'Microsoft.KeyVault/vaults@2023-07-01' = { ... }

// ❌ NEVER hardcode resource names
resource keyVaultName 'Microsoft.KeyVault/vaults@2023-07-01' = { ... }

Resource Definitions

// ✅ Use resource properties as outputs — don't fabricate URLs
output appUrl string = appService.properties.defaultHostName

// ❌ NEVER construct URLs manually
output appUrl string = 'https://${appServiceName}.azurewebsites.net'

// ✅ Implicit dependencies via symbolic references
resource appService 'Microsoft.Web/sites@2023-01-01' = {
  properties: {
    serverFarmId: appServicePlan.id   // ← implicit dependency
  }
}

// ✅ Use existing keyword for cross-resource references
resource existingKv 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: keyVaultName
}

// ✅ child resources via parent property — never construct child names manually
resource secret 'Microsoft.KeyVault/vaults/secrets@2023-07-01' = {
  parent: keyVault
  name: 'mySecret'
  properties: { value: secretValue }
}

// ✅ Extract complex expressions into variables
var appServiceConfig = {
  alwaysOn: environmentName == 'prod'
  minTlsVersion: '1.2'
  ftpsState: 'Disabled'
}