docs(adr)!: 알림 결정 기록을 docs/adr로 옮긴다

결정 기록이 두 폴더(docs/adr/, docs/notification/adr/)에 나뉘어 있다.
문서 지도, 수명 표, 머리 블록 절, 문서 검사의 결정 기록 폴더 목록이
모두 두 폴더를 따로 적어야 하고, 루트 README의 「왜 이렇게 정했는지
보기」도 두 곳을 가리킨다.

NOTIF-ADR-001~005를 이름 그대로 docs/adr/로 옮긴다(git mv, 본문·머리
블록 그대로). 가리키던 곳을 함께 고친다.
- 루트 README 문서 지도 행, docs/README.md 지도·수명 표·머리 블록 절
- scripts/check-docs.py의 RECORD_KINDS·DECISION_PREFIXES와 설명
- NotificationReleaseGateTest: ADR 넷의 존재를 docs/adr/에서 본다
- docs/upgrade/2026-11-docs-records.md: 옮긴 경로 표와 찾는 명령

파일 이름 앞머리(NOTIF-ADR-)는 바꾸지 않았다. 설계서·리뷰·모듈 문서가
NOTIF-ADR-005처럼 번호로 부르고 있어, 이름을 ADR-NOTIF-로 바꾸면
기록 본문의 부름이 맞지 않게 된다.

