diff --git a/README.md b/README.md index 1994aa9b..c961aca4 100644 --- a/README.md +++ b/README.md @@ -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/` | diff --git a/docs/README.md b/docs/README.md index e43e5876..ca6021d5 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 diff --git a/docs/notification/adr/NOTIF-ADR-001-durable-acceptance.md b/docs/adr/NOTIF-ADR-001-durable-acceptance.md similarity index 100% rename from docs/notification/adr/NOTIF-ADR-001-durable-acceptance.md rename to docs/adr/NOTIF-ADR-001-durable-acceptance.md diff --git a/docs/notification/adr/NOTIF-ADR-002-event-ledger-projection.md b/docs/adr/NOTIF-ADR-002-event-ledger-projection.md similarity index 100% rename from docs/notification/adr/NOTIF-ADR-002-event-ledger-projection.md rename to docs/adr/NOTIF-ADR-002-event-ledger-projection.md diff --git a/docs/notification/adr/NOTIF-ADR-003-ambiguous-submission.md b/docs/adr/NOTIF-ADR-003-ambiguous-submission.md similarity index 100% rename from docs/notification/adr/NOTIF-ADR-003-ambiguous-submission.md rename to docs/adr/NOTIF-ADR-003-ambiguous-submission.md diff --git a/docs/notification/adr/NOTIF-ADR-004-fcm-fid-primary.md b/docs/adr/NOTIF-ADR-004-fcm-fid-primary.md similarity index 100% rename from docs/notification/adr/NOTIF-ADR-004-fcm-fid-primary.md rename to docs/adr/NOTIF-ADR-004-fcm-fid-primary.md diff --git a/docs/notification/adr/NOTIF-ADR-005-canonical-namespace.md b/docs/adr/NOTIF-ADR-005-canonical-namespace.md similarity index 100% rename from docs/notification/adr/NOTIF-ADR-005-canonical-namespace.md rename to docs/adr/NOTIF-ADR-005-canonical-namespace.md diff --git a/docs/upgrade/2026-11-docs-records.md b/docs/upgrade/2026-11-docs-records.md index 0357e710..e135ee16 100644 --- a/docs/upgrade/2026-11-docs-records.md +++ b/docs/upgrade/2026-11-docs-records.md @@ -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` 「기록 문서의 머리 블록」이다. diff --git a/scripts/check-docs.py b/scripts/check-docs.py index c5736f85..52b64be4 100755 --- a/scripts/check-docs.py +++ b/scripts/check-docs.py @@ -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") diff --git a/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationReleaseGateTest.java b/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationReleaseGateTest.java index 42b949ef..35d0204b 100644 --- a/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationReleaseGateTest.java +++ b/src/adapter/outbound/notification/src/test/java/dev/caskeleton/adapter/outbound/notification/platform/autoconfigure/NotificationReleaseGateTest.java @@ -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