Censseo Specforge Architecture Decision Records

Architecture Decision Records

Document significant technical decisions with context, rationale, and consequences.

Core Principles

• Capture the WHY: Document rationale, not just the decision
• Record early: Write ADRs before implementation, not after
• Keep it brief: One page, focused on one decision
• Immutable history: Never modify accepted ADRs, create new ones to supersede
• Living documents: Keep an index, update statuses

Quick Reference

When to Write an ADR

Significant Decisions:

• New framework or library adoption
• Database or data store selection
• API design choices (REST vs GraphQL)
• Security architecture decisions
• Breaking changes to existing systems
• Integration patterns between services

NOT Needed For:

• Minor version updates
• Bug fixes
• Configuration changes
• Routine refactoring

Standard Format

# ADR-{number}: {Title}

## Status
{Proposed | Accepted | Rejected | Deprecated | Superseded by ADR-XXX}

## Context
{What is the issue? What forces are at play?}

## Decision
{What is the change being proposed/made?}

## Consequences
{What becomes easier or harder because of this decision?}

Decision Checklist

Before accepting an ADR:

• Is the context clear to someone unfamiliar with the project?
• Are alternatives documented with trade-offs?
• Are consequences (positive and negative) listed?
• Is the decision reversible? What's the cost?
• Who are the stakeholders? Have they reviewed it?

When to Load References

• For templates: Read references/templates.md
• For examples: Read references/examples.md

External Resources

• ADR GitHub Organization
• adr-tools CLI

Converted and distributed by TomeVault — claim your Tome and manage your conversions.