home-assistant-best-practices

Home Assistant のベストプラクティス

基本原則： できる限り Home Assistant のネイティブ構成要素を使用してください。テンプレートは検証を迂回し、実行時にエラーが通知されないまま失敗し、デバッグを困難にします。

どのツールからも HA API にアクセスできませんか？ アクセス権を尋ねて作業を止めないでください。HA のウェブ UI をブラウザーで操作できる場合は、変更内容を保存する前に、まず正確な変更内容をユーザーに提示し、承認を待ってから UI で変更してください。クリックの承認だけでは、何が書き込まれるかをユーザーに示せません。それができない場合は、UI で作成する設定一式をユーザーに提示してください（オートメーションの場合はエディターの Edit in YAML モード用の YAML、ヘルパーの場合はフォームの各フィールド）。想定したエンティティ ID も明記してください。YAML でしか書き込めない設定は、File editor アプリ（または Container インストールでは設定フォルダー）で編集します。まずファイルのコピーを保存し、次に設定を確認して、Tools の YAML タブで該当するリロードを実行してください（2026.8 より前は Developer Tools という名称です。項目がなければ再起動してください）。

リリース番号（2026.5+）が付いた機能は、インスタンスのバージョンに依存します。 選択する前に確認してください。GET /api/config の version、または UI の Settings → About で確認できます。そのリリース以降であれば、その機能を使用し、古い方法を同等の選択肢として提示しないでください。バージョンを確認できない場合は、現行リリースを前提とし、古い方法を代替案として提示する際は、必要なバージョンを明記してください。

回答する前に、該当するリファレンスを読んでください。 このページでは、Reference Files にあるファイルの内容を要約しているにすぎません。正確なキー、フィールド、動作する例はそれらのファイルに記載されています。タスクに該当する行があるファイルだけをすべて読み、先にすべてのリファレンスファイルを読み込まないでください。

判断ワークフロー

オートメーションを作成するときは、次の手順に従ってください。

0. 判定：既存の設定を変更しますか？

変更がエンティティ ID、表示名、またはコンポーネント間の参照に影響する場合（エンティティやデバイスの名前変更、テンプレートセンサーからヘルパーへの置き換え、デバイストリガーへの変換、オートメーションの再構成など）は、まず safe-refactoring を読んでください。このリファレンスでは、影響分析、同じデバイスに属するエンティティの特定、表示名の上書き、変更後の検証について説明しています。先に進む前に、そのワークフローを完了してください。

以下の手順 1～5 は、新しい設定の作成またはパターンの評価に適用されます。

1. 目的に特化したトリガー／条件を確認し、次に汎用のネイティブトリガー／条件を確認する

2026.7 以降、標準の構成要素は目的に特化したトリガー／条件です。これは <domain>.<name> キー（動体検知、バッテリー残量低下、ドア開放など）と、エリア／フロア／ラベルのターゲットを使用します。まず意図に合うものがあるか確認し、次に汎用のネイティブトリガー／条件を確認してから、テンプレートを検討してください。トリガーを記述する前に、triggers-and-conditions #purpose-specific-triggers--conditions-default-since-20267 を読んでください。

目的に特化したトリガーでも、target: に entity_id を指定できます。そのため、既知のセンサーが 1 つあることを理由に trigger: state に切り替えないでください。目的に特化したトリガーを使ってオートメーションを記述し、任意のアップグレードとしてのみ提示することは避けてください。

よくある置き換え：

• 動体、占有、またはドアの binary_sensor に対する trigger: state → target: {entity_id: ...} またはエリアが既知の場合は area_id を指定した motion.detected／motion.cleared、occupancy.detected／occupancy.cleared、または door.opened／door.closed
• トリガー内に個別のセンサーエンティティを列挙 → エリア／フロア／ラベルの target: を指定した目的に特化したトリガー 1 つ
• 「どこでも N 分間動体が検知されない」ために motion.detected の後に delay を置く → options: {behavior: all, for: ...} を指定した motion.cleared。ターゲットとなるすべてのセンサーがその時間だけクリア状態になると 1 回だけ実行されます（unavailable および unknown のセンサーはカウントから除外されます）
• {{ states('x') | float > 25 }} → above: 25 を指定した numeric_state 条件
• {{ is_state('x', 'on') and is_state('y', 'on') }} → state 条件を使った condition: and
• {{ now().hour >= 9 }} → after: "09:00:00" を指定した condition: time

