From 3f354c2b067f1d0b5297a9338d7b21373dbbbd0a Mon Sep 17 00:00:00 2001
From: yyh <92089059+lyzno1@users.noreply.github.com>
Date: Mon, 10 Aug 2026 19:04:18 +0800
Subject: [PATCH] docs(web): clarify ref mutation ownership (#40426)

---
 .agents/skills/how-to-write-component/references/runtime.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.agents/skills/how-to-write-component/references/runtime.md b/.agents/skills/how-to-write-component/references/runtime.md
index c2b5a667355..24554d895f5 100644
--- a/.agents/skills/how-to-write-component/references/runtime.md
+++ b/.agents/skills/how-to-write-component/references/runtime.md
@@ -4,6 +4,7 @@ Read this document when a change introduces Effects, navigation side effects, me
 
 ## Effects
 
+- Keep render pure: do not read or write `ref.current` during render except for predictable null-guarded lazy initialization. Update interaction-owned refs in event handlers, synchronize external-system refs after commit, and use state or derivation for rendered values.
 - Use Effects only to synchronize with a named external system such as a browser API, subscription, timer, analytics integration, non-React widget, or imperative DOM API.
 - Do not use Effects to transform render state, handle user actions, copy query data, reset state from props, or fetch data owned by framework APIs or TanStack Query.
 - Initialize query-backed forms with keyed remounts or surface-entry hydration instead of copying data through Effects.