AI-Powered Architectural Decisions: Ending the "Why Did They Do That?"

Every software architect has faced it: the legacy system, a labyrinth of undocumented choices, where the original builders have long since vanished, taking with them the crucial "why." It's a problem that breeds technical debt and slows innovation. But what if AI could help bridge that knowledge gap, not by making the decisions, but by meticulously documenting them? A new approach, detailed in a recent article, suggests that AI-powered architectural decisions can transform how teams capture and understand the rationale behind critical design choices. According to the announcement, this isn't about AI replacing human architects, but augmenting their ability to formalize the often-overlooked "why."

The article, penned by Salesforce Lead Developer Advocate Dave Norris, champions a structured method called the Architectural Decision Record (ADR). An ADR serves as a formal document that captures the context, alternatives, and final rationale behind a significant design choice. The problem? Crafting a well-thought-out ADR is time-consuming. This is where AI steps in, not as a decision-maker, but as a tireless assistant.

The Architect in the Loop

At the heart of this new methodology is a "human-in-the-loop" (HITL) approach. It's a disciplined practice that recognizes the current limitations of Large Language Models (LLMs). While an AI can rapidly research options and format information, it lacks the project-specific context, stakeholder empathy, and nuanced experience that define a skilled architect. The architect remains firmly in control, using the AI to accelerate the tedious parts of the process while providing the critical oversight and judgment.

To achieve this, Norris outlines a five-step "prompt chaining" strategy. Instead of one massive query, the architect guides the AI through a series of focused prompts, with checkpoints for human review and refinement at each stage.

A Five-Step Blueprint for AI-Assisted Decisions

Using the common architectural dilemma of a single-org vs. multi-org Salesforce setup as an example, the process unfolds as follows:

1. Context & Criteria: The architect first feeds the AI the project's business context, organizational structure, goals, constraints, and pain points. The AI's task is not to solve the problem, but to generate a list of objective assessment criteria based on a proven methodology like the Salesforce Well-Architected Framework.
2. Human Refinement: The architect then reviews the AI's generated criteria.⁵ This is a crucial step to inject human experience, correct any AI assumptions, and add project-specific nuances or stakeholder concerns that the model could never know.
3. Options Analysis: With a refined set of criteria, the AI is tasked with the heavy lifting: creating a comprehensive, side-by-side comparison of the options (e.g., single-org vs. multi-org), complete with risk ratings. This provides a solid draft for the architect to analyze.
4. Architectural Nuance: The architect once again steps in to challenge and correct the AI's analysis. For example, while an AI might rate merging orgs as a low-risk task, an experienced architect knows the data-model complexities could make it a nightmare. This step ensures the final analysis is both accurate and relevant.
5. ADR Creation: Once the human architect has made the final call, the last prompt instructs the AI to assemble all the previous inputs, context, criteria, analysis, and the final decision, into a professional, fully-formatted ADR document.

The Future is Augmented, Not Automated

This process effectively turns the daunting task of documentation into a manageable, repeatable workflow. It prevents architects from starting with a blank page and allows them to focus their energy on strategy and validation.

Norris concludes that while this chat-driven workflow is a significant time-saver, the future may lie in autonomous AI agents that manage these processes proactively. But the core principle remains the same: generative AI is a tool to elevate the architect's role. By delegating the repetitive work of drafting and formatting, architects are freed to make the strategic calls that lead to truly well-architected solutions.