重要な技術的決定をどのように行い、文書化しますか?

Question

Accepted Answer

重要な技術的決定は、**意図的で透明性があり、記録される**べきであり、誰かの頭の中で行われて忘れられてはいけません。優れたプロセスはトレードオフを浮き彫りにし、合意を構築し、将来のエンジニアが*何を*だけでなく*なぜ*を理解できるようにします。

## 意思決定フレームワーク

```text
1. FRAME the problem and the constraints (cost, time, team skill, scale)
2. LIST the realistic options — usually 2-4, including "do nothing"
3. EVALUATE each against the constraints and trade-offs
4. DECIDE, and state the reasoning explicitly
5. RECORD it (ADR) and communicate it
6. REVISIT if assumptions change
```

## ADRで記録する

**Architecture Decision Record**は短く、永続的なノートです:

```markdown
# ADR 014: Use PostgreSQL for the new service

## Status: Accepted

## Context
We need a primary datastore. Team knows SQL; data is relational; scale is moderate.

## Decision
Use PostgreSQL.

## Consequences
+ Strong consistency, team familiarity, rich querying.
- Vertical scaling limits later; revisit if write volume 10x's.

## Alternatives considered
DynamoDB (rejected: relational data, team unfamiliar).
```

## 管理すべきトレードオフ

すべてを文書化することはオーバーヘッドです。何も文書化しないと制度的知識が失われます。**逆転するのにコストがかかる**決定や、将来のエンジニアが質問するであろう決定にADRを予約しておきます。

## なぜ重要なのか

文書化されていない決定は何度も再検討され、新しいエンジニアは毎回「なぜこれを選んだのか?」と再び質問します。

理由を書き下すことで、明確さが強制されます: 紙の上でそれを正当化できなければ、おそらくそれについて十分に考えていません。