PRD - azure-functions-doctor

Overview

azure-functions-doctor is a diagnostic CLI for projects built on the Azure Functions Python v2 programming model.

It inspects a local project and reports common configuration, dependency, and environment issues before they surface during local runs or deployment.

Problem Statement

Azure Functions Python projects can fail for routine reasons that are easy to miss:

• missing host.json
• missing or incorrect azure-functions dependency
• unsupported Python configuration
• incomplete local development setup
• inconsistent project layout

These failures are often discovered late, through confusing runtime errors or deployment issues.

Goals

• Provide fast, readable diagnostics for Azure Functions Python v2 projects.
• Surface required and optional checks with clear pass/fail output.
• Support both local CLI use and CI integration.
• Keep checks aligned with representative example projects.

Non-Goals

• Fixing project issues automatically
• Replacing Azure Functions Core Tools
• Managing deployment workflows
• Supporting the legacy function.json-based Python v1 model

Primary Users

• Maintainers of Azure Functions Python repositories
• Developers setting up local Azure Functions projects
• Teams that want lightweight CI diagnostics for Functions projects

Core Use Cases

• Run diagnostics against the current project directory
• Run diagnostics against a specific example or target path
• Use a smaller profile for required-only checks
• Consume human-readable or machine-readable output in automation

Success Criteria

• Representative examples pass diagnostic smoke tests in CI
• Broken example copies fail in predictable ways
• CLI output remains stable enough for user troubleshooting and automation

Example-First Design

Philosophy

A diagnostic CLI earns trust by showing exactly what it does. azure-functions-doctor ships runnable example projects — both healthy and intentionally broken — so developers can see real pass/fail output before pointing the tool at their own code.

Quick Start (Hello World)

Run diagnostics against the representative example:

pip install azure-functions-doctor
azure-functions doctor --path examples/v2/http-trigger

Expected output shows a clean diagnostic pass:

Azure Functions Doctor

  [PASS] HOST_JSON_EXISTS
  [PASS] REQUIREMENTS_TXT_EXISTS
  [PASS] AZURE_FUNCTIONS_DEPENDENCY
  [PASS] V2_DECORATORS_USED
  ...

Result: All checks passed

Run against a broken example to see clear failure output:

azure-functions doctor --path examples/v2/broken-missing-host-json

Why Examples Matter

1. Lower entry barrier. Developers can run the CLI against bundled examples before applying it to their own project. The pass/fail contrast builds confidence.
2. AI agent discoverability. Tools like GitHub Copilot, Cursor, and Claude Code recommend libraries based on README, PRD, and example content. CLI output samples in documentation help AI agents understand what azure-functions-doctor does and when to suggest it.
3. Cookbook role. For niche ecosystems, examples/ and docs/ often serve as the primary learning material. Both healthy and broken examples teach diagnostic patterns.
4. Proven approach. FastAPI, LangChain, SQLAlchemy, and Pandas all achieved early adoption through extensive, copy-paste-friendly examples and clear output samples.

Examples Inventory

Role	Path	Pattern
Representative	examples/v2/http-trigger	Minimal HTTP trigger (passes all checks)
Representative	examples/v2/timer-trigger	Timer trigger (passes all checks)
Complex	examples/v2/multi-trigger	Multiple triggers in one app
Complex	examples/v2/blueprint	Blueprint-based modular routing
Broken	examples/v2/broken-missing-host-json	Missing host.json
Broken	examples/v2/broken-missing-requirements	Missing requirements.txt
Broken	examples/v2/broken-missing-azure-functions	Missing azure-functions dep
Broken	examples/v2/broken-no-v2-decorators	No v2 decorators

All examples are smoke-tested in CI. New diagnostic rules should ship with a corresponding broken example that demonstrates the failure.