mcp: Instructions file for Codex

AGENTS.md

Do

• Use primary constructors for all C# classes
• Use System.Text.Json
• Make command classes sealed unless designed for inheritance
• Make members static when possible for AOT compatibility
• Put each class and interface in separate files
• Use subscription parameter (never subscriptionId) - supports both IDs and names
• Use resourceGroup (not resourceGroupName)
• Use singular nouns for resource names (e.g., server, not serverName)
• Run dotnet build after making changes
• Follow the {Resource}{Operation}Command naming pattern
• Use the two-generic pattern SubscriptionCommand<TOptions, TResult> for new commands
• Use [Option] attributes on flat POCO option classes for option declaration
• Use ISubscriptionOption interface on options classes that need subscription/tenant
• Always call HandleException(context, ex) in catch blocks
• Include live tests for all commands that interact with Azure resources
• Create Bicep templates for Azure service commands (test-resources.bicep)
• Include post-deployment scripts (test-resources-post.ps1)
• Record all live tests according to the guidelines in /docs/recorded-tests.md
• Submit one tool per pull request
• Use BaseAzureResourceService for Resource Graph queries when possible
• Register all response models in JSON serialization context for AOT safety
• Register all commands in the appropriate Setup.cs file
• Use concatenated lowercase for command group names (no dashes)
• Prefer file-scoped changes over project-wide modifications when possible
• Always review your own code for consistency, maintainability, and testability
• Always ask for clarifications if the request is ambiguous or lacks sufficient context
• Write transport-agnostic commands that work in both stdio and HTTP modes
• Keep commands stateless and thread-safe for multi-user remote scenarios
• Test commands with different RBAC permissions for OBO scenarios

Don't

• Use subscriptionId parameter name
• Add unnecessary "-name" suffixes (use --account vs --account-name)
• Use the old one-generic RegisterOptions/BindOptions pattern for new commands (see /docs/option-conversion.md)
• Use OptionDefinitions static classes for new commands (use [Option] attributes instead)
• Use options class inheritance hierarchies (use flat POCOs with interface constraints)
• Skip live tests, live test infrastructure, or test recordings for Azure service commands
• Redefine base class properties in Options classes
• Leave commands unregistered
• Skip error handling or comprehensive tests
• Use dashes in command group names (use concatenated lowercase)
• Make project-wide changes when file-scoped changes suffice
• Check transport type in commands (stdio vs HTTP)
• Store per-request state in command instance fields
• Access HttpContext directly from commands
• Make transport-specific decisions in command logic
• Assume single-user scenarios when implementing services
• Use git stash in linked worktrees; the stash stack is shared across worktrees and can collide during concurrent work