flake8-agents 0.2.0

Flake8 plugin for detecting static-analysis escape hatches in Python code

flake8-agents

English | 한국어

flake8-agents is a Flake8 plugin for codebases that use AI-generated Python. It exists because generated code often hides problems from static analysis with reflection, broad types, casts, raw namespace access, and stale suppressions.

The plugin turns those escape hatches into explicit AGT diagnostics.

Usage

uv sync
uv run flake8 --select AGT src
uv run module-size src --warn-lines 800 --error-lines 1000

Minimal Flake8 config:

[flake8]
select = AGT

Rules

Suppressions

Code	Catches	Example
AGT001	unused explicit AGT noqa suppressions	value: int = 1 # noqa: AGT105
AGT100	broad type-checker suppressions	value = 1 # type: ignore[assignment]

Type escapes

Code	Catches	Example
AGT101	typing.cast used as a narrowing bypass	result = cast(int, value)
AGT102	broad object annotations	def handle(value: object) -> None: ...
AGT103	known-shape containers that erase value shape	payload: dict[str, object]
AGT104	vague callable signatures	callback: Callable[..., int]
AGT105	broad Any at non-local boundaries	def handle(value: Any) -> None: ...
AGT106	legacy type-parameter factories	T = TypeVar("T")
AGT107	classmethod factories returning their class name	def build(cls) -> "Box": ...

Dynamic anti-patterns

Code	Catches	Example
AGT200	dynamic attribute reads	value = getattr(target, "name")
AGT201	dynamic attribute writes	setattr(target, "name", value)
AGT202	raw namespace extraction	namespace = vars(target)
AGT203	dynamic import builtin	module = __import__("package")
AGT204	importlib.import_module calls	module = importlib.import_module("package")
AGT205	setattr-style mutation methods	target.setattr("name", value)
AGT206	direct __setattr__ calls	target.__setattr__("name", value)
AGT207	direct __new__ construction	instance = Target.__new__(Target)
AGT208	direct raw __dict__ indexing	value = target.__dict__["name"]
AGT209	aliasing raw __dict__	namespace = target.__dict__
AGT210	indexing raw __dict__ aliases	value = namespace["name"]
AGT211	aliasing dotted module imports	import package.module as alias
AGT212	types.SimpleNamespace dynamic attribute bags	data = types.SimpleNamespace(name="value")

Import boundaries

Code	Catches	Example
AGT300	private project imports across module boundaries	from module import _private
AGT301	configured retired project import paths	import module.legacy
AGT302	declarations before the module import section is complete	VALUE = 1 before import ast

module-size

module-size is a separate command that fails on oversized Python modules.

uv run module-size src --warn-lines 800 --error-lines 1000

Option	Default	Meaning
paths	required	Python files or directories to scan
--warn-lines	800	print warning findings at or above this line count
--error-lines	1000	return failure at or above this line count
--exclude REGEX	none	skip files whose resolved path matches the regex
--suppress-warnings	false	hide warning findings from stdout

PATH                              LINES  LEVEL    THRESHOLD
/path/to/src/package/large.py     1012   error    1000

Python support

flake8-agents supports Python >=3.11 and is typed (py.typed). Runtime dependencies are intentionally small: flake8 and typing-extensions.

Design note

AGT rules prefer code that people and static tools can inspect. They are not a blanket claim that dynamic declarations, dynamic imports, casts, broad types, or suppressions are anti-patterns in every codebase. The concern is AI-generated code overusing those escape hatches until intent and program shape are hard for humans to audit. AI models may improve, but today's generated code can take the shortest path to satisfy the last prompt, paper over uncertainty, or make an incomplete change look complete. These rules also make those moves harder to hide. When the trade-off is intentional, keep the code and add a targeted explicit noqa with the specific diagnostic code, for example # noqa: AGT204.

License

MIT. See LICENSE.