ESSAY · OCTOBER 13, 2026

The Clean Architecture of Working with Agents

Harold Maussa · Inspired by Robert C. Martin’s The Clean Architecture (2012)

Not long ago I watched something happen that repeats itself in many teams. A feature was built that, on paper, was fine: the code worked, the tests passed and the review approved it. But product had already decided not to build it, because maintaining it over time was unsustainable. That decision existed: it was made in a meeting and written down in a wiki nobody reads. Nobody mentioned it in the ticket or remembered it in the review.

Nobody did anything wrong. The decision simply wasn't where the work was happening.

Now imagine that same change made by an agent. It would have written it in an afternoon, without hesitation, tests included. And it wouldn't have known about that meeting either. The difference is that an agent doesn't make one change a week: it makes ten a day.

1. The problem: the agent writes fast, but doesn't know what was decided

In a few months, who writes the code changed. Today an agent like Claude Code can read a repository, understand what is being asked, and deliver in an afternoon what used to take a week. Speed is no longer the problem.

The problem now is a different one: the agent doesn't know the business. It doesn't know that the free check must never show the details of a lien, because those details are what we sell. It doesn't know that a subscription was tried and dropped because the buyer only decides once. It doesn't know there is a prohibition that costs money every time it is broken. None of that is in the code. It lives in a chat from three months ago, in a meeting, or in someone's head.

When a person on the team wrote the code, that knowledge traveled with them. They knew because they were in the meeting. The agent wasn't in any meeting. Every conversation starts from zero, and the product owner ends up repeating the same things over and over, or finding out in production that the agent did something reasonable but wrong.

The usual answer has been to write more instructions: rules files, per-task specs, prompt templates. They help, but they share a fundamental flaw: nobody approved them. They are text someone wrote at some point, which may be stale, may contradict another file, and which the agent treats as a suggestion. They have no authority.

This essay proposes a way to organize work with agents in which what was decided has authority, lives in a single place, and governs everything else.

2. The origin: the Dependency Rule

In 2012, Robert C. Martin published The Clean Architecture, an idea that became a reference in software design. He drew it as concentric circles. At the center, the business rules. Moving outward, the use cases, the adapters and, at the edge, the details: the database, the UI and the frameworks.

What mattered was not the circles but a single rule: dependencies point inward. Code in an outer circle can know about the inner ones, but never the other way around. The business rules know nothing about the database. That way, what matters most and changes least is protected from what changes most.

The question of this essay is what happens if we apply that rule not to the code, but to the development process itself. What if what we put at the center is not the code, but the rules the business has approved?

3. The model

The model has a center, three rings and one rule.

The center: the map

At the center is the product's map: the set of what the business decided, with authority. It is not the spec for a task, nor an architecture document. It is the product's permanent knowledge, organized by areas, with entries of different types:

• Business rules: what the business requires. "The seller image is only generated if the public verdict is green."
• Technical rules: what engineering requires. "Every payment goes through the payment gateway."
• Prohibitions: what is never done. For the agent they are a hard stop: if what it is about to do breaks one, it stops and says so.
• Decisions: a choice between options, with its reason, including what was tried and didn't work.
• Flows: a person's journey, step by step.
• Expected behaviors: concrete examples of what must happen, which later become tests.

Every entry carries its why, which is mandatory, because without it the agent can't tell when the entry applies. And every entry is versioned: nothing is deleted, it is retired, and you can see the map as it was on any date.

What makes this center different is how it changes. Nobody edits an active rule directly, neither people nor agents. Every change arrives as a proposal and becomes active when the right person approves it, according to the type of rule: a business rule is approved by the product owner; a technical rule, by the developer.

The first ring: intents

Around the map are the intents. An intent replaces the ticket, but it tells much more. It has:

• the what and the why, in the person's own words;
• the bet: which business outcome it aims at and why we believe it will move it, with today's measured value and a target;
• the changes it proposes to the map;
• the expected screens, if the change touches something visible;
• the plan.

An intent is not judged by having shipped, but by whether it moved the number it promised to move.

The second ring: building

In the next ring lives the agent. It builds: it writes the code and one test per expected behavior, takes screenshots of what it built and compares them with the approved screens, and delivers a report with real numbers.

The third ring: production and measurement

At the edge is what changes most: the deployment, the live checks and the measurement. Did the number move?

The rule: everything points inward

As in Martin's architecture, there is a single rule: the code obeys the map, never the other way around. If the code and the map disagree, neither is silently corrected. Either the code breaks an active rule, and a fix intent is opened, or the map is wrong, and a change to it is proposed. A person decides.

From the inside out, the rings go from what lasts longest to what changes most. A business rule can last for years. An intent, for weeks. A deployment, for minutes.

4. Every boundary has a contract and a gate

In the original Clean Architecture, the most useful thing is knowing what crosses each boundary. The same holds here, with one difference: every boundary has a gate, and only a person can open it.

The gates require only what the intent needs. A change with no screens asks for no screenshots. But nothing is skipped silently: if a requirement doesn't apply, a person authorizes skipping it, with a reason, and it is recorded. An agent can never authorize it.

5. If something isn't on the map, the agent asks

The model's second loop is what sets it apart most from a static rules system.

