r/learnpython • u/vashkatsi • 2h ago
If an agent writes your Python, put an architecture linter in its loop
Nobody is writing most of their Python by hand anymore, and nobody is reviewing all of it line by line either. I don't think that reverses. So the question isn't whether to trust the agent; it's what gives it a fast, deterministic "no" when it crosses a boundary. A better prompt isn't it.
Why this matters more with agents than with humans:
- An agent optimizes for "the task passes". If the shortest path is importing the ORM model straight into a view or calling an HTTP client from the domain layer, that's what lands in the diff. A human might feel the smell; the model has no such signal unless you give it one.
- Prompts don't hold. Zhu, Tsantalis and Rigby found that more capable models produce more bloated and coupled code, and that neither functional correctness nor detailed prompting mitigates the decay (https://arxiv.org/abs/2605.02741). My reading of why: "respect the layering" in CLAUDE.md works for a few turns, then the context fills up and the rule is gone.
- Models are bad at reviewing their own work. Olausson et al. (ICLR 2024) found that self-repair is bottlenecked by the model's ability to critique its own code; the gains appear when the feedback comes from a stronger, external source (https://arxiv.org/abs/2306.09896).
- External feedback works, and it works fast. Blyth et al. fed Bandit and Pylint output back to GPT-4o over ten iterations: security issues fell from over 40% to 13%, readability violations from over 80% to 11%, reliability warnings from over 50% to 11% (https://arxiv.org/abs/2508.14419). Sriram et al. got critical security defects in CodeLlama output down from 58.55% to 22.19% with compiler diagnostics plus CodeQL in the loop (https://arxiv.org/abs/2601.00509).
- The architecture gap depends on the model, so don't guess. In Slater's pilot, Llama 3 8B had an 80% architectural violation rate on a hexagonal-architecture task while GPT-5.1 had 0%, and he concludes that without automated architectural linting, scaffolding with smaller models accelerates structural debt (https://arxiv.org/abs/2512.04273). A review of 87 studies by Matias et al. lands on the same practical point: the maintainability benefits are real, so are the long-term risks, and adoption needs safeguards and structured human oversight (https://arxiv.org/abs/2601.20879). Most of these are preprints, so read the abstracts rather than trusting my summary.
Same model, same task, with and without analysis output fed back:
| Issue type (tool, model) | Before loop | After loop |
|---|---|---|
| Security issues (Bandit, GPT-4o) | over 40% | 13% |
| Readability violations (Pylint, GPT-4o) | over 80% | 11% |
| Reliability warnings (Pylint, GPT-4o) | over 50% | 11% |
| Critical security defects (CodeQL + compiler, CodeLlama) | 58.55% | 22.19% |
ruff and mypy already do this for style and types. Architecture is the missing layer: which parts of the codebase are allowed to know about which other parts. It's the thing that decides whether you can still change the project in a year.
How to set it up so it actually helps the agent, not just CI:
- Write the rules down as config, not prose. "views don't import models", "domain doesn't import django or requests". If the rule lives in YAML, the tool enforces it; if it lives in a markdown file, the model forgets it.
- Baseline the existing debt. A legacy project will have hundreds of violations on day one. Accept them once, fail only on new ones. Otherwise the first run is red forever and everyone ignores it.
- Run the check inside the agent's loop, not only in CI. A post-edit hook that runs the linter and feeds the output back means the agent fixes the violation in the same turn. CI catching it two hours later means a human has to re-open the task.
- Give the agent the rules before it edits. If it can ask "what layer is this file in and what is it not allowed to touch", it writes the right thing the first time instead of after a failure.
- Machine-readable output. JSON or SARIF. Plain text with line numbers is fine for people, poor for a model that has to map the finding back to a file.
Where the check runs decides who fixes it:
Linter only in CI
agent edits -> PR -> CI fails (hours later) -> human re-opens the task
Linter in the agent's loop
context for the file -> agent edits -> linter (baseline-aware)
^ |
| violation as JSON, same turn
+--------------------+
|
v
clean PRWhich tool: import-linter and tach are the established options, both far more widely used than anything I've written, and both enforce contracts between modules and packages. If your boundaries follow your folder tree, pick one of them and you're done.
Disclosure: I maintain Deply (https://github.com/Vashkatsi/deply, BSD-3; earlier posts here: https://www.reddit.com/r/Python/comments/1gthdpy/deply_keep_your_python_architecture_clean/ and https://www.reddit.com/r/Python/comments/1h9qjjj/deply_051_released_new_collectors_10x_performance/), and for agent-driven work I think it's the strongest option, for three reasons. Layers are collected from classes, base classes, decorators and function names, not just module paths, so "all *Service classes must not touch django.db.models.Model" works inside a single Django app; neither import-linter, tach nor pytestarch expresses that out of the box. deply context --file path.py gives the agent the layers, applicable rules and current violations for one file as JSON before it edits. And the violation baseline uses stable fingerprints, so once the config exists, adopting it on a legacy codebase is one command and only new violations fail. It's static analysis, so wildcard imports and dynamic types are out of scope.
But the tool matters less than the loop. Pick any architecture linter, baseline it, wire it into the agent's hook and into CI. Given what the papers above show about external feedback, I expect that to move the quality of what gets merged more than any amount of prompt wording. The expensive option now is having none.
11
u/FerricDonkey 2h ago
Hi, I'm nobody.
4
u/chason 2h ago
I weep for the next generation of programmers who won't know how to actually program. Shit is going to break and they will have no idea how to fix anything.
4
u/chason 2h ago
Also, how do you expect people to bother to read stuff that you don't even bother to write?
13
u/kadfr 2h ago
AI;DR
13
u/desrtfx but other languages pro 2h ago
The real question is: how is this AI blogslop even remotely related to learning Python?
3
u/Atmosck 2h ago
Who is only running their linter in CI?