번역 네 묶음(D2a~D2d)을 합친 트리는 문서만이 아니라 문서를 읽는 테스트의 기대 문구도 바꿨다. runbook 머리말 status 어휘(stub·active → 초안·운영), 루트 README의 「## 시작하기」, 알림 지원 매트릭스의 등급 칸 이름, 파일서버·JPA 문서의 한국어 제목과 문구, 패키지 소유 표의 머리 칸이다. 자기 runbook을 두었거나 그 문서를 고친 파생 서비스는 merge 뒤 mainCheck의 document-contract lane이 실패한다. 그런데 이것을 적은 안내가 없다. docs/README.md도 「아직 옮기지 않은 문서는 예외 목록에 있다」고 적어 지금(목록이 빔)과 맞지 않고, ADR 본문을 옮긴 사실이 「본문은 원문 그대로」라는 기록 규칙 설명과 부딪친다. - docs/upgrade/2026-11-docs-records.md에 4절(2단계)을 더했다. 할 일 다섯과, 기대 문구가 바뀐 문서·테스트 표다. 범위·「누가 읽나」·3절의 「본문은 원문 그대로」를 2단계에 맞게 고쳤다. - docs/README.md 「문서 수명과 언어」: 모두 옮겼고 예외 목록이 비었다, ADR 번역은 뜻을 바꾸지 않은 옮김이고 원문은 03a313ed에 있다. 「기록 문서의 머리 블록」: ADR만 본문을 옮겼다. 버린 대안: 새 업그레이드 문서를 따로 쓰기. 같은 날 같은 문서 체계 일의 두 단계이고, 옮긴 경로 표(2절)를 2단계의 ADR 이동과 함께 한 곳에서 찾게 하는 편이 낫다. 한계: ADR 머리 블록 둘째 줄 「본문은 결정한 때의 원문이다」는 고치지 않았다. 그 문구는 design-docs conventions/docs-system.md가 정하고 check-docs.py가 글자 그대로 본다. 바꾸려면 정본부터 바꿔야 한다. docs-check를 파생 서비스가 유지할지(docs/ci-cd/template-vs-consumer.md 분류)는 이 변경이 정하지 않는다. 검증(노트북): check-docs.py OK, 자기 시험 68 OK, check-work-docs.py OK. 안내의 테스트 이름·기대 문구는 각 테스트 소스에서 확인했다 (RunbookCoverageContractTest RUNBOOK_STATUSES, DeveloperExperience ContractTest, NotificationEvidenceVerifier GRADE_COLUMN_HEADER, NotificationReleaseGateTest, FileserverDocumentationCoverageTest, JpaDocumentationContractTest, TemplatePackageOwnershipDocumentTest).
5.3 KiB
5.3 KiB
업그레이드 안내 — 2026-11 기록 문서 위치
- 범위: 템플릿
docs/의 설계서·계획서·납품 패키지·증거·학습 문서를 옮긴 변경(1단계, 2·3절)과, 살아 있는 문서·ADR을 한국어로 옮기고 알림 결정 기록을docs/adr/로 옮긴 변경(2단계, 2·4절) - 근거:
docs/README.md「설계와 기록」, design-docsconventions/docs-system.md
1. 누가 읽나
이 템플릿을 upstream remote로 두고 merge해 받는 파생 서비스가 읽는다. 1단계에서는 코드·설정·빌드가
바뀌지 않았고 문서 경로만 바뀌었다. 2단계에서는 문서를 읽는 테스트의 기대 문구가 한국어로 바뀌었다(4절).
2. 옮긴 경로
| 전 | 지금 |
|---|---|
docs/superpowers/specs/ |
docs/design/ |
docs/superpowers/plans/ |
docs/history/plans/ |
docs/superpowers/packages/<어댑터>/ |
docs/history/packages/<어댑터>/ |
docs/graphql-superpowers-package/ |
docs/history/packages/graphql-superpowers-package/ |
docs/web-superpowers-package/ |
docs/history/packages/web-superpowers-package/ |
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. 할 일
- 서비스 문서·코드 주석이 위 「전」 경로를 가리키면 「지금」 경로로 바꾼다.
git grep -n -e docs/superpowers -e superpowers-package -e docs/evidence -e docs/study -e notification/adr로 찾는다. - 서비스가 이 기록을 지웠다면 merge에서 「삭제 대 이름 바꿈」 충돌이 난다. 지운 쪽을 고르면 된다.
- 옮긴 기록 파일과 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)꼴로 영어 제목을 괄호에 남겼다. 서비스 문서·코드 주석의 영어 절 제목 인용은 그대로 찾아진다.