Architectural Decision Making in AI-Assisted Development: ADR

Architectural Decision Making in AI-Assisted Development: ADR

When code gets written with AI tools, decision-making velocity increases. ChatGPT, Claude, or Cursor proposes three different approaches to an architectural question in minutes. Each has pros and cons. You quickly pick one and move forward.

A month later you don't remember why you made that decision. Two months later a new developer joins and asks "why did we do it this way?" Three months later you're re-debating the same question in a different context — because the first discussion was never recorded anywhere.

AI accelerates. But what it accelerates isn't just code — it's also the volume of decisions. And when those decisions aren't recorded, knowledge travels with the person, not with the team.

Decision Scatter in AI-Assisted Development

In traditional development, architectural decisions were made slowly. Research happened, the team debated, sometimes weeks passed. This slowness etched the decision into memory — everyone who lived through the process knew why that decision was made.

AI accelerated this process. Now the following scenario is very common:

At 10am an architectural problem surfaces. You ask Claude or ChatGPT, five minutes later three options arrive. You evaluate them, pick the most sensible one, start implementation. Before noon the work is done.

This speed is valuable. But that five-minute evaluation — which alternatives you eliminated and why, which constraints shaped that decision, which trade-offs you accepted — was never written down anywhere. It only lived in that moment's conversation.

The result: the team moves fast but leaves no trail. Decisions are tied to people, not to systems. When people change, the knowledge goes with them.

What Is ADR and Why Is It Still Necessary?

ADR (Architecture Decision Record) is the practice of recording every important architectural decision in a structured format. Defined by Michael Nygard in 2011, it's been one of software teams' most valuable but least used practices ever since.

The core idea is simple: write it at the moment the decision is made, together with its context.

In the AI era, the importance of ADR hasn't decreased — it's increased. Because the abundance of options that AI provides makes the evaluation process even more important. "Why did we choose this option, why did we eliminate the others?" is a question that applies just as much to choices made between AI suggestions.

The classic ADR format has five sections: Context, Options, Decision, Consequences, Status. In Alios, this format moves into the node description — no separate documentation system needed.

ADR Node Format in Alios

A separate node gets opened for each architectural decision. This node isn't a task — it's a permanent record. It doesn't get closed in a sprint; it gets archived.

📌 ADR — [Number]: [Decision Title]
Status: Active / Revised / Superseded
Date: [Decision date]
Decision Makers: [Names or roles]
AI Tools Used: [Claude / ChatGPT / Cursor / etc.]

📍 CONTEXT

[Why did this decision become necessary?]
[Which problem or requirement started this discussion?]
[If applicable, summary of AI suggestion:]
"AI proposed these three approaches: ..."
[What were the technical and business constraints?]

⚖️ OPTIONS EVALUATED

Option A: [Name]
Source: [Own research / Claude suggestion / Docs]
Pros:
- [Item]
- [Item]
Cons:
- [Item]
- [Item]

Option B: [Name]
Source: [Own research / ChatGPT suggestion / Benchmark]
Pros:
- [Item]
Cons:
- [Item]

Option C: [Name — with reason for elimination]
Why eliminated: [1-2 sentences]

✅ DECISION MADE

[Which option was chosen — one sentence]

Rationale:
[Why this option? Which constraints were decisive?]
[What was taken from the AI suggestion, what was changed?]
[What were the trade-offs, which were accepted?]

⚠️ ACCEPTED CONSEQUENCES

Positive outcomes:
- [What we gain with this decision]

Negative / Trade-off:
- [What we lose or which risk we accept]

Unknown:
- [Not yet clear, will become clear over time]

🔗 REFERENCES

AI conversation: [Link or summary if available]
Related nodes: [Connected task or epic]
Documents: [Benchmark, RFC, official docs]
PR / Commit: [Code where decision was implemented]

🔄 REVISION CONDITION

[When should this decision be reviewed?]
[Which condition would make this decision invalid?]
[Example: If user count exceeds 100K]

📋 CLOSING CRITERIA

This ADR node is marked "Active" and archived when:
- [ ] Decision was implemented — PR or commit link added
- [ ] Team was informed of this decision
- [ ] Other affected nodes were given this ADR as a reference
- [ ] Revision condition was written
- [ ] Can a new team member read this node and
      understand the context? If yes, it can be closed.

Example: Fully Filled ADR

Using a realistic architectural decision made with an AI suggestion:

📌 ADR-007: WebSocket vs SSE for Real-time Feature
Status: Active
Date: March 18, 2025
Decision Makers: CTO, Lead Backend Dev
AI Tools Used: Claude Sonnet

📍 CONTEXT

We're adding a real-time data update feature to the
dashboard. Users should see live order status and
stock changes without refreshing the page.

Claude was asked about architectural options. It
suggested three approaches: WebSocket, Server-Sent
Events (SSE), and Long Polling. It explained the
trade-offs for each comparatively.

