# Architecture Decision Records

> Create and manage Architecture Decision Records (ADRs): document technical decisions, alternatives considered, and rationale.

- Skill: `thinkfleetai/architecture-decision-records` (Agent Skill)
- Install (CLI): `npx skillmds@latest add thinkfleetai/architecture-decision-records`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thinkfleetai/architecture-decision-records/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: thinkfleetai (https://skillmd.com/u/thinkfleetai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thinkfleetai/architecture-decision-records

---


# Architecture Decision Records

Document significant technical decisions so future you (and your team) understands *why*.

## Create an ADR

### Standard format

```markdown
# ADR-001: Use PostgreSQL for primary database

## Status
Accepted

## Date
2024-01-15

## Context
We need a primary database for the application. Requirements:
- Relational data with complex queries
- Full-text search capability
- JSON column support for flexible schemas
- Strong consistency guarantees

## Decision
Use PostgreSQL with pgvector extension for vector similarity search.

## Alternatives Considered

### MySQL
- Pros: Familiar to team, wide hosting support
- Cons: Weaker JSON support, no native vector search
- Rejected: Missing key features we need

### MongoDB
- Pros: Flexible schema, good for document storage
- Cons: Weaker consistency, complex transactions
- Rejected: Our data is fundamentally relational

## Consequences
- Team needs PostgreSQL expertise
- Hosting on Supabase (managed Postgres)
- pgvector enables future AI/semantic search features
- Migration path exists if we need to switch (standard SQL)
```

## Directory Structure

```
docs/
  adr/
    000-template.md
    001-use-postgresql.md
    002-adopt-nextjs-app-router.md
    003-api-authentication-strategy.md
    README.md  # Index of all ADRs
```

## ADR Index

```bash
# Generate index from ADR files
echo "# Architecture Decision Records" > docs/adr/README.md
echo "" >> docs/adr/README.md
for f in docs/adr/[0-9]*.md; do
  title=$(head -1 "$f" | sed 's/^# //')
  status=$(grep "^## Status" -A1 "$f" | tail -1)
  echo "- [$title]($f) — $status" >> docs/adr/README.md
done
```

## When to Write an ADR

- Choosing a framework, language, or database
- Changing authentication/authorization approach
- Adopting a new deployment strategy
- Major refactoring decisions
- Third-party service selection
- API design decisions (REST vs GraphQL, versioning strategy)

## When NOT to Write an ADR

- Routine bug fixes
- Minor library version updates
- Code style changes (use linter config instead)
- Anything that doesn't affect other developers

## Updating ADRs

Don't edit old ADRs. If a decision changes, write a new ADR that supersedes the old one:

```markdown
## Status
Superseded by [ADR-007](007-switch-to-supabase-auth.md)
```

## Notes

- ADRs are immutable history. They record what was decided and why *at that time*.
- Keep them short. One page is ideal. If it's longer, the decision might be too complex.
- Store ADRs in the repo, not in a wiki. They should travel with the code.
- The "Alternatives Considered" section is the most valuable part — it prevents re-litigating decisions.