위험: 이 ADR을 가리키던 문서·주석을 가진 파생 서비스는 경로를 바꿔야
한다(upgrade 안내 3절). notification-platform.yml의 pull_request 경로
필터 docs/notification/**는 이제 이 ADR을 보지 않는다. ADR 존재 시험
(NotificationReleaseGateTest)은 PR의 ci(:adapter:outbound:notification:
check)에서 계속 돈다. workflow는 이 변경에서 고치지 않았다.

이 ADR을 예외로 둔 줄은 없었다(합친 트리의 예외 목록이 이미 비어 있다).

검증(노트북): check-docs.py OK(language·head·reference·number·map·
readme 걸림 0), 자기 시험 65 OK, check-work-docs.py OK,
check-repo-layout.py OK, 살아 있는 문서에서 notification/adr 참조 0.

BREAKING CHANGE: docs/notification/adr/NOTIF-ADR-*.md가 docs/adr/로
옮겨졌다. 파생 서비스 문서·주석의 옛 경로를 docs/adr/NOTIF-ADR-*.md로
바꾼다.
This commit is contained in:
DongHyeonka
2026-11-07 18:10:33 +09:00
parent a1d75a924c
commit 39d4f24803
10 changed files with 15 additions and 14 deletions
+1 -1
View File
@@ -88,7 +88,7 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src
| 새 업무 기능 만들기 | 개발 매뉴얼 [docs/manual/README.md](docs/manual/README.md)와 생성 명령 `scripts/new-feature.sh` |
| 계약 확인하기(HTTP, 오류 코드, env 키, 메트릭, 헤더) | [docs/web/http-contract.md](docs/web/http-contract.md), `docs/registries/` |
| 기능 운영하기(설정, 장애 대응) | 영역 운영 문서(`docs/jpa/`, `docs/redis/` 등), 장애 코드별 런북 `docs/runbooks/` |
| 왜 이렇게 정했는지 보기 | 결정 기록 `docs/adr/`, `docs/notification/adr/` |
| 왜 이렇게 정했는지 보기 | 결정 기록 `docs/adr/` |
| 예전 설계·계획·리뷰 찾기 | 기록 `docs/design/`, `docs/history/`, `docs/reviews/`. 쓴 때의 글이고 지금 동작은 각 머리 블록의 「현재 정본」을 읽는다 |
| 템플릿 변경을 파생 서비스에 받기 | `docs/upgrade/` |
+3 -4
View File
@@ -69,8 +69,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
| 폴더 | 무엇 |
| --- | --- |
| `adr/` | 아키텍처 결정 기록(ADR) |
| `notification/adr/` | 알림 플랫폼의 결정 기록 |
| `adr/` | 결정 기록(ADR). 영역마다 파일 이름 앞머리가 다르다(`ADR-JPA-`, `NOTIF-ADR-` 등) |
### 설계와 기록
@@ -111,7 +110,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
| 수명 | 문서 | 위치 | 언어 | 고치는 법 |
| --- | --- | --- | --- | --- |
| 살아 있음 | README, `CLAUDE.md`, `AGENTS.md`, 매뉴얼(`manual/`, `work/`), 영역 운영 문서, `registries/`, `runbooks/`, `upgrade/` | 제자리 | 한국어 | 코드와 같은 변경에서 고친다 |
| 결정 | 결정 기록(ADR) | `adr/`, `notification/adr/` | 한국어 | 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 보완 절을 덧붙인다. 크게 바뀌면 새 ADR을 쓰고 옛 ADR을 「대체됨」으로 한다 |
| 결정 | 결정 기록(ADR) | `adr/` | 한국어 | 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 보완 절을 덧붙인다. 크게 바뀌면 새 ADR을 쓰고 옛 ADR을 「대체됨」으로 한다 |
| 기록 | 설계서, 계획서, 납품 패키지, 증거, 학습 문서, 리뷰 | `design/`, `history/`, `reviews/` | 머리 블록은 한국어, 본문은 쓴 때의 원문 | 머리 블록의 칸만 고친다 |
- 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 제품 이름은 원문으로 둔다.
@@ -120,7 +119,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
## 기록 문서의 머리 블록
`design/`, `history/`, `adr/`, `notification/adr/`의 `.md` 파일은 맨 위에 이 블록을 둔다.
`design/`, `history/`, `adr/`의 `.md` 파일은 맨 위에 이 블록을 둔다.
블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다).
```text
+4 -2
View File
@@ -1,6 +1,7 @@
# 업그레이드 안내 — 2026-11 기록 문서 위치
- 범위: 템플릿 `docs/`의 설계서·계획서·납품 패키지·증거·학습 문서를 옮긴 변경 하나
- 범위: 템플릿 `docs/`의 설계서·계획서·납품 패키지·증거·학습 문서를 옮긴 변경(1단계)과, 알림 결정 기록을
`docs/adr/`로 옮긴 변경(2단계)
- 근거: `docs/README.md` 「설계와 기록」, design-docs `conventions/docs-system.md`
## 1. 누가 읽나
@@ -20,13 +21,14 @@
| `docs/websocket-superpowers-package/` | `docs/history/packages/websocket-superpowers-package/` |
| `docs/evidence/` | `docs/history/evidence/` |
| `docs/study/` | `docs/history/study/` |
| `docs/notification/adr/NOTIF-ADR-*.md` | `docs/adr/NOTIF-ADR-*.md` (2단계. `docs/notification/adr/` 폴더는 없어졌다) |
`docs/superpowers/plans/2026-09-25-review-followup-tools/__pycache__/`의 `.pyc`는 실행 산출물이라 지웠다.
## 3. 할 일
1. 서비스 문서·코드 주석이 위 「전」 경로를 가리키면 「지금」 경로로 바꾼다.
`git grep -n -e docs/superpowers -e superpowers-package -e docs/evidence -e docs/study`로 찾는다.
`git grep -n -e docs/superpowers -e superpowers-package -e docs/evidence -e docs/study -e notification/adr`로 찾는다.
2. 서비스가 이 기록을 지웠다면 merge에서 「삭제 대 이름 바꿈」 충돌이 난다. 지운 쪽을 고르면 된다.
3. 옮긴 기록 파일과 ADR 맨 위에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달았다. 본문은 원문 그대로다.
서비스가 그 파일을 고쳤다면 맨 위 몇 줄에서 충돌이 날 수 있다. 형식은 `docs/README.md` 「기록 문서의 머리 블록」이다.
+2 -3
View File
@@ -7,7 +7,7 @@
language 살아 있는 문서(기록이 아닌 .md)는 한국어다. 판정은 보고 언어 훅 H11과 같다:
코드·명령·인용·링크·URL·경로·파일 이름을 빼고, 영어 낱말이 3개 이상이고
한글 덩어리 비율이 0.3 미만이면 영어다.
head 기록(docs/design, docs/history, docs/adr, docs/notification/adr)의 .md는 맨 위에
head 기록(docs/design, docs/history, docs/adr)의 .md는 맨 위에
머리 블록이 있다. 상태는 종류별 고정 어휘, 작성일은 날짜, 요약은 한국어, 현재
정본과 대체됨이 가리키는 경로는 지금 있다.
reference 살아 있는 문서의 인라인 코드 안 repo 경로(src/, docs/, scripts/, compose/, .github/로
@@ -63,11 +63,10 @@ RECORD_KINDS = [
("docs/history/evidence/", "증거"),
("docs/history/study/", "학습 문서"),
("docs/adr/", "결정 기록"),
("docs/notification/adr/", "결정 기록"),
]
# 리뷰도 기록이다. 머리 블록은 아직 요구하지 않는다(docs/README.md).
NOT_LIVING = ("docs/design/", "docs/history/", "docs/reviews/")
DECISION_PREFIXES = ("docs/adr/", "docs/notification/adr/")
DECISION_PREFIXES = ("docs/adr/",)
# 살아 있는 문서 중 지운 것을 일부러 적는 곳: 제거 표, 파생 서비스용 변경 안내, 매뉴얼 규칙의 근거 기록.
# 참조·숫자 검사는 이 문서들을 보지 않는다(docs/README.md 「문서와 코드를 같은 변경에서 고친다」).
HISTORY_HOLDERS = ("docs/capability-status.md", "docs/upgrade/", "docs/work/evidence.md")
@@ -17,6 +17,7 @@ import org.junit.jupiter.api.Test;
class NotificationReleaseGateTest {
private static final Path DOCS = Path.of("..", "..", "..", "..", "docs", "notification");
private static final Path ADRS = Path.of("..", "..", "..", "..", "docs", "adr");
@Test
void requiredDocumentationAndAdrsExist() {
@@ -29,10 +30,10 @@ class NotificationReleaseGateTest {
assertThat(DOCS.resolve("configuration-reference.md")).exists();
assertThat(DOCS.resolve("migration-guide.md")).exists();
assertThat(DOCS.resolve("module-mapping.md")).exists();
assertThat(DOCS.resolve("adr/NOTIF-ADR-001-durable-acceptance.md")).exists();
assertThat(DOCS.resolve("adr/NOTIF-ADR-002-event-ledger-projection.md")).exists();
assertThat(DOCS.resolve("adr/NOTIF-ADR-003-ambiguous-submission.md")).exists();
assertThat(DOCS.resolve("adr/NOTIF-ADR-004-fcm-fid-primary.md")).exists();
assertThat(ADRS.resolve("NOTIF-ADR-001-durable-acceptance.md")).exists();
assertThat(ADRS.resolve("NOTIF-ADR-002-event-ledger-projection.md")).exists();
assertThat(ADRS.resolve("NOTIF-ADR-003-ambiguous-submission.md")).exists();
assertThat(ADRS.resolve("NOTIF-ADR-004-fcm-fid-primary.md")).exists();
}
@Test