There are a number of dimensions we normally wish to obtain and monitor in our codebases: Useful correctness (works as supposed), architectural health<\/a> (is quick\/safe\/usable sufficient), and maintainability. I outline maintainability right here as making it simple and low threat to alter the codebase over time – often known as \u201cinner high quality\u201d<\/a>. So I do not solely need to have the ability to make adjustments shortly right now, but additionally sooner or later. And I do not wish to fear about introducing bugs or degradation of health each time I make a change – or have AI make a change. I normally see the primary indicators of cracks within the maintainability of an AI-generated codebase when the variety of recordsdata modified for a small adjustment will increase. Or when adjustments begin breaking issues that used to work.<\/p>\n Inner high quality issues have an effect on AI brokers in related ways in which they have an effect on human builders. An agent working in a tangled codebase would possibly look within the incorrect place for an current implementation, create inconsistencies as a result of it has not seen a replica, or be pressured to load extra context than a process ought to require.<\/p>\n On this article, I describe my experimentation with varied sensors that assist us and AI replicate on the maintainability of a codebase, and what I discovered from that.<\/p>\n I am engaged on an inner analytics dashboard for group managers that reads chat area exercise, engagement, and demographic knowledge from a mixture of APIs and presents the information in an online frontend.<\/p>\n Determine 1: The tech stack is a TypeScript, NextJS, and React. The backend reads and joins knowledge from the APIs. The appliance has been round for some time, however for the sake of those experiments I rebuilt it with AI from scratch.<\/p>\n There are hardly any guides (e.g. markdown recordsdata) for AI about code high quality and maintainability current, I needed to see how effectively it may well do exactly by counting on sensor suggestions.<\/p>\n Determine 2: That is an summary of the sensors I arrange throughout the trail to manufacturing.<\/p>\n Throughout coding session<\/b><\/p>\n Sensors that run constantly alongside the agent to offer quick suggestions.<\/p>\n After integration – pipeline<\/b><\/p>\n The identical computational sensors run once more in CI. The in-session sensors give the agent early suggestions throughout growth. The CI pipeline confirms the outcome on clear infrastructure and after integration.<\/p>\n Repeatedly<\/b><\/p>\n Sensors that run on a slower cadence to detect drift that accumulates over time, somewhat than errors that happen within the second.<\/p>\n With this context out of the best way, let’s dive into the primary class of sensors.<\/p>\n<\/section>\n All through constructing the applying, I used a mixture of Cursor, Claude Code, and OpenCode (in that order of frequency). My default mannequin was normally Claude Sonnet, for among the planning and evaluation duties I used Claude Opus, and for implementation duties I ceaselessly used Cursor’s composer-2 mannequin.<\/p>\n<\/section>\n<\/section>\n I will begin with my learnings from utilizing ESLint on this software. Primary linting instruments like ESLint largely goal maintainability threat on the stage of particular person recordsdata and features.<\/p>\n In my expertise, the AI failure modes which might be probably the most low-hanging fruit for static code evaluation are<\/p>\n Nonetheless, these weren’t even lively in ESLint’s default preset, I needed to configure maximums for them first. Hopefully, static evaluation instruments will evolve to offer higher presets for utilization with AI. A little bit of analysis exhibits that individuals are additionally beginning to publish ESLint plugins with rule units which might be particularly focusing on recognized agent failure modes, like this one by Manufacturing unit<\/a>, with guidelines about issues like requiring check recordsdata or structured logging.<\/p>\n<\/section>\n A sensor is supposed to provide the agent suggestions in order that it may well self-correct. Ideally, we wish to give the agent additional context for that self-correction – an excellent type of immediate injection. To do this, I constructed a customized ESLint formatter to override among the default messages – with the assistance of AI after all, naturally.<\/p>\n Right here is an instance of my steering for the Static code evaluation has been round for a very long time, and but, groups usually did not use it persistently, even once they had it arrange. One of many causes for that’s the administration overhead that comes with it. Efficient use of this evaluation requires a workforce to maintain a \u201cclear home\u201d, in any other case the metrics simply turn out to be noise. Specifically warnings just like the With coding brokers, we would now have an opportunity at that clear baseline. Within the steering textual content above, the agent is advised to make a judgment name, and allowed to suppress a warning within the code. This retains the suppressions manageable, seen and reviewable.<\/p>\n For thresholds, like the utmost variety of traces, or the utmost allowed cyclomatic complexity, I advised the agent within the lint message that it might barely improve the thresholds if it thinks {that a} refactoring is pointless or unimaginable in a selected case. This does not suppress the brink without end, simply will increase it, in order that the rule fires once more if it will get even worse sooner or later. Constraints are preserved with out forcing a binary suppress-or-comply selection.<\/p>\n<\/section>\n General, I used to be positively shocked by what number of issues I can cowl with static evaluation. I needed to remind myself a number of occasions why it has been considerably underused up to now, and what has modified: The price-benefit stability. Value is decreased as a result of it is less expensive to create customized scripts and guidelines with AI. And the profit has additionally elevated: the evaluation outcomes assist me get a primary sense of numerous hygiene elements that would not even occur that a lot after I write code myself, so I can get frequent AI errors out of the best way.<\/p>\n Nonetheless, I am unable to assist however surprise if this could additionally result in a false sense of safety and an phantasm of high quality. In any case, one more reason why linters like this have been much less used up to now is that they’ve limits, and we’ve got been cautious of utilizing them as a simplified indicator of high quality. There are many extra semantic features of high quality that static evaluation can not catch, it stays to be seen if AI can adequately fill that hole in partnership with these instruments. I additionally found new supposed points within the code each time I activated a brand new algorithm. It was at all times a mixture of irrelevant issues and issues that truly matter. So I fear about suggestions overload for the agent, sending it right into a spiral of over-engineered refactorings. <\/p>\n<\/section>\n<\/section>\n Primary linting is generally focussed on high quality and complexity inside a file or perform. Subsequent I began wanting into sensors that would give me and the agent suggestions about maintainability considerations that cross file and module boundaries. Evaluation instruments on this space are traditionally much more underused than the fundamental linting.<\/p>\n To study concerning the potential of sensors that may assist us and AI sustain good modularity inside a codebase, I explored three issues:<\/p>\n Let’s begin with dependency guidelines. I labored with the agent to provide you with a layered module construction for my software, about half method by way of implementing it. I requested it to assist me write Determine 3: For instance, one of many guidelines enforces that code within the As with the ESLint messages, I additionally expanded the error messages a bit to be self-correction steering, recapping the layering idea as an entire:<\/p>\n On the level after I launched these guidelines, the structuring of code into folders had already turn out to be slightly bit haphazard. I might see how the principles helped the agent clear that up, after which proceed implement these layers going ahead. So I’ve discovered it fairly a helpful substitute for describing code construction in a markdown information. Nonetheless, instruments like this are restricted to what’s expressible through imports, file names, and folder construction.<\/p>\n<\/section>\n<\/section>\n Subsequent, I experimented with the extraction of typical coupling metrics from my codebase, i.e. the variety of incoming and outgoing imports and calls per file.<\/p>\n I did not use any current instruments for this, as an alternative I had a coding agent write an software that creates these metrics with the assistance of the typescript compiler, in order that I might have most flexibility to mess around with this as a part of my experimentation. I had it add two interfaces: An online interface with a bunch of various visualisations of these metrics for my very own human consumption. And a CLI that may present these metrics to a coding agent.<\/p>\n Determine 4: Most of those visualisations are effectively established ideas, like a dependency construction matrix (DSM). I discovered them tedious to interpret, and though they have been vibe coded and will most definitely be improved, I feel that had extra to do with the character of the information. It is fairly detailed knowledge that wants a variety of context and expertise to interpret it, and map it again to extra excessive stage good practices. So I’ve a sense that these kind of instruments nonetheless will not actually assist cut back a human’s cognitive load a lot when reviewing codebases that have been modified by AI.<\/p>\n<\/section>\n I gave an agent entry to this practice CLI ( Right here is an excerpt of what that immediate appeared like – I am primarily reproducing this to point out you that I did not truly give it a lot steering on what good or dangerous modularity seems like, I largely delegated to the mannequin to interpret what good and dangerous seems like:<\/p>\n Produce a markdown report on modularity and coupling high quality for the goal TypeScript codebase, grounded in precise CLI output from Execute the CLI and seize stdout. Use the Use clear headings. Choose concrete module IDs \/ paths and numbers<\/strong> quoted or paraphrased from CLI output.<\/p>\n Urged sections:<\/p>\n Context<\/strong> \u2014 What was analyzed<\/p>\n<\/li>\n Govt abstract<\/strong> \u2014 2\u20135 bullets: general modularity posture, high 1\u20133 systemic points.<\/p>\n<\/li>\n Findings from the device<\/strong> \u2014 Summarize hotspots, high dangers, notable cycles or mutual dependencies, and behavioural highlights as reported by the CLI<\/strong>.<\/p>\n<\/li>\n Interpretation (modularity lens)<\/strong> \u2014 Tie metrics to software program design: cohesion vs. unfold of change, stability vs. dependency route, fan-in\/fan-out instinct, cycle influence.<\/p>\n<\/li>\n Deep dives for every excessive and significant difficulty<\/strong><\/p>\n<\/li>\n<\/ol>\n \u2026<\/p>\n<\/div>\n This LLM-led evaluation truly pointed me to the identical coupling sizzling spots that I’d have discovered by wanting by way of the visible diagrams, simply in a format that was extra digestible. And asking the LLM to floor its evaluation within the outcomes from the deterministic device gave me the next stage of confidence, and possibly additionally used much less time and tokens than if the agent had scanned the codebase itself to search out coupling issues.<\/p>\n<\/section>\n What the LLM discovered based mostly on this knowledge was fairly lackluster (I used Claude Opus 4.7 for this):<\/p>\n The examples above present that much more so than with the fundamental linting, good<\/i> and dangerous<\/i> doesn’t have a transparent definition, as an alternative it’s all about what’s acceptable<\/i>. And what coupling is acceptable relies on a variety of context, not simply the uncooked name and import graph of a codebase. So based mostly on this small experiment, I haven’t got the impression that one of these coupling knowledge is helpful to AI by itself.<\/p>\n A extra sensible use I can think about for this knowledge is throughout threat triage for code evaluate. Once I evaluate a code change made by AI, it appears helpful to know what the influence radius of the modified recordsdata is, in order that I will pay extra consideration when e.g. a file with 10+ callers is modified. Or an AI evaluate agent might use the information to prioritise the place it spends its tokens.<\/p>\n<\/section>\n<\/section>\n The lackluster outcomes from the coupling knowledge experiment might have a number of causes:<\/p>\n So the ultimate factor I did was to go totally down the inferential route and use Vlad Khononov’s \u201cModularity Abilities\u201d<\/a> to analyse the codebase design and discover modularity points. This proved to be very fruitful! It gave me numerous fascinating pointers for refactorings that will clearly cut back the danger of future adjustments. I ran the talents a second time and gave them entry to my coupling evaluation CLI. The AI largely discovered affirmation within the knowledge, however not any extra findings. Quite the opposite, it identified numerous issues that the CLI was lacking. It is also value noting that the second run of the evaluation (with out context of the primary one) surfaced yet one more difficulty that the primary run didn’t discover. A helpful reminder that when it issues, it is usually value operating an LLM-based evaluation a number of occasions, to get a fuller image.<\/p>\n Listed below are some highlights from the outcomes (mannequin used was Claude Opus 4.7, similar as for the coupling evaluation):<\/p>\n General, codebase design and modularity looks as if a priority the place computational sensors alone can not assist us a lot, AI is required so as to add semantic interpretation, and contemplate trade-offs.<\/p>\n<\/section>\n<\/section>\nThe appliance<\/h2>\n
![\"Overview](\"https:\/\/martinfowler.com\/articles\/sensors-for-coding-agents\/sensors-example-application.png\")
<\/p>\n
\n The instance app: internet UI, service layer, and exterior APIs.\n <\/p>\n<\/div>\nOverview of all sensors used<\/h3>\n
![\"Overview](\"https:\/\/martinfowler.com\/articles\/sensors-for-coding-agents\/sensors-example-overview.png\")
<\/p>\n
\n The place sensors can run: through the preliminary coding session, within the pipeline, on a schedule, and in manufacturing.\n <\/p>\n<\/div>\n\n
\n
Base harnesses and fashions<\/h3>\n
Static code evaluation: Primary linting<\/h2>\n
Guidelines for typical AI shortcomings<\/h3>\n
\n
Steerage for self-correction<\/h3>\n
no-explicit-any<\/code> warning.<\/p>\nWe would like issues to be typed to make it simpler to keep away from errors, particularly for key ideas.\nHowever we additionally wish to keep away from cluttering our codebase with pointless sorts. Make a judgment\nname about this. In case you select to not introduce a sort, suppress it with:\n\/\/ eslint-disable-next-line @typescript-eslint\/no-explicit-any -- (give cause why)`,<\/pre>\n<\/section>\n
Managing warnings – now extra possible?<\/h3>\n
no-explicit-any<\/code> instance above are difficult, since you do not at all times wish to repair them – it relies upon. And suppressing them one after the other has at all times felt tedious, and like noise within the code.<\/p>\nObservations<\/h3>\n
\n
no-console<\/code>, telling AI off when it makes use of console.log<\/code>. Within the backend, I would like it to make use of a logger part as an alternative. Within the frontend, I’d wish to not use direct logging in any respect, or on the very least I would like to make use of a distinct logging part. That is one other instance of the facility of the self-correction steering, and the place AI might help with semantic judgment and administration of research warnings.<\/li>\nmax-lines<\/code> and max-lines-per-function<\/code> guidelines. I’ve seen AI do fairly a little bit of helpful refactoring and breakdown into smaller features and parts because of this sensor suggestions. Nonetheless, within the React frontend, I am seeing a worrying pattern of parts with heaps and many properties because of passing values by way of a rising chain of smaller and smaller parts. I have never bought helpful observations but about how good AI may be at making constant selections between tradeoffs like that.<\/li>\n<\/ul>\n<\/section>\nMost important takeaways<\/h3>\n
Static code evaluation: Dependency guidelines<\/h2>\n
\n
dependency-cruiser<\/code><\/a> guidelines to implement these layers.<\/p>\n![](\"https:\/\/martinfowler.com\/articles\/sensors-for-coding-agents\/sensors-structure-chativity.png\")
<\/p>\n
\n Layered module construction and dependency guidelines\n <\/p>\n<\/div>\nshoppers<\/code> folder by no means imports something from the providers<\/code> folder:<\/p>\n{\n title: \u201cclients-no-services\u201d,\n remark:\n \u201cAPI shoppers should not rely on the orchestration layer above them. \u201c + LAYERS,\n severity: \u201cerror\u201d,\n from: { path: \u201c^server\/shoppers\/\u201d, pathNot: \u201c\/__tests__\/\u201d },\n to: { path: \u201c^server\/providers\/\u201d },\n},<\/pre>\nERROR clients-no-services\n API shoppers should not rely on the orchestration layer above them. \n [Layers: routes -> services -> clients + domain; Services orchestrate: fetch data via clients, compute via domain -- no I\/O, no SDKs, no knowledge of data fetching.]<\/pre>\n
Observations<\/h3>\n
\n
dependency-cruiser<\/code> suggestions, so it did assist maintain my folder ideas.<\/li>\nMost important takeaways<\/h3>\n
Static code evaluation: Coupling knowledge<\/h2>\n
![](\"https:\/\/martinfowler.com\/articles\/sensors-for-coding-agents\/sensors-coupling-dashboards.png\")
<\/p>\n
\n Coupling metrics: internet visualisations and CLI for brokers.\n <\/p>\n<\/div>\nFor human consumption<\/h3>\n
For AI consumption<\/h3>\n
coupling-analyser<\/code>) and requested it to create a report based mostly on the information, together with recommendations of find out how to enhance the essential points.<\/p>\nnpx coupling-analyser<\/code>, not guesswork from static searching alone.<\/p>\nCollect proof (run the CLI)<\/h2>\n
report<\/code> subcommands\u2014mix as helpful for the query:
\n\u2026<\/p>\nWrite the markdown report<\/h2>\n
\n
\n
Observations<\/h3>\n
\n
zod<\/code>) schema between frontend and backend, declared a \u201cgod module\u201d by the LLM. It is a frequent sample although to create an express contract between backend and frontend, and isn’t as a lot of a problem when backend and frontend evolve collectively anyway, and even dwell collectively in the identical repo, like in my case.<\/li>\nindex.ts<\/code> file within the area folder indiscriminately uncovered all recordsdata in .\/area<\/code>, and is imported by numerous locations. Whereas that can be a standard sample to create express contracts for a layer, it does have its professionals and cons, and is a minimum of value an investigation to see whether it is acceptable for this codebase.<\/li>\n<\/ul>\n<\/section>\nMost important takeaways<\/h3>\n
Static code evaluation: AI modularity evaluate<\/h2>\n
\n
Observations<\/h3>\n
\n
Most important takeaways<\/h3>\n
\n
dependency-cruiser<\/code> may be efficient dwell sensors to implement some fundamental folder buildings and dependency instructions, however they will solely go to this point.<\/li>\n