Architectural Autonomous Agentic LoopsArchitectural Autonomous Agentic Loops

My work as a software architect is shifting towards designing systems that can self-validate.

This, in turn, enables the usage of autonomous agentic loops that don't compromise the quality of the code.

I want to show you in this issue what my learnings are when designing architectural autonomous agentic loops.

#The prerequisites

Letting agents code autonomously in a project without a harness is right down a temerity.

Not only you are going to lose intent about what the code should look like, you are going to end up with how the average looking system is, which, to me, doesn't reflect best practices.

“

Agents don't have taste.

”

So, a strong test suite, including unit, integration and e2e tests, is down right essential. Mutation and property testing are also an interesting approach to reduce the number of bugs.

Architectural tests are something I'm also looking at.

Linting through Biome or Oxlint can catch a ton of inconsistencies, while compiling using TypeScript is mandatory for scalable projects, even with AI.

As you can see, anything that can validate the project through code.

All of this still doesn't matter if you can't capture the intention of the changes.

#The intention

Pre-AI setting the intention for a new feature was part of the process.

We would first describe the problem to solve through a User Story, following Agile Methodologies. When using AI to develop features, it's extremely easy to fall into the mindless trap of letting agents figure out all the paths and solutions to a given problem. Sometimes it is going to solve the problem at hand and sometimes, is going to solve something it wasn't supposed to solve. Or solve it in a way that is not architecturaly correct.

Moreover, figuring out what needs to be solved and why is what creates intention.

Don't you feel in full agentic designed systems that the knowledge about what things do or why they behave like they do is... diluted?

Rightly so, you can see that there's no intention behind the prompts sent to AI. These types of prompts look like this:

• Implement all issues
• Refactor the app for best practices
• Fix production

This prompts arise too many questions. How should the issues be implemented? What are best practices? What and why is broken?

So, we need touchpoints where we can set a well-thought-out, verbalized intention about the task at hand. What and why.

Right now I'm in the process of figuring out those touchpoints. ADRs (Architectural Decision Records), User Stories, issues, specs, or change releases are all candidates for these touchpoints for a Human in the Loop (HITL). The touchpoints should be designed so they bring out intention.

Once we have the intention, we can move on to execution.

#Goals for planning loops

When I'm tackling a big, yet well-defined, task, and once I have a harness I can trust, I start with the /plan mode.

I feed all the information necessary and context. I'm mindful about how much context I feed into, only the necessary. Too much context is also an issue.

Once the context is set, then, I ask the AI to interview me to gather more context about the task at hand.

/plan I want to migrate [module] from [current state] to [target state].

Context:
- Issue: [link]
- Related code: [paths]
- From the team: [messages, constraints]

Before planning anything, explore the code and then interview me to gather more context:
the current flow, edge cases, what's out of scope, what done looks like. Keep asking
rounds of questions until you have no relevant ones left. Only then write the plan.

This is one of the techniques I've found most useful. Sometimes you don't know what questions needs to be answered. Well, let the AI figure that out while you still provide the right answers.

Once it has detailed the plan, I go over it, making adjustments if necessary.

And then, depending on if it's an open plan where I want the agent to have more freedom, or a closed plan where in turn I want the agent to have less freedom, I choose to use /goal or /loop.

/goal The plan in [plan.md] is fully implemented: every step checked off, tests passing,
lint and typecheck clean, no commits pending, and the change verified manually in [environment].

/loop Work the next unchecked phase in [plan.md] to a green gate: tests, lint and
  typecheck passing. Commit, tick its boxes and continue until all phases are complete.

They might seem similar, but knowing when to use which one is important.

I've found useful for migrations to ask the AI to generate a skill where it documents its learnings, when the migration is finished, that skill is deleted.

Then after it has generated the code, commits and updated the pull request, I review the code. Since I have the harness, and a well-defined plan, the output is what I was expecting: high-quality, intention-driven code. Just as I like it.

#Conclusion

Knowing about best practices, architecture, design patterns and having a problem-solving mind translates well into designing architectural autonomous agentic loops.

Agents can code whatever you tell them to code. Knowing how they should code and creating a system where we can validate the quality of the code, is the only realistic way of creating an architecture that lasts.

P.S: No P.S today.