azure-sdk-for-net: Skill for Claude Code

Skill: mitigate-breaking-changes

Patterns and techniques for mitigating breaking changes when regenerating Azure management-plane .NET SDKs. Use these to preserve backward compatibility in the generated SDK surface.

When Invoked

Trigger phrases: "mitigate breaking changes", "fix breaking change", "customization patterns", "how to keep backward compat", "CodeGenType", "CodeGenSuppress", "markAsPageable", "hierarchyBuilding", "base type change".

SDK-Side Customizations (in SDK repo)

Use Custom/*.cs or Customization/*.cs partial classes (follow the package's existing structure) for .NET-side fixes.

Custom code file organization

Keep custom code types split into separate files:

• Put each custom type/partial type in its own .cs file.
• Name the file after the class it contains, for example src/Custom/Models/MyModel.cs for public partial class MyModel.
• Align the custom code folder structure with the generated code structure, such as using Models/ for model customizations and Extensions/ for extension customizations when those folders exist.
• Do not group multiple compatibility types in a single broad file such as Compatibility.cs; split them so each file name aligns with the class name.

Partial class (add members, suppress generated members)

// src/Custom/Models/MyModel.cs (or src/Customization/Models/MyModel.cs — follow the package's existing convention)
namespace Azure.ResourceManager.<Service>.Models
{
    public partial class MyModel
    {
        // Add computed properties, rename via [CodeGenMember], etc.
    }
}

[CodeGenType] — Override accessibility or rename a generated type

When a generated type is internal and @@access in client.tsp doesn't work (common for nested/wrapper types), use [CodeGenType] in Custom code to make it public:

// src/Custom/Models/MyPublicModel.cs
using Microsoft.TypeSpec.Generator.Customizations;

namespace Azure.ResourceManager.<Service>.Models
{
    [CodeGenType("OriginalTypeSpecModelName")]
    public partial class MyPublicModel
    {
    }
}