Why Good Software Is Also AI-Friendly Software

A few years ago, I was facing an architecture problem that had nothing to do with AI.

A product had to support multiple tenants and white labeling. In the end, we needed roughly seven clients. Functionally and technically, they were closely related, while still having deliberate differences. The simplest description was:

same, but different.

At the time, I already had fairly clear ideas about how I wanted to modularize Angular applications. What I was missing was a sustainable structure for multiple applications, shared capabilities, and deliberately separated specifics without ending up with seven largely independent copies or a configuration monster that nobody could reason about anymore.

While looking for that structure, I more or less stumbled across Nx. Not because I desperately wanted a monorepo, and certainly not because I wanted to optimize a repository for coding agents. Coding agents in their current form did not even exist yet.

I was initially interested in a very concrete product problem. Only afterwards did I discover the more general properties that a shared workspace brought with it: applications, libraries, and their relationships were discoverable in one place. Tooling could be standardized. Dependencies became more visible. Shared technical capabilities could be reused deliberately.

For me, the emphasis is still on deliberately.

I am not particularly fond of the idea that a monorepo is primarily an invitation to maximize reuse. A shared codebase makes reuse easier. That does not answer whether another shared dependency is architecturally sensible.

Looking back, something else interests me more today:

Many of the properties that are becoming useful for coding agents were originally built for humans.

Monorepos are only one example. Visibility, shared toolchains, reproducible builds, clearly defined dependencies, and automated tests were classic developer-experience topics first. Coding agents give them a second consumer.

That does not mean that every large shared repository automatically becomes agent-friendly.

Having everything in one place is not architecture.

From Repository to Executable Workspace

The more interesting step for me came later.

In professional environments, I had long been used to a very traditional separation: frontend here, backend there, each with its own repositories, build processes, and development environments. The two sides communicated through defined contracts.

There is nothing inherently wrong with that. I could test the frontend locally, test the backend locally, and inspect the contract to understand how both sides were supposed to communicate.

A problem spanning the complete system flow still introduced another boundary. Perhaps the issue started in persistence, was transformed incorrectly in a service, passed through an API, and only became visible in the client. Technically, this was one failure scenario. For analysis, however, the relevant parts lived in several different workspaces.

At some point, something about Nx became more important to me than repository organization itself. Nx knows projects and their relationships through the Project Graph. Targets or tasks describe executable capabilities of those projects. Task pipelines and dependsOn allow dependencies between tasks to be expressed, while run-many can execute the same standardized tasks across multiple projects.

For me, the decisive idea is not tied to a particular Nx version:

If a workspace knows its dependencies, it can do more than organize files. It can orchestrate parts of the system.

At first, this was classic developer experience again: fewer manual startup sequences, less project-specific knowledge about which command had to be run where, and less custom orchestration logic for relationships that the workspace already understood.

Privately, I pushed that idea further in my own SCS system. Central parts of several domain systems live in one shared codebase. Depending on the area, that includes the client, API, service, database-related infrastructure, libraries, contracts, container configuration, tests, and Infrastructure as Code.

The CI pipeline uses that system knowledge as well. Through Nx, it determines which deployable projects are affected, builds only the relevant Docker targets, and then maps them to the concrete stacks and services.

That changes what the repository represents. It no longer contains only the system’s code, but increasingly also the mechanisms used to build, start, test, and operate substantial parts of that system.

The system itself becomes an executable workspace.

At first, this development had nothing to do with agentic work. That is exactly why I find it so interesting today.

Understand System-Wide, Change Locally

An executable workspace explicitly does not mean that I give a coding agent one giant task that cuts through the entire system from database to view.

With sufficiently clear requirements, an agent could probably implement such an end-to-end change. I still try to do almost the opposite: the actual work packages should remain as small as possible.

What the shared system changes most is analysis.

If a defect has to be traced from the view into a backend service or all the way to persistence, I want as few artificial boundaries as possible in the agent’s line of sight. If a contract changes, the dependent code should be reachable. If an E2E test fails, the analysis should not stop simply because the next relevant layer happens to live in another repository that the current workspace cannot access.

