Maintainability sensors for coding agents
Birgitta Böckeler · article · 2026-05-19 source ↗ Reader 🖥️
Back Pressure (Verification-Bound Autonomy)Code QualityCoding AgentsFeedback LoopsSoftware Design Fundamentals
Static analysis tools like ESLint, now cheap to customize because AI can write the rules and messages, are an immediately high-value sensor for keeping an AI coding agent's output maintainable — provided their warnings are rewritten as explicit self-correction guidance for the agent rather than left as generic human-facing messages — but this same newfound ease risks producing feedback overload and a false sense of quality assurance.
practical · mixed — Primarily expository/narrative case study (a real application rebuild) in service of a practical argument about how to configure and message static-analysis sensors for a coding agent; closes with an argumentative caution about the approach's limits.
Structure
| Part | Role |
|---|---|
| Definition of maintainability ('internal quality') as distinct from functional correctness and architectural fitness, and the claim that internal-quality problems affect agents the way they affect humans (wrong-place lookups, unnoticed duplication, excess context load). | context |
| The example application (an internal analytics dashboard, TypeScript/NextJS/React, rebuilt from scratch by AI with almost no markdown guidance) and the full taxonomy of sensors used across the path to production (during coding session, pipeline, repeated cadence, runtime). | evidence / empirical scaffold |
| Which ESLint rules target typical AI failure modes (max arguments, file length, function length, cyclomatic complexity) and the observation that none of these are in ESLint's default preset. | evidence |
| Design of self-correction guidance: a custom ESLint formatter that overrides default messages with instructions for the agent (e.g. the no-explicit-any guidance, and permission to slightly raise numeric thresholds instead of suppressing rules). | evidence — the core mechanism |
| Argument that coding agents make consistent warning management ('a clean baseline') newly feasible, where human teams historically let static analysis decay into noise because of management overhead. | evidence / conclusion |
| Concrete observations: exceptions as a code-review starting point; the cyclomatic-complexity rule (the one lacking explicit guidance) being the only category where the agent defaulted to raising thresholds; the no-console rule needing different resolutions in backend vs. frontend; and the max-lines rules triggering good refactoring but also an unresolved React prop-drilling side effect. | evidence |
| Main takeaways: the cost-benefit balance for static analysis has shifted (cheaper to build, more valuable given AI's error profile), but static analysis still can't catch semantic quality, and activating more rule sets both surfaces real issues and risks feedback overload for the agent. | conclusion / caveat |
Key terms
- Maintainability (internal quality)
Making it easy and low-risk to change the codebase over time — not just being able to make changes quickly today, but also in the future, without worrying about introducing bugs or degrading fitness with each change (including changes made by AI). - Sensor (computational vs. inferential) Feedback Loops
A feedback mechanism on the path to production that gives the agent (and the human) information to reflect on and correct maintainability. Computational sensors are deterministic tools (ESLint, type checker, dependency-cruiser, mutation testing); inferential sensors are AI-judgment-based (a security-review prompt, a data-handling-review prompt). Some sensors are hybrid. - Self-correction guidance Feedback Loops
Custom lint/error messages engineered to instruct the agent on how to judge and act — described as 'a good kind of prompt injection' — as opposed to generic, human-oriented default tool messages. - Clean baseline
A codebase state where static-analysis warnings are kept triaged (fixed or deliberately, visibly suppressed) rather than accumulating into ignored noise — historically hard for human teams to sustain, which the author argues coding agents may now make newly feasible. - Threshold increase (vs. suppression)
Letting the agent slightly raise a numeric limit (e.g. max-lines, cyclomatic complexity) when it judges a refactor unnecessary or impossible, instead of permanently suppressing the rule — so the constraint still fires again if things get worse, rather than disappearing.
Propositions
- explicitInternal-quality (maintainability) problems affect AI coding agents in similar ways to how they affect human developers — an agent in a tangled codebase may look in the wrong place, create inconsistencies by missing a duplicate, or be forced to load more context than a task should require.conf: high
- explicitThe ESLint rules that are the most low-hanging fruit for catching typical AI coding failure modes are: max number of function arguments, file length, function length, and cyclomatic complexity — none of which are active in ESLint's default preset.conf: high
- explicitRewriting a lint rule's message as explicit self-correction guidance for the agent (telling it when suppression is acceptable, and how to record the reason) measurably changes the agent's behavior.conf: highextendsHarness engineering for coding agent users · p4 — Bockeler's harness-engineering piece states in the abstract that feedback sensors are most powerful with LLM-optimized signals, citing custom linter messages with self-correction instructions as the example; this document supplies the concrete case study (the no-explicit-any formatter, the cyclomatic-complexity before/after comparison) that instantiates and confirms that exact claim.
- explicitThe one rule category where the agent's default behavior went unchallenged (repeatedly raising the cyclomatic-complexity threshold instead of refactoring) was also the one rule for which the author had not written explicit self-correction guidance.conf: high
- explicitLetting an agent slightly raise a numeric threshold, rather than suppress a rule outright, preserves the constraint for the future (it still fires again if things get worse) while avoiding a binary suppress-or-comply choice.conf: highextendsAddy Osmani's Post · p6 — Osmani's general claim that well-designed constraints act as back-pressure, resisting bad work before it propagates, is given a specific mechanism here: letting the agent raise (not suppress) a numeric threshold preserves the back-pressure for the future instead of removing it.
- explicitCoding agents make disciplined, consistent static-analysis warning management ('a clean baseline') newly feasible, where the historical obstacle for human teams was management overhead rather than the value of the analysis itself.conf: high
- implicitcorroboratedReviewing the exceptions an agent created (suppressed warnings, increased thresholds) is a more efficient entry point for human code review than reading the whole diff.conf: mediumsupports ←Brownfield Agentic Engineering · p6 — Both treat the record of an agent's exceptions/corrections (suppressed warnings, repeated review comments) as a more efficient and higher-signal review entry point than reading the whole diff.
- explicitA single rule can need different resolutions in different parts of the same codebase (e.g. no-console requiring a logger component in the backend but different or no direct logging in the frontend), and an agent can apply this kind of contextual judgment given the right guidance.conf: high
- explicitCheaper AI-assisted rule/message authoring has shifted static analysis's cost-benefit balance: it is now cheaper to create custom scripts and rules, and more valuable because it catches AI-specific hygiene mistakes that a human author would make less often.conf: high
- explicitStatic analysis cannot catch many of the more semantic aspects of code quality, and its ease of use with agents risks producing a false sense of security and an illusion of quality.conf: high
- explicitActivating additional lint rule sets produces a mix of genuinely relevant findings and irrelevant noise, risking feedback overload that could push the agent into a spiral of over-engineered refactoring.conf: high
- explicitSensors are organized across four points on the path to production — during the coding session (fast, mostly computational, for real-time self-correction), after integration in the pipeline (the same computational sensors re-run in CI on clean infrastructure), repeatedly on a slower cadence (mostly inferential, to catch drift that accumulates over time), and at runtime in production — with cheaper, faster checks concentrated earliest in that sequence.conf: highextendsHarness engineering for coding agent users · p6 — The abstract claim that controls should be distributed across the change lifecycle by cost/speed/criticality, cheapest shifted left, is exactly what this article's sensor taxonomy (during coding session -> pipeline -> repeated -> runtime, computational sensors run fast and often, inferential ones on a slower cadence) operationalizes with a concrete, working example.
Arguments
Static analysis (ESLint in particular) is now a higher-value sensor for AI-agent-generated code than it was for human-written code. strength: medium
Explicit premises:
- Custom rules and custom lint messages are now much cheaper to create because AI can write them.
- Static analysis surfaces hygiene-factor mistakes that agents make more than a human author typically would, at least while there is little other maintainability guidance (e.g. markdown guides) in place.
Implicit premises:
- The main historical obstacle to static-analysis adoption was social/managerial overhead (keeping a 'clean house'), not the technical value of the analysis.
- An agent can be instructed to consistently triage, suppress, or refactor in response to warnings without the interpersonal friction of asking a human colleague to address someone else's warnings.
Inferences:
- If agents can sustain a clean baseline, static-analysis hygiene could become an expected, near-automatic property of agent-authored code in a way it never reliably was for human-authored code — potentially making 'lint cleanliness' a standard checkpoint teams start measuring.
A sensor's feedback message must be engineered as explicit guidance for the agent, not merely left as an alert meant for a human, in order to reliably produce agent self-correction.
Explicit premises:
- The custom no-explicit-any message tells the agent when suppression is acceptable and instructs it to record its reasoning inline.
- The threshold-increase design explicitly tells the agent that raising a limit is a narrow, non-final option rather than a way to make the rule go away.
- The one rule without such explicit guidance (cyclomatic complexity) was the only category where the agent's default response (raise the threshold) went unchallenged until the author manually nudged it.
Implicit premises:
- Agents follow instructions that are literally present in the feedback message more reliably than they infer the unstated intent behind a bare rule name and default message.
- A generic linter warning under-specifies the judgment call an agent needs to make, even where it might be sufficient context for an experienced human engineer who already understands the rule's purpose.
Inferences:
- Off-the-shelf ESLint rule sets, written without agent-directed guidance, will systematically under-perform custom LLM-targeted messages until static-analysis tooling and presets are designed with an agent audience in mind — a shift the article notes is already starting to happen (e.g. Factory's eslint-plugin).
Narratives
- The author rebuilt, from scratch with AI, a pre-existing internal analytics dashboard (TypeScript/NextJS/React, reading chat/engagement/demographic data from four APIs) specifically to test how well an agent handles maintainability using sensor feedback alone, with almost no markdown guidance in place.
→ Establishes the empirical grounding for every subsequent observation and frames maintainability's stakes concretely (more files touched per small change, or previously-working things breaking, as the first visible cracks). - The cyclomatic-complexity rule was the only category where the agent repeatedly chose to raise the threshold rather than refactor — until the author noticed she'd never written self-correction guidance for that specific rule, unlike every other rule where she had.
→ Supports Argument 2 directly: it is the article's single sharpest evidence that explicit, LLM-targeted guidance (not just the presence of a lint rule) is what drives agent self-correction. - The no-console rule needed opposite treatments in the backend (use a logger component) versus the frontend (avoid direct logging, or use a different component) of the same codebase.
→ Illustrates the proposition that agents can apply contextual/semantic judgment about a single rule across different code regions, given the right guidance — evidence for self-correction guidance's power beyond simple suppress/fix binaries. - The max-lines and max-lines-per-function rules drove useful refactoring and component breakdown, but also seemed to push the React frontend toward components with growing prop lists as values were threaded through longer chains of smaller components — a trend the author flags as 'worrying' but says she doesn't yet have useful observations about how well AI navigates that kind of rule tradeoff.
→ The article's own unresolved counter-example: it complicates the piece's optimistic cost-benefit conclusion by showing the very mechanism credited with fixing one maintainability problem apparently contributing to a different one, without yet having a way to detect or judge that tradeoff.
Questions addressed
- ✅ Can static-analysis feedback alone, without markdown guides, meaningfully shape an AI coding agent's maintainability decisions?
Largely yes — the author reports being 'positively surprised' by how much static analysis can cover, provided the sensor's messages are engineered as self-correction guidance; but she qualifies this with concern about false security and feedback overload. - ✅ Which specific ESLint rules matter most for catching AI-typical maintainability failure modes?
Max function arguments, file length, function length, and cyclomatic complexity — none active by default, requiring manual configuration. - ⭕ How should an agent resolve rule tradeoffs, such as satisfying max-lines/max-lines-per-function while it apparently drives excessive prop-drilling elsewhere?
Explicitly left open: 'I haven't got useful observations yet about how good AI might be at making consistent decisions between tradeoffs like that.' - ⭕ Does static analysis catch the semantic aspects of code quality, beyond hygiene-level issues?
Explicitly not resolved — the author states static analysis 'cannot catch' many semantic quality aspects and says 'it remains to be seen' whether AI can fill that gap in partnership with these tools. - ⭕ How can static analysis help maintain good modularity and coupling across files and modules, not just within a single file or function?
Explicitly deferred to 'the next update to this article' — which already exists in this corpus as the dependency-cruiser/coupling-metrics/modularity-review installment (extract-fowler-bockeler-static-sensors-iii).
Gaps
- incompleteThe article's own opening heuristic for detecting maintainability decay in an AI-generated codebase — 'the number of files changed for a small adjustment increases' or 'changes start breaking things that used to work' — is never quantified anywhere in the piece. No before/after measurement of files-touched-per-change, defect rate, suppression counts, or warning volume is offered; every claim about the sensor setup's effectiveness is anecdotal.
Read next: Quantitative studies of AI-code maintainability degradation over time, e.g. commit-pattern analyses (GitClear-style) that could supply the missing baseline this article gestures at but never measures. - incompleteThe piece names a real risk ('feedback overload for the agent, sending it into a spiral of over-engineered refactorings') from activating more rule sets, but doesn't examine how many of the newly surfaced findings were actually net-helpful versus noise, nor propose any staging, severity-tiering, or gating mechanism for introducing new rules without triggering that spiral.
Read next: Practices for incrementally rolling out static-analysis rule sets to agents (staged activation, severity tiers, rule-adoption cadence) rather than activating full sets at once. - incompleteAll observations come from a single practitioner working solo on one greenfield rebuild. The article never addresses how self-correction guidance and the threshold-increase mechanism would behave with multiple developers and multiple concurrent agents sharing the same ruleset — e.g. whether inconsistent judgment calls about suppressions/threshold increases across people or agent sessions would recreate the same 'clean house' management-overhead problem she credits agents with solving for a single author.
Read next: Team-scale (not single-practitioner) case studies of agent-maintained lint hygiene across many contributors and concurrent agent sessions. - illogicalThe article's central optimistic thesis — that the cost-benefit balance for static analysis has shifted decisively in AI's favor — sits uneasily next to its own unresolved counter-example: the max-lines rules produced good refactoring in isolation but also seemed to drive a 'worrying trend' of React components with growing prop lists, a different maintainability problem the author admits she can't yet detect or judge. The piece doesn't reconcile these two observations, nor consider whether the sensor setup itself (optimizing per-rule, per-file) structurally can't see this kind of cross-component tradeoff regressing even as every individual rule stays green.
Read next: The next installment already in this corpus (extract-fowler-bockeler-static-sensors-iii) is a partial answer — it addresses cross-file/module concerns with dependency-cruiser rules and an inferential modularity review, though it doesn't specifically revisit the prop-drilling example raised here.
Related documents
- Addy Osmani's Post
- [FULL WORKSHOP] AI Coding For Real Engineers - Matt Pocock, AI Hero
- Eight years of wanting, three months of building with AI
- It Ain't Broke: Why Software Fundamentals Matter More Than Ever
- Why Rust is different, with Alice Ryhl
- 11 Tips For AI Coding With Ralph Wiggum
- 5 Things World-Class Engineers Do That You Don't
- Have your agent record video demos of its work with shot-scraper video
- Agentic AI and Code Reviews
- All models, no matter how smart, will eventually build systems...