🚨 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:

• Pipeline-level variables (az devops YAML)

• Variable groups (shared across pipelines)

• Azure Key Vault (secrets)

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