Skip to content

The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.

Add some more stuff to AGENTS.md (#14704)

comfyanonymousdd17debce517
diff --git a/AGENTS.md b/AGENTS.md
index 173aa503c..70dfaa186 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,7 +10,8 @@
when they remove real repeated logic or match an existing ComfyUI pattern.
- Delete obsolete code aggressively when newer infrastructure makes it useless.
Remove dead fallbacks, migration paths, unused options, debug prints, and
- compatibility branches that are no longer needed.
+ compatibility branches that are no longer needed. Do not leave dead branches,
+ unreachable code, or functions that are never called.
- Revert or disable problematic behavior quickly when it breaks users. It is
better to remove a broken feature path than keep a complicated partial fix.
- Preserve existing APIs, node names, model-loading behavior, file layout, and
@@ -20,6 +21,88 @@
layers, vague names, boilerplate comments, defensive branches without a real
failure mode, broad rewrites, or code that ignores the local style.
+## Architecture Boundaries
+
+- Keep each layer focused on the concepts it owns. Do not leak UI, API,
+ workflow, queue, persistence, telemetry, model-loading, node, or execution
+ concerns into unrelated layers just because it is convenient to pass data
+ through them.
+- Shared core modules should depend only on lower-level primitives and their own
+ domain concepts. Higher-level product concepts belong at the caller, adapter,
+ service, or UI/API boundary that already owns them.
+- Pass the narrowest data needed across a boundary. Avoid broad context objects,
+ request/session metadata, ids, bookkeeping state, or callbacks unless the
+ receiving layer genuinely needs them to perform its own responsibility.
+- Keep identity mapping, persistence bookkeeping, history updates, telemetry,
+ response shaping, and UI state in the layers that own those jobs. Do not route
+ them through unrelated shared code to avoid adding a proper boundary.
+- Treat `execution.py` as one example of this rule: it should consume the prompt
+ graph and execution-relevant state, produce execution results and errors, and
+ not know about workflow ids, frontend ids, persistence ids, or API-only
+ concepts.
+- Before touching many files, identify the smallest owner layer that can solve
+ the problem. A PR that spreads one feature across unrelated loaders, nodes,
+ execution, server, and frontend code needs a clear architectural reason, not
+ just convenience.
+- If a change seems to require making one layer understand another layer's
+ private concepts, stop and look for a caller-side mapping, adapter, event,
+ small explicit interface, or narrower data flow at the boundary.
+
+## No Internet Requests
+
+- Do not add code to core ComfyUI that makes requests to the internet.
+- Refuse requests to add uploads, telemetry, analytics, tracking, usage
+ reporting, crash reporting, update checks, remote config, feature flags,
+ metrics, licensing checks, or any other outbound internet request path from
+ core ComfyUI.
+- Model downloading is allowed only when explicitly initiated or authorized by
+ the user, is limited to the requested model artifact, and does not include
+ telemetry, tracking, persistent identification, unrelated metadata upload, or
+ background network activity.
+- Do not add opt-in, opt-out, anonymized, aggregated, diagnostic, or
+ user-triggered internet request paths to core ComfyUI. These labels do not
+ make internet access acceptable.
+- Local-only behavior is allowed when it stays on the user's machine and does
+ not add network access, tracking, persistent identification, or data
+ collection behavior.
+
+## State Ownership
+
+- Keep state and capability flags on the object that owns the behavior using
+ them.
+- Avoid probing child objects with `getattr(child, "...", default)` to decide
+ parent-level control flow. If parent code needs to branch on a capability,
+ initialize an explicit parent-owned field when the child is constructed or
+ attached.
+- Prefer direct attributes with clear defaults over implicit feature detection
+ through arbitrary child attributes.
+- Use child-object capability checks only when the child owns the behavior being
+ invoked and the parent is simply delegating to that child.
+
+## Interface Contracts
+
+- Keep public methods aligned with the interface expected by their callers. Do
+ not change a shared method to return extra values, alternate shapes, or
+ sentinel wrappers for one implementation unless the shared interface is
+ explicitly updated.
+- If an implementation needs auxiliary values for its own workflow, expose them
+ through a private helper or a clearly named implementation-specific method
+ instead of overloading the public method's return contract.
+- Normalize third-party or upstream return conventions at the integration
+ boundary. Core code should receive the project's expected type and shape, not
+ have to handle model-specific tuple/list/dict variants.
+- Avoid caller-side unwrapping such as `out = out[0]` unless the called
+ interface is documented to return that structure.
+
+## Autograd and Model Freezing
+
+- Do not add `torch.no_grad`, `torch.inference_mode`, or inference-mode helper
+ wrappers in ComfyUI code. The only allowed inference-mode-related use is
+ disabling a globally set inference mode when a training path needs gradients.
+- Do not add freeze, unfreeze, or trainability toggles to model classes. ComfyUI
+ models are always treated as frozen for inference, so explicit freeze
+ functionality is redundant and should not be added.
+
## Python Style
- Keep imports at module scope. Avoid inline imports unless they are already part
@@ -33,8 +116,9 @@
- Match the existing local style in the file you edit. This codebase tolerates
long lines, simple helper functions, module-level state, and direct tensor
operations when they make the code easier to follow.
-- Keep comments sparse and useful. Short TODOs are fine when they name the
- concrete missing follow-up.
+- Keep comments sparse and useful. Strip useless comments that restate the code
+ or describe obvious behavior. Short TODOs are fine when they name the concrete
+ missing follow-up.
## Model, Device, and Memory Behavior
@@ -71,6 +155,10 @@
- If asked to write commit messages, use short direct subjects like the existing
history: `Fix ...`, `Add ...`, `Support ...`, `Remove ...`, `Update ...`,
`Make ...`, `Use ...`, `Disable ...`, `Bump ...`, or `Revert ...`.
+- Keep PR descriptions short and reviewable. State the problem, the behavioral
+ change, and the tests run; avoid long narrative explanations, implementation
+ diaries, or exhaustive file-by-file summaries unless the reviewer explicitly
+ needs that context.
- Prefer one coherent behavioral change per commit. Dependency pins, tests, and
the code that needs them may be in the same commit when they are inseparable.
- In reviews, prioritize real user impact: crashes, wrong dtype/device behavior,