Technical constraints:
- Current infrastructure: Node.js + Express, AWS EC2
- Team: 3 backend developers, limited WebSocket experience
- User count: 2,000 now, 15,000 target in 6 months
- Browser support: All modern browsers

Business constraints:
- Must go live within 2 sprints
- Not increasing infrastructure complexity is a priority

⚖️ OPTIONS EVALUATED

Option A: WebSocket
Source: Claude suggestion + MDN documentation
Pros:
- Two-way communication — flexible for future features
- Low latency, true real-time
- Wide ecosystem support
Cons:
- Potential compatibility issues with HTTP/2 proxies
- Limited team experience — learning cost exists
- Complex connection management (reconnect, heartbeat)

Option B: Server-Sent Events (SSE)
Source: Claude suggestion + web.dev article
Pros:
- One-way (server to client) — sufficient for our case
- Runs over HTTP — no proxy issues
- Built-in automatic reconnect
- Team can learn quickly with existing HTTP knowledge
- Simple Express integration
Cons:
- Server to client only — separate HTTP endpoint needed
  for sending data from client
- Max connection limit in some browsers (HTTP/1.1)

Option C: Long Polling
Why eliminated: Creates more server load than SSE and
WebSocket. With good modern browser support for SSE
and WebSocket, no valid reason to prefer Long Polling.

✅ DECISION MADE

Server-Sent Events (SSE) selected.

Rationale:
Our use case is one-directional — server sends data to
client, no real-time data stream from client is needed.
SSE is simpler and easier to learn than WebSocket for
this scenario.

Claude's suggestion highlighted WebSocket but added
the note: "For scenarios where you don't need
bidirectional communication, SSE is less complex
and serves the same purpose." We found this note
decisive.

The team can quickly learn SSE with their HTTP
knowledge and meet the sprint goal. WebSocket's
advantages are more than we need for the current
requirement.

⚠️ ACCEPTED CONSEQUENCES

Positive:
- Can go live within 2 sprints
- No proxy or infrastructure issues
- Low team learning cost

Negative / Trade-off:
- If we later need real-time data from client to server,
  SSE won't suffice — WebSocket migration may be needed
- Connection limit in HTTP/1.1 environments should
  be monitored

Unknown:
- SSE performance at 15,000 users — load test not
  yet done, to be evaluated in Q3

🔗 REFERENCES

Claude conversation: [Key points copied — "SSE vs WebSocket
comparison, SSE recommendation for single-direction use"]
MDN SSE docs: [Link]
web.dev SSE article: [Link]
Related node: "Real-time Dashboard Feature" epic
PR: [To be added when implemented]

🔄 REVISION CONDITION

This decision should be reviewed if:
- User count exceeds 50,000 — SSE scale test needed
- Client-to-server real-time data sending need arises
  — WebSocket migration to be evaluated
- Connection limit issues in HTTP/1.1 environments

📋 CLOSING CRITERIA

- [x] Decision implemented — PR #58 merged
- [x] Team notified in Slack — March 20
- [x] "Real-time Dashboard" epic node given this ADR
      as a reference
- [x] Revision condition written
- [x] New developer can read this node and understand
      why we use SSE
→ Marked ACTIVE, moved to archive

Moving AI Conversations into ADRs

Three things are critical when moving an AI suggestion into an ADR.

Record the rationale, not the suggestion. "Claude recommended WebSocket" isn't an ADR. "Claude recommended WebSocket, but noted that for our one-directional communication scenario SSE would be less complex and serve the same purpose — we found this rationale decisive" is an ADR.

What did you take, what did you change, and why? AI suggestions aren't always applied directly. The AI doesn't know the team's context, constraints, and priorities. How those factors shaped the AI suggestion is the most valuable part of the ADR.

Copy the essence of the conversation. AI conversations aren't permanent. Links can break, conversations can be deleted. Copying or summarizing the decisive AI output — a comparison table, a critical note, a warning — into the ADR's reference section is what ensures permanence.

Which Decisions Need an ADR?

Not every technical choice needs an ADR. Decisions that meet these criteria should be recorded: costly to reverse (database selection, framework decision, API architecture, authentication approach), where the AI suggestion was decisive (if AI's comparison or rationale shaped the decision, that process should be recorded), where there was team debate (decisions with disagreement — decisions where "why not this one?" will be asked), and where it constrains other decisions (if a choice narrows the space for subsequent choices, that constraint should be visible).

Small implementation details, tool configurations, and temporary workarounds don't need an ADR.

Final Thought

AI tools increase decision-making velocity. That's good. But speed shouldn't mean leaving no trail.

ADR nodes in Alios build decision memory in AI-assisted development. The team moves fast and leaves a trail. A new developer asks "why did we do it this way?" — the answer is written in the node.

AI suggests, the team decides, Alios records.