GitHub Copilot Instructions for All Projects

---

applyTo: "**"

Core Development Principles

Code Quality & Maintainability

• Readability First: Prioritize clear, self-documenting code over clever solutions
• Comprehensive Documentation: Include meaningful comments explaining business logic, not just syntax
• Error Handling: Implement robust exception handling with specific, actionable error messages
• Design Decisions: Document architectural choices and trade-offs in comments
• Performance Considerations: Comment on time/space complexity for algorithms and optimization decisions

Testing & Validation

• Test-Driven Approach: Include unit tests for all critical functions and edge cases
• Edge Case Coverage: Handle empty inputs, null values, invalid data types, boundary conditions, and large datasets
• Test Documentation: Write descriptive test names and include comments explaining test scenarios
• Integration Testing: Consider end-to-end test scenarios for complex workflows

Security Best Practices

• Input Validation: Sanitize and validate all user inputs
• Least Privilege: Apply minimal necessary permissions and access rights
• Secrets Management: Never hardcode credentials; use secure configuration management
• Encryption: Implement encryption for sensitive data at rest and in transit
• Audit Logging: Include security-relevant event logging for compliance and monitoring

Language-Specific Guidelines

PowerShell Scripts

Every PowerShell script should begin with comprehensive help documentation:

<#
.SYNOPSIS
    Brief description of the script's primary function

.DESCRIPTION
    Detailed explanation of what the script does, its dependencies, and usage scenarios

.PARAMETER ParameterName
    Description of each parameter, including type and valid values

.EXAMPLE
    Example-Command -Parameter "Value"
    Description of what this example demonstrates

.NOTES
    Author: [Author Name]
    Created: [Date]
    Version: [Version Number]
    Dependencies: [Required modules/versions]
    
.LINK
    Related documentation or repository links
#>

Python Development

• Style Guide: Strictly follow PEP 8 with these specifics:
  • Use 4 spaces for indentation (no tabs)
  • Maximum line length: 88 characters (Black formatter standard)
  • Use type hints for function parameters and return values
  • Include comprehensive docstrings using Google or NumPy style
• Package Management: Use requirements.txt or pyproject.toml for dependency management
• Virtual Environments: Always specify virtual environment setup instructions

JavaScript/TypeScript

• Modern Standards: Use ES6+ features and TypeScript where possible
• Linting: Follow ESLint and Prettier configurations
• Documentation: Use JSDoc comments for functions and classes
• Error Handling: Implement proper async/await error handling patterns

C# .NET

• Conventions: Follow Microsoft C# coding conventions
• Documentation: Use XML documentation comments
• Async Patterns: Properly implement async/await patterns
• Dependency Injection: Use built-in DI container patterns

Microsoft Azure Development Guidelines

Azure Well-Architected Framework Priority

Follow these pillars in order of importance:

1. Security: Zero-trust architecture, identity-based access, encryption, compliance
2. Operational Excellence: Monitoring, automation, DevOps practices, incident response
3. Performance Efficiency: Scalability, load testing, caching strategies, optimization
4. Reliability: High availability, disaster recovery, fault tolerance, backup strategies
5. Cost Optimization: Resource right-sizing, reserved instances, cost monitoring, governance

Infrastructure as Code (IaC) Standards

• Multi-Tool Support: Provide solutions for Bicep (preferred), Terraform, and PowerShell
• Environment Strategy: Support dev/staging/production with parameter-driven configuration
• Modularity: Create reusable, composable modules following DRY principles
• CI/CD Integration: Ensure compatibility with GitHub Actions and Azure DevOps Pipelines
• Local Testing: Include standalone execution capabilities for development and testing

Deployment Strategy & Feature Management

• Safe Deployment Practices:
  • Ring-based deployments (canary → early adopters → broad deployment)
  • Blue-green deployment strategies where applicable
  • Automated rollback mechanisms
• Feature Flags:
  • Implement removable feature flags that don't impact existing resources
  • Provide clear migration paths when features become permanent
  • Include warnings for changes affecting deployed solutions
• Change Management: Small, incremental changes over large deployments

Default Configuration Standards

• Primary Regions: Use these as defaults (configurable via parameters):
  • Primary: swedencentral (for European compliance/GDPR)
  • Secondary: germanywest (for disaster recovery)
  • Alternative: uksouth (fallback option)
• Naming Conventions:
  • Variables: snake_case at file top
  • Parameters: camelCase with validation
  • Resources: Consistent prefixing with environment indicators
• Validation: Include parameter validation with clear error messages

Performance & Quality Metrics

Track these KPIs for deployment effectiveness:

• DORA Metrics:
  • Deployment frequency
  • Lead time for changes
  • Change failure rate
  • Mean time to recovery (MTTR)
• Business Metrics:
  • Customer satisfaction scores
  • System availability percentages
  • Performance benchmark compliance
• Security Metrics:
  • Security vulnerability resolution time
  • Compliance audit success rate
  • Incident response effectiveness

Additional Best Practices

• Infrastructure Testing: Include validation scripts, compliance checks, and integration tests
• Documentation: Comprehensive README files, architecture diagrams, deployment guides
• Monitoring & Alerting: Implement comprehensive observability from day one
• Version Control: Semantic versioning, proper branching strategies, pull request workflows
• Security Integration: SAST/DAST scanning, dependency vulnerability checks, compliance validation
• Cost Management: Budget alerts, resource tagging strategies, regular cost reviews
• Community Engagement: Reference Azure documentation, participate in Azure community discussions

Multi-Perspective Code Review

For every Azure solution, provide analysis from these viewpoints:

