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