The Strategic Ledger: Architecture Decision Records for Humans and Agents

reddit [#143] Created with Sketch.
Glenn Ji Mason
Glenn Ji Mason
1 min read

Architecture is not a set of diagrams; it is the sum of the decisions made under pressure, limited by the information available at the time. For a Technical Strategist, the greatest risk isn’t making a “wrong” decision—it’s losing the context of why that decision was made.

In an era where agentic coding tools are moving from novelty to necessity, the humble Architecture Decision Record (ADR) has evolved. It is no longer just a record for “Future Me”, but the primary source of truth for the AI agents building your system.

Architecture as a Second Brain: The Zettelkasten Connection

If you are a practitioner of Personal Knowledge Management (PKM), the structure of a good ADR will feel familiar. At its core, an ADR is a Zettelkasten—an atomic note that captures a single idea or, in this case, a single architectural pivot.

By applying these principles to our repositories, we move away from “The Big Book of Specs” and toward a linked knowledge graph:

  1. Atomicity: Each ADR focuses on one decision. If you find yourself writing a 20-page ADR, you aren’t making one single decision. Break each down so they can be referenced individually.
  2. Bi-directional Linking: ADRs should not exist in isolation. A new decision might supersede or amend an existing record. This creates a chronological thread of logic that anyone (human or AI) can follow.
  3. The “Conversation”: Just as Niklas Luhmann “conversed” with his card index, an engineer should be able to converse with the repository. When you ask, “Why aren’t we using WebSockets?”, the graph should point you directly to the record explaining the previous security audit or infrastructure constraint.

The AI Context Gap (Why Agents Need “Why”)

Current LLMs and agentic tools are exceptional at understanding what code does. However, they are historically blind to the why.

Without a record of architectural constraints, an agent might suggest a “cleaner” implementation that inadvertently violates a hard requirement—like bypassing a specific encryption standard or introducing a library that conflicts with your immutable deployment strategy.

ADRs and AGENT.md

Modern repositories are increasingly adopting an AGENT.md file (or similar .cursorrules patterns). This acts as the “Operating Manual” for any AI interacting with the codebase.

  • AGENT.md defines the rules e.g. “Use functional patterns,” “Always write tests in Vitest,” or “Consult the /docs/adr folder before proposing infrastructure changes.”
  • ADRs define the reasoning: They explain the trade-offs that led to those rules.

When an AI agent understands the reasoning (the “linking thinking”) behind a decision, it stops hallucinating “better” ways to do things that you have already rejected.

Why ADRs Matter to Leadership

In a high-growth environment, institutional memory is fragile. ADRs provide three critical functions for the Technical Strategist:

  1. Contextual Integrity: They prevent “Chesterton’s Fence” errors—the removal of a vital constraint because the team (or the AI) no longer understands why it was put there.
  2. Velocity through Clarity: By documenting the “path not taken,” you stop the same debates from resurfacing every quarter.
  3. Agentic Governance: ADRs serve as the guardrails for autonomous agents, ensuring that AI-generated PRs align with your long-term technical vision.

External Resources & Deep Dives

A Worked Example: Project Platypus

Let’s look at how an ADR, Zettelkasten principles, and an AI agent intersect in a hypothetical activity-booking platform.

ADR 012: Choice of Primary Data Store for Availability State

Status: Accepted
Supersedes: [[ADR-004: Standardizing on PostgreSQL]]

Context

Project Platypus requires real-time availability tracking for highly volatile inventory. Our current RDBMS implementation (see [[ADR-004]]) is hitting locking contention during peak booking spikes.

Constraints:

  • Must support atomic increments/decrements.
  • Operational overhead must be minimal as we prioritize self-hosted infrastructure.
  • Must maintain high performance under concurrent write loads without degrading the guest data store.

Decision

We will migrate availability counters to Redis, utilizing Lua scripting for atomic transactions.

Consequences

  • Positive: Offloads high-write contention from the primary database.
  • Negative: Introduces a “split-brain” risk where Redis might momentarily desync from the PostgreSQL source of truth.
  • Linking Thinking: This decision informs [[ADR-013: Resilience Patterns for Redis Desync]].

Note for AI Agents: Do not attempt to refactor the Lua scripts into application-level logic. See [[ADR-012]] for the concurrency constraints that necessitated this specific atomic approach.

Final Thoughts for the Strategist

If you are acting as a CTO or Engineering Manager, your job is to ensure the quality of the decision-making process, not just the output.

By treating your ADRs as an “Architecture Zettelkasten,” you are building a searchable, immutable history of the company’s technical soul. You are ensuring that when a “Future You” or an autonomous agent steps into the codebase, they aren’t just looking at files—they are stepping into a well-reasoned, ongoing conversation.