Key Takeaways
- Modern architectures often use legacy services for specific tasks, but these services may lack accurate documentation and using them can be risky if you don't understand them well. AI coding agents can help close that knowledge gap.
- You can use an AI coding agent to find and suggest fixes for common architectural problems that are organization-specific or generic.
- AI coding agents can be used to identify and patch security vulnerabilities, which is especially useful when the architecture includes open source packages
- AI coding agents can free teams to experiment, but they need constraints to conform to specific, measurable architectural goals and trade-offs. They can then create prepackaged shell applications that form the foundation for developer-driven prototypes.
- An AI coding agent provides an efficient, fast way to generate Minimum Viable Architectures (MVAs) and evaluate the MVA code through measurable tests.
Automated code generation is not a new concept, but AI coding agents are dramatically faster at coding than anything that has come before. This speed creates huge benefits, but it also creates unique problems because it's very easy to lose control of the quality of the output. This loss of control is especially true of the architecture; if you only feed the AI with functional requirements, the AI isn’t somehow going to make sure the architecture is sound. You have to feed it with specific architectural goals, such as measurable Quality Attribute Requirements (QARs) and trade-offs (see "A Skeptic’s Guide to Software Architecture Decisions"). The AI-generated code needs to be tested to evaluate QAR satisfaction.
Using AI coding agents to develop resilient, scalable, secure systems is in its infancy. You could take a course in using coding agents, read a book, or even find some coaching, but we’re all learning as we go along, trying things, making mistakes, and learning from our experiences. There are, however, some good ways to jump into it, to make the most of experiences without wasting too much time simply trying random things. What follows are some suggestions we have found useful in starting the journey toward using AI coding agents to develop systems with a sound architecture. These suggestions are not a cookbook, not a process, but some useful ways to gain experience and learn purposefully, at least enough so that you can direct your own journey.
Use an AI Coding Agent to Document a Legacy Service That Your Architecture Depends On #
It is common for modern architectures to use legacy services to perform specific tasks, such as retrieving current and historical policy information from an older insurance policy system that may have been created decades earlier. Unfortunately, these services may lack accurate documentation and using them may create issues when their logic and data aren’t well understood.
Example
A seldomly used legacy service written to retrieve information from an IMS database may have unknown issues such as logic or security flaws that cause it to return incorrect information when used in a context that was not planned for when the service was originally written a long time ago. These issues could surface late in the development cycle, for example during system or user acceptance testing, or even after the new system has been moved to production.
In order to mitigate this risk, an AI coding agent can map the system design of the legacy service, including documenting data flows. In addition, it can scan the code of the legacy service, identify potential issues and suggest fixes for these issues. Should the team decide that the legacy service is really in bad shape and has too many issues, the coding agent could refactor the service to make it more understandable and maintainable. This refactoring would eliminate a key risk with the new architecture.
Use an AI Coding Agent to Find and Fix Architectural Flaws #
In addition to finding and fixing security flaws, you can use an AI coding agent to find and suggest fixes for common architectural problems. This coding agent use might be as simple as finding places where architectural standards have been bypassed, where good coding practices have lapsed, or where code needs to be refactored to make it more maintainable. You can even use the coding agent to suggest changes to resolve the issues it finds.
Example
Use the AI coding agent to find common architectural problems such as API design issues, including interfaces that are difficult to use, insecure, or inefficient, and Domain-Driven Design (DDD) boundary violations. Be specific where you would like to look for these issues. For instance, you may ask the AI coding agent to evaluate your service layer to see if it identifies any component directly accessing the internal states of another domain or reusing code from that domain. There is a point of diminishing returns with this evaluation, because the AI will nearly always find improvements. You will need to decide which findings are important and which ones are not.
Using this approach requires that AI coding agents are guided by team members who are experienced in dealing with architectural challenges and know how to phrase the prompt to achieve their desired results by guiding and constraining the coding agent.
Teams provide this guidance in the form of specific, measurable architectural goals and well-articulated trade-offs and alternatives, if they are known, to help focus the coding agent and keep the cost of using it manageable. This approach requires experience to articulate the trade-offs that may need to be made, so that the coding agent can consider them when it generates a solution. Coding agent prompts that only feature functional requirements will miss this focus, and the resulting system’s architecture will likely fail to meet its QARs.
One unintended benefit of using a coding agent in this way is that it forces the team to be more articulate about their trade-offs and what they are willing to accept.
Use an AI Coding Agent to Perform a Security Audit on Your System #
Recent reports of AI coding agents being used by malicious parties to exploit security flaws in existing systems have nearly everyone on edge, but there is a flip side to these risks: AI coding agents can identify these vulnerabilities and patch them, especially when the architecture includes open-source packages. That is to say, are we even using the correct, patched version with the latest security fixes?
You can use an AI coding agent to find security vulnerabilities by scanning source code files, mapping out the design of a system, and writing tests to discover software issues. In addition to pointing out bad code, an AI coding agent can survey a whole system, find complex logic flaws, and generate code to fix these issues. Specifically, you would ask the AI Coding Agent to:
- Map the system design by tracing data flows and identifying risky files (limit the agent's access to reading only approved files).
- Scan the code, looking for complex logic flaws across files (mitigate risk by masking or hiding sensitive database passwords and secrets from AI prompts).
- Test potential vulnerabilities by generating hacker-style scripts to stress-test your defense (keep the agent in a locked network environment so it cannot accidentally attack live servers).
- Fix security issues by generating code patches to close security holes (doing human code reviews is mandatory before merging any code changes).
Example
Following up on testing for vulnerabilities, we received a report from a client that several npm packages that were currently being used were flagged as a security risk. Using an AI coding agent, we evaluated those risks and were able to respond to the client. We provided a detailed report of implications. This approach led us to update two of the packages, replace one package and leave one of the packages as the vulnerability was a false flag. All of this work was done with the assistance of an AI coding agent.
As LLM’s get smarter and more dangerous in the cybersecurity space, it becomes even more important to use AI coding agents to identify potential security issues in your architectures before they can be exploited by bad agents.
Use an AI Coding Agent to Provide Developers with an Architectural Foundation for Their Work #
AI coding agents can free teams to experiment and help users provide requirements by showing them a prototype almost instantly. Unless the coding agent is directed to pay attention to architecture, the result is unlikely to achieve the QARs for the system and will be, for the most part, throwaway prototypes.
To remedy this problem, AI coding agents need to be directed and constrained to conform to specific, measurable architectural goals and clearly articulated trade-offs. The coding agent can then be used to create pre-packaged shell applications which will form the foundation for developer-driven prototypes. The architectural goals and constraints take the form of QARs, coding styles, DB designs, APIs, preferred platforms, and frameworks in Markdown format, while providing this information to the AI coding agent to further refine the model applications.
Example
If you are working with a small React application, use an AI coding agent to look at your folder structure and evaluate it against modern practices. If you are out of alignment with what is recommended or what the React community has adopted, the coding agent can make big or small changes while assisting with that work. As always, check that its recommendations match the context of the problem you are solving.
Additional Example
Teams start new applications all the time. If you find that there are common patterns, you can leverage the GitHub template feature. With this leverage, you can stub out the common structure of applications, create skills the AI can use for you to get a fast start, and have coding standards built right into it, allowing teams to get off the ground in an architecturally sound way.
Describing what you want to achieve yields better results than telling the coding agent what solution it needs to generate. It is natural for people to start describing the solution, but teams should avoid doing this planning; describing goals, constraints, and the means by which goal achievement will be verified is far more effective.
What this decision signifies for architecting is that many unspoken architectural requirements and constraints that were assumed to be understood by good developers now have to be made explicit enough to be implementable and testable. In addition, the team needs to actually test these QARs; it is insufficient to have testable requirements. If you generate these tests using an AI coding agent, you will need to at least review and verify them to make sure they measure correctly.
In effect, coding becomes simpler with AI coding agents, but creating requirements becomes dramatically more difficult. The skills developers have honed over the years (such as writing code) are now less important. What developers have avoided because they find it unpleasant (i.e., understanding and articulating requirements and constraints) is the most important skill the AI-assisted developer needs to hone.
Use an AI Coding Agent to Generate Testable MVAs #
An AI coding agent provides an efficient and quick way to generate code, provided that requirements are correctly specified. At first glance, this approach seems like a good, cost-effective way to quickly replace older, hard-to-maintain applications, such as COBOL programs, with more modern technologies. Unfortunately, some of what the AI coding agent generates will turn out to be wrong. Inspecting AI-generated code is important, but insufficient. Evaluating the code through measurable tests is essential to creating a high-quality software architecture.
As a result, the Minimum Viable Architecture (MVA) needs to include all the code necessary to prove that it satisfies the QARs while also satisfying functional requirements. Using an AI coding agent does not change this fact. Using an AI coding agent to generate the code that tests the architectural foundation is important to validate the architecture. If the team has provided QAR and trade-off information in the prompts to generate the code, then the coding agent already has the information it needs to generate the test code, including test harnesses, test data, and test environment (e.g., containers) configurations.
The team also needs to consider the risk that the AI agent may not be able to generate an MVA that fully satisfies their QARs and that they need to extend the generated MVA. To mitigate the risk that this extension will be more costly than they can afford, the team can include architectural change cases in their evaluation of the suitability of the AI-generated MVA.
Conclusion #
While AI coding agents offer dramatic speed improvements, they need effective guardrails to ensure that the work they produce meets quality goals. Software architecture is a way of guaranteeing that quality goals are met. Teams need to provide AI coding agents architectural context to achieve quality goals. AI coding agents are proving to be valuable tools in generating solutions to architectural requirements, but they introduce a new set of challenges that we are only beginning to understand. Because working with AI coding agents is new and still rapidly evolving, this article presents concrete suggestions for using AI Coding Agents to help improve or even develop your software architecture. They are not the last word on the topic, but provide a solid starting point to help teams on their journey.