Expert Bicep Bot

An Azure Bicep development agent that assists with writing, debugging, and optimizing Bicep templates for Azure infrastructure deployments, with expertise in resource types, API versions, and deployment patterns.

When to Use This Agent

Choose Expert Bicep Bot when:

• Need quick help writing Bicep resource definitions
• Debugging Bicep compilation errors or deployment failures
• Converting ARM JSON templates to Bicep syntax
• Finding the correct API version and property names for Azure resources
• Understanding Bicep language features (decorators, loops, conditions)

Consider alternatives when:

• Designing full production Bicep module architectures (use Expert Bicep Implement)
• Using Azure Verified Modules (use Azure Verified Modules Guru)
• Working with Terraform instead of Bicep (use a Terraform specialist)

Quick Start

Copy
# .claude/agents/expert-bicep-bot.yml
name: Expert Bicep Bot
description: Quick Bicep template writing and debugging
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - WebSearch

Example invocation:

claude "Write a Bicep template for Azure Container Apps with Dapr sidecar, custom domain, and auto-scaling rules"

Core Concepts

Bicep Language Reference

Feature	Syntax	Example
Parameter	param name string	param location string = 'eastus2'
Variable	var name = expr	var appName = 'myapp-${env}'
Resource	resource sym 'type@version'	resource vnet 'Microsoft.Network/...'
Module	module sym 'path'	module app './modules/app.bicep'
Output	output name type = value	output id string = resource.id
Loop	[for item in list: {}]	[for i in range(0,3): { ... }]
Condition	if (condition)	resource r '...' = if (isProd) { }
Existing	existing	resource kv '...' existing = { name: x }

Common Resource Patterns

Copy
// Container App with Dapr
resource containerApp 'Microsoft.App/containerApps@2023-05-01' = {
  name: 'myapp'
  location: location
  properties: {
    managedEnvironmentId: environment.id
    configuration: {
      ingress: {
        external: true
        targetPort: 3000
        transport: 'http'
        corsPolicy: {
          allowedOrigins: ['https://myapp.com']
        }
      }
      dapr: {
        enabled: true
        appId: 'myapp'
        appPort: 3000
        appProtocol: 'http'
      }
      secrets: [
        { name: 'db-connection', value: dbConnectionString }
      ]
    }
    template: {
      containers: [
        {
          name: 'myapp'
          image: '${acrName}.azurecr.io/myapp:latest'
          resources: {
            cpu: json('0.5')
            memory: '1.0Gi'
          }
          env: [
            { name: 'DB_CONNECTION', secretRef: 'db-connection' }
          ]
        }
      ]
      scale: {
        minReplicas: 1
        maxReplicas: 10
        rules: [
          {
            name: 'http-rule'
            http: { metadata: { concurrentRequests: '50' } }
          }
        ]
      }
    }
  }
}

// Loop: Deploy multiple storage containers
resource containers 'Microsoft.Storage/storageAccounts/blobServices/containers@2023-01-01' = [for name in containerNames: {
  parent: blobService
  name: name
  properties: {
    publicAccess: 'None'
  }
}]

// Conditional: Only deploy Redis in production
resource redis 'Microsoft.Cache/redis@2023-08-01' = if (environment == 'prod') {
  name: 'redis-${environment}'
  location: location
  properties: {
    sku: { name: 'Premium', family: 'P', capacity: 1 }
    enableNonSslPort: false
    minimumTlsVersion: '1.2'
  }
}

Configuration

Parameter	Description	Default
api_versions	Prefer latest API versions	latest-stable
style	Code style (compact, verbose)	verbose
linter_level	Bicep linter strictness (default, strict)	default
comments	Include inline comments	true
region_default	Default Azure region	resourceGroup().location
naming	Naming convention pattern	Azure CAF

Best Practices

1. Always specify API versions explicitly rather than using wildcards. API versions determine which properties are available and how they behave. Using the latest stable API version ensures access to current features. Pin the version so template behavior does not change when new API versions are released. Update API versions deliberately when you need new features.

2. Use string interpolation rather than concat() for readable templates. Bicep's '${prefix}-${name}-${suffix}' is clearer than the ARM JSON concat(variables('prefix'), '-', parameters('name'), '-', variables('suffix')). String interpolation produces identical output but is far more readable and less error-prone.

3. Declare resources with the minimum required properties. Include only the properties you explicitly want to set. Azure fills in defaults for omitted properties, and including default values clutters the template without adding value. When you need to override a default, include the property with a comment explaining why the default was changed.

4. Use @secure() decorator for any parameter containing secrets. Parameters marked @secure() are not logged in deployment history, are not visible in the Azure portal's deployment details, and are masked in CLI output. Never pass secrets as regular string parameters — they will be visible in deployment logs and ARM activity logs.

5. Validate templates with az bicep build before deploying. Catch syntax errors, type mismatches, and linter warnings locally before pushing to CI. Add az bicep build to pre-commit hooks or as the first CI step. Bicep's linter catches common issues like hardcoded resource names, missing descriptions, and deprecated API versions.

Common Issues

Bicep compilation succeeds but deployment fails with property validation errors. Bicep validates syntax but not Azure-specific property constraints. A property might have the right type (string) but an invalid value (empty string where Azure requires non-empty). Check the Azure REST API documentation for the specific resource type and API version to understand property constraints that go beyond Bicep type checking.

Child resources fail with "parent resource not found" even though it is in the template. Child resources (like Microsoft.Storage/storageAccounts/blobServices/containers) must correctly reference their parent. Use the parent property to establish the relationship: parent: storageAccount for the blob service, then parent: blobService for the container. Nested resource syntax (resource container 'containers' = { ... } inside the parent) also works but is less readable for deep nesting.

Template deploys successfully but resource configuration does not match expected values. Some Azure properties are read-only or are only set at creation time (cannot be updated). Check whether the property is marked as readOnly or createOnly in the API documentation. Properties marked as createOnly require deleting and recreating the resource to change. Check deployment outputs to verify the actual values applied.