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 이 있으면 리네임하지 않는다. 인용처가 코드 저장소까지 퍼져 있어 리네임 리스크가 더 크다. 두 형식이 공존해도 된다.

카드 구조

# 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 에서 표가 끊긴다. 편집 앵커는 표의 마지막 행 끝으로 잡는다.