Design: Architecture, Decisions and Constraints with AI

Design is the point at which a developer chooses what the code that follows may and may not do. This chapter treats that choice: the constraints that a design sets, the records that keep the reasons for it, what AI contributes as a generator of options and a reviewer of drafts, what is known about the drift of generated codebases away from their intended design, and where the developer's design work ends and the architect's begins. It concerns D2 Design, the developer function of choosing the constraints: architecture, interfaces, data, security by design, decisions and their records. It leans on D1 Frame, which supplies the need and the quality attributes that a design must satisfy (Chapter 5), and it hands over to D3 Build (Chapters 7 and 8), where the constraints meet code, and to D4 Prove (Chapter 9), where conformance to them is checked.

The chapter describes design without AI first, because the question of what changes cannot be answered without a baseline. It then asks where an assistant helps, where it flatters, and what an organisation has to write down so that a design decision can still be explained when the people and the tools that took part have changed. The delegation ladder is simple for this function. In both organisations of this book, design is at Level 0 Advisory for every tool: an assistant may propose, critique and draft, and a named developer decides. The reasons are the book's own conclusion from the evidence below, and the chapter ends with what would change them.

A design decision with its human decision points and its record

Figure 6.1: A design decision with its human decision points and its record.

The figure shows one decision from need to review date. The need and the constraints come from the specification and from law and data class. An assistant drafts options and challenges them. The developer adds the options the tool did not offer, and a pre-mortem and recorded dissent follow. A named developer decides and gives reasons. A decision that is hard to reverse or that crosses a boundary goes to the architect or the design forum. The Architecture Decision Record (ADR) states the AI contribution, the dissent and the review date, and a rule derived from it is checked in the pipeline by something other than the generator. A drift finding returns to the pre-mortem, and the review date reopens the need.

Design as the choice of constraints

A design is a set of constraints on the code that will be written. It does not describe the code; it limits it. A boundary says what may not call what. An interface says what a caller may assume and what a provider must hold. A data decision says where a datum lives, who may read it and how long it is kept. A failure decision says what happens when a dependency is slow, wrong or gone. Each of these limits the next thousand decisions that nobody will record, and that is its value: a good constraint spares every later developer, and every later tool, the same deliberation.

Parnas gave the classic argument. Comparing two ways of dividing one system into modules, he showed that the division determines how flexible and how comprehensible the system is, and that the better division hides a design decision that is likely to change inside one module, behind an interface, instead of splitting the work along the steps of the processing (124, Parnas, 1972). The lesson for this chapter is the criterion, not the date: the first design question is what is likely to change, and the answer decides where the boundary goes. An assistant that completes the next line has no way to know which of the surrounding decisions are expected to change, because that information is in no file.

Conway's observation points the same way from the organisation's side: a system's structure copies the communication structure of the group that designs it (77, Conway, 1968). Brooks put conceptual integrity at the centre of system design, the idea that a system is best when it reflects one coherent set of design ideas (215, Brooks, 1995). Both observations matter in an organisation in which many developers and several tools propose changes at once. Integrity does not arise from the volume of correct local decisions. It arises because someone holds the idea of the whole and the constraints that follow from it.

Security by design is the oldest set of design constraints with a name. Saltzer and Schroeder set out design principles for protection mechanisms, among them economy of mechanism (keep the design small and simple), fail-safe defaults (base access decisions on permission rather than exclusion) and least privilege (125, Saltzer & Schroeder, 1975). European law has made parts of this a duty. Article 25 of the GDPR requires the controller to implement appropriate technical and organisational measures, such as pseudonymisation, both when deciding how to process and during processing, and to ensure that by default only personal data necessary for each specific purpose are processed (4, European Union, 2016). Article 13 of the Cyber Resilience Act requires a manufacturer to ensure that a product with digital elements is designed, developed and produced in accordance with the essential requirements of Annex I, Part I, and to assess the cybersecurity risks of the product and take the result into account throughout its life; Annex I, Part I, point 2 includes that a product is made available without known exploitable vulnerabilities and with a secure-by-default configuration (242, European Union, 2024). Article 21(2)(e) of NIS 2 lists security in the acquisition, development and maintenance of network and information systems among the measures that entities in scope must take (3, European Union, 2022). NIST's Secure Software Development Framework groups the practice of designing software to meet security requirements and mitigate security risks as PW.1, in its group Produce Well-Secured Software (232, Souppaya et al., 2022). Chapter 24 examines which party carries which duty for software that is built, bought or published. For this chapter the implication is narrower: where these instruments apply, a design decision is something an authority or a supervisor may ask to see, and the record of it is part of the evidence.

Five kinds of constraint recur, and a design review that does not ask about all five has not reviewed the design.

