From e0d8000007beb22f66fb093399379de8f592075c Mon Sep 17 00:00:00 2001
From: Clyde Stubbs <2366188+clydebarrow@users.noreply.github.com>
Date: Thu, 26 Mar 2026 00:34:34 +1000
Subject: [PATCH] [ai] Add instructions regarding constructor parameters
 (#15091)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 .ai/instructions.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/.ai/instructions.md b/.ai/instructions.md
index 240a47a52fd..a7e08f9c4d5 100644
--- a/.ai/instructions.md
+++ b/.ai/instructions.md
@@ -124,6 +124,28 @@ This document provides essential context for AI models interacting with this pro
     *   **Indentation:** Use spaces (two per indentation level), not tabs
     *   **Type aliases:** Prefer `using type_t = int;` over `typedef int type_t;`
     *   **Line length:** Wrap lines at no more than 120 characters
+    *   **Constructor parameters vs setters:** Component properties that are both **required** and **invariant**
+        (never change after construction) should be constructor parameters rather than set via setter methods.
+        This makes the dependency explicit and prevents use of the object in an incompletely-initialized state.
+        In code generation, when calling `cg.new_Pvariable()` or the relevant helper function to create the component, pass these as arguments.
+        ```cpp
+        // Good - required invariant dependency as constructor parameter
+        class SourceTextSensor : public text_sensor::TextSensor, public Component {
+         public:
+          explicit SourceTextSensor(text::Text *source) : source_(source) {}
+         protected:
+          text::Text *source_;
+        };
+        ```
+        ```cpp
+        // Bad - required invariant dependency as setter
+        class SourceTextSensor : public text_sensor::TextSensor, public Component {
+         public:
+          void set_source(text::Text *source) { this->source_ = source; }
+         protected:
+          text::Text *source_{nullptr};
+        };
+        ```
 
 *   **Component Structure:**
     *   **Standard Files:**