Implementation follows a different rule.

Wide view, narrow change scope: for analysis, the agent should be able to understand the relevant flow across the system, while the actual implementation remains limited to a small autonomous workspace.

I do not see a contradiction there.

The agent may understand system-wide without having to change system-wide.

Article 10 in this series looked at the open decision space: where do we need exploration, where do decisions have to be made, and when should implementation become as boring as possible? This is a related but different question. A small implementation task does not mean that we should artificially remove every view of the surrounding system from the agent. For analysis and verification in particular, the broader view can be valuable.

At the same time, a huge implementation task does not become better merely because the agent can theoretically reach the entire system.

The architecture should support both: a wide field of view and a narrow change scope.

The Knowledge That Is Not in the Repository

That broader view does not solve another problem: a repository never automatically contains all the knowledge a team has about its system.

Humans compensate for this surprisingly well. A developer may have worked in a system for five years and know that a particular class looks like the right entry point but should no longer be used for new functionality. They know that a service is historically located in the wrong place. They know about a dependency that is barely visible in the code. And they know which of two existing patterns is more common, but should no longer be continued.

Sometimes the most honest description is simply:

It is written down nowhere. We just know it.

Software development is a knowledge-intensive activity, and research on software maintenance, tacit knowledge, and architecture decision knowledge has long described how relevant domain, architecture, and historical decision knowledge is often documented only incompletely. Coding agents do not change that fundamental problem.

They simply do not automatically possess the organization-specific history that has accumulated in a team’s heads over the years.

Initially, they can work with what is reachable and interpretable: code, repository structure, documentation, contracts, tests, build configuration, agent files, static rules, version history, logs, and executable tools.

Current research on coding agents already shows that even finding the correct repository context is a separate challenge. Agent Retrieval Bench isolates precisely this phase and shows, among other things, that recorded agent trajectories miss all files marked as relevant in a substantial share of cases. ContextBench examines the same mechanism from another direction and finds measurable gaps between explored context and context that is actually used.

That does not mean every piece of experiential knowledge should be documented. That would be neither realistic nor useful. It does mean, however, that a system becomes less mysterious to an agent the more relevant rules and relationships can be derived from the system itself.

Hidden knowledge versus explicit system knowledge: knowledge that exists only in the team's heads is not automatically available to the agent; contracts, tests, boundaries, and documented decisions are reachable and can partly be checked mechanically.

Explicit contracts help a new developer. They also help the agent. Architecture rules help the team. They also help the agent. A reproducible build helps the developer who set up a new laptop on Monday morning. It also helps an agent that is supposed to verify its own change.

This is where old software-engineering ideas gain a new audience.

Consistency, Standards, and Machine-Readable Structure

I have a pronounced preference for consistency. Or, less diplomatically:

Consistency is my mantra.

When I slice domains, I want them to read similarly at a structural level. Not identically – different domain problems can require different solutions. But familiar layers should have the same meaning. Recurring patterns should be recognizable. Commands should not differ without reason. Lint rules should apply centrally. Tooling configuration should produce as few local surprises as possible.

That was already my position as a tech lead, long before I started working seriously with coding agents.

Interestingly, I am more cautious about claiming that an agent needs this consistency in the same way a human does. Humans orient themselves strongly through recognition. If ten domain areas are structured similarly, the cognitive entry cost into the eleventh is lower. An agent may be able to analyze one area perfectly well without ever having seen the other nine.

And that is actually desirable.

An agent does not need to understand the whole repository if the architecture ensures that it does not have to.

Consistency still matters. It stabilizes expectations within the relevant area, enables generic checks, reduces special knowledge in build and test logic, and increases the likelihood that an explicit rule can actually be enforced across the system.

That leads to a second mantra of mine:

Stick to the standards.

I have experienced firsthand with Nx what happens when structures deviate unnecessarily far from the mechanisms the tool expects. Custom executor logic, special-case configuration, and individual project structures can look clever in the short term. During later upgrades, that special knowledge has to be migrated as well.

