LLMGRAPH Agent Rules

AR-01: Why do star imports make my coding agent miss callers?

Fri, 30 Oct 2026 00:00:00 GMT

Import names explicitly. Don't use from module import * in code that agents edit.

AR-02: Do barrel files hide calls from coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

Re-export through an explicit list (__all__, named export { }), not export * chains.

AR-03: What happens when two functions share a name?

Fri, 30 Oct 2026 00:00:00 GMT

One public name, one definition: don't define the same function name in two modules a file can import together.

AR-04: Do import aliases confuse coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

Alias imports only to resolve a real clash, and never alias a module to a one-letter name in shared code.

AR-05: Why do fallback imports make agents edit the wrong code?

Fri, 30 Oct 2026 00:00:00 GMT

No conditional imports that bind the same name to different objects (try/except ImportError fallbacks get a typed shim).

AR-06: Why does my agent not see what importing this module does?

Fri, 30 Oct 2026 00:00:00 GMT

Keep import side effects out of modules; registration happens in an explicit setup call.

AR-07: Why does my coding agent miss calls made through getattr?

Fri, 30 Oct 2026 00:00:00 GMT

Don't build method names as strings (getattr(obj, f\"handle_{x}\"), obj[name]()).

AR-08: How do I write dispatch that type checkers can follow?

Fri, 30 Oct 2026 00:00:00 GMT

Dispatch over a closed set with a typed mapping keyed by a literal type, or an explicit match.

AR-09: How should plugin registries be written for coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

For open sets (plugins), register explicitly into a typed registry next to a typed contract.

AR-10: Why can't any tool see calls made through eval?

Fri, 30 Oct 2026 00:00:00 GMT

No eval/exec/Function() to call code.

AR-11: Why does my agent break calls that go through **kwargs?

Fri, 30 Oct 2026 00:00:00 GMT

Avoid **kwargs/...args pass-through layers that hide the real signature; spell the parameters or use ParamSpec/Parameters<>.

AR-12: Do decorators hide function signatures from coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

Use functools.wraps / preserve signatures in decorators; don't let decorators replace a function with a different shape.

AR-13: Why is Any a blind spot for coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

Annotate public function parameters and returns. Use Any/any only at a documented boundary.

AR-14: How should I type callbacks so agents can follow them?

Fri, 30 Oct 2026 00:00:00 GMT

Type callback and handler parameters (Callable[...], function types), not object/Function.

AR-15: How do I make duck typing visible to type checkers?

Fri, 30 Oct 2026 00:00:00 GMT

Use Protocol/interfaces for duck-typed parameters.

AR-16: Why do dict-shaped objects make agents guess?

Fri, 30 Oct 2026 00:00:00 GMT

Prefer dataclasses/TypedDict/interfaces over free-form dicts for structured data passed between modules.

AR-17: Which type checker settings make code easier for agents?

Fri, 30 Oct 2026 00:00:00 GMT

Turn on strict type checking in the paths agents edit (pyright strict / mypy strict / tsconfig strict).

AR-18: Why does monkeypatching break agent edits?

Fri, 30 Oct 2026 00:00:00 GMT

No monkeypatching in production code. In tests, patch through the fixture/mock API at the import site.

AR-19: Why does reassigning methods hide callers from agents?

Fri, 30 Oct 2026 00:00:00 GMT

Keep a function's callers findable: don't assign functions onto objects at runtime (obj.method = other).

AR-20: Where should a registry live so coding agents can find it?

Fri, 30 Oct 2026 00:00:00 GMT

No hidden global registries mutated from many modules; one module owns the registry.

AR-21: Do metaclasses hide code from coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

Keep metaclass and __init_subclass__ generation out of edit paths; when you use it, document what it generates.

AR-22: Why do getattr proxies confuse coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

Avoid __getattr__ (and JavaScript Proxy) forwarding on domain objects; expose explicit methods.

AR-23: How should generated code be handled for coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

Generated code is committed, or its generator is in the repo with the command to run it. Mark it, and tell agents to edit the source.

AR-25: What to check before changing a function signature?

Fri, 30 Oct 2026 00:00:00 GMT

Before changing a signature, list every caller and the dynamic sites that might reach it.

AR-26: How does an agent know an edit is finished?

Fri, 30 Oct 2026 00:00:00 GMT

After an edit, re-check the callers of every changed function before declaring the task done.

AR-27: Is a list of callers ever the full list?

Fri, 30 Oct 2026 00:00:00 GMT

Treat \"callers found\" as the full list only when the tool says the list is full.

AR-28: Why is find-and-replace a bad rename for coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

Rename through the language server's rename, not text replace.

AR-29: What should a coding agent run before finishing?

Fri, 30 Oct 2026 00:00:00 GMT

Run the type checker and the affected tests before saying \"done\".

AR-30: What should an agent report when it can't verify an edit?

Fri, 30 Oct 2026 00:00:00 GMT

Write down what you couldn't verify in the final message.

AR-31: Why does my coding agent miss Django signal receivers?

Fri, 30 Oct 2026 00:00:00 GMT

