Software Architecture: Agent-Friendly Architecture

Software architecture is the foundation on which any digital solution is built. It defines not individual lines of code or specific technologies, but the overall way the system is organised: how its parts are connected, how responsibilities are distributed, and how the project’s evolution, resilience and clarity are ensured.

This article examines the use of both established and emerging architecture types in work with AI agents.

Using established architectures with AI agents

For development involving AI agents, what emerges is not so much entirely new “classical architectures” as architectural styles and practices that make a project understandable, changeable and safe for an agent.

The core idea: an AI agent needs an architecture with explicit boundaries, small modules, good contracts and fast tests.

Using emerging architecture types with AI agents

The best architectures specifically for AI-assisted development

Three of the most convenient options.

1. Modular monolith + Clean/Hexagonal in the context of AI agents

This is probably the most practical option.

app/
  modules/
    orders/
      domain/
      application/
      infrastructure/
      api/
    payments/
      domain/
      application/
      infrastructure/
      api/
    users/
      domain/
      application/
      infrastructure/
      api/

Why this works well for AI:

Task: "add order cancellation"

The agent understands:
- go to modules/orders
- look for business rules in domain
- write the cancellation scenario in application
- add the endpoint in api
- put the database work in infrastructure

This reduces the chance that the agent will start changing everything in sight.

In other words, business logic does not depend directly on the database, API, queues or LLM. It communicates with them through interfaces — ports and adapters.

Example:

OrderService
 ├─ uses PaymentPort
 ├─ uses NotificationPort
 └─ does not know whether it is Stripe, PayPal or a mock

This matters for an AI agent, because it can:

• change one module without breaking the whole system;
• quickly find the business logic it needs;
• write tests using mock adapters;
• safely replace external integrations;
• add AI features as a separate adapter rather than smearing LLM code across the project.

In short: a modular monolith gives the agent clear boundaries, while Clean/Hexagonal gives it safe points of change.

2. Vertical Slice Architecture in the context of AI agents

Very convenient for feature-driven development with agents.

features/
  orders/
    create-order/
      command.ts
      handler.ts
      validator.ts
      tests.ts
    cancel-order/
      command.ts
      handler.ts
      validator.ts
      tests.ts
  payments/
    pay-invoice/
      command.ts
      handler.ts
      tests.ts

The key characteristic: code is organised by user scenario, not only by technical layer.

This suits prompts such as:

Add a "cancel order" feature

It is easier for the agent to create a new feature folder and leave everything else alone.

Drawback: the shared business model still has to be maintained carefully, otherwise rules will be duplicated.

The core idea:

one business capability = one vertical slice of code.

This helps agents to:

• find the right place faster;
• change a feature locally without touching anything extraneous;
• understand the business context more easily;
• write tests next to the logic;
• refactor more safely;
• generate new features from an existing template more effectively.

In short: Vertical Slice Architecture makes the codebase look like a set of clear tasks rather than a maze of layers.

3. Plugin / Extension Architecture in the context of AI agents

A good fit when an AI agent has to add new capabilities frequently.

core/
  plugin-api.ts
  plugin-loader.ts

plugins/
  export-to-pdf/
  telegram-notifications/
  stripe-payments/
  ai-summary/

Why it is convenient:

New capability = new plugin
Less risk of breaking the system core

This is especially useful for IDEs, CMSs, internal platforms, automation systems and SaaS products with extensions.

In the context of AI agents it is particularly convenient: the agent does not have to rewrite the whole system and can instead plug in a new function as a separate module.

What makes an architecture “agent-friendly”

Poor architecture choices for AI agents

Practical recommendation

For most projects that will be actively developed with AI agents, I would choose:

Modular monolith
+ Vertical Slice for features
+ Hexagonal/Clean inside complex modules
+ DDD for complex business logic
+ strict typing
+ tests next to the code

Example:

src/
  modules/
    orders/
      domain/
        order.entity.ts
        order-status.ts
        order-policy.ts

      features/
        create-order/
          create-order.command.ts
          create-order.handler.ts
          create-order.test.ts

        cancel-order/
          cancel-order.command.ts
          cancel-order.handler.ts
          cancel-order.test.ts

      ports/
        order-repository.ts
        payment-gateway.ts

      adapters/
        postgres-order-repository.ts
        stripe-payment-gateway.ts

      api/
        order.controller.ts

This style suits both humans and AI agents: it is clear where the business logic is, where the scenarios are, where the integrations are, and what can be changed safely.