When the agent finds a case the map doesn't cover, it doesn't guess. It opens a question, addressed to the right person, with concrete options and what would happen if each one is chosen. Meanwhile, it keeps working on whatever doesn't depend on the answer.

The person answers, often with a single tap. And the answer isn't lost in a chat: it becomes a proposed rule, which goes through its gate and stays on the map.

This way, every doubt the agent has is a chance for the business to write down something that used to live only in someone's head. The map grows with use, from real questions.

6. The loop closes: what is measured goes back to the map

The third loop is measurement. When an intent reaches production, the outcome is measured against the bet. It worked, it didn't, or it was reverted. And what was learned goes back to the map as a decision, with its why.

The next time someone, person or agent, wants to try something similar, the map will tell them it was already tried and what happened.

7. The principles

1. The approved rules are at the center, and everything else depends on them.
2. Everything points inward. The code obeys the map, never the other way around.
3. The agent writes; the person approves.
4. An agent never approves. Not rules, not screens, not the release to production. If it works with no person present, it never approves.
5. Nobody edits an active rule directly. Every change is a proposal that goes through its gate.
6. Every rule carries its why. Without the why, nobody knows when it applies.
7. Every boundary has a contract and a gate. You know what crosses and who lets it through.
8. The agent doesn't guess: it asks, and the answer becomes a rule.
9. The work ends when it is measured, not when it ships.
10. What is inferred has no authority. What the agent infers from the code is useful for proposing, but only what was approved governs.

8. What it is not

It is not a per-task spec. Recent tools, such as GitHub Spec Kit and Kiro, organize an agent's work in phases (requirements, design, tasks), with a person approving each phase. It is a big step forward, and this model shares the human gate with them. The difference is in what gets approved: a spec lives and dies with its task; the map is the product's permanent knowledge, which governs every task and grows with each one.

It is not a rules file. Instruction files for agents are useful, but nobody approves them, they go stale, and they don't tell a preference from a prohibition. On the map, every entry has a type, an owner, a version and the signature of whoever approved it.

It is not Jira with AI. There are no story points, no sprints, and no tickets that get closed without anyone looking back. What goes first is decided by how much it moves a business outcome.

It doesn't take the person out of the loop. Many agent systems aim for the person to step in as little as possible. This model puts the person at the center: they define the what and the why, and they approve what defines the business. The agent executes within those boundaries, at full speed.

9. The limits

An honest model has to say where it can fail.

The friction of approving. If every change needs a signature, approving can become a burden. The model's answer is that only what defines the business gets approved; the agent records progress without blocking anyone. But this has to be measured: how many approvals there are per week and how long they wait.

The agent can forget. Rules and instructions are, in the end, text the agent reads. In a long task it can forget to record progress or to check the map. That is why instructions are not enough: you need reminders at fixed moments, such as when a branch is created or a pull request is opened, that tell the agent what is due, right when it is due.

The map can fall short. The map only knows what someone approved. The question loop makes it grow, but at first it will be incomplete, and the agent will ask a lot.

Infer or approve. Some argue that context should be inferred from the code and its history, because documents go stale. It is a serious criticism. This model's answer is that what is inferred has no authority, and that the question loop keeps the map from going stale. But the proof is not the argument: it is measuring whether, after a few weeks, the agent stops doing things the business doesn't expect.

10. A real case

The model is not theoretical: we are using it on PlacaSegura, a product that checks a vehicle's history before you buy it.

The owner wrote, in plain words: "The How it works section is dull and irrelevant." From that sentence, the agent:

1. Checked the map for the areas the change touched and respected their rules, including the prohibition on showing, in the free check, the details that are sold.
2. Drafted the intent: rebuild the section as a three-step journey with real pieces of the product, betting that if visitors see what they get for free and what they unlock by paying, more of them will try the free check. It measured today's value (4.1% of homepage visits) and proposed a target (5% in 28 days, without lowering purchases).
3. Uploaded the expected screens, for phone and desktop, and a spec, for the owner to approve before any code was written.
4. Proposed a new expected behavior for the map, which later became a test.
5. Built it and recorded each step of the plan, compared the screenshots with the approved screens and delivered a build report.
6. Deployed it, with its report of checks, and the intent moved to measurement.

Today that intent is waiting for its deadline to find out whether the number moved.

The case also showed the limits. In the first run, the agent built and shipped without recording any progress: the instructions were there, but it forgot them. The fix was the one described above: reminders at fixed moments that tell it what to record. In another run, the agent uploaded a mockup that didn't render outside the project, and the system learned to reject that kind of mockup with a message that says what is missing. Every failure ended in a new rule or a fix to the system. That is, on a small scale, the model working on itself.

11. Closing

When the code is written by an agent, writing is no longer the hard part. The hard part is deciding well what to build, knowing what was decided before, and checking whether it worked.

We don't need a faster Jira. We need a place where what was decided has authority, where the agent asks instead of guessing, and where the work ends when it is measured.

Clean Architecture taught us to protect the business rules from the details that change. In the age of agents, the lesson is the same, one level up: protect what the business decided from the speed at which code is written today.

The agent writes. The person approves. An agent never approves.

This model is being built as a platform at Daidara.