diff --git a/docs/README.md b/docs/README.md index e6f418d5..8535108d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -115,12 +115,14 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마 - 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 제품 이름은 원문으로 둔다. - 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다. -- 아직 한국어로 옮기지 않은 살아 있는 문서와 ADR은 문서 검사의 예외 목록에 있다(「문서 검사」). +- 살아 있는 문서와 ADR 본문은 2026-11-07에 모두 한국어로 옮겼다. 문서 검사의 예외 목록은 비어 있다(「문서 검사」). +- ADR 본문의 번역은 뜻을 바꾸지 않은 옮김이다. 옮기기 전 원문은 커밋 `03a313ed`에 있다(알림 ADR은 그때 다른 + 폴더에 있었다. 옛 경로는 `docs/upgrade/2026-11-docs-records.md`). ## 기록 문서의 머리 블록 `design/`, `history/`, `adr/`의 `.md` 파일은 맨 위에 이 블록을 둔다. -블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다). +블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다). ADR만은 본문을 한국어로 옮겼다(「문서 수명과 언어」). ```text diff --git a/docs/upgrade/2026-11-docs-records.md b/docs/upgrade/2026-11-docs-records.md index e135ee16..0cfd0ccf 100644 --- a/docs/upgrade/2026-11-docs-records.md +++ b/docs/upgrade/2026-11-docs-records.md @@ -1,13 +1,13 @@ # 업그레이드 안내 — 2026-11 기록 문서 위치 -- 범위: 템플릿 `docs/`의 설계서·계획서·납품 패키지·증거·학습 문서를 옮긴 변경(1단계)과, 알림 결정 기록을 - `docs/adr/`로 옮긴 변경(2단계) +- 범위: 템플릿 `docs/`의 설계서·계획서·납품 패키지·증거·학습 문서를 옮긴 변경(1단계, 2·3절)과, 살아 있는 문서·ADR을 + 한국어로 옮기고 알림 결정 기록을 `docs/adr/`로 옮긴 변경(2단계, 2·4절) - 근거: `docs/README.md` 「설계와 기록」, design-docs `conventions/docs-system.md` ## 1. 누가 읽나 -이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 코드·설정·빌드는 바뀌지 않았다. -문서 경로만 바뀌었다. +이 템플릿을 `upstream` remote로 두고 merge해 받는 파생 서비스가 읽는다. 1단계에서는 코드·설정·빌드가 +바뀌지 않았고 문서 경로만 바뀌었다. 2단계에서는 문서를 읽는 테스트의 기대 문구가 한국어로 바뀌었다(4절). ## 2. 옮긴 경로 @@ -30,5 +30,35 @@ 1. 서비스 문서·코드 주석이 위 「전」 경로를 가리키면 「지금」 경로로 바꾼다. `git grep -n -e docs/superpowers -e superpowers-package -e docs/evidence -e docs/study -e notification/adr`로 찾는다. 2. 서비스가 이 기록을 지웠다면 merge에서 「삭제 대 이름 바꿈」 충돌이 난다. 지운 쪽을 고르면 된다. -3. 옮긴 기록 파일과 ADR 맨 위에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달았다. 본문은 원문 그대로다. +3. 옮긴 기록 파일과 ADR 맨 위에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달았다. 본문은 원문 그대로다 + (ADR 본문만 2단계에서 한국어로 옮겼다. 4절). 서비스가 그 파일을 고쳤다면 맨 위 몇 줄에서 충돌이 날 수 있다. 형식은 `docs/README.md` 「기록 문서의 머리 블록」이다. + +## 4. 2단계 — 문서 번역 (2026-11-07) + +살아 있는 문서(README, `CLAUDE.md`, 모듈 문서, 영역 운영 문서, 레지스트리 설명 칸, runbook)와 ADR 본문을 한국어로 +옮겼다. 뜻은 바꾸지 않았다. 다만 코드와 다른 주장은 옮기면서 코드에 맞췄다(무엇을 고쳤는지는 각 `docs(...)` 커밋 +본문). 문서 검사에 `map`·`readme` 두 검사가 더해졌고, 예외 목록과 그 기준선(`FROZEN`)은 비었다(`docs/README.md` +「문서 검사」). + +### 할 일 + +| # | 할 일 | 안 하면 | 해당 서비스 | +|---|---|---|---| +| 1 | 템플릿 문서를 고친 적이 있으면, merge 충돌이 난 파일에서 자기 변경을 한국어판 위에 다시 얹는다 | 영어판이 남거나 충돌이 풀리지 않는다 | 템플릿 문서를 고친 서비스 | +| 2 | 자기 runbook(`docs/runbooks/*.md`) 머리말의 `status`를 `초안` 또는 `운영`으로 바꾼다(옛 `stub` → `초안`, `active` → `운영`) | `mainCheck`의 `:app-bootstrap:documentContractTest`(`RunbookCoverageContractTest`)가 실패한다. 두 값 밖의 `status`도 실패다 | `docs/runbooks/`에 자기 runbook을 둔 서비스 | +| 3 | 루트 `README.md`를 자기 것으로 고쳐 썼으면 `## 시작하기` 절과 「첫 실행 진입점은 하나다.」 문장을 둔다 | `:app-bootstrap:documentContractTest`(`DeveloperExperienceContractTest`)가 실패한다 | 루트 README를 바꾼 서비스 | +| 4 | `docs-check` workflow를 유지하면, 자기 문서 폴더를 `docs/README.md` 「문서 지도」 표에 더하고 루트 README가 정해진 `##` 절을 정해진 순서로 갖게 한다(`scripts/check-docs.py`의 `README_SECTIONS`) | `check-docs.py`의 `map`·`readme` 검사가 실패한다 | `docs-check`를 유지하는 서비스 | +| 5 | 아래 문서를 자기 것으로 고쳤으면, 그 문서를 읽는 테스트가 찾는 한국어 제목·칸 이름을 지킨다 | 그 테스트가 실패한다 | 해당 문서를 고친 서비스 | + +5번의 문서와 테스트: + +| 문서 | 테스트가 찾는 것 | 테스트 | +| --- | --- | --- | +| `docs/notification/support-matrix.md` | 등급 칸 이름 `등급`(옛 `Grade`), 절 「## 지원하지 않는 것」 | `NotificationEvidenceVerifier`, `NotificationReleaseGateTest` | +| `docs/fileserver/operations.md`, `docs/fileserver/support-matrix.md` | runbook 절 제목(「## 저장소 가득 참」 등)과 「## 주장하지 않는 것」 | `FileserverDocumentationCoverageTest` | +| `docs/jpa/support-matrix.md`, `docs/jpa/repository-adaptation.md` | 「운영 보장이 아니」, 「PostgreSQL 계약 증거」, 「알려진 빈틈」 | `JpaDocumentationContractTest` | +| `src/application-core/CLAUDE.md` | 패키지 소유 표 둘(application·domain)의 첫 머리 칸 `패키지 (…)` | `TemplatePackageOwnershipDocumentTest` | + +- 다른 문서가 영어 절 제목으로 가리키던 절은 `## 한국어 제목 (English title)` 꼴로 영어 제목을 괄호에 남겼다. + 서비스 문서·코드 주석의 영어 절 제목 인용은 그대로 찾아진다.