Writing Adr

---
name: writing-adr
description: 방향 결정을 기록하거나(ADR 작성), 기존 결정을 뒤집을 때(supersede) 사용한다. ADR ID 형식, 카드 구조, 인덱스 등재, supersede 절차를 정한다.
---

# ADR 작성 절차

**결정 1건 = 파일 1개.** 다른 문서는 결정을 재서술하지 말고 ADR ID 로 인용한다 - 판단이
뒤집힐 때 고칠 곳이 그 파일 하나로 좁혀지게 하기 위함이다.

## 언제 ADR 을 쓰는가

방향을 바꾼 결정에만 쓴다. 판단 기준:

- 나중에 "왜 이렇게 했지?" 라는 질문이 나올 만한 선택인가
- 다른 선택지가 실제로 있었는가
- 이 결정이 뒤집히면 여러 곳을 고쳐야 하는가

셋 중 둘 이상이면 ADR. 하이퍼파라미터급 조정, 오타 수정, 되돌린 실험은 ADR 이 아니다
(현황판 일자별 로그나 `AI_USAGE.md` 로 간다).

## ID 형식

`ADR-YYMMDD-<작업자id>-slug.md`

인용은 **확장자를 뺀 파일명 전체**로 쓴다 - `ADR-260821-abc-parallel-docs`.

기존에 다른 형식(`ADR-NNN-slug.md`)의 ADR 이 있으면 **리네임하지 않는다.** 인용처가 코드
저장소까지 퍼져 있어 리네임 리스크가 더 크다. 두 형식이 공존해도 된다.

## 카드 구조

```markdown
# ADR-YYMMDD-<id>-slug - 제목

| | |
|---|---|
| 날짜 | YYYY-MM-DD |
| 상태 | accepted / superseded-by-<ID> / rejected |
| 대체(supersedes) | (있으면 ID) |
| 관련 | (관련 ADR·문서) |
| 원문 | (서사가 아카이브에 있으면 그 경로) |

## 결정

무엇을 하기로 했는지. 한 문단.

## 근거

왜. 검토한 대안과 그것을 택하지 않은 이유.

## 영향·조건

이 결정으로 무엇이 바뀌는지, 어떤 조건에서 재검토해야 하는지.
```

- 서사 원문이 아카이브에 있으면 `원문` 행으로 가리키고 **본문에 다시 옮기지 않는다.**
- 개별 ADR 에는 `## 목차`를 두지 않는다(짧은 결정 카드라 예외).

## 새 결정을 만들 때

1. `docs/decisions/` 에 새 파일을 만든다.
2. `docs/decisions/README.md` 인덱스 표에 한 줄 추가한다.
3. 현황판 일자별 로그에 **ID 를 인용**한다(내용 재서술 금지).

병행 기간에는 1·2 를 자기 `docs_<id>/decisions/` 와 그 폴더의 `README.md` 에 한다 -
병합 때 메인 인덱스로 옮긴다.

## 판단을 뒤집을 때 (supersede)

1. 기존 ADR 의 **상태만** `superseded-by-<새 ID>` 로 바꾼다. **본문은 고치지 않는다** -
   왜 틀렸는지는 새 ADR 에 적는다. 그래야 당시의 판단 근거가 남는다.
2. 새 ADR 의 `대체(supersedes)` 행을 채운다.
3. `grep -rn "<기존 ID>"` 로 인용처를 전부 찾아 고친다. 인덱스 표의 상태 열도 같이 고친다.
4. 검사기를 돌려 죽은 인용이 없는지 확인한다.

## 인덱스 유지

`README.md` 의 목록 표는 ID·날짜·상태·결정 요약 네 열을 유지한다. 검사기가 잡는 것은
**인덱스에 빠진 결정과 존재하지 않는 ID 인용**까지다 - 상태 열이 실제 파일과 어긋나는 것은
검사기가 못 본다. supersede 할 때 인덱스 상태 열을 같이 고치는 것은 사람 몫이다.

> [!WARNING]
> 인덱스 표에 행을 추가할 때 **표 행 사이에 빈 줄을 넣지 않는다.** GFM 에서 표가 끊긴다.
> 편집 앵커는 표의 마지막 행 끝으로 잡는다.