This is not an argument for accepting every default without question. Framework and tooling standards are not laws of nature. The more interesting engineering rule is:

Every unnecessary deviation creates additional special knowledge.

For humans, for tooling, and increasingly for agents.

That is why there is room here for a small argument in favor of Nx. Not for turning every software system into an Nx monorepo, and certainly not for claiming that Nx is an AI platform.

What interests me about Nx is that it is a concrete example of how classic software-engineering ideas can become explicit, queryable, and executable. The workspace consists of projects. The Project Graph describes their relationships. Tags can express semantic categories. Targets or tasks describe executable capabilities. Task pipelines describe dependencies between those tasks. run-many executes standardized tasks across multiple projects. affected combines a Git diff with the Project Graph and determines which part of the workspace may be affected.

The graph itself is not merely a visualization either. Nx can export Project Graph and Task Graph data or expose them for concrete executions. That makes part of the repository topology machine-readable.

I do not like Nx because every system should be a monorepo. I like the idea that substantial parts of repository topology can become explicit, queryable, and verifiable.

For humans, that is good developer experience. For agents, it becomes accessible structure.

Architecture That Can Talk Back

I have used module boundaries in Nx practically from the beginning. Here too, AI had nothing to do with the original motivation.

For example, I wanted to prevent UI-specific libraries from suddenly being used in the business layer. Domain areas should not be able to import each other’s internals arbitrarily. Dependency directions should not exist only as a diagram.

For JavaScript and TypeScript projects, Nx provides @nx/enforce-module-boundaries for this purpose. Projects can be classified using tags, and dependency constraints can define which categories an area may access or which dependencies are forbidden. For cross-language rules on the Project Graph, Nx additionally provides conformance rules.

Article 8 explained why mechanisms like these limit the structurally valid solution space. Here, a different effect interests me: they provide feedback.

An agent changes code. Lint runs afterwards. And the architecture can answer a concrete violation.

This import is not allowed.

At that point, the agent does not need a perfect interpretation of my architectural intent. It receives machine-readable feedback about the result of its change.

Mechanically executable architecture can tell an agent where its own work has violated a boundary.

That is the difference between a rule that exists only on a wiki page and a rule that produces a failed task when violated. Documentation explains intent. The executable rule checks part of the result. Both have their place.

`affected`: Making Scope Executable

One of the concepts I find particularly strong in Nx is affected.

Its core behavior is straightforward: Nx determines changed files via Git, maps them to projects using the Project Graph, and then includes dependent projects as well. Tasks such as test, lint, or build can therefore be limited to that subset.

That is where affected becomes architecturally interesting to me.

If everything depends on everything else, everything is affected all the time. A Project Graph still exists formally, but its practical value as a scope limiter drops considerably.

For affected to be truly powerful, a system needs properties we should want anyway: autonomy, clean dependencies, limited change radii, and deliberate boundaries.

In my private system, affected is no longer merely a CI optimization. The pipeline determines affected projects with a docker:build target and then limits build and deployment to the resulting services or stacks.

For agentic work, this adds another interpretation.

Affected as verification scope: with cleanly separated dependencies, a small change leads to a small affected graph and therefore a smaller verification space.

This is explicitly not a universal architecture metric. A central library may legitimately have many consumers. Some changes are system-wide by nature. And an incorrect dependency graph can merely create a false sense of safety.

I still find the scope interesting as an engineering signal.

A small affected scope is not only faster. It can indicate that a change can be understood and verified locally.

For me, affected therefore becomes CI optimization, scope detector, and verification aid at the same time.

Reuse Without a Shared-Code Festival

At this point, a classic monorepo reflex appears: if everything is reachable together, surely we can finally reuse everything.

Technically, yes. Architecturally, I consider that conclusion dangerous.

With domain reuse, I want to look very closely. If two areas genuinely own the same domain concept with the same responsibility and the same reason to change, a shared owner can make sense.

