azure-api-review

Azure API Review -- Shared Rules

This skill contains cross-cutting API review rules that apply regardless of whether the specification is authored in OpenAPI v2 (Swagger) JSON or TypeSpec. These rules are the single source of truth -- referenced by the format-specific instruction files and review agents.

When to Use

• Reviewing Azure REST API specification PRs (OpenAPI JSON or TypeSpec)
• Building review agents or CI workflows that validate API specs
• Understanding Azure API design rules that span both OpenAPI and TypeSpec formats

Reference Files

Each reference file covers one cross-cutting rule area with:

• The canonical rule definition
• Links to authoritative external sources (RPC contract, Azure REST API Guidelines, TypeSpec docs)
• Format-specific guidance for OpenAPI JSON and TypeSpec
• Rule IDs for citation in review findings

Authoritative External Sources

These external documents are the upstream authorities. When they conflict with each other, the precedence order is:

1. Azure Resource Provider Contract (RPC) -- ARM control-plane contract (highest precedence for ARM resources)
2. Azure REST API Guidelines -- general Azure API design (highest precedence for data-plane)
3. TypeSpec Azure library docs -- TypeSpec-specific patterns for Azure
4. ARM wiki / RP guidelines -- supplementary ARM guidance

Design Principles

These principles guide how the ARM API Reviewer agent, its instruction files, and reference files are designed and maintained:

1. Expert persona. The agent operates as a seasoned engineer -- meticulous, skeptical, and uncompromising on quality -- with years of hands-on experience designing APIs for Azure and other cloud providers: globally distributed, highly scalable, reliable, and secure services that have earned customer trust. It works alongside experienced human reviewers who hold every Azure service to the highest standards of security, reliability, consistency, performance, and maintainability. Missing a violation means a broken SDK, a security hole, or an inconsistency that millions of Azure customers will encounter. Findings should reflect depth of judgment, not mechanical rule-checking alone.
2. Consistency and reusability. Every rule is defined in exactly one place (a reference file or an instruction file section) and cross-referenced everywhere else. No duplication. When the same concept applies to OpenAPI and TypeSpec, the shared reference file covers both formats. File structure, naming, upstream-alignment comments, and severity levels follow uniform conventions across all files.
3. Low maintenance overhead. The files are designed so that maintainers spend minimal effort. Updates are needed only when upstream guidance (RPC contract, Azure REST API Guidelines, ARM wiki) changes. When that happens, a maintainer refreshes the affected instruction/reference files, updates the Upstream alignment date, and the change propagates through all cross-references automatically.

Maintenance & Upstream Alignment

The instruction files and reference files in this skill are derived from the authoritative external sources listed above. They are not replacements for those documents — they distill the most commonly violated rules into a structured format optimized for LLM-based review agents.

Why inline rules instead of raw document references: LLM review agents produce more consistent, actionable findings when rules are codified with explicit rule IDs, severity levels, and fix suggestions. Raw upstream documents are prose-heavy and not structured for automated consumption.

Keeping rules current:

• Each instruction file includes an Upstream alignment date in an HTML comment at the top. This date indicates when the rules were last verified against the upstream documents.
• When an upstream document changes a rule, the corresponding instruction file MUST be updated to match. The upstream document always takes precedence.
• Rules that overlap with existing linter checks are annotated with (Also enforced by: ...). The review agent should check CI results before flagging these to avoid duplicating linter findings.
• To avoid conflicts with the azure-typespec-author skill (used for TypeSpec code generation), coordinate rule changes with that skill's maintainers. A rule flagged by the reviewer agent should not contradict guidance given by the authoring agent.
• Formatting: After editing any .md file under skills/ or agents/, run npm run format from the .github/ directory (Prettier). Note: instruction files (*instructions.md) are excluded from Prettier via .prettierignore and do not need formatting.

Repository Documentation

These documents in this repo provide additional context:

• Breaking changes guidelines
• Uniform versioning
• Directory structure
• OpenAPI authoring automated guidelines
• Swagger extensions
• CI fix guide
• TypeSpec dev process

Relationship to Instruction Files

The format-specific instruction files reference these shared rules: