From 02c688429e40577510fad10c1e113cceb72b5d6d Mon Sep 17 00:00:00 2001
From: comfyanonymous <121283862+comfyanonymous@users.noreply.github.com>
Date: Sun, 26 Jul 2026 14:21:05 -0700
Subject: [PATCH] Update AGENTS.md (#15096)

---
 AGENTS.md | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 20014ce7edc..bfe0976fdc5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -162,8 +162,26 @@
   adding parallel code paths. Use `comfy.quant_ops`, `comfy.model_management`,
   `comfy.memory_management`, `comfy.pinned_memory`, `comfy_aimdo`, and
   `comfy-kitchen` helpers where they already solve the problem.
-- Use optimized comfy-kitchen ops in places where they improve performance
-  without changing the expected dtype, device, memory, or interface behavior.
+- Model implementations must use an existing optimized Comfy Kitchen or
+  ComfyUI operation whenever one supports the required math and tensor layout
+  without changing expected dtype, device, memory, or interface behavior. This
+  is the default implementation requirement, not an optional follow-up
+  optimization.
+- Before implementing model math, inspect the operations already exposed by
+  Comfy Kitchen, `comfy.quant_ops`, and existing ComfyUI model helpers. Check
+  for optimized single, paired, fused, layout-specific, and quantized variants
+  before writing a local implementation or composing lower-level torch ops.
+- Use the compatible optimized operation first and adapt the model's inputs to
+  its documented layout while preserving the model's exact math. If several
+  optimized variants apply, benchmark representative model shapes and select
+  the fastest valid path.
+- Add or retain a local implementation only when no existing optimized
+  operation supports the required math, layout, dtype, device, autograd, or
+  patch contract. Keep differentiable or patch-compatible fallbacks when the
+  optimized inference operation does not provide those contracts.
+- Use the existing ComfyUI cast, offload, and cleanup helpers for parameters
+  passed to optimized operations. Preserve model-specific epsilon, scaling,
+  layout, dtype, device, and output-shape behavior.
 - Prefer ComfyUI's shared optimized kernels and backend dispatchers over
   handwritten implementations of the same operation. Remove duplicate local
   kernels and adapt inputs to the shared operation's documented layout while