Agent-Friendly Architecture / AI-Native Development Architecture

That is, an architecture deliberately optimised not only for people but also for AI agents that read code, plan changes, run tests, refactor and open pull requests.

Important: this is not yet a canonical architecture with a single agreed name, but an emerging style. Recent material from OpenAI and Martin Fowler, along with articles from 2025–2026, speaks more about the shift towards AI-native engineering, agentic workflows and the need for an architecture in which humans focus more on design and oversight while the agent handles implementation.

How it differs from conventional architecture

Conventional architecture was optimised for:

The core idea:

A good architecture for an AI agent is one in which a task can be completed locally, against an explicit contract, with a fast test and minimal risk of breaking neighbouring parts.

Agent-Friendly Architecture is a way of designing a product, codebase or system so that AI agents can work with it comfortably.

The idea is simple: the agent should be able to understand, change, verify and safely complete a task.

In practice this usually means:

• A clear project structure: where the logic, tests, configs and documentation live.
• Good documentation for the agent: for example README, AGENTS.md, instructions for running the project and code style guidelines.
• Automated checks: tests, linters and CI, so the agent can verify its own changes.
• Small independent modules: it is easier for the agent to change one part without breaking everything.
• Explicit contracts: APIs, types, data schemas, sample inputs and outputs.
• Safe operations: a staging environment, dry runs, and restrictions on access to secrets and production.

What the new architecture might look like

Provisionally, it could be called:

Agent-Oriented Modular Architecture

Or, more briefly:

AOMA — Agent-Oriented Modular Architecture

This is not an official standard, but it is a good working name.

Its essence:

The system is divided not merely into modules, but into agent-friendly workspaces:

• - each module has an explicit contract
• - each feature has a local context
• - tests sit alongside the code
• - there is a README for the agent
• - there are machine-readable specifications
• - architectural rules are checked automatically

Example structure:

src/
  modules/
    orders/
      AGENT.md
      README.md
      module.contract.yaml

      domain/
        order.ts
        order-policy.ts

      features/
        create-order/
          task.md
          create-order.handler.ts
          create-order.test.ts

        cancel-order/
          task.md
          cancel-order.handler.ts
          cancel-order.test.ts

      ports/
        order-repository.ts
        payment-gateway.ts

      adapters/
        postgres-order-repository.ts
        stripe-payment-gateway.ts

      architecture.rules.ts

The key new characteristic

Not simply “clean layers”, but a codebase as a navigable environment for the agent.

That is, the architecture answers not only the question:

How should the system work?

but also the question:

How can an AI agent safely change this system?

The main principles of such an architecture

How this differs from Clean Architecture

How it differs from microservices

Microservices give you independent deployment, but they are not always convenient for an AI agent: it is harder for the agent to account for the network, API versions, distributed transactions, observability and asynchronous effects.

By 2026 there are already discussions and even benchmarks comparing which architectures agents find easier to work in. Material on ModulithBench, for example, argues that a modular monolith may be more convenient for agent reasoning than microservices, thanks to locality and lower distributed complexity. This is not a settled scientific consensus, but the direction is telling.

A practical version of the “new” architecture

For a real project I would choose the following formula:

Agent-Oriented Modular Architecture =
  Modular Monolith
  + Vertical Slice Architecture
  + Hexagonal boundaries
  + DDD for complex domains
  + AGENT.md in every module
  + architecture tests
  + typed contracts
  + local tests for every feature

Example AGENT.md

# Orders Module — Agent Guide

Purpose:
This module manages order lifecycle.

Allowed changes:
- Add new order features inside features/
- Put business rules in domain/
- Use ports/ for external dependencies

Do not:
- Call payment provider directly from domain/
- Import infrastructure from domain/
- Modify payments module without updating contract tests

Common tasks:
- New order action → create folder in features/
- New persistence logic → update adapter + repository port
- New business rule → update order-policy.ts and tests

This is extremely useful: the agent does not merely “guess” where to write code, it receives local instructions.

Conclusion

There is as yet no completely new, officially recognised architecture. But a new style really is taking shape:

Agent-Friendly / AI-Native / Agent-Oriented Architecture

Its defining characteristic:

design the codebase so that an AI agent can safely understand, change, test and extend it in small, controlled steps.

In practice, the best foundation for this right now is a modular monolith + vertical slices + typed contracts + local documentation for agents.