Constraint The question it answers What a missing answer costs later
Boundary What may call what, and what may never? Dependencies grow along the path of least resistance
Interface What may a caller assume, and what must the provider hold? Callers depend on behaviour nobody promised
Data Where does the datum live, who may read it, how long is it kept? Copies, leaks and retention that no one decided
Failure What happens when a dependency is slow, wrong or gone? The first outage becomes the design review
Security What does the component do by default, and with whose authority? Defaults that fail open, authority nobody granted

Table 6.1: Five kinds of design constraint and the cost of leaving one unanswered.

Two properties of a constraint decide how much care it deserves. The first is reversibility. Bezos wrote that many decisions are reversible, "two-way doors", and can use a light-weight process, and he refers to his earlier letter for the fuller account (139, Bezos, 2017). The statement is a practitioner's rule of thumb, not research, and the contrast with decisions that cannot be reversed is this book's own extension of it: a published interface that residents or other systems rely on is one-way, and an internal module boundary behind a stable interface is two-way. The second is scope. A decision that stays within one repository belongs to the team. A decision that crosses a boundary between teams, or between a product and the platform, or that touches a security-critical path, has a wider audience, and the wider audience is the architect or the design forum (below).

The five functions of the developer loop meet here in a particular way. D1 Frame states the quality attributes and acceptance criteria the design must meet. D2 Design turns them into constraints. D3 Build writes within them, and D4 Prove checks that the code stayed within them. A design that nobody turns into a check is a wish. The last section of this chapter returns to that point under the name of drift.

Decision records

The habit that makes a design survive its authors is the decision record. Nygard's proposal was a short text file for each architecturally significant decision, kept beside the code, with a title, a status, the context, the decision and the consequences, numbered and not altered once accepted, so that a later decision supersedes an earlier one instead of rewriting it (89, Nygard, 2011). Architecture as Code (Chapter 4) took that discipline into the repository as the Architecture Decision Record (ADR) and established that the rationale outlives the people who made the decision when it is stored where the code is (161, Nordqvist, 2025). AI Platform and Security, Chapter 5, kept the same short, numbered, immutable form for AI Decision Records, added the fields that AI needs, validated them against a schema, and made the architecture repository the single source for technical documentation (163, Nordqvist, 2026). AI Leader, Chapter 7, treated the decision record for leadership decisions and set the principle that the record is written before the outcome is known, so that the decision is judged by its process and not by hindsight (174, Nordqvist, 2026).

This chapter takes over three conclusions from that line. Reasons are what survives, so a record that states the decision and omits the options and the reasons has little value. The record is written at the time of decision, because a later reconstruction supplies a coherence the decision did not have. And an AI-assisted decision without a traceable human rationale should receive an ADR, retrospectively if need be, which is the habit on which Architecture as Code ended.

What an ADR records when AI took part

An ADR keeps its classic fields: title, status, context, options, decision, reasons and consequences. When an assistant or an agent took part, five further fields are needed, and each answers a question that an auditor, a colleague or the developer herself will ask a year later.

  1. Who decided. One named developer, with the role. The record does not say that the team or the tool decided. "Decides" is used of a system only where a decision was formally delegated, and the delegation profile for design delegates none.
  2. What the tool contributed. Which tool, in which usage mode, running where, and which options or critiques came from it. The contribution is stated in a sentence a reader can check against the options list, not as a transcript.
  3. What the human added or rejected. The options the tool did not offer and the ones the developer set aside, with reasons. This field is the evidence that the decision was not the tool's first answer accepted.
  4. Dissent. Who disagreed, with what argument, and how the decider answered it. A record without dissent from a decision that touched several teams should make a reader suspicious.
  5. Reversibility and review date. Whether the decision is one-way or two-way, who can revert it and outside what system, and the date on which the decision is re-read against the evidence.

The fifth field applies the stewardship principle to design. A decision passes Name if its decider is identifiable in the record to colleagues, operators and auditors. It passes Understand if the decider can explain the decision and its alternatives without the tool that proposed them. It passes Revert if someone has the authority, the access and the time to undo it, and the record says how. The principle was defined for changes that reach production in Chapter 4, and a design decision is the earliest of those changes, since it fixes what the later ones may be.

Practical guide: writing an ADR in which an assistant proposed options and a named developer decided

Purpose. To produce a decision record that shows the reasons, the AI contribution and the human decision, and that can be read by a colleague, an auditor or a member of the public a year later.

Roles. The developer who owns the decision (decider); a second developer who challenges the options (not the same tool in a second window); the tech lead or architect when the decision is one-way or crosses a boundary; the product owner when a quality attribute is traded against a feature.

