원칙 문서 규격

<!-- 원칙 문서 규격 v0.1 · https://namtank96.github.io/assets/a10-principles -->

# 설계 원칙(Principles) 작성 규격

## 이 문서를 읽는 법

원칙은 **어긴 대가를 치르고 남은 것이다.** 지어낸 문장은 올리지 않는다.
각 절에 *어디서 시험됐는지*를 적는다. 근거가 없는 원칙은 취향이다. 시험 기록이 없으면 그 원칙은 지울 후보다.

새 결정이 원칙과 부딪히면 **원칙이 이긴다.**
원칙을 바꾸려면 그것이 틀렸다는 사례를 먼저 가져온다. 불편하다는 이유로는 못 바꾼다.

## 원칙 하나의 형식 (고정)

```markdown
## N. {원칙 이름 — 명사구}

**{한 문장 선언.}** {한 문장 부연.}

- {따라 나오는 금지·의무 3~5개. 각 한 줄.}
- {"~하지 않는다" 형태를 우선한다. 금지가 허용보다 검증하기 쉽다.}

> **시험**: {언제 어디서 이 원칙을 어겼고 무슨 대가를 치렀는지 1~2문장.}
> — {그 사건을 가리키는 문서·이슈·커밋}
```

`> 시험` 줄이 없는 원칙은 초안이다. **초안은 원칙 목록에 올리지 않는다.**

## 작성 규칙

1. **선언은 한 문장.** 두 문장이 필요하면 원칙이 두 개인 것이다. 쪼갠다.
2. **금지형을 우선한다.** "항상 X 한다"보다 "X 하지 않는다"가 위반을 판정하기 쉽다.
3. **시험 기록은 구체적으로.** "문제가 있었다" ✕. 무엇을 했고 무엇이 깨졌는지 적는다.
   숫자가 있으면 넣는다. 없으면 어떤 증상이 났는지 적는다.
4. **원칙 개수를 10개 아래로 유지한다.** 넘어가면 아무도 안 읽는다.
   늘리기 전에 기존 원칙에 흡수되는지 먼저 본다.
5. **원칙끼리 충돌하면 우선순위를 명시한다.** "둘 다 중요하다"는 답이 아니다.
   충돌 상황을 적고 어느 쪽이 이기는지 적는다.
6. **규칙이 예시를 이긴다.** 본문과 부록 예시가 어긋나면 예시를 고친다.
7. **원칙을 지운 기록을 남긴다.** 폐기 절을 두고 아래 폐기 형식으로 적는다.
   지운 이유가 다음 사람에게는 자산이 된다.

## 원칙이 되기 위한 세 조건

원칙 후보를 올릴 때 셋 다 만족하는지 확인한다. 하나라도 아니면 원칙이 아니라 규격 항목이다.

| 조건 | 확인 질문 |
|---|---|
| **일반성** | 이 건에만 해당하는가, 앞으로도 반복되는가 |
| **비용** | 어겼을 때 실제로 무엇을 잃었는가. 잃은 게 없으면 취향이다 |
| **판정 가능성** | 지켰는지 안 지켰는지 제3자가 볼 수 있는가 |

## 자주 나오는 실패

- **다 좋은 말 나열.** "품질을 중시한다", "사용자 중심으로 생각한다" 같은 것. 판정할 수 없으니 원칙이 아니다.
- **시험 기록 없이 늘어남.** 회고 때마다 하나씩 붙어서 20개가 된다.
- **원칙과 규격의 혼동.** 필드명·포맷·임계값은 규격이지 원칙이 아니다. 원칙은 *왜 그 규격이 그 모양인가*다.
- **원칙을 어긴 채로 두고 예외를 늘림.** 예외가 세 번째면 원칙이 틀린 것이다. 원칙을 고친다.

## 폐기

```markdown
## 폐기된 원칙

- ~~{원칙 이름}~~ — 폐기 YYMMDD
  사유: {왜 틀렸는지. 어떤 사례가 반증했는지.}
```