Internal documentation for contributors and AI coding agents working on the Azure Developer CLI (
azd).
For end-user documentation, see aka.ms/azd. For template examples, see awesome-azd.
Core mental models, terminology, and feature lifecycle.
- Glossary — Key terms and concepts used throughout the codebase
- Feature Stages — How features graduate from alpha → beta → stable
- Alpha Features — How experimental features are gated and discovered
Task-oriented how-tos for common contributor workflows.
- Contributing — How to build, test, lint, and submit changes
- Adding a New Command — End-to-end walkthrough for new CLI commands
- Creating an Extension — How to build and publish an azd extension
- Observability and Tracing — Adding telemetry, traces, and debugging
Schemas, flags, environment variables, and configuration details.
- Environment Variables — All environment variables that configure azd behavior
- azure.yaml Schema — Project configuration file reference
- Feature Status — Current maturity status of all features
System overviews, design context, and decision records.
- System Overview — High-level architecture and code organization
- Command Execution Model — How commands are registered, resolved, and run
- Extension Framework — gRPC-based extension system architecture
- Provisioning Pipeline — How infrastructure provisioning works
- ADR Template — Template for lightweight architecture decision records
| You want to document… | Put it in… |
|---|---|
| A new term or concept | docs/concepts/glossary.md |
| A how-to for contributors | docs/guides/ |
| A configuration reference | docs/reference/ |
| A system design or ADR | docs/architecture/ |
| Detailed implementation design | cli/azd/docs/design/ |
| Extension development details | cli/azd/docs/extensions/ |
| Style and coding standards | cli/azd/docs/style-guidelines/ |
- AGENTS.md — AI agent coding instructions
- cli/azd/docs/ — Detailed implementation-level documentation
- cli/azd/docs/style-guidelines/ — Code style guide
- cli/azd/docs/extensions/ — Extension framework details