Inputs. The specification record for the need (Chapter 5); the constraints from law and data class; the existing ADRs that touch the same boundary; the delegation profile that sets the ceiling for the design class.

Steps.

  1. State the decision as a question and the context in a few sentences: the need, the quality attributes and the constraints that are not negotiable.
  2. Write down your own options first, however few. Doing this before asking the tool prevents the tool's list from becoming the frame.
  3. Ask the assistant for options and for objections to each, giving it the context and not the credentials, personal data or classified material that its approved use excludes. Note which tool and mode you used.
  4. Add the options the tool did not offer. Ask a colleague who knows the codebase which option is missing; the tool does not know what the repository does not say.
  5. Hold a short pre-mortem: assume the decision failed in a year and write down the likeliest reasons (145, Klein, 2007). Record the reasons that apply.
  6. Decide. Write the reasons in your own words and what would change your mind.
  7. Record dissent, including what you did with it. Set reversibility and the review date. If the decision is one-way or crosses a boundary, send it to the architect or the design forum before it is marked accepted.
  8. Derive the rule: what in the code could show that the decision is being followed or broken, and who owns that check (the section on drift below).
  9. Commit the ADR beside the code, and link the pull requests that implement it.

Result. An ADR in the repository, with its AI contribution stated, a named decider, recorded dissent, a review date and a rule that the pipeline can check.

AI as option generator and design reviewer

An assistant is useful at design in two ways: it produces options quickly, and it produces objections quickly. Both uses are legitimate at Level 0 Advisory, and both have a failure mode that follows from how the tools behave, as measured.

What the assistant is good for

Dhar, Vaidhyanathan and Varma tested whether large language models can generate the decision section of an Architecture Decision Record from its context. In their exploratory study, presented at the 2024 IEEE International Conference on Software Architecture, GPT-4 generated relevant and accurate decisions in a zero-shot setting but fell short of human-level quality, GPT-3.5 reached similar results with few-shot prompting, and a fine-tuned Flan-T5 model reached comparable results (182, Dhar et al., 2024). The abstract reports no figures, and the models are those of early 2024, so the finding is an indicator of kind, not a measurement of present capability. Its practical meaning is the one the practitioners in both organisations report: an assistant is a competent source of the options a textbook would list, and a weak source of the option that fits this codebase.

Three uses survive that limit. The first is breadth: asking for options the developer has not considered, which cheaply reduces the chance that the first idea becomes the only one. The second is critique of a draft: asking what would break under load, under failure, under a change of supplier. The third is translation between audiences: producing from the ADR a plain-language explanation for a product owner or a works council, which the developer then checks. None of the three is a decision. In each the developer reads the output with the question the assistant cannot ask, which is whether it fits what the repository, the organisation and the law actually are.

What it flatters

Four mechanisms, documented elsewhere in the series and in the literature, bear on design review in particular.

Agreement. Sharma and colleagues found that assistants from several providers tend to produce responses that match a user's views over truthful ones, and that both human raters and preference models sometimes prefer a convincing sycophantic response to a correct one (86, Sharma et al., 2023). A developer who describes a design and asks "is this sound?" supplies the view the tool may match. The remedy is procedural: ask for the strongest case against the design, ask the tool to argue for each option in turn, and do not tell it which option the team prefers.

Homogenisation. Doshi and Hauser found, in an experiment on short story writing, that access to generative AI ideas raised the evaluated creativity of individual stories and reduced the diversity of the stories collectively (87, Doshi & Hauser, 2024). The population and task differ from design, and the result is cited as a warning about mechanism, not as a measurement of architecture. If every team in an organisation asks the same tool for options, the lists may converge. The remedy is the developer's own list written first, and a colleague's view of what is missing.

Shared blind spots. Kim and colleagues found, across more than 350 models on two leaderboards and a resume-screening task, that model errors are substantially correlated, most strongly among larger and more accurate models, even across architectures and providers (35, Kim et al., 2025). Panickssery, Bowman and Feng found that models such as GPT-4 and Llama 2 can somewhat recognise their own generations, and that in fine-tuning experiments stronger recognition went with stronger preference for them when the model acts as an evaluator (36, Panickssery et al., 2024). Taken together, a second model reviewing the first model's design is a weaker check than it appears. This is the independence principle of AI Purple (Chapter 15) applied to design: a check by the same family of tools verifies less than a check by a different kind of thing, such as an architect, a conformance test or a failure experiment (169, Nordqvist, 2026).

Automation bias. A systematic review found that people tend to over-rely on automated advice, accepting it where it is wrong, and that the effect depends on user characteristics, trust, workload and time pressure, and the design of the advice (43, Goddard et al., 2012). A design review is a task with high workload and a persuasive product: a fluent, well-structured critique looks like reasoning. The Transformed Security Architect, Chapter 14, recommends reviews that do not start from the AI's answer, independent reproduction and seeded errors (166, Nordqvist, 2026). For design the equivalent is to write one's own assessment of the options before reading the tool's.