With purely technical reuse, I am far more cautious. An OAuth guard that represents a genuine shared technical capability may deserve its own library. Two mappers that happen to look almost identical are not enough reason for me to couple otherwise autonomous areas.

I would rather write a mapper twice than introduce a new dependency between two autonomous areas to save three lines of code.

That is not a blanket rule against reuse. It is a prioritization of autonomy over reflexive DRY.

Vaughn Vernon points out in this context that DRY is easily confused with merely avoiding identical lines of code, even though the underlying idea is more strongly about duplicated knowledge. For my argument, the more cautious conclusion is sufficient anyway: code that looks similar is not automatically the same model, and it is not automatically a good reason for a new dependency.

A monorepo is not a shared-code festival. A common codebase makes reuse possible. Architecture still decides when that becomes a meaningful shared capability and when it merely introduces new coupling.

From Developer Experience to Agent Infrastructure

Up to this point, it might sound as though this article is mostly about monorepos and Nx. That would miss the point. Nx is simply a particularly tangible example.

The actual idea becomes visible when we look at the entire development environment.

For years, we have invested effort in reproducible local environments, containers, standardized startup commands, unit tests, integration tests, E2E, lint, formatting, type checks, build targets, dependency graphs, architecture rules, Infrastructure as Code, and CI pipelines.

The original consumer was the developer.

A good local environment was supposed to prevent a new team member from spending three days interpreting hand-written setup instructions. A standardized build was supposed to be reproducible. Tests were supposed to provide feedback. Lint was supposed to detect trivial errors and rule violations automatically. Containers were supposed to reduce environmental differences. CI was supposed to repeat relevant checks reliably.

All of that was developer experience.

Then a new consumer of that infrastructure arrived.

A coding agent can now use the same mechanisms itself.

Developer experience becomes agent infrastructure: the agent makes changes, uses build, lint, and tests, starts relevant services, runs E2E, reads failures, corrects the change, and verifies again.

This is not merely a theoretical product idea. Software-engineering benchmarks and agent environments such as SWE-agent, SWE-Gym, and SWE-bench are built around the ability to navigate repositories, edit files, and evaluate generated changes against executable runtime and test environments.

That does not yield a general productivity claim for my own repository. The underlying mechanism is still clear: a coding agent becomes significantly more useful when it can interact with an executable software environment rather than merely generate text.

What used to be developer experience is increasingly becoming agent infrastructure.

Agent-Readable Is Not Enough

For me, this is probably the strongest consequence.

When we talk about AI-friendly repositories, we quickly arrive at context: good documentation, agent files, clear filenames, repository maps, and architecture overviews. All of that matters. An agent has to be able to find relevant information.

A repository can be highly readable and still be a poor agentic workspace.

Imagine a system with excellent documentation. The agent understands the architecture, finds the right service, identifies the relevant contract, and writes a plausible patch.

And then?

The build works only on one colleague’s machine. Tests barely exist. The local backend stack has not started successfully for months. E2E means someone manually clicks through five steps in a test environment. Lint rules differ between subprojects. The most important architecture rule exists only in a diagram.

The agent can formulate its hypothesis very well. It can barely test it.

AI-friendly therefore does not mean only agent-readable. It means agent-verifiable.

Or, more generally:

AI-friendly software gives an agent not only context. It gives the agent feedback.

A larger context window can hold more files. It does not create a working test. Better repository search can find the right service. It does not make a broken local build reproducible. An excellent agent file can explain that Presentation must not depend on Infrastructure. A mechanical boundary rule can additionally reject the concrete violation.

That changes how we should judge a good agentic workspace. Not only: How much repository context can the agent see? But also: How reliably can it move from “I think this change is correct” to a trustworthy verification result?

The Feedback Loop Belongs to the Workspace

In my own work, I actually let coding agents use these mechanisms.

After a change, I do not want the agent to merely present a diff. Depending on the task, it runs unit tests, runs lint, builds the relevant projects, starts the required stack for suitable features, runs E2E, reads failures, corrects the implementation, and verifies again.

None of these steps proves complete functional correctness. A green build says nothing about whether we built the right feature. A unit test can perfectly protect a wrong assumption. An E2E test checks only the scenarios we actually described. Module boundaries do not prevent every bad architecture decision.

What matters is the combination of different feedback channels. Build answers different questions from lint. Architecture rules answer different questions from unit tests. E2E answers different questions from type checks. Human review answers different questions from all automated mechanisms.

For me, agentic work becomes more robust when the agent can use as many of these channels as possible before the result even reaches me.

My own review shifts its emphasis accordingly. If the agent has already built, linted, and tested the change, I can focus more strongly on questions such as: Is the responsibility in the right place? Is new unwanted coupling being introduced? Does the domain boundary remain intact? Does the solution match the architecture decision made beforehand? Does the patch introduce structural drift? Is the solution appropriate, or merely technically functional?

The agent increasingly verifies function and technical consistency. My own review shifts more strongly toward architecture and decisions.

The word more strongly matters. I still review functionality, I do not blindly trust a green test run, and I do not hand architecture over to a review model. Article 10 already described why I also often use a strong model as another review channel. Human review and model review do not replace one another for me. Executable infrastructure complements both.

I also do not currently optimize primarily for minimum runtime. If I have to choose between a very fast green signal and a complete, traceable report, I choose the report.

I do not only care whether tests were green, but which projects were affected, what was built, which tests ran, which architecture rules were checked, what was skipped, which warnings appeared, and which failures may have had to be corrected first.

That result then serves a second purpose: it becomes context itself. I can review the report and additionally give it to a review model, asking, for example, whether the verification performed was sufficient for this change or which risks are still not covered.

Fast feedback is pleasant. Trustworthy feedback is what matters.

Clean boundaries and affected reduce the scope anyway. Parallelization or subagents could optimize runtime further, but would open up other cost questions. That belongs in a later article.

Explicit, Bounded, Verifiable

If I had to condense the argument so far, I would end up with three properties. Not as a new checklist for “AI-ready repositories,” but as a description of what works well in my own practice.

Explicit: Relevant structure should be visible in the system wherever possible. Projects, dependencies, contracts, layers, commands, tests, architecture rules, and documented decisions where their rationale cannot later be reconstructed reliably from code alone. An agent should not have to guess years of team history for an ordinary change.

Bounded: System-wide reachability may exist. The concrete task should still have a small workspace. A domain does not need to know about five other domains merely because they happen to live in the same repository.

Verifiable: The agent needs trustworthy feedback through build, lint, tests, architecture rules, a reproducible runtime, and E2E where appropriate.

That gives me a fairly precise description:

AI-friendly software makes relevant knowledge explicit, keeps the concrete workspace small, and allows the agent to verify its own change.

Interestingly, none of these properties was invented for AI.

Monorepo Is Infrastructure, Not an Agent Strategy

That brings us back to where this article started.

A repository with two million lines of Big Ball of Mud does not become agent-friendly because all files happen to live in the same Git checkout. The agent may now be able to reach everything. That still says nothing about how much of it must be understood.

Large structured repository versus large interpretation space: clear domain boundaries, explicit dependencies, and small local workspaces allow system-wide reachability with limited scope; global utilities, unclear ownership, cross-dependencies, and competing patterns create a large interpretation space instead.

Another repository may be the same size and have a completely different structure. What matters is not the size of the checkout, but how much of it must actually be understood for a concrete change.

That is why I would never write that monorepos automatically make agents better. There is neither a clean causal relationship nor a universal architecture rule behind that claim.

My statement is smaller:

A monorepo is infrastructure. Agent-friendliness emerges from structure.

A shared workspace can make system-wide analysis and orchestration easier. Whether it becomes a good agentic workspace depends on its structure.

And What Happens to the Big Ball of Mud?

That brings us to an uncomfortable counter-question.

On this site, I have already discussed the Big Ball of Mud extensively as a long-term architecture and economics problem. Coding agents may change something about that – just perhaps not in the way we first expect.

