There's a function in your codebase that does something weirdly specific. Maybe it retries three times with a 200ms backoff. Maybe it serializes a UUID as a string here and an int over there. Maybe it imports a library nobody else on the team imports. You stare at it. You don't remember writing it. Git blame says you did, eighteen months ago, on a Tuesday.
You can guess at the why — there was probably a reason — but the reason is gone. So you have a choice: leave the strange thing alone in case it's holding something up, or rip it out and find out the hard way at 2am.
Architecture Decision Records exist to fix that exact moment. A short markdown file, written when the decision was made, that says: this is the choice we made, this is what we considered, this is what happens next. ADRs are great in theory. In practice most teams try them once, the wiki entries drift away from the code, the agent on your shoulder doesn't read them, and eighteen months later you're back to staring at a function with no memory of why.
This post is about the version that actually sticks: ADRs as plain markdown in a vault your AI agent can search, where every decision is one Capy question away from showing up in the next thing you try to ship. (For the wider pattern of catching reasoning before it slips, see The Capture Habit: Remembering the Things That Actually Matter.)
Why most ADR attempts quietly die
Look at the postmortems and you'll see the same pattern. The team picks a tool — Confluence, a separate ADR repo, a Notion database. The first ten go in with energy. By number twenty, the format drifts. By number forty, someone wrote one in a Google Doc instead. By number sixty, search has stopped surfacing the right ones because tagging fell off in month two. By number eighty, nobody's writing them, because the previous eighty haven't been opened in a month.
The friction isn't writing the ADR. It's the distance between where the ADR lives and where the work happens. If the wiki is in a different tab, behind a different login, with a search box that doesn't know your codebase, the ADR stops being a tool you reach for. It becomes a chore.
The shape of an ADR is meant to be small — Title, Context, Decision, Consequences — so the system around it should be small too. A folder of markdown files. Search that works. An agent that reads them.
The ADR shape — short, opinionated, dated
Before getting into the tooling, here's the shape we keep coming back to. Nothing original — it's the Michael Nygard format most teams use, lightly trimmed:
# ADR-0042: Use Postgres for the rate-limit store
Status: Accepted
Date: 2026-03-14
Decider: Harp
## Context
Rate limits were living in Redis but we kept losing them on
Redis restarts. Redis is right for many things; durability for
quota counters isn't one.
## Decision
Move rate-limit counters to Postgres with a per-user row,
incremented inside the same transaction as the API call.
## Consequences
- Slightly higher write latency (~3ms p50 instead of ~0.4ms)
- Rate limits survive restarts
- We can stop running the Redis-snapshotting cron
- One more table, schema-migrated like everything else
That's it. No template engine, no Jira ticket, no architecture review board. The point is the file existing — searchable, dated, signed — not the ceremony around it.
ADRs as plain markdown, not block-tree pages
When we built Docapybara, we made a deliberate call: notes live as plain markdown files, one page per file, the same shape Obsidian uses. Not a JSON block tree. The reason is selfish — the AI agent works much faster on plain text — but the side effect is exactly what you want for ADRs.
You can copy an ADR out into a pull-request description, and it renders. You can paste it into Slack, a GitHub issue, your README, and it travels intact. You can pull every ADR out of the vault as .md files anytime, drop them into a git repo if you want a second backup, and nothing is locked away.
That portability is what quietly keeps ADRs alive. The moment a format makes the decision feel trapped — only readable inside one app — people start writing decisions somewhere else, and the central record drifts. The same logic applies to operational know-how — see How to Document Institutional Knowledge Before People Walk Out the Door for the broader pattern.
An ADR index as an inline database
The hardest part of running ADRs at any scale isn't writing them, it's finding them. After fifty, the question stops being "what was decided" and starts being "did we ever decide anything about retry logic." You need an index.
Docapybara has inline databases — a :::database::: directive that drops a live, queryable database directly into a markdown page, alongside your prose. Not in a separate tab. Same doc as the rest of your engineering notes.
What that looks like for ADRs: one page called ADR Index. At the top, a paragraph explaining the format you use. Below that, an inline database with columns for ADR number, title, status (Proposed / Accepted / Superseded / Deprecated), date, area (frontend / backend / infra / data), and decider. Each row links to the ADR page itself.
You sort by date when you want to read recent ones. You filter by area when you're about to make a change in that area. You filter by status to find anything still Proposed that needs a verdict. The database lives in the same vault as the ADR pages it tracks, so adding a row is the same context-switch cost as opening a new tab — none.
"Have we ever decided anything about X?" — ask the agent
This is the part that changes the math on whether ADRs are worth keeping.
Capy, the integrated agent in Docapybara, has 27 tools and reads every page in your vault. If you ask it "have we ever decided anything about retry logic for outbound webhooks?" — it searches the ADRs, finds the relevant ones, and shows you the Context and Decision sections, with links back to the original pages.
That sounds like a small thing. It is not. The reason ADRs die is that the cost of asking did past-me think about this? is too high, so present-me skips the question and re-decides from scratch. When the cost drops to one sentence in plain English, the question gets asked. And then the ADR you wrote eighteen months ago actually does its job.
You can also turn the question around. Before you commit a change, paste the diff into a chat with Capy and ask "does this contradict any of our existing ADRs?" — it'll surface the relevant ones if so. That's the loop you actually want: not a wiki you hope someone reads, but an agent that reads them all so you don't have to.
Group ADRs by area, not by flat numbering
A common ADR mistake is the flat naming convention — 0001-use-postgres.md, 0002-use-typescript.md, all in one directory. Fine at twenty. Painful at two hundred.
Docapybara has unlimited page nesting (the real, no-cap kind, OneNote-style hierarchy), so a more useful shape is:
ADRs/
├── ADR Index ← the inline database lives here
├── Frontend/
│ ├── ADR-0007: TanStack Router over React Router
│ ├── ADR-0019: TipTap over BlockNote for the editor
│ └── ADR-0034: Skip storybook on mobile-only components
├── Backend/
│ ├── ADR-0042: Postgres for rate-limit store
│ └── ADR-0058: Switch from Celery to django-tasks
└── Infra/
├── ADR-0061: Caddy on Linode for docapybara.com
└── ADR-0073: Cloudflare Tunnel + Nginx Proxy Manager on G3
The numbering still increments globally — it's useful to be able to say ADR-58 in a PR review and have everyone know what you mean. But the folders make browsing real. Drop into Frontend/ when you're about to touch the editor; you see every editor decision you've ever made in one glance.
Snippets, status changes, and the boring parts that matter
A few small mechanics that make the difference between an ADR system that lives and one that gets quietly abandoned:
- Keep one snippet page with the empty ADR template. When you start a new ADR, you copy from there. No "set up the template" step the first time you sit down to write one. If you're after the same idea for ops runbooks, Standard Operating Procedures, Without the Wiki Maintenance Tax covers it from the SOP angle.
- Use Status as a verb, not a label. When ADR-19 gets superseded by ADR-58, edit ADR-19's status to Superseded by ADR-58 — and link the two. The agent picks up the link. So does future-you reading the older one.
- Date everything. The decisions matter most in context — what did we know in March 2026 that we didn't know in March 2024. Strip the date and an ADR loses half its value.
- Sign it. "Decider: Harp" is more useful than it looks. When somebody asks why, knowing who to ask is half the answer.
- Keep the Consequences section honest. This is the part everyone skips and the part future-you most wants to read. Even one sentence — "slightly higher write latency, but counters survive restarts" — saves a future debugging session.
What this looks like for a solo developer or small team
If you're alone or a team of two-to-five, you don't need ADR governance. You need the file to exist. The version of this that works for small teams:
- One Docapybara vault per project, or one shared vault if you want all projects together
- An ADRs folder, an ADR Index page with the inline database, sub-folders by area
- A snippet page with the empty template
- A habit: the moment you make a decision you'll forget the reason for in three months, write the ADR before doing the work. It takes ten minutes. It will save you a day, eventually.
The agent does the work of reading them later. That's the whole bargain — write once when the context is fresh in your head, and then never have to reconstruct the reasoning, because Capy can pull it back up when you need it.
Try Docapybara free — your ADRs live where you can search them, and Capy can read them when you're about to undo a decision. Start with one decision you've been putting off documenting; the second one will be easier.