home-assistant-best-practices
Native Home Assistant constructs for automations, helpers, scripts, and Lovelace dashboards.
- Prioritizes built-in conditions, triggers, and helpers over Jinja2 templates; includes decision workflow for choosing between native state conditions, numeric_state, time triggers, and template helpers
- Covers automation modes (single, restart, queued, parallel) with scenarios, entity_id vs device_id usage, and Zigbee button/remote patterns for ZHA and Zigbee2MQTT
- Provides safe refactoring workflow for entity renames, helper replacements, and trigger restructuring to prevent silent breakage across dashboards and scripts
- Documents anti-patterns (template conditions, wait_template polling, device_id brittleness) with native alternatives and reasoning
Home Assistant Best Practices
Core principle: Use native Home Assistant constructs wherever possible. Templates bypass validation, fail silently at runtime, and make debugging opaque.
Decision Workflow
Follow this sequence when creating any automation:
0. Gate: modifying existing config?
If your change affects entity IDs or cross-component references — renaming entities, replacing template sensors with helpers, converting device triggers, or restructuring automations — read references/safe-refactoring.md first. That reference covers impact analysis, device-sibling discovery, and post-change verification. Complete its workflow before proceeding.
Steps 1-5 below apply to new config or pattern evaluation.
1. Check for native condition/trigger
Before writing any template, check references/automation-patterns.md for native alternatives.