Back to Blog
January 5, 20266 min

ADR-Driven Development: Technical Governance That Actually Works

ArchitectureDocumentationBest Practices

At NEXUS, we have a rule: no significant technical decision gets implemented without an ADR. At first, my team thought this would slow us down. Instead, it's become our most valuable practice.

What's an ADR?

An Architecture Decision Record is a short document that captures: - **Context**: What situation are we in? - **Decision**: What are we going to do? - **Consequences**: What are the tradeoffs?

That's it. No 50-page design docs. Just enough to understand why a decision was made.

Our ADR Examples

Here are some real ADRs from NEXUS:

**ADR-100: Single Agent Architecture** - Context: Need to process NEPA comments with AI extraction - Decision: Use single SimpleProcessor agent with Gemini 2.0 Flash - Consequences: Simpler debugging, lower latency, but requires careful prompt engineering

**ADR-400: JSONB Extension Layer** - Context: Need flexibility for AI-extracted fields while maintaining PIC standard compliance - Decision: Add JSONB column for NEXUS-specific extensions - Consequences: Schema evolution without migrations, but queries slightly more complex

**ADR-800: Vertex AI SDK Migration** - Context: Raw aiohttp calls to Vertex AI causing reliability issues - Decision: Migrate to official google-genai SDK with circuit breaker - Consequences: Better retry handling, slightly increased complexity

Why ADRs Work

**1. They force clarity before code.** Writing an ADR requires you to articulate the problem clearly. Often, just writing the "Context" section reveals that you don't fully understand the problem yet.

**2. They create institutional memory.** Six months from now, when someone asks "why did we do it this way?", the answer is in the ADR. No archaeology through Slack threads required.

**3. They enable disagreement.** An ADR gives people something concrete to review. It's easier to push back on "ADR-100 doesn't consider latency implications" than "I don't like your approach."

**4. They document what we didn't do.** The "Alternatives Considered" section is often as valuable as the decision itself. It shows we thought through other options.

Tips for Good ADRs

  • Keep them short (1-2 pages max)
  • Write them BEFORE implementation
  • Include the date and author
  • Link to related ADRs
  • Update status (proposed → accepted → deprecated)

Start Today

You don't need a fancy template or tooling. A markdown file with Title, Context, Decision, and Consequences is enough to start.

The best technical documentation is the documentation that exists.

Back to all posts