For the last decade, I've been a disciplined developer. I followed the rules. I built Controllers that talked to Services, Services that talked to Repositories, and Repositories that talked to the database.

I drew the diagrams. I put everything in its own little box. I was proud of how "decoupled" my code was. If you asked me why, I'd say: "So it's easier to maintain."

But recently, I've been building AI agents, and I realized something painful: The architecture that makes code easy for humans to read makes it terrible for AI to use.

The Problem with "Hiding" Things

The whole point of Clean Architecture is abstraction. You hide the messy details (like SQL queries or API calls) behind nice, clean interfaces so the developer doesn't get overwhelmed.

But AI agents need the details.

When you ask an LLM to "check the last five orders and refund the ones that are stuck," it needs context.

It needs to know what the data looks like.
It needs to know which tools are available.
It needs to know how things connect.

If you bury that logic behind five layers of abstraction, the AI is flying blind.

An Example: The "Clean" Trap

Here is the kind of code I used to write. It's "clean."

class OrderService:
    def __init__(self, repository, notification_service):
        self.repo = repository
        self.notifier = notification_service

    def place_order(self, order_data):
        # 1. Validate
        # 2. Save to DB
        # 3. Send Email
        # 4. Return result
        pass

To a human, this is great. To an AI agent trying to use this code, it's a black box. The agent doesn't know that place_order also sends an email. It doesn't know if it checks inventory first.

To figure that out, the AI has to:

Read the OrderService file.
Realize it needs to check the Repository interface.
Realize it needs to check the NotificationService.

That is a lot of "thinking" steps. In the world of LLMs, every step costs money (tokens) and time (latency).

AI Doesn't Want Layers; It Wants Tools

I'm starting to realize that building for AI means unlearning some of my favorite habits. AI doesn't thrive on vertical layers; it thrives on flat registries of tools.

Instead of a deep hierarchy, an agent wants a menu:

get_order_status(id)
refund_order(id)
update_shipping_address(id, new_address)

It doesn't care if the code behind refund_order is "clean." It just needs a reliable function description so it knows exactly what will happen when it calls it.

The "Spaghetti" Dilemma

Does this mean we go back to writing messy code? I hope not.

But the "unit" of our architecture is changing. We used to optimize for Human Cognitive Load—breaking things down so they fit in our brains. Now, we have to optimize for Context Windows—fitting the right info into the prompt so the AI can reason about it.

I'm finding that my new architecture looks different:

For Writes (Saving data): I still use strict layers. We can't have AI Hallucinating database transactions.
For Reads (Getting info): I'm tearing down the walls. I'm giving the AI direct, read-only access to data views so it doesn't have to jump through hoops just to answer a question.

The Bottom Line

Clean Architecture was designed for a world where humans were the only ones reading the code. That world is gone.

If you're building agents, stop worrying about whether your dependency injection is pure. Start worrying about whether your AI can actually find the tools you built for it. The prettiest architecture is useless if the agent can't figure out how to use it.

Anas Douib

I Spent Years Learning "Clean Architecture." AI Just Killed It.