Connect Django signals with an explicit sender, and keep the receivers in one signals.py per app, imported in AppConfig.ready().

AR-32: Do string model references hide dependencies in Django?

Fri, 30 Oct 2026 00:00:00 GMT

Import models directly when no import cycle forces a string. When a string is needed, use the absolute form \"app_label.ModelName\" and say why.

AR-33: How do I keep FastAPI routes visible to coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

Declare dependencies as typed functions used through Annotated[..., Depends(fn)], and write routes as decorated functions on an APIRouter.

AR-34: Why does my agent break pytest fixtures it can't see?

Fri, 30 Oct 2026 00:00:00 GMT

Keep fixtures in the nearest conftest.py, name them for what they return, and don't use autouse to change behaviour.

AR-35: Where should I patch in pytest?

Fri, 30 Oct 2026 00:00:00 GMT

Patch the name the code under test looks up, through monkeypatch or mocker, on the module object. Don't reassign module globals in a test.

AR-36: Do higher-order components hide props from coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

In React, prefer hooks and explicit props over higher-order components that inject props.

AR-37: Why does my agent miss dynamically imported components?

Fri, 30 Oct 2026 00:00:00 GMT

In React and Next.js, don't call import() with a computed path for components agents edit.

AR-38: How should Express routes be organised for coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

AR-39: How do I make event emitters traceable for coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

Declare event names as a typed union or enum with typed payloads. Don't emit free strings with any arguments.

AR-40: How do DI containers hide calls from coding agents?

Fri, 30 Oct 2026 00:00:00 GMT

Bind interfaces to implementations in one container module, using typed tokens and constructor injection.

CH-01: Why does my Django signal break after a refactor?

Fri, 30 Oct 2026 00:00:00 GMT

Chimera CH-01: a Django project that tests AR-07, AR-08, AR-25, AR-31. Why does my Django signal break after a refactor?

CH-02: Why do my pytest tests pass for a reason I can't see?

Fri, 30 Oct 2026 00:00:00 GMT

Chimera CH-02: a pytest project that tests AR-18, AR-34, AR-35. Why do my pytest tests pass for a reason I can't see?

CH-03: Why did my plugin registry lose a format after an edit?

Fri, 30 Oct 2026 00:00:00 GMT

Chimera CH-03: a Python (__init_subclass__ registry) project that tests AR-06, AR-09, AR-21. Why did my plugin registry lose a format after an edit?

CH-04: Why does a React prop stop arriving after a rename?

Fri, 30 Oct 2026 00:00:00 GMT

Chimera CH-04: a React (higher-order component, barrel) project that tests AR-02, AR-36. Why does a React prop stop arriving after a rename?

LLMGRAPH Agent Rules

AR-01: Why do star imports make my coding agent miss callers?

AR-02: Do barrel files hide calls from coding agents?

AR-03: What happens when two functions share a name?

AR-04: Do import aliases confuse coding agents?

AR-05: Why do fallback imports make agents edit the wrong code?

AR-06: Why does my agent not see what importing this module does?

AR-07: Why does my coding agent miss calls made through getattr?

AR-08: How do I write dispatch that type checkers can follow?

AR-09: How should plugin registries be written for coding agents?

AR-10: Why can't any tool see calls made through eval?

AR-11: Why does my agent break calls that go through **kwargs?

AR-12: Do decorators hide function signatures from coding agents?

AR-13: Why is Any a blind spot for coding agents?

AR-14: How should I type callbacks so agents can follow them?

AR-15: How do I make duck typing visible to type checkers?

AR-16: Why do dict-shaped objects make agents guess?

AR-17: Which type checker settings make code easier for agents?

AR-18: Why does monkeypatching break agent edits?

AR-19: Why does reassigning methods hide callers from agents?

AR-20: Where should a registry live so coding agents can find it?

AR-21: Do metaclasses hide code from coding agents?

AR-22: Why do __getattr__ proxies confuse coding agents?

AR-23: How should generated code be handled for coding agents?

AR-25: What to check before changing a function signature?

AR-26: How does an agent know an edit is finished?

AR-27: Is a list of callers ever the full list?

AR-28: Why is find-and-replace a bad rename for coding agents?

AR-29: What should a coding agent run before finishing?

AR-30: What should an agent report when it can't verify an edit?

AR-31: Why does my coding agent miss Django signal receivers?

AR-32: Do string model references hide dependencies in Django?

AR-33: How do I keep FastAPI routes visible to coding agents?

AR-34: Why does my agent break pytest fixtures it can't see?

AR-35: Where should I patch in pytest?

AR-36: Do higher-order components hide props from coding agents?

AR-37: Why does my agent miss dynamically imported components?

AR-38: How should Express routes be organised for coding agents?

AR-39: How do I make event emitters traceable for coding agents?

AR-40: How do DI containers hide calls from coding agents?

CH-01: Why does my Django signal break after a refactor?

CH-02: Why do my pytest tests pass for a reason I can't see?

CH-03: Why did my plugin registry lose a format after an edit?

CH-04: Why does a React prop stop arriving after a rename?

AR-22: Why do getattr proxies confuse coding agents?