From a2434f9aa3321feaf0e217375495efae31076a84 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Fri, 9 Oct 2026 07:09:33 -1000
Subject: [PATCH] [core] Document numeric scheduler ids in AGENTS.md (#20382)

---
 AGENTS.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index dc364e4e5c..d5d33b32af 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -177,6 +177,13 @@ file does, and it is the authority when they disagree. The most useful starting
         Pick the primitive by cadence: under 250 ms use a gated `loop()`; 500 ms and above use
         `set_interval`. Full reasoning, including why `set_interval` costs more below 500 ms:
         https://developers.esphome.io/architecture/components/advanced/#quick-rule-of-thumb
+    *   **Scheduler ids:** name a timer only when it must be cancelled or replaced, and use a
+        `static constexpr uint32_t` id, never a string. Ids are per component instance and cannot clash with other
+        components, so number them from 0 and keep all of a component's ids together in one place.
+        ```cpp
+        static constexpr uint32_t READ_TIMEOUT_ID = 0;
+        this->set_timeout(READ_TIMEOUT_ID, 50, [this]() { this->read_(); });
+        ```
     *   **Don't override a default with the same value:** if a base class method already returns what you
         want, do not override it. `Component::get_setup_priority()` returns `setup_priority::DATA`, so a
         component that wants `DATA` should simply leave it alone.