My current personal hypothesis is: A coding agent may be able to work productively in a Big Ball of Mud for a surprisingly long time. Perhaps even longer than a human.

An agent can search very large amounts of code, follow repetitive structures, reconstruct deep call chains, and analyze the same relationships again and again. The fact that humans eventually hit cognitive and organizational limits in systems like these does not automatically mean an agent will fail at the same point.

Current repository-retrieval research clearly shows that large codebases and context acquisition remain difficult problems. But it does not show that agents necessarily fail immediately in unstructured systems.

That is why the simple claim would be too convenient for me:

Bad architecture does not work with AI.

It probably works for a surprisingly long time.

The more interesting question is: at what price?

Here we leave the realm of robust empirical claims and enter an engineering hypothesis. A growing Big Ball of Mud increases the space of potentially relevant information. More dependencies have to be investigated, more historical patterns compared, more ripple effects ruled out, and more results reviewed.

Over time, that could increase context acquisition, model context, analysis effort, verification scope, review effort, and variable cost per change. I do not know of a robust study from which a general economic curve could be derived today, and I am not going to invent one.

As an engineering inference, however, the following still seems plausible to me:

The technical ability of agents to work with a Big Ball of Mud does not answer the economic or human question of whether continuing to evolve it remains sensible.

Put more pointedly:

A Big Ball of Mud may be irrelevant to the agent for a surprisingly long time. It may not be irrelevant to the budget or to the human who still has to understand the generated solution.

AI may even shift the point at which we perceive a problematic system as no longer economically maintainable. Humans often keep systems like these alive for a long time because they build hidden knowledge. Coding agents could automate part of that navigation.

At the same time, the opposite dynamic exists: if agents produce changes much faster, they can also multiply structural problems much faster. More output does not automatically mean more architecture. If every fast change adds another local exception, higher productivity can accelerate structural erosion.

We do not yet know which of these forces will dominate in the long term.

Agentic work does not remove the technical properties of a Big Ball of Mud. It can change how long we are willing to tolerate their economic consequences.

The full calculation belongs in the later article on economics.

If Good Cuts Become Cheaper

For new functionality, the same cost shift could work in the opposite direction.

Many poor architecture decisions do not happen because nobody can see a better structure. They happen because the cheaper short-term path is attractive: one more feature in the existing large component, one more special case in the existing service, one more consumer of the same shared library, one more small dependency.

A clean new boundary costs time as well.

If code production becomes cheaper through agents, that calculation can change. It may become economically easier to create a new small autonomous unit instead of integrating the next feature into an already overloaded component.

This is not an argument for microservices. An autonomous unit can just as well be a domain slice or a module inside a modular monolith.

The interesting thought is simply:

Cheaper code production can also change the cost of creating good boundaries.

That question leads directly to a later topic in this series: what happens to software architecture when code itself is no longer the most expensive part of software development?

The New Consumer of Old Engineering Ideas

When I used Nx for seven similar but different clients, I was not trying to build an AI-friendly repository. When we standardized build commands, the goal was developer experience. Module boundaries were meant to prevent unwanted dependencies. Automated tests were meant to give humans faster feedback. Containers were meant to make local environments more reproducible. Infrastructure as Code was meant to make infrastructure understandable and reproducible. affected was initially a way to run CI more selectively.

All of these things now have an additional user: the coding agent.

It can read a contract, analyze a Project Graph, invoke a standardized target, receive a boundary violation as a lint error, run a test, start a container, read the failure, correct its patch, and run the cycle again.

That does not suddenly change the definition of good software. But it changes who can benefit from these properties.

The quality of this workspace therefore does not depend only on how large a context window is or how intelligent the next model generation becomes. Part of it lives in ordinary engineering: in boundaries, contracts, the toolchain, tests, reproducibility, and the question of how much relevant knowledge is actually visible in the system.

Many properties of AI-friendly software are old software-engineering ideas with a new consumer.

That is why the shift in perspective now feels fairly clear to me: