Topic: adr template notion
ADR Template for Notion
Indie teams already live in Notion. Here's a Notion database schema for architecture decision records — properties, a page-level template, and the supersedes-from/to relation that makes "what replaced this?" a one-click query.
TL;DR
Create a database called Decisions. Use the property list below (8 properties, one of them a self-relation). Set the database template to the page body shown further down. Filter the default view by Status = Accepted and group by Stack. That's it — you have a working ADR workspace.
The database schema
Eight properties. Order matters here for the table view; the leftmost three are what people scan.
| Property | Type | Notes |
|---|---|---|
| Title | Title | The name of the decision. Format: NNNN — short description, e.g. 0001 — Use Postgres over MongoDB. The number is part of the title so it sorts naturally. |
| Status | Select | Options: Proposed, Accepted, Deprecated, Superseded. Lock to these four — free-text status makes the database unsearchable inside a quarter. |
| Date | Date | The decision date, not the page-creation date. Backfill from chat logs or PR merge dates if you're importing. |
| Stack | Multi-select | Tags like backend, data, frontend, infra, auth. Used for grouping in views; a single ADR can sit under multiple tags. |
| Deciders | People | Notion's built-in person property. Assigning makes the decision visible on each person's profile. |
| Supersedes | Relation → Decisions | Self-relation. Link from the new ADR to the one(s) it replaces. Notion auto-creates the inverse "Superseded by" property when you turn on two-way sync. |
| Linked PR | URL | The implementing PR. One field, one click to find the code that this decision became. |
| Original chat | URL | Optional. The ChatGPT / Claude / Slack thread the decision came out of. This is the property most teams skip and most regret skipping six months in. |
The page template
In Notion, open the database, click the dropdown next to New, choose + New template, and paste the structure below into the page body. Every new entry in the database starts with this layout pre-filled.
## Context
What forces are at play? What problem are we solving?
2-4 sentences. Include team size, scale assumptions, deadlines —
anything a future reader needs to understand why this mattered now.
## Decision
The choice, in one sentence: "We will use X."
A short paragraph on how we'll use it.
## Alternatives considered
- **Option B** — rejected because <one-line reason>
- **Option C** — rejected because <one-line reason>
## Consequences
### Positive
- What this unlocks.
### Negative
- What we're giving up.
### Neutral
- What this doesn't change.
## Links
- Linked PR: (use the property above)
- Original chat: (use the property above)
- Related ADRs: @-mention them inlineKeep the page body short. The first time someone writes a 2,000-word "context" section, the format is dead — nobody reads them, nobody adds new ones. The 250-word cap from the Markdown ADR convention applies just as hard in Notion.
The views you'll actually use
- Active — table view, filtered to
Status = Accepted, sorted by Date descending. Default landing view. - By stack — board view, grouped by the Stack multi-select. Useful when onboarding ("show me everything we decided about auth").
- Pending — table view,
Status = Proposed. Reviewer queue. Empty most of the time; that's a feature. - History — calendar view on the Date property. Quarterly review at-a-glance.
Skip the temptation to build twelve views. Four is enough; more becomes a maintenance burden and signals to the team that the database is precious. Precious databases die.
The supersedes relation
This is the property most teams under-use. When you replace a decision, don't delete the old ADR — change its Status to Superseded and link the new ADR via the Supersedes property. Notion's two-way sync auto-fills "Superseded by" on the old record. Now the old ADR's page shows you the new one inline; the new ADR's page shows you what it replaced. That trail is what makes the database a real audit log instead of a folder of half-current documents.
The pattern is identical to the Markdown ADR convention's Supersedes: / Superseded by: headers — Notion just does the cross-linking for you.
How WhyChose helps
WhyChose's Pro tier exports decisions extracted from your AI chats directly into a Notion database with this schema. You connect the database via the Notion API, point WhyChose at your ChatGPT/Claude exports, and structured rows land in the database with the page body pre-filled — Status set to Proposed, Linked PR blank for you to add, Original chat URL populated automatically. You promote the row to Accepted when the decision is real. The extractor is open-source if you want to roll your own Notion sync.
Related questions
Should ADRs live in Notion or in the repo?
Repo, ideally. Notion's strength — searchable database, multi-property views — also makes it tempting to drift away from the code. If your team's center of gravity is engineering, use the Markdown template in the repo. If it's product/ops/cross-functional, Notion is fine and the format here keeps the structure intact.
Can I import existing Markdown ADRs into this database?
Yes. Notion's Markdown import is reasonable for the body but loses property metadata. Easier path: write a 30-line script that reads your doc/decisions/*.md files, parses the YAML frontmatter or top-of-file fields, and posts to POST /v1/pages via the Notion API with the property mapping done explicitly.
What about syncing both ways?
Don't. Pick one source of truth. Two-way sync between Markdown files and Notion sounds elegant and is a maintenance nightmare; you end up resolving conflicts by hand for the rest of the project's life. One-way (repo → Notion mirror, or Notion → repo export) is fine; bidirectional is not worth it.
Further reading
- ADR template in Markdown — the canonical text format the database mirrors.
- Decision log template — a lighter-weight format for non-architectural calls (good as a sibling Notion database).
- How to document architecture decisions — the practice that makes either format actually work.
- ADR storage format comparison — Notion as one of five storage layers compared head-to-head against Markdown, AsciiDoc, Confluence, and SharePoint, with the team-shape decision matrix and the migration paths between layers (Notion → Markdown is the easier direction at 6–8 hours per 50 ADRs).
- ADR template in Linear — Documents, custom properties, and the graduated handoff — the parallel guide for teams that use Linear for project management: Linear Documents as the drafting surface, custom Status/Decider/Date decided properties, Relations linking ADRs to the triggering Issues, and the graduated handoff to committed Markdown that makes Linear and git complement rather than compete with each other.
- ADR template for Jira — custom fields, Confluence integration, and the graduated handoff — the parallel guide for Atlassian-stack teams: Jira Issue as ADR container (with custom fields for ADR Status, Decider, Date Decided, Supersedes, and Repo File) for small teams, or Confluence page linked from Jira Epic for teams that need full-body document formatting with Atlassian macros. The same graduated handoff to committed Markdown applies here as in Notion and Linear.
- Notion AI export — what's saved, what's lost, and how to archive AI-assisted content — the data portability companion: if you used Notion AI to draft ADR text, the accepted output is in the workspace export but the prompt history and Q&A thread are not; explains why using Claude.ai or ChatGPT for architecture deliberation (then Notion for storage) produces more recoverable decision records than Notion AI alone.