🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

• •❌ WRONG: D:/repos/project/file.tsx
• •✅ CORRECT: D:\repos\project\file.tsx

This applies to:

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

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

• •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

Comprehensive best practices for creating and maintaining Azure DevOps YAML pipelines.

Pipeline Structure

Multi-Stage Pipelines:

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

Benefits:

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

Triggers and Scheduling

Best practices:

• •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

Hierarchy:

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

Security:

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

Caching

Implement caching for:

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

Impact:

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

Templates

Use templates for:

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

Benefits:

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

Security Practices

Essential:

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

Performance

Optimize:

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

Monitoring

Track:

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

Always verify best practices against latest Azure DevOps documentation.