2. 組み込みヘルパーまたは Template Helper を確認する

テンプレートセンサーを作成する前に、helper-selection を読んでください。

よくある置き換え：

• 複数のセンサーの合計／平均 → min_max 統合
• いずれかがオン／すべてがオンというバイナリロジック → group ヘルパー
• 変化率 → derivative 統合
• しきい値の超過検出 → threshold 統合
• 消費量の追跡 → utility_meter ヘルパー

適切な組み込みヘルパーがない場合は、YAML ではなく Template Helper を使用してください。 HA の設定フローを使って作成してください（プログラムから、または UI から： Settings → Devices & Services → Helpers → Create Helper → Template）。フローで作成したヘルパーは UI で編集できますが、template: YAML エントリでは template.reload が必要で、UI からは編集できません。

ユーザーから依頼された場合、どちらの方法も使えない場合、または設定にフローの入力欄にないキーが必要な場合は、template: YAML を記述します。よくある例はトリガーベースのテンプレートと attributes: です。その場合は、手作業で編集せず、管理対象の YAML 編集（yaml-only-integrations）を使用してください。

3. 適切なオートメーションモードを選択する

デフォルトの single モードは適切でないことがよくあります。automation-actions #automation-modes を参照してください。

シナリオ	モード
タイムアウト付きの人感ライト	restart
順次処理（ドアロック）	queued
エンティティごとに独立したアクション	parallel
1回限りの通知	single

4. device_id より entity_id を使用する

デバイスを再追加すると device_id は無効になります。device-control を参照してください。

例外： Zigbee2MQTT の自動検出されたデバイストリガーは使用しても問題ありません。

5. ボタンとリモコンの場合

• event.* エンティティを公開する統合： そのエンティティを対象とする event.received を使用してください（下記のアンチパターンの行を参照）
• ZHA： イベントエンティティはありません。device_ieee を指定した event トリガーを使用してください（永続的です）
• Z2M： イベントエンティティは実験的な機能で、デフォルトでは無効です。自動検出された device トリガーまたは mqtt トリガーを使用してください

トリガーを記述する前に、device-control #buttonremote-patterns を読んでください。

---

重大なアンチパターン