1. Site Reliability Engineer: Scalability, monitoring, incident response capabilities
2. Operations Manager: Deployment complexity, maintenance overhead, team training needs
3. Security Consultant: Threat model compliance, access controls, data protection
4. Microsoft Technical Specialist: Azure best practices adherence, service optimization
5. Business Analyst: Cost implications, business value alignment, ROI considerations
6. On-call Engineer: Troubleshooting capabilities, alerting quality, documentation clarity

Azure Bicep Development Standards

Project Organization & Structure

• File Location: Place all Bicep files under the infra/ folder unless explicitly specified
• Module Architecture: Organize deployments into logical, reusable modules
• Scope Strategy: Use targetScope = 'resourceGroup' by default, escalate to subscription level when needed
• Regional Strategy: Default to swedencentral with parameterized location support

Template Metadata & Documentation

Begin every Bicep template with comprehensive metadata:

metadata name = 'resourceName'
metadata description = 'Clear description of template purpose and deployed resources'
metadata owner = 'Jonathan Vella'
metadata version = '1.0.0'
metadata lastUpdated = '2025-01-25'
metadata documentation = 'Link to detailed documentation or README'

Parameter & Variable Conventions

Standardized Parameter Naming:

• Use double underscores for parameters: __location__, __environment__, __resourcePrefix__
• Use single underscores for variables: _storageAccountName_, _keyVaultName_

Required Standard Parameters:

@description('Azure region for resource deployment')
@allowed(['swedencentral', 'norwayeast', 'westeurope'])
param __location__ string = 'swedencentral'

@description('Environment designation for resource deployment')
@allowed(['dev', 'test', 'staging', 'prod'])
param __environment__ string

@description('Resource tags for governance and cost tracking')
param __tags__ object = {}

@description('Prefix for consistent resource naming')
@minLength(2)
@maxLength(5)
param __resourcePrefix__ string

Security & Compliance Framework

• Identity Management: Implement managed identities over service principals
• Network Security: Deploy private endpoints, NSGs, and Azure Firewall where appropriate
• Data Protection: Enable encryption at rest and in transit for all data services
• Access Control: Apply RBAC with least-privilege principles
• Monitoring: Configure diagnostic settings and security monitoring for all resources
• Compliance: Enable Microsoft Defender for Cloud and compliance frameworks

Cost Optimization Strategies

• SKU Flexibility: Provide multiple tier options with clear cost implications
• Resource Sizing: Include scaling configurations and auto-scaling where beneficial
• Storage Optimization: Implement appropriate storage tiers and lifecycle policies
• Development vs Production: Use cost-effective configurations for non-production environments

Resource Naming & Tagging Strategy

Implement consistent naming and comprehensive tagging:

var _defaultTags_ = union(__tags__, {
  Environment: __environment__
  Owner: 'Jonathan Vella'
  CreatedBy: 'Bicep'
  LastModified: utcNow('yyyy-MM-dd')
  CostCenter: 'IT-Infrastructure'
  Project: 'BrewBliss'
})

var _resourceToken_ = toLower(uniqueString(subscription().id, resourceGroup().id))
var _storageAccountName_ = 'st${__resourcePrefix__}${__environment__}${_resourceToken_}'

Error Prevention & Validation

• Parameter Validation: Use @allowed, @minLength, @maxLength, and custom validation
• Conditional Logic: Implement proper conditional deployments and resource dependencies
• Output Standards: Provide meaningful outputs for integration and troubleshooting
• Dependency Management: Explicitly define resource dependencies using dependsOn where needed

Template Modularity & Reusability

• Single Responsibility: Each module should have a clear, single purpose
• Parameter Passing: Minimize parameter complexity while maintaining flexibility
• Nested Templates: Use child templates for complex, multi-resource deployments
• Module Versioning: Implement semantic versioning for module libraries

Documentation & Maintenance

• Inline Comments: Explain complex logic, business requirements, and architectural decisions
• Deployment Instructions: Include step-by-step deployment guides in template headers
• Parameter Examples: Provide sample parameter files for different environments
• Change Logs: Document version changes and breaking modifications

Output Standards & Integration

Always include these essential outputs:

@description('Resource ID for downstream integrations')
output resourceId string = deployedResource.id

@description('Resource URI for application configuration')
output resourceUri string = deployedResource.properties.endpoint

@description('Resource name for reference in other templates')
output resourceName string = deployedResource.name

Terraform Coding Guidelines

Code Style & Structure

• Use Terraform v1.9+ features where possible.
• Use consistent indentation (2 spaces) for readability.
• Group related resources logically (e.g., networking, compute, storage).
• Keep resource blocks short and well-organized—avoid large, complex blocks.

Module Usage

• Prefer reusable modules over repeating code.
• Use the standard module structure: main.tf, variables.tf, outputs.tf, README.md.
• For shared modules, source them from the approved GitHub organization or the Terraform Registry.

Variables & Outputs

• All variables must have descriptions and types defined.
• Avoid hardcoding values—use variables or locals.
• Outputs should be meaningful and named consistently for reuse in parent modules.

Security & Secrets

• Never hardcode secrets or credentials.
• Use environment variables or secure backends like Azure Key Vault, AWS Secrets Manager, or Vault.
• Mark sensitive outputs with sensitive = true.

Validation & Testing

• Include terraform validate and terraform fmt -check in CI.
• Use pre-commit hooks to enforce formatting and checks before merge.
• Run terraform plan with a named workspace in all pipelines.

Naming & Tags

• Use azurecaf_naming_convention for naming resources.
• Apply consistent naming with project, environment, and region prefixes (e.g., app-dev-brew-swc01).
• All resources must include the following tags:
  • Name
  • Environment
  • Owner

Comments & Documentation

• Add comments for complex resources or unusual patterns.
• Include a README.md in each module with usage examples and input/output documentation.