Cloud architecture is never finished. Services evolve, teams reorganize, regulations change and new workloads such as AI agents arrive with requirements nobody anticipated. In that environment, the biggest architectural risk is often not a single bad decision but drift: hundreds of small changes that slowly erode the qualities a system was designed to have. Nobody remembers why a boundary exists, so it is crossed. Nobody checks a latency budget, so it is exceeded. A resilience pattern is quietly removed during a refactor.
Two practices, used together, address this problem well. Architecture decision records (ADRs) capture why significant decisions were made. Fitness functions continuously verify that the system still has the qualities those decisions were meant to protect. This playbook explains how to introduce both in a cloud environment, how they fit into modern delivery pipelines and how AI coding tools change the picture.
Why Decision Records Matter More in 2026
The case for documenting decisions has always been strong, but three trends make it more urgent today.
- AI-assisted development has increased the volume of change. When coding assistants and agents produce more code faster, the guardrails that keep architecture coherent must be explicit and machine-checkable, not tribal knowledge.
- Regulators and auditors increasingly ask why. Operational resilience rules, AI governance requirements and data regulations often require organizations to explain design choices, such as how a critical service recovers or where data is stored.
- Teams change faster than systems. The engineers who made a decision are often gone by the time it needs revisiting. Without a record, teams either repeat old debates or unknowingly contradict the original intent.
The Azure Well-Architected Framework makes this last point directly: undocumented decisions tend to be forgotten, leading to repeated debates or changes that contradict the original intent. It recommends keeping the decision log openly accessible with the workload’s documentation as a single source of truth, and notes that it supports operational excellence, audits and incident response.
A decision record explains why the architecture is the way it is; a fitness function proves it still is. You need both to evolve a cloud system safely.
What Good Decision Records Look Like
The guidance from Microsoft and AWS is consistent on the essentials. Microsoft recommends recording key decisions for architecturally significant requirements, including alternatives that were ruled out, and limiting records to choices that affect the system’s structure or key quality attributes or that are difficult to reverse. A consistent template should include:
- A problem statement with context.
- The options considered.
- The decision outcome, including important trade-offs.
- A confidence level, because some significant decisions are made with low confidence, and saying so helps future teams know when to revisit them.
- A status, such as proposed, accepted or superseded.
Two principles from the guidance deserve special emphasis. First, records should be append-only: Microsoft advises not editing accepted records and instead writing a new record that supersedes the original, linking the two so the history of reasoning is preserved. Second, records should be focused. Microsoft suggests splitting multi-phase decisions into separate records, keeping records pithy and factual, and linking to supplemental material rather than turning records into design guides. AWS guidance similarly recommends focusing each ADR on a single decision and exploring alternatives in a separate design document if needed.
A Lightweight ADR Process That Teams Will Actually Use
The AWS Prescriptive Guidance on ADRs describes a clear life cycle. An ADR owner, usually the author, moves the record to proposed and starts a review. The review meeting begins with a reading period of about 10 to 15 minutes, during which members read and comment. The owner then discusses each comment, and the team reaches one of three outcomes: action points (the ADR stays proposed and is reviewed again), rejection (with the reason recorded so the topic is not reopened without new information) or approval (the owner adds a timestamp, version and stakeholder list, and the record becomes immutable).
An AWS Architecture Blog post drawing on more than 200 ADRs adds practical advice: cap meetings at roughly 30 to 45 minutes, keep the group under about 10 people while representing every affected team, limit the process to one to three readouts, resolve every comment, and push for timely decisions because most decisions are reversible. It suggests measuring success through time to decision, team satisfaction, reduced rework and better collaboration.
In cloud environments, a practical adaptation looks like this:
- Store ADRs in the repository alongside the code or infrastructure they govern, as Markdown files with a numbered naming convention. Platform-wide decisions live in the platform repository; workload decisions live with the workload.
- Use pull requests for review. A proposed ADR is a pull request. Comments happen in the review tool, and a synchronous meeting is held only when asynchronous review stalls.
- Define what is architecturally significant. Publish a short list of triggers: a new data store, a new region, a change to identity or network boundaries, a new external dependency, a change to recovery objectives, a new AI model or agent capability with access to production systems.
- Reference ADRs in code reviews. AWS guidance notes that reviewers can cite an ADR when a change violates a decision. Make that a normal part of review culture.
- Backfill selectively. For existing systems, Microsoft recommends retroactively documenting known past decisions where information is available. Focus on the decisions that most often cause confusion.
From Decisions to Fitness Functions
A decision record captures intent, but it does not enforce anything. The concept of an architectural fitness function, popularized in the literature on evolutionary architecture, fills that gap: it is any mechanism that objectively assesses whether the system still meets a defined architectural characteristic. Fitness functions can be automated tests, policy checks, monitoring alerts or periodic experiments.
The key move is to link each significant ADR to one or more fitness functions where possible. If an ADR says that a service must remain stateless to support horizontal scaling and zonal failover, a fitness function can check that no persistent volumes are attached to its deployment. If an ADR says that customer data must stay in a specific region, a policy-as-code rule can block resources elsewhere.
Common categories of cloud fitness functions
- Structural: dependency rules between modules or services, checked in the build. For example, the presentation layer must not call the database directly, or a domain service must not depend on another domain’s internal APIs.
- Infrastructure and policy: policy-as-code checks on infrastructure definitions and deployed resources, covering regions, encryption, network exposure, tagging and approved services.
- Operational: service level objective alerts, latency budgets and error budgets that fail a release or trigger review when breached.
- Resilience: scheduled failover tests, zone or region disconnect experiments and backup restore tests. Google’s Well-Architected Framework added guidance in 2026 on periodic zone and region disconnect testing, a good example of a resilience fitness function.
- Cost: unit cost thresholds, budget alerts and checks that block untagged or oversized resources.
- Security: dependency vulnerability gates, secret scanning and least-privilege checks on roles, including roles assigned to AI agents.
- AI-specific: evaluation suites that must pass before a model or prompt change is released, and checks on which tools and data an agent can access.
The Playbook: Introducing ADRs and Fitness Functions in Eight Weeks
The following plan suits a team or platform group starting from little or no formal practice.
Weeks 1–2: Set up the basics
Choose a template that includes context, options, decision, trade-offs, confidence and status. Create a decision log folder in the relevant repositories and agree on the triggers for an ADR. Pick one pilot team; the AWS blog post recommends starting with a pilot team and clear templates.
Weeks 2–4: Capture the decisions that matter most
Ask the pilot team to list the five to ten decisions that newcomers most often question or that have caused incidents. Write retroactive ADRs for them, clearly marked as backfilled and with honest confidence levels. Then require ADRs for any new significant decisions.
Weeks 4–6: Attach fitness functions
For each ADR, ask: how would we know if this decision were violated? Implement the cheapest reliable check. Often that means a policy rule, a dependency test in the build or an existing monitoring alert linked explicitly to the ADR. Add the fitness function’s location to the ADR so the connection is visible in both directions.
Weeks 6–8: Integrate into delivery and review
Make fitness functions part of the pipeline where they are fast, and schedule slower ones such as failover tests on a regular cadence. Add an ADR check to the pull request template: does this change require a new or superseding ADR? Review the experience with the pilot team, adjust the template and triggers, and expand to the next teams.
How AI Coding Tools Change the Picture
AI coding assistants and agents are now routine in many teams, and they interact with architecture governance in two important ways.
First, they increase the importance of machine-readable constraints. An agent that generates a new service or modifies infrastructure will follow the patterns it sees and the instructions it receives. If architectural decisions exist only in people’s heads, the agent cannot respect them. Clear ADRs in the repository, combined with fitness functions in the pipeline, give both humans and agents explicit guardrails, and the pipeline catches violations regardless of who or what made the change.
Second, AI tools can reduce the cost of good practice. Assistants can draft an ADR from a design discussion, summarize the options considered, suggest which existing ADRs a pull request might affect, or propose a fitness function for a new decision. These uses save time, but the human owner remains accountable for the content, and reviews should check that drafted rationale reflects the real reasoning rather than plausible-sounding text.
A Hypothetical Example
Imagine a hypothetical online travel company running a booking platform on a major cloud provider. After two incidents caused by a well-intentioned refactor that introduced synchronous calls between services, the platform team introduces ADRs and fitness functions.
The first backfilled ADR records an old decision that the booking and payment services communicate asynchronously through a message queue, so that payment provider outages do not block bookings. The confidence level is high, and the trade-off of eventual consistency is documented. A structural fitness function is added to the build that fails if the booking service adds a direct HTTP client for the payment service. A second ADR records the decision that all customer data stays in two specific regions, enforced by a policy-as-code rule. A third, newer ADR records a medium-confidence decision to use a managed vector database for a customer support assistant, with a note to revisit after six months of usage data; its fitness functions include an evaluation suite and a cost-per-conversation alert.
Six months later, a new engineer proposes replacing the queue with direct calls to simplify debugging. The build fails, the engineer reads the ADR, and the discussion focuses on whether circumstances have changed, rather than rediscovering the original reasoning from scratch. The team decides to keep the asynchronous pattern but improve tracing, and records that as a new ADR.
Pitfalls to Avoid
- Documenting everything. Recording trivial choices buries the important ones. Use clear significance triggers.
- Editing history. Rewriting accepted records destroys the reasoning trail. Supersede instead.
- Records without rationale. Microsoft warns that records without justification cannot be evaluated when circumstances change.
- Fitness functions nobody owns. A failing check that is routinely ignored is worse than no check. Assign owners and fix or retire noisy functions.
- Heavyweight review boards. Long meetings and large groups slow decisions. Keep reviews small and time-boxed, as the AWS guidance suggests.
Conclusion
Cloud architectures will keep changing, and AI-assisted delivery will make change faster still. Decision records and fitness functions turn architecture from a set of diagrams that age quickly into a living system of intent and verification. Start small with a pilot team, capture the decisions that matter most, attach the cheapest reliable checks, and integrate both into everyday delivery. Over time, the result is an architecture that can evolve quickly without losing the qualities that make it valuable, and a clear answer whenever anyone asks why the system is built the way it is.
How Hanoi Technology Can Help
Hanoi Technology helps engineering teams set up decision records, policy-as-code guardrails and automated fitness functions for their cloud platforms, through projects, dedicated teams or managed services.
Further Reading
- Architecture decision record – Azure Well-Architected Framework, Microsoft Learn
- ADR process – AWS Prescriptive Guidance
- Master architecture decision records (ADRs): Best practices for effective decision-making – AWS Architecture Blog
- What’s new in the Google Cloud Well-Architected Framework – Google Cloud