Over the past months I’ve been writing a lot of code with a good colleague
(claude code). There are a few constraints that I’ve noticed with him. His
memory is not great and whenever he writes himself notes (.memory/ or
AGENT.md files), on what he was employed to do, it becomes a bit of a mess
because he is also subpar in outlining the steps and considerations that it
takes for him to achieve the goal.
You then go ahead and tell him with your years of experience “go do X” as if it would be trivial. But even though this less experienced co-worker might try his best to execute it, he is just not able to, he does not know why it was requested that way.
I’m sure within the next years these co-workers of ours will pick up more pace and have less of such primal limitations. But for now I’ve managed to figure out what solves the problems in most my smaller scale projects: Architectural Decision Records (ADRs).
To take some of the definition out of the ADR project’s website1:
An Architectural Decision Record captures a single AD (Architectural Decision) and its rationale; Put it simply, ADR can help you understand the reasons for a chosen architectural decision, along with its trade-offs and consequences.
That way whenever I speak to a new colleague or intern that was just employed
(AI agent), I can just point him to the docs/ADRs/ directory I created on the
root of the current project, to allow him to discover himself what is there to
do, and what is there that was done, while getting a feel on how the decisions
in the past came to be.
To take an excerpt out of a recent project of mine at work, this is what an ADR directory may look like2:
ADR-000-v1-baseline-isc26.md
ADR-001-streaming-first-architecture.md
ADR-002-2d-data-layout.md
ADR-003-row-header-encoding.md
ADR-004-host-preprocessing-pipeline.md
ADR-xxx-..md
README.md # Includes little ToC/descriptions of each ADR
Notice the prefix, padding in the filename, the markdown format. This allows us to also very easily render the ADRs within our documentation or export them to any format we may need.
An example entry then looks like the following2, including the most important fields
- title
- Status [accepted/denied]
- date [
date -Ifor iso format] - context of the decision
- decision
- rationale
- consequences
- references to further decisions that follow or that the ADR is based on.
# ADR-001: Streaming-First Architecture
**Status:** Accepted
**Date:** 2026-05-31
## Context
...
An earlier prototype assumed A fits entirely on the wafer and treated the
single-SpMV case as the primary target. This limits applicability to small or
very sparse matrices.
## Decision
Design all on-wafer data flow and host preprocessing for the **streaming
case**, where A is too large to reside on the wafer simultaneously.
...
## Rationale
- H2D bandwidth is the system bottleneck for SpMV regardless of problem size;
designing for streaming does not penalise the fits-on-wafer case
- ...
## Consequences
- A must be decomposed into column slices on the host before transmission (see
ADR-003, ADR-004)
- Per-PE SRAM budget must allocate space for a single in-flight A tile plus
permanent x slice and partial y (see ADR-002)
- PE logic must process arriving data incrementally rather than operating on a
static array
So the template I use is:
# ADR-X: title
**Status:** Accepted/Denied/Succeeded (by ADR-Y)
**Date:** `date -I`
## Context
## Decision
## Rationale
## Consequences
If you look at the website I linked earlier they have different flavors available, minimal templates3, or much more extensive ones4.
This may make sense for large scale projects or ones in the industry that many more people depend on, but for my usage most info is not needed.
Conclusion
Think of ADRs as commented, high-level diffs. Some accepted, some rejected, some not yet implemented.
At my work the ADRs are now a part of most of my projects. That helps my coworkers and interns to help me (productively). However it’s also a good interface to other researchers to convey information. It takes 10 minutes to write down the ADR, and you make the considerations on how or what to implement either way, one just has to write it down to log it. Can recommend giving it a try.
About the scientific upsides of ADRs such as reproducibility, not of code but of ideas and initial assumptions of the problem and solution, I want to discuss in the next weeks. As soon as it’s published I’ll link to it from here.