writing-adrs

Writing Architecture Decision Records

Overview

Architecture Decision Records (ADRs) capture significant technical decisions in a concise, standardized format. They answer "why did we do this?" for future developers and AI agents. DorkOS ADRs live in decisions/ with a manifest.json index.

When to Write an ADR

Write an ADR when a decision:

• Chooses between alternatives — "We picked X over Y because..."
• Adopts a pattern or technology — New library, architecture pattern, data model
• Has lasting consequences — Affects how future features are built
• Would surprise a new team member — Non-obvious choices that need explanation

When NOT to Write an ADR

Skip ADRs for:

• Trivial implementation details — Variable naming, file placement within an established structure
• Obvious choices — Using TypeScript in a TypeScript project
• Temporary decisions — Workarounds that will be replaced soon
• Single-feature scope — Decisions that only affect one spec with no project-wide impact

Writing Guidelines

Context (2-5 sentences)

Focus on the problem, not the solution. What situation existed? What forces were at play?

• Good: "DorkOS runs as both a standalone web app and an Obsidian plugin. The Obsidian plugin cannot make HTTP requests to localhost, so the client needs a way to communicate with the server that works in both environments."
• Bad: "We needed an architecture." (Too vague)
• Bad: A full page of background. (Too long — that belongs in the spec)

Decision (2-5 sentences)

State what was decided in active voice. Start with "We will..."

• Good: "We will use a Transport interface that abstracts the communication layer. HttpTransport handles standalone mode via REST/SSE. DirectTransport handles Obsidian mode via in-process function calls."
• Bad: "The transport pattern was implemented." (Passive, vague)

Consequences

List concrete positives and negatives. Every decision has trade-offs — if you can't list a negative, think harder.