maf-doctor: Instructions file for GitHub Copilot

MAF Production Deployment — Patterns That Hold Up

This file is loaded when you edit a file that wires MAF into a host process (Program.cs, DI registration, infrastructure). The rules below are the ones we've learned the hard way — every one has a production incident behind it.

Identity — the rule that catches half of all incidents

// ❌ NEVER in production
services.AddSingleton<TokenCredential>(_ => new DefaultAzureCredential());

// ✅ Production
services.AddSingleton<TokenCredential>(_ => new ManagedIdentityCredential());

Why: DefaultAzureCredential walks a chain of credential providers (env vars, CLI, VS, IDE, MSI). In dev that's convenient. In prod it's a footgun: a dev's stale AZURE_* env var leaking into the container, an unintended az login token surviving in the build image, and silent fallback when MSI isn't available all produce subtle, hard-to-trace auth failures. The Roslyn analyzer MAF002 fires on any new DefaultAzureCredential() outside test code — keep it pinned to "warning" or escalate to "error" in CI.

When you NEED a fallback chain (e.g., for a tool that runs both locally and in the cloud), build the chain explicitly with ChainedTokenCredential — never rely on DefaultAzureCredential's implicit chain.

Cost — every chat-completion call needs a ceiling

// ❌ Unbounded — production cost incident waiting to happen
_agent = new ChatClientAgent(client, new ChatClientAgentOptions
{
    ChatOptions = new ChatOptions { Instructions = "..." }
});

// ✅ Always cap MaxOutputTokens
_agent = new ChatClientAgent(client, new ChatClientAgentOptions
{
    ChatOptions = new ChatOptions
    {
        MaxOutputTokens = 1024,        // hard ceiling — adjust per agent intent
        Instructions = "..."
    }
});

Why: A misbehaving prompt or an injection-induced "summarize this 30-page doc again" can blow through token budget in seconds. The MafEstimateCost tool surfaces every unbounded site; MafDoctor weights them into the grade. Default cap recommendation: 1024 for chat agents, 4096 for summarization agents, 8192+ ONLY for explicitly-scoped batch jobs.