アンチパターン	代わりに使用	理由	参照
float > 25 を使った condition: template	condition: numeric_state	キーとしきい値は読み込み時に検証されます。unavailable または unknown の状態は false になり、デフォルト値なしで float を使うとエラーが発生します	triggers-and-conditions #native-conditions
すでに条件を満たしている可能性がある場合に、状態トリガーを使った wait_for_trigger	wait_template	状態トリガーは状態が変化したときだけ発火するため、エンティティがその状態を離れて再び戻るまで待機するか、timeout がなければ永久に待機します（safe-refactoring #trigger-restructuring を参照）	automation-actions #wait-actions
トリガーでの device_id	entity_id（ZHA の場合は device_ieee）	デバイスを再追加すると device_id は無効になります	device-control #entity-id-vs-device-id
event.* エンティティがあるボタンに、インテグレーションのイベントバスイベント（例：hue_event）を使った event トリガー	そのエンティティを対象とする event.received を使い、値は event_types 属性から読み取る	インテグレーションが安定した一意の ID を維持している場合、エンティティは名前を変更でき、再追加後も維持されます。イベントバスのデータはインテグレーションごとに異なります	device-control #buttonremote-patterns
高コストなアクションを駆動する、ガードなしの numeric_state トリガー	trigger.from_state の unavailable／unknown を拒否する条件	再起動や一時的な途切れによってトリガーが再設定されると、値が変わっていなくてもしきい値をまたがずに発火します（このガードは実際のしきい値超過も除外します）	triggers-and-conditions #unavailable-arms-a-numeric-state-trigger
モーションライトに mode: single を使う	mode: restart	再トリガー時にタイマーをリセットする必要があります	automation-actions #automation-modes
automations.yaml のトップレベルキーとして enabled: false を指定する	一時的な無効化には automation.turn_off、恒久的な無効化にはエンティティレジストリで無効化する	有効なトップレベルキーではないため、スキーマ検証時に拒否され、オートメーションは unavailable として読み込まれます	automation-actions #disabling-automations
合計／平均のテンプレートセンサー	min_max ヘルパー	宣言的に記述でき、利用不可状態にも対応します	helper-selection #numeric-aggregation
しきい値付きのテンプレートバイナリーセンサー	threshold ヘルパー	ヒステリシスに標準対応しています	helper-selection #threshold
影響範囲を分析せずにエンティティ ID を変更する	safe-refactoring ワークフローに従う	名前を変更すると、ダッシュボード、スクリプト、シーン、Config-Entry データ、ストレージ内のダッシュボードが気付かれないまま動作しなくなります	safe-refactoring #entity-renames
Config-Entry ベースのグループ（UI グループ）のメンバーの名前を、メンバーシップを更新せずに変更する	レジストリで名前を変更した後、Options Flow でグループのメンバーシップを更新する	エンティティレジストリで名前を変更しても、Config Entry の options.entities は更新されないため、グループが気付かれないまま動作しなくなります	safe-refactoring #config-entry-groups
Min/Max ヘルパーやカスタム Config-Entry インテグレーション（例：Better Thermostat）で使われているエンティティの名前を、Config-Entry データを確認せずに変更する	Config Entry の data＋options を検索し、名前を変更したエンティティを Min/Max Options Flow で選び直します。data にエンティティを保持するインテグレーション（Better Thermostat）には API による修正方法がありません。ユーザーに伝え、名前を変更する前に完全バックアップを取得します	エンティティ ID は Config Entry に保存されており、レジストリで名前を変更しても更新されません。Threshold（2025.6 以降）や Generic Thermostat など、単一ソースのヘルパーは自動で更新されます	safe-refactoring #config-entry-data--blind-spots-for-entity-registry-renames
YAML の template: センサー／バイナリーセンサー	設定フローから Template Helper を使う	フローで作成したヘルパーはその場で再読み込みでき、UI で編集できますが、template: エントリーは設定の再読み込みが必要で、その場では再読み込みできません。実際に例外もあり、トリガーベースのテンプレートと attributes: にはフロー用のフィールドがありません	helper-selection #template-helpers
.storage/ ファイルなどの HA 内部状態を直接編集する	HA REST／WebSocket API を使って状態と設定エントリーを管理する	.storage/ ファイルは HA の内部状態データベースです。直接編集すると検証を迂回し、破損のリスクがあり、HA によって気付かれないまま上書きされる可能性があります	—
.storage/ 内でオートメーション設定を探す	HA 設定 API を通じてオートメーションを読み書きします。UI で作成したものは automations.yaml に保存されます	どの設定モードでも、オートメーション設定を保持する .storage/ ファイルはありません。.storage/ に保存されるのはオートメーションのエンティティレジストリエントリーだけです	—
YAML のみで設定するインテグレーションのために、configuration.yaml を手作業で直接編集する	バックアップと検証を備えた、管理された YAML 設定編集を使う	管理されていない編集では構文エラーが発生するリスクがあり、バックアップもなく、check_config も実行されません。管理された編集なら、そのすべてに対応できます	yaml-only-integrations
オートメーション／スクリプト／シーン用の YAML スニペットを生成する	HA 設定 API を使ってオートメーション／スクリプトをプログラムで作成します。API にアクセスできない場合は、代わりに UI エディター用の設定を提示します	API 呼び出しでは設定が検証され、構文エラーを防げるうえ、手動でのファイル編集や再起動が不要です	triggers-and-conditions, automation-actions, examples.yaml
インテグレーションの設定のために、ユーザーに configuration.yaml の編集を指示する	HA UI の「設定」>「デバイスとサービス」にユーザーを案内する	ほとんどのインテグレーションは UI で設定されます。YAML によるインテグレーション設定はまれで、インテグレーションごとに異なります	—
HA の「アドオン」と呼ぶ	「Apps」という用語を使う	HA は 2026.2 でアドオンの名称を Apps に変更しました。「Apps は Home Assistant と並行して実行されるスタンドアロンアプリケーションです」	—
ベンダーの部屋 ID を使った vacuum.send_command	セグメントがマッピング済みの場合は、cleaning_area_id に HA のエリア ID を指定した vacuum.clean_area	HA 標準のエリアを使用し、インテグレーション間で動作します。ただし、最初にエンティティ設定でセグメントをエリアにマッピングする必要があります	device-control #vacuum-control
ライトアクションで color_temp（ミレッド）を使う	値を変換して color_temp_kelvin を使う：ケルビン = 1,000,000 ÷ ミレッド（500 ミレッド = 2000 K）	color_temp パラメーターは 2026.3 で削除されました。ケルビンのみがサポートされます。また、HA は正の数ならどの値でも受け付けるため、ミレッド値をそのままコピーするとケルビンとして解釈されます（500 ミレッドは 500 K になります）	device-control #lights
一時的な変更後にデバイスを元に戻すため、状態や属性を variables: に保存する、または値をハードコードする	変更前に snapshot_entities を指定して scene.create を実行し、その後、そのシーンに対して scene.turn_on を実行する	スナップショットは電源がオフだったライトを含め、各エンティティ固有の状態を 1 回の呼び出しで保持します。変数を使う場合は属性ごとにテンプレートが必要で、エンティティごとに復元手順も必要です	scenes #snapshot--restore-scenecreate
Person／Device Tracker の entered_home／left_home デバイストリガー、または is_home／is_not_home 条件	state トリガーの to: home／to: not_home、または state 条件	これらは 2026.5 で削除されました。正しい代替手段は状態トリガーと状態条件です	triggers-and-conditions #presence-and-person-triggers-and-conditions-removed-in-20265
エリア／フロア／ラベルを対象にできるのに、トリガーでエンティティリストを使う	target: {area_id: ...} を指定した目的別トリガー	デバイスが変わってもオートメーションはエリアのメンバーシップに追従するため、古いエンティティリストが残りません	triggers-and-conditions #purpose-specific-triggers--conditions-default-since-20267
古い目的別キー（battery.low、vacuum.docked、timer.time_remaining、…）やトリガーの behavior: any／last	2026.7 で改名されたキー（battery.became_low、…）と、behavior: each／all（2026.6 で改名）	古いキーは読み込まれなくなります。古い動作値は修復に関する問題を発生させ、将来的に削除される予定です	triggers-and-conditions #purpose-specific-triggers--conditions-default-since-20267
AppDaemon：__init__ でコールバックを登録する、キャンセルしない run_in タイマー、インスタンス変数に状態を保持する、エンティティ ID をハードコードする	initialize() で登録し、再スケジュール前にキャンセルし、input_* ヘルパーを使って永続化し、self.args 経由で ID を渡す	いずれも、気付かれないまま失敗する、再読み込み時にリセットされる、または再利用を妨げます	appdaemon #appdaemon-specific-anti-patterns
ブループリント：エンティティをハードコードする、セレクターを使うべき箇所に自由入力テキストを使う、テンプレート内で !input を使う、source_url を省略する	型付きの !input セレクターを使い、テンプレートで使う前に入力を variables: に割り当て、必ず source_url を設定する	ハードコードすると再利用できなくなり、自由入力では入力ミスが発生し、!input はテンプレート値ではなく YAML タグです	blueprint-guide #common-pitfalls
バックアップ：1 つのオブジェクトの編集を元に戻すために完全復元する、取り消せない操作（レジストリの削除、インテグレーションの削除、Core／OS のアップグレード）の前にバックアップを取らない、取り消し方を示さずに操作を「元に戻せる」と呼ぶ	そのオブジェクトだけをロールバックし、操作前に バックアップを取り、具体的な取り消し操作を明示するか、取り消せない操作として扱う	完全復元すると、それ以降に行われた関係のない変更もすべて巻き戻され、HA が再起動します。操作後に取ったバックアップには、すでに損害が含まれています	backups #when-a-full-backup-earns-its-cost
ユーザーの明示的な確認なしにバックアップを復元／削除する、または Core／OS をアップグレードする	具体的な影響を説明して毎回確認し、回答を待つ。バックアップの有無は問いません	完全復元では、復元対象のすべての部分についてアーカイブ以降の変更が破棄され、HA が再起動します。Supervisor の部分復元では、選択したアーカイブ部分だけが上書きされます。削除すると復旧ポイントが失われます。Core／OS のアップグレードは影響が大きく、復旧手段はアップグレード前のバックアップです	backups
複数のテンプレートで同じ複雑な Jinja 式を繰り返す	ネイティブのトリガー／条件と組み込みヘルパーを使えないことを確認したら、config/custom_templates/*.jinja にマクロとして一度だけ定義してインポートする	ルールが変わったときに修正する定義を 1 つにでき、別々にずれていく複製を避けられます	template-guidelines #reusable-macros
インポートしたマクロ内で trigger、this、value_json、または {% set %} 変数を使う	マクロに引数として渡す	インポートでは呼び出し元のコンテキストは引き継がれません。マクロ内では変数が未定義となり、空に展開されます。また、変数の属性にアクセスするとエラーになります（states など HA 独自の関数はグローバルであり、使用できます）	template-guidelines #imports-do-not-carry-the-callers-context

---

参考ファイル

回答する前に、タスクに該当する行のファイルをそれぞれ読んでください。

ファイル	読むタイミング
safe-refactoring	エンティティやその表示名の変更、ヘルパーの置き換え、自動化の再構成、既存の設定の変更を行う場合
triggers-and-conditions	自動化のトリガーや条件を記述する場合：用途に特化したトリガーと標準のトリガー／条件、for: の期間、トリガー ID
automation-actions	自動化やスクリプトのアクションを記述する場合、またはそのモードを選択する場合：待機、変数、アクションの応答の取得、continue_on_error、スクリプト内の管理者専用アクション（Unauthorized）、シーケンスの停止、繰り返し、if/then と choose の使い分け、並列処理、ステップの文書化／注釈付け、自動化の無効化、複数の自動化にまたがる last_triggered を使った経過時間の測定、Mobile App の notify アクションとエンティティ — エンティティ ID をアクションとして使用すると action not found が発生します。トレースの保持 — トリガーの頻度が高いと、実行がデバッグ用の保存済みトレース 5 件から押し出されます
helper-selection	組み込みヘルパーとテンプレートセンサーのどちらを使うか決める場合 — 集計、変化率、しきい値、状態の継続時間、カウント／計時、スケジューリング、グループ化、確率的推論、平滑化、気候、ドメイン変換、判断マトリックス
template-guidelines	用途にテンプレートが適していることを確認する場合、または custom_templates マクロを使ってテンプレート間で Jinja ロジックを共有する場合
yaml-only-integrations	設定フローのない YAML 専用インテグレーション（例：command_line、プラットフォームベースの mqtt、rest）を作成または編集する場合
device-control	アクションやボタン／リモートの自動化を記述する場合、または target: を使う場合
scenes	シーンを作成または有効化する場合、一時的な変更の後にデバイスを元の状態に戻す方法を含む、スナップショット／復元パターンを使う場合、スナップショットとスクリプトの違いを確認する場合
dashboard-guide	Lovelace ダッシュボードを設計または変更する場合 — レイアウト、ビューの種類、ストラテジー、セクション、カード、バッジ、CSS スタイル、HACS
dashboard-cards	組み込みのカードタイプ（コア、エネルギー、レガシー）やカードのフィールドを確認する場所を調べる場合。エンティティカードの属性行 — type: attribute のない attribute: を指定した行には、属性ではなくエンティティの状態が表示されます
domain-docs	インテグレーション／ドメインのドキュメント、または特定のトリガー、条件、アクション専用のドキュメントページを調べる場合
examples.yaml	複数のベストプラクティスを組み合わせた例が必要な場合
appdaemon	AppDaemon アプリを扱う場合：ネイティブの HA と使い分けるタイミング、アプリの構造、アクション、スケジューリング、エラー処理、安全なリファクタリングの影響
blueprint-guide	再利用可能なブループリントを作成する場合：メタデータと source_url、入力とセレクター、target と entity の使い分け、デフォルト値、入力セクション、!input のテンプレート化、バージョン管理
backups	操作前にバックアップが必要か判断する場合、完全復元・部分復元・単一オブジェクトのロールバックから選ぶ場合、アーカイブに実際に含まれるもの、暗号化キーと緊急キット、復元の検証、バックアップ削除時に HA が保護するものと保護しないもの、Git の設定リポジトリが完全バックアップの代わりになるかを確認する場合