Rules for use

The four mechanisms lead to rules that both organisations can adopt without new tooling, and that the delegation profile records.

  • The tool receives the context of the decision, never credentials, special-category data or the rules of a high-risk system that the usage classification excludes.
  • The developer writes the options and the reasons; the tool may add and challenge.
  • A second human who knows the codebase reads the ADR before it is accepted. A review by a second assistant may be added; it does not replace the human.
  • The ADR states the tool, the mode and its contribution in one paragraph.
  • A decision in a security-critical or safety-critical path (authentication, authorisation, cryptography, payment, clinical or life-safety logic) is reviewed by a named developer and, in both organisations, by the architect or the forum. No tool reviews it alone, and no tool changes the rules the review uses.

Architectural drift

Architectural drift is the gradual divergence of the code from the design that was intended for it. Its older name is erosion. It occurs without AI: Conway's observation, Brooks's argument for integrity and every maintainer's experience describe it. The question for this book is whether generation by assistants and agents changes its rate or its kind, and the honest answer at the date of writing is that the evidence is suggestive, partly from vendors, partly from small studies, and does not yet settle it.

What has been measured

Source What was measured Result Limit
GitClear, 2025 (177, GitClear, 2025) 211 million changed lines, January 2020 to December 2024, from repositories owned by large technology companies and enterprises Lines classified as copy/pasted rose from 8.3 to 12.3 per cent between 2021 and 2024; the share of changed lines associated with refactoring fell from 25 per cent in 2021 to under 10 per cent in 2024; a decline in moved lines, read as less reuse Vendor research with the vendor's own classification; terms such as AI-assisted not defined on the page; it shows a pattern in changed lines, not an architecture violation, and does not establish a cause
Slater, 2025 (183, Slater, 2025) Three models asked to build one standardised microservice under hexagonal architecture constraints, checked by parsing the syntax tree No violations for GPT-5.1 and an 80 per cent violation rate for Llama 3 8B, which skipped interface adapters and created circular dependencies between domain and infrastructure layers; the open-weight models generated about 60 per cent fewer logical lines Single-author pilot, one task, one architecture, number of runs not stated, preprint without a peer-reviewed venue found
Zhu, Tsantalis and Rigby, 2026 (184, Zhu et al., 2026) Code and architecture of single-file tasks and agent-generated systems The authors report that more capable models produced more bloated and coupled code, that code volume predicted structural degradation and that neither functional correctness nor detailed prompting prevented it Only the abstract was read; no figures there; preprint without a peer-reviewed venue found
DevOps Research and Assessment (DORA) programme, 2024 (221, Google Cloud, 2024) A survey-based programme; an estimated association between AI adoption and delivery performance For a 25 per cent increase in AI adoption: estimated decreases of 1.5 per cent in delivery throughput and 7.2 per cent in delivery stability, and estimated gains of 7.5 per cent in documentation quality and 3.4 per cent in code quality Survey associations, not trials; size of the sample not stated on the page; stability is a delivery measure, not an architectural one

Table 6.2: Evidence on drift and related measures in AI-assisted codebases (accessed 2026-11-11).

Read with care, the table supports three statements and no more. First, the measures that exist point in one direction: more duplication, less refactoring and, in controlled but small tests, structure that departs from a stated architecture where the model is weaker or the code volume is greater. Second, none of the sources measures drift against an intended architecture in long-lived, real production codebases with and without AI, which is the study the question needs. Third, every source is young, and the models in them are already replaced; the evidence has an age and the organisation's own measurement will be better than any of it. The series' rule of claims with evidence applies to the sources themselves: a reader should not say that generated code erodes architecture, nor that it does not.

The mechanism that is not in doubt

One mechanism does not depend on the studies. A tool that generates code sees the files it is given, and a design constraint that appears in no file cannot be seen. If the rule that portal services may not read the case system's database exists only in the ADR and in the heads of two senior developers, a completion tool and an agent are as likely to break it as a new colleague, and faster. The rule has to exist where the tool and the pipeline can meet it: in a conformance check that fails the build, in the repository's structure, or at the least in a short file of instructions that the tool reads. The first is the strongest, because it does not depend on the tool reading anything.

This is the point of the last step of the practical guide. Each ADR that sets a boundary derives at least one rule that a machine can check, and the rule has an owner who is not the generator. The principle of the independent test oracle from Chapter 4 applies here as it will in Chapter 9: a conformance check written by the tool that wrote the code verifies less than it appears to, and an agent must not edit the rules, the exemptions or the pipeline gates that check it. That is one of the Level 4 prohibitions, and in practice it means that the file of conformance rules sits under code ownership that names a human team and that a change to it needs that team's review.

# Conformance rules derived from ADR-NR-0031 (illustrative). Owned by the
# platform team; a change to this file needs review by that team.
rule_set: RULES-NR-PORTAL-01
derived_from: ADR-NR-0031
owner_team: platform-team
changed_only_by_review_of: platform-team
rules:
  - id: R1
    statement: Portal services do not import the case system schema or read its tables.
    check: dependency-scan
    on_violation: fail-build
  - id: R2
    statement: Public status values are produced only by the status mapping and are validated against the status vocabulary.
    check: contract-test
    on_violation: fail-build
  - id: R3
    statement: The status API returns no field that the vocabulary does not define.
    check: schema-diff
    on_violation: fail-build
exemptions:
  mechanism: expiring record, approved by owner_team, maximum 90 days
review_date: 2031-04-15

Treating drift as a finding

A drift finding names the rule, the commit and the author of the change, human or tool, and returns to the decision it concerns. It shows that the rule was wrong, in which case the ADR is superseded; or that the change was wrong, in which case it is corrected; or that the rule never reached the author, in which case the repository failed to carry it. It is not a reason to blame the tool or the developer, and it feeds the pre-mortem of the next decision.

The boundary to the architect

The developer designs. The architect designs, too, at another scale, and the boundary between them is not the size of the diagram but the scope of the consequences.

Architecture as Code established architecture as a discipline whose decisions, models and policies live in the repository and are checked by the pipeline (161, Nordqvist, 2025). AI Governance, Chapters 12 and 14, treated organisational design as architecture by other means and gave the AI architect ownership of the seams between the architecture roles (162, Nordqvist, 2026). The Transformed Security Architect, Chapter 17, set the design authority and the rule of gates instead of meetings, so that routine decisions are delegated to pipelines and forums under written decision rights, and Chapter 7 described boundaries designed to hold whatever anyone, human or agent, intends (166, Nordqvist, 2026). This book takes those as given and states the developer's side of the seam.

The developer decides The architect or the design forum decides or is consulted
Structure within one repository or team boundary A boundary between teams, or between a product and the platform
A two-way decision that can be reverted by the team A one-way decision: a published interface, a data residency or supplier commitment, a lock-in
Choice among options that meet the constraints already set Setting or changing a constraint that applies to several teams
The ADR for the decision, with its rule Review of the ADR where it crosses scope; approval where the instrument or policy requires it
Security by design within the golden path Threat model, identity model and containment of the product (the security architect)

Table 6.3: The seam between the developer's design decisions and the architect's.

The seam moves with the tools. When assistants propose options, a junior developer can produce a plausible design for a large decision in minutes, and plausibility may be mistaken for review. The rule is about scope, not seniority: a decision crosses to the architect because of what it touches, however it was produced, and the ADR states the scope so that the check does not rest on the author's own judgement of it. The architect cannot be the reviewer of last resort for all generated design, since the volume would make the review a rubber stamp; Chapter 16 develops the roles further.

A worked decision: Nordvik Region's status interface

The example is illustrative and agrees with the development profile of Nordvik Region. The e-services team of Applications and Integration wants the citizen portal (SVC-NR-002) to show an applicant the status of a benefits case held in the case-management system (SVC-NR-003), a Java 8 application on an Oracle database built on the vendor product Ärendia, whose vendor support ends in 2033. The integration and data team, led by Anders Falk, runs the API gateway to the national registers and owns the decision. The Mode 2 pilot NR-DEV-001 (a self-hosted open-weight coding model, completion and chat) is available to him. Under DLG-NR-DEV-01 (AIDR-1101) the design class is Level 0 Advisory.

Anders Falk first writes three options of his own: read the case system's status table directly from the portal service; build a status interface behind the gateway that maps the internal status to a public vocabulary; or call the vendor's own interface. He then asks the assistant for options and objections, giving it the description of the need and the constraints but no data and no connection details. The assistant offers the same three and adds that a direct read couples the portal to a schema that the vendor controls. It does not offer the fourth option, which comes from the senior developer on the case platform team, Linnea Sjöberg: publish status changes from the audit table that the case system already writes, into a separate store that the portal reads. Her dissent concerns the second option. The status transitions are performed by stored procedures whose rules are undocumented, and a mapping written now would encode a guess. She asks that the mapping be validated against closed cases before it is relied on.

Anders Falk decides on the status interface behind the gateway, with the mapping validated by Linnea Sjöberg against a sample of closed cases before release, and records why the fourth option was deferred: it is attractive and he judges the audit table an unproven source. He marks the public status vocabulary as one-way, because residents rely on it, and the interface as two-way. The enterprise architect is consulted on the vocabulary because it crosses to the citizen channel. The ADR is committed beside the portal code and derives the three rules of the file above.

adr: ADR-NR-0031
title: Case status for applicants is served by a status interface behind the gateway
status: accepted
date: 2030-10-21
decider: {name: Anders Falk, role: ROLE-NR-TCL-01}
context: >
  The portal SVC-NR-002 will show applicants the status of a benefits case held in
  SVC-NR-003. Quality attributes: no coupling of the portal to the case schema,
  a stable public vocabulary, no new access to special-category data.
options:
  - {id: A, text: Portal reads the case status table directly, source: decider, rejected: couples to schema}
  - {id: B, text: Status interface behind the gateway with a mapping, source: decider-and-assistant, chosen: true}
  - {id: C, text: Call the vendor interface, source: decider-and-assistant, rejected: ties to vendor support ending 2033}
  - {id: D, text: Publish from the audit table to a status store, source: Linnea Sjöberg, deferred: source unproven}
ai_involvement:
  tool: NR-DEV-001
  usage_mode: Mode 2
  hosting: self-hosted, Region reserved capacity
  contributed: objection to A (schema coupling) and the wording of option C
  not_contributed: option D, the vendor-lifetime argument, the vocabulary
  input_excluded: credentials, case data, benefits-triage rules
  transcript: summary only, full transcript not retained, retention question open (AIDR-1106)
dissent:
  - {by: Linnea Sjöberg, point: transitions are undocumented stored procedures, answer: mapping validated on closed cases before release}
reversibility: {interface: two-way, public_vocabulary: one-way, revert_by: integration-and-data-team}
consulted: [enterprise-architect]
rules: RULES-NR-PORTAL-01
review_date: 2031-04-15
decision_record: AIDR-1106

Three things in this record matter more than its form. The tool's contribution is stated narrowly and is checked against the options list: it supplied an objection and a wording, and the option that changed the discussion came from a person who knows the system. The dissent is recorded with the answer to it. And the open question about prompts is shown as open, not hidden: under the Region's public-access and archives rules, a design document the Region holds can be an official document that is available on request, unless a secrecy provision applies, and is preserved (the Freedom of the Press Act, Chapter 2 (155, Sveriges riksdag, 1949), and the Archives Act (103, Sveriges riksdag & Regeringskansliet, 1990)), and whether a transcript of a conversation with a coding tool is such a document is a question for the Region's archivist and legal counsel.

Nordvik Region and Hansa Mutual

Nordvik Region. Its design decisions must survive a public-access request. An ADR is therefore written for a reader who is not a developer: it names no credential, no personal data and no internal system detail that would not be disclosed, it states reasons in plain language, and it keeps the tool's contribution to what can be defended. The Region decided, in AIDR-1106 (illustrative, dated 2030-10-21), that Applications and Integration records AI involvement in the ADR by the fields above, retains a summary but not the transcript until the archivist and legal counsel have answered the retention question, and records the decider by role and name. Its constraint is capacity: about 25 people write code as their main work, and there is one enterprise architect and one AI architect. The scope rule of Table 6.3 therefore sends few decisions to the architect and protects the architect's time.

Hansa Mutual. Its design decisions pass the architecture review board and its design authority, where the group's architects meet the delivery teams. The example is again illustrative. The claims core delivery team in Hamburg, led by Stefan Brückner, designs the interface by which the claims core (SVC-HM-001) hands a payment instruction to the COBOL settlement module (SVC-HM-004). Payment is a security-critical path in DLG-HM-DEV-01 (AIDR-1153): design is Level 0 Advisory, generation inside the path is Level 1 Assisted, and the forum reviews the decision. An agentic work tool at Mode 3, reached through the Hansa Forge gateway and running on self-hosted models in Frankfurt because the claims product line is handled only by self-hosted models, proposes in a plan a direct call into a settlement routine. The developer rejects it and the ADR records why: the duplicated settlements of June 2029 (INC-HM-2029-0207) followed a change that the only other person who knew the module had approved, and a direct call would add a second path into a module with few people who can explain a change. The forum accepts the instruction interface as the only path and the rule that follows from it (a conformance check in Hansa Forge that fails any build calling the settlement routine outside the interface), which is owned by Hansa Forge and changed only with that team's review. The group records the decision in AIDR-1156 (illustrative, dated 2030-11-18), extending the ADR template to Group Application Development. DORA applies to the EU entities, and a design that concerns an important function is something a supervisor may ask the group to explain; the same record serves the forum, the change process and the supervisor.

The two organisations show the same principle at two scales. Nordvik relies on a few senior developers, and the knowledge must reach the record before they retire. Hansa writes many records, and must keep the forum from becoming a queue for decisions the team could make.

Across the usage modes

The usage modes name how AI takes part in a developer's work; for design, each differs in what it can see and in what it can change. The delegation profile of both organisations sets design at Level 0 Advisory for every mode, and the table shows why, and what a mode could safely be allowed in future.

Mode What it does to design Main risk to the design Highest degree set for design
Mode 0 Ambient AI Completes the next line from nearby code; takes no design question Follows the local pattern whatever the intended design; the influence is invisible None: design is never taken in completion; the pipeline's conformance rules catch the result
Mode 1 Conversational assistants Offers options and objections to a described problem Agreement with the framing; homogenised option lists; data pasted by mistake Level 0 Advisory; internal-classification text only at Nordvik
Mode 2 Embedded workplace assistants Sees repository context and critiques structure in chat Plausible critique of code, silent about what the repository does not say Level 0 Advisory (NR-DEV-001, HM-DEV-001)
Mode 3 Agentic work tools Plans multi-file changes; a plan is design in effect A plan accepted as a diff; a new path around a boundary Level 0 Advisory; the plan is read and the ADR written before execution (Hansa, about 120 engineers; Nordvik platform team only)
Mode 4 Built AI applications Explains legacy structure to a developer Fluent but wrong account of undocumented behaviour Level 0 Advisory (HM-DEV-003 pilot); test drafting HM-DEV-002 is Level 1 and is not design
Mode 5 Autonomous production agents None for design in either organisation Would change the architecture, its rules and its gates None; Level 4 is never used for a change to the agent's own mandate, gates or conformance rules, nor for design of a security-critical path without a named reviewer

Table 6.4: Design across the usage modes, with the highest degree of delegation set in the two organisations' profiles.

Observable, expected, speculation

Observable. Developers in both organisations use assistants to generate design options and objections, in Mode 1 at both and in Mode 2 under the two profiles; the studies in Table 6.2 report more duplication, less refactoring and, in small tests, architectural violations in generated code; and a model tested in 2024 produced relevant design decisions that fell short of human level (182, Dhar et al., 2024). The evidence is dated and partly vendor-owned, and the organisations' own measurements are better evidence than any of it.

Expected. Conformance checks that derive from ADRs and run in the pipeline will become a normal part of the delivery path for organisations that write ADRs, because the tools to generate code at volume are already in use and the Cyber Resilience Act, NIS 2 and DORA ask for evidence of secure development, which a checked rule provides more cheaply than a document does. Assistants will become better at proposing options that fit a given repository when they are given its ADRs and rules as context. Both statements are expectations from a trend and from decided instruments, not findings.

Speculation. That an AI system could own an architecture, holding the idea of the whole over years, answering for it and being the party that the three tests of Name, Understand and Revert identify, is plausible to some and unevidenced. Nothing in the studies cited supports it, and the stewardship principle rules it out as a matter of design: AI may draft and propose, and it may not own. The author's own projections are kept to Chapters 29 and 33.

Summary

Design is the choice of constraints on the code that follows, and its question is what is likely to change, what may call what, where data lives, what happens on failure and what the component does by default. Parnas, Saltzer and Schroeder gave the criteria, Conway and Brooks the reasons why they must be held by someone, and the GDPR, the Cyber Resilience Act, NIS 2 and the Secure Software Development Framework make parts of them a duty or an expectation. This is D2 Design, and it is where the developer's role as framer and steward is most clearly different from the author of code.

The decision record is how a design outlives its authors. The ADR of Nygard and Architecture as Code gains five fields when AI took part: who decided, what the tool contributed, what the human added or rejected, the dissent, and the reversibility with a review date. The ADR is the application of the stewardship principle to design: a named decider (Name), reasons the decider can give without the tool (Understand), and a stated way to undo the decision (Revert). In both organisations design is at Level 0 Advisory, and the highest-risk design, in security-critical and safety-critical paths, goes to a named reviewer and the forum.

An assistant produces options and objections cheaply, and the evidence is that it is competent at the textbook list and weaker at the option that fits a given codebase. It tends to agree with the framing, it may homogenise the options that teams consider, and a second model is a weaker check on the first than it appears. The remedy is procedural: write one's own options first, ask for the case against, and have a human who knows the codebase read the ADR. Evidence on drift is young and partly from vendors; it points to more duplication and less refactoring, and the unambiguous mechanism is that a constraint that exists in no file is invisible to the tool. Each ADR that sets a boundary therefore derives a rule that the pipeline can check, owned by someone other than the generator, and no agent may change that rule.

The seam to the architect runs along scope and reversibility, not along seniority, which keeps the architect's attention on the decisions where it is scarce. Chapter 7 moves from the constraints to the tools of D3 Build: how developers write code with assistants, and what the controlled studies found about it.

Sources

  1. European Parliament and Council of the European Union. Regulation (EU) 2016/679 (General Data Protection Regulation). Official Journal of the European Union, 4 May 2016. (4, European Union, 2016)
  2. European Parliament and Council of the European Union. Directive (EU) 2022/2555 (NIS 2 Directive). Official Journal of the European Union, 27 December 2022. (3, European Union, 2022)
  3. European Parliament and Council of the European Union. Regulation (EU) 2024/2847 (Cyber Resilience Act). Official Journal of the European Union, 20 November 2024. (242, European Union, 2024)
  4. Sveriges riksdag. Tryckfrihetsförordning (1949:105). (155, Sveriges riksdag, 1949)
  5. Sveriges riksdag, Regeringskansliet. Arkivlag (1990:782). (103, Sveriges riksdag & Regeringskansliet, 1990)
  6. Souppaya, M., Scarfone, K. & Dodson, D. (2022). Secure Software Development Framework (SSDF) Version 1.1. NIST SP 800-218. (232, Souppaya et al., 2022)
  7. Parnas, D. L. (1972). On the Criteria To Be Used in Decomposing Systems into Modules. Communications of the ACM 15(12). (124, Parnas, 1972)
  8. Saltzer, J. H. & Schroeder, M. D. (1975). The Protection of Information in Computer Systems. Proceedings of the IEEE 63(9). (125, Saltzer & Schroeder, 1975)
  9. Conway, M. E. (1968). How Do Committees Invent? Datamation, April 1968. (77, Conway, 1968)
  10. Brooks, F. P. (1995). The Mythical Man-Month: Essays on Software Engineering, Anniversary Edition. Addison-Wesley. (215, Brooks, 1995)
  11. Nygard, M. (2011). Documenting Architecture Decisions. Cognitect blog. (89, Nygard, 2011)
  12. Bezos, J. (2017). 2016 Letter to Shareholders. Amazon.com, Inc. (139, Bezos, 2017)
  13. Klein, G. (2007). Performing a Project Premortem. Harvard Business Review, September 2007. (145, Klein, 2007)
  14. Dhar, R., Vaidhyanathan, K. & Varma, V. (2024). Can LLMs Generate Architectural Design Decisions? An Exploratory Empirical Study. ICSA 2024. (182, Dhar et al., 2024)
  15. Sharma, M. et al. (2023). Towards Understanding Sycophancy in Language Models. arXiv:2310.13548. (86, Sharma et al., 2023)
  16. Doshi, A. R. & Hauser, O. P. (2024). Generative AI enhances individual creativity but reduces the collective diversity of novel content. Science Advances 10(28). (87, Doshi & Hauser, 2024)
  17. Kim, E., Garg, A., Peng, K. & Garg, N. (2025). Correlated Errors in Large Language Models. ICML 2025. (35, Kim et al., 2025)
  18. Panickssery, A., Bowman, S. R. & Feng, S. (2024). LLM Evaluators Recognize and Favor Their Own Generations. arXiv:2404.13076. (36, Panickssery et al., 2024)
  19. Goddard, K., Roudsari, A. & Wyatt, J. C. (2012). Automation bias: a systematic review of frequency, effect mediators, and mitigators. JAMIA 19(1). (43, Goddard et al., 2012)
  20. GitClear (2025). AI Copilot Code Quality: 2025 Look Back at 12 Months of Data. (177, GitClear, 2025)
  21. Slater, T. (2025). Quantitative Analysis of Technical Debt and Pattern Violation in Large Language Model Architectures. arXiv:2512.04273. (183, Slater, 2025)
  22. Zhu, Y., Tsantalis, N. & Rigby, P. C. (2026). AI-Generated Smells: An Analysis of Code and Architecture in LLM and Agent-Driven Development. arXiv:2605.02741. (184, Zhu et al., 2026)
  23. Google Cloud (2024). Announcing the 2024 DORA report. Google Cloud Blog. (221, Google Cloud, 2024)
  24. Nordqvist, G. (2025). Architecture as Code. (161, Nordqvist, 2025)
  25. Nordqvist, G. (2026). AI Governance. (162, Nordqvist, 2026)
  26. Nordqvist, G. (2026). AI Platform and Security. (163, Nordqvist, 2026)
  27. Nordqvist, G. (2026). The Transformed Security Architect. (166, Nordqvist, 2026)
  28. Nordqvist, G. (2026). AI Leader. (174, Nordqvist, 2026)
  29. Nordqvist, G. (2026). AI Purple. (169, Nordqvist, 2026)