🚨 CRITICAL GUIDELINES

Windows File Path Requirements

\

/

• ❌ WRONG:

  D:/repos/project/file.tsx

• ✅ CORRECT:

  D:\repos\project\file.tsx

• Edit tool file_path parameter
• Write tool file_path parameter
• All file operations on Windows systems

Documentation Guidelines

• Priority: Update existing README.md files rather than creating new documentation
• Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
• Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
• User preference: Only create additional .md files when user specifically asks for documentation

Azure Pipelines Best Practices

Pipeline Structure

# Recommended structure
stages:
  - stage: Build
  - stage: Test
  - stage: DeployDev
  - stage: DeployStaging  
  - stage: DeployProduction

• Clear separation of concerns
• Conditional stage execution
• Environment-specific configurations
• Approval gates between stages

Triggers and Scheduling

• Use path filters to avoid unnecessary builds
• Enable batch builds for high-frequency repos
• Use PR triggers for validation
• Schedule nightly/weekly builds for comprehensive testing

trigger:
  batch: true
  branches:
    include: [main, develop]
  paths:
    exclude: ['docs/*', '**.md']

pr:
  autoCancel: true
  branches:
    include: [main]

schedules:
  - cron: '0 0 * * *'
    displayName: 'Nightly build'
    branches:
      include: [main]
    always: false  # Only if code changed

Variable Management

1. Pipeline-level variables (az devops YAML)
2. Variable groups (shared across pipelines)
3. Azure Key Vault (secrets)
4. Runtime parameters (user input)

• Never hardcode secrets
• Use Key Vault for sensitive data
• Mark secrets in variable groups
• Secrets are automatically masked in logs

Caching

• Package dependencies (npm, pip, NuGet, Maven)
• Docker layers
• Build outputs

• Faster builds (up to 90% reduction)
• Reduced network usage
• Lower costs

Templates

• Reusable build patterns
• Standardized deployment steps
• Consistent security scanning
• Company-wide best practices

• DRY (Don't Repeat Yourself)
• Centralized updates
• Consistent processes

Security Practices

• Code scanning (SAST, dependency)
• Container image scanning
• Secret scanning
• Compliance checks
• Branch protection policies
• Required approvals

Performance

• Parallelize independent jobs
• Use caching extensively
• Shallow git clones (fetchDepth: 1)
• Appropriate agent pools
• Clean up artifacts

Monitoring

• Build success rates
• Build durations
• Test pass rates
• Deployment frequency
• Mean time to recovery (MTTR)