Commit Graph
6 Commits
Author SHA1 Message Date
DongHyeonka 74be416f93 docs(adr): 아키텍처 결정 기록 본문을 한국어로 옮긴다
문제: `docs/adr/`의 결정 기록 26개는 머리 블록만 한국어이고 본문이
영어다. 소유자는 2026-11-07에 결정 기록도 본문까지 한국어로 쓰기로
정했다(design-docs `repo-structure/README.md` 3.2절).

방법: 결정의 뜻을 바꾸지 않고 옮긴다. 머리 블록(상태·작성일·요약·
현재 정본·대체됨)은 한 글자도 바꾸지 않는다. 본문의 상태·날짜·범위
줄, 나중에 붙인 보완·대체 메모, 따져 본 대안도 함께 옮긴다. 코드·
명령·경로·식별자·설정 키·SQL·표 구조는 원문으로 둔다. 본문이 인용한
영어 원문(루트 CLAUDE.md의 한 문장, 플러그인 주석)은 원문을 두고 뜻을
괄호로 붙인다. 결정 기록은 본문을 고치지 않는 문서라서, 번역하며 본
지금 코드와 다른 점(예: ADR-MONGO-ADV-001은 지웠다고 적은
`scripts/verify-mongodb-advanced.sh`가 지금 있다)은 고치지 않고 보고에
남긴다.

위험: 머리 블록 둘째 줄 「본문은 결정한 때의 원문이다」는 번역한 뒤
문자 그대로는 맞지 않는다. 문구를 고칠지는 통합 단계에서 정한다.

검증: python3 scripts/check-docs.py rc=0(language 줄 26개 지움,
head 실패 0), 머리 블록이 HEAD와 같은지 26개 모두 diff로 대조,
check-work-docs.py --links(gates.md 범위) 깨진 링크 0.
2026-11-07 17:33:54 +09:00
DongHyeonka 8813b02e54 docs(adapter-outbound): outbound 어댑터 모듈 문서를 한국어로 옮긴다
문제: outbound 어댑터 leaf의 CLAUDE.md 열세 개와 README 아홉 개가
영어이거나 영어 절이 섞여 있다. 열 CLAUDE.md는 Spring Boot 버전
(4.0.0, 4.0.8)을 복사해 두었고 실제 버전(libs.versions.toml)과 다르다.

방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·설정 키·로그 문자열·
표 구조는 원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을
가리키게 고친다. 번역하며 본 코드와 어긋난 주장은 코드에 맞춘다:
identifier CLAUDE.md의 `.claude/hooks/ca_import_gate.py`(저장소에 없는
hook)를 registry 방향 게이트로, cache-redis README의 「app-bootstrap
`IdempotencySettings`」를 실제 위치 `composition:idempotency`로,
redis-sdk compose README의 ACL 파일 위치 `acl/`을 lane이 실제로
mount하는 `compose/redis/acl/`로 고친다. persistence-mongo 문서에는
지운 namespace(`spring.data.mongodb.`)를 쓰지 않는다
(MongoNamespaceContractTest가 본다). 다른 영역 문서의 절 제목을 인용한
곳(`docs/jpa/migration-guide.md` "Bound the lock wait" 등)은 그 문서가
아직 영어라 원문 제목으로 둔다.

위험: 인용한 docs/jpa 절 제목은 그 문서를 번역하는 쪽이 제목을 바꾸면
낡는다. 통합 단계에서 맞춰야 한다. ArchUnit 규칙 이름의 대소문자는 다음
커밋에서 맞춘다.

검증: python3 scripts/check-docs.py rc=0(language 줄 19개, number 줄
10개 지움, src/** number 줄 0), check-work-docs.py rc=0,
--links(gates.md 범위) 깨진 링크 0.
2026-11-07 17:24:33 +09:00
DongHyeonka 5a3784be58 docs(adapter-inbound): inbound 어댑터 모듈 문서를 한국어로 옮긴다
문제: inbound 어댑터 leaf(messaging, web, web-advanced, websocket,
graphql, grpc)의 CLAUDE.md가 영어이거나 영어 절이 섞여 있다. 다섯
CLAUDE.md는 Spring Boot 버전(4.0.0, 4.0.8)을, graphql README는 leaf
개수(19·24·43)를 복사해 두었고 그 수는 registry가 바뀌면 틀린다.

방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·설정 키·표 구조는
원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을, leaf 수는
registry를 가리키게 고친다. 번역하며 본 코드와 어긋난 주장은 코드에
맞춘다: web CLAUDE.md의 `adapter-persistence`(없는 이름)를
`adapter:outbound:persistence-jpa`로, Jackson 속성 위치를
`spring.jackson.serialization.*`·`generator.*`에서 실제 키
`spring.jackson.deserialization.*`·`spring.jackson.datatype.*`로,
「`WRITE_BIGDECIMAL_AS_PLAIN=true`로 고정」을 「설정 키가 아니라
`JacksonSerializationPolicyTest`가 지수 표기 없음을 단언」으로 고친다.
매뉴얼 장 번호만 쓴 참조는 경로와 절 제목으로 바꾼다.

위험: ArchUnit 규칙 이름의 대소문자(문서는 소문자, 코드는 대문자
상수)는 이 커밋에서 그대로 두고 다음 커밋에서 한꺼번에 맞춘다.

검증: python3 scripts/check-docs.py rc=0(language 줄 4개, number 줄
7개 지움), check-work-docs.py rc=0, --links(gates.md 범위) 깨진 링크 0.
2026-11-07 17:12:03 +09:00
DongHyeonka c91cc3fb10 docs(core): core·조립·빌드·플랫폼 모듈 문서를 한국어로 옮긴다
문제: core 계층(application·domain·shared-contract), app-bootstrap,
composition, registry, build-logic, optional 빌드의 모듈 문서가 영어다.
세션이 처음 읽는 지역 규칙인데 소유자는 2026-11-07에 살아 있는 문서를
모두 한국어로 쓰기로 정했다. leaf CLAUDE.md 셋은 Spring Boot 버전을
4.0.0으로 복사해 두었는데 실제 버전(libs.versions.toml)과 다르다.

방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·표 구조는 원문으로
둔다. 버전은 `src/gradle/libs.versions.toml`을 가리키는 말로 바꾼다.
다른 문서·코드가 제목으로 가리키는 절(application-core의
Naming convention·Package ownership·Canonical use case shape·Allowed
transactional shapes, shared-contract의 Responsibility·Forbidden,
messaging의 발행 재시도 절)은 영어 원제를 괄호로 남겨 그 참조가
계속 찾아지게 한다. 참조하는 쪽을 고치는 것은 이 작업 범위 밖이다.
코드와 어긋난 주장은 코드에 맞춘다: TransactionPort 구현을
`adapter-persistence`에서 `adapter:outbound:persistence-jpa`의
`SpringTransaction`으로, registry README의 빈 의존 목록 예를
persistence-mongo(실제 목록은 application-core·shared-contract)에서
domain-core·shared-contract·messaging-core-api로 고친다.
TemplatePackageOwnershipDocumentTest는 표 머리 문자열로 표를 찾으므로
머리 상수를 한국어 머리(`| 패키지 (...) |`)로 맞춘다. 표와 기계 사본을
대조하는 계약은 그대로다.

위험: 영어 원제를 괄호로 남긴 제목은 참조하는 문서가 한국어 제목으로
바뀌면 괄호를 지울 수 있다. 본문의 짧은 이력 번호(07-08, 06-01,
11-M9)는 뜻을 바꾸지 않으려고 그대로 옮겼다.

검증: python3 scripts/check-docs.py rc=0(번역한 파일의 language 줄 8개,
number 줄 3개 지움), check-work-docs.py rc=0, --links(gates.md 범위)
깨진 링크 0, unittest discover scripts/tests 43개 통과.
2026-11-07 17:07:16 +09:00
DongHyeonka 8251616767 fix(docs): 지우고 옮긴 경로에 문서 검사 예외와 참조를 맞춘다
문제: 구조 정리와 문서 체계를 합친 트리에서 `python3 scripts/check-docs.py`가
23건으로 실패한다. 문서 검사는 구조 정리 전 트리를 기준선으로 만들어졌다.
- 예외 목록이 지운 파일(infra 아래 README 6개, 샘플 CLAUDE.md의 언어·숫자
  두 줄)을 가리킨다.
- 옮긴 문서 넷(infra/keycloak, infra/redis-sdk, infra/redis-sdk/acl,
  src/optional-platforms의 README)은 옛 예외 줄이 낡고 새 경로가 영어 문서로
  걸린다.
- `docs/jpa/security.md`는 구조 정리가 한국어 절(운영 DB 조건)을 더해 더는
  영어 문서로 판정되지 않는다.
- 살아 있는 문서 넷이 지운 `infra/`, `src/sample-portfolio`,
  `src/Dockerfile.sample`을 인라인 코드로 가리킨다.

고친 방법: 문서 체계 인계 노트의 「구조 정리와 합칠 때」를 따른다.
- 지운 파일과 더는 걸리지 않는 줄 아홉은 예외 목록에서 지운다.
- 옮긴 문서 넷은 예외 줄의 경로를 새 경로로 바꾸고, FROZEN에서 옛 줄의
  지문을 새 줄의 지문으로 바꾼다. FROZEN에 새로 더한 지문은 없다.
- 결정 색인의 두 행은 지운 경로 대신 지운 목록이 있는 업그레이드 안내
  B-49·B-50을 가리킨다(docs/README.md 「지운 경로는 upgrade/에 쓴다」).
- JPA 적응 표의 「저장소 현실」 칸과 리뷰 기준 18행에서 지운 경로를 뺀다.
- docs/README.md의 검사 설명은 지운 infra 폴더를 인라인 코드 밖에서 적는다.
  검사는 지운 infra/ 아래 경로를 계속 본다(다시 나타나면 낡은 참조다).

버린 대안: 결정 색인을 참조 검사 제외 목록(HISTORY_HOLDERS)에 넣기. 색인은
지금 결정을 찾는 곳이라 낡은 경로를 걸러야 한다.

위험·한계: `docs/jpa/security.md`는 영어 본문이 그대로 남아 있지만 판정에서
빠졌다. 번역 단계의 대상 목록에서 빠지지 않게 인계 노트에 적는다.

검증(노트북, 이 트리): check-docs.py rc=0(언어 걸림 173·예외 173, 참조 걸림 7·
예외 7, 숫자 걸림 28·예외 28), `python3 -m unittest discover -s scripts/tests`
42개 통과, check-work-docs.py rc=0.
2026-11-07 15:03:56 +09:00
DongHyeonka 1c00f89765 ci(docs): 문서 언어·머리 블록·참조·숫자를 PR에서 검사한다
문제: 살아 있는 문서의 언어, 기록의 상태 표시, 인라인 코드 경로, 복사한
버전·개수를 아무 검사도 보지 않는다. lychee는 마크다운 링크만 보는데
경로 대부분은 인라인 코드로 쓰여 있고, leaf CLAUDE.md는 Spring Boot
버전을 4.0.0으로 적어 둔 채 낡았다.

고른 방법: Gradle 밖 scripts/check-docs.py 하나에 검사 넷을 둔다.
- language: 살아 있는 문서와 ADR 본문이 한국어인가. 판정은 보고 언어 훅
  H11과 같다(코드·명령·경로·인용을 빼고 영어 낱말 3개 이상, 한글 비율
  0.3 미만이면 영어).
- head: 기록·ADR 맨 위 머리 블록의 칸, 종류별 상태 어휘, 날짜, 한국어
  요약, 현재 정본·대체됨 경로.
- reference: 인라인 코드 안 src/·docs/·scripts/·infra/·.github/ 경로와
  Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, 「> 이력」 인용,
  제거 표, upgrade/는 건너뛴다. leaf 기준 경로는 어느 파일의 끝부분과
  맞으면 있다고 본다.
- number: Spring Boot x.y.z와 leaf 개수 문장.
예외 목록(scripts/check-docs-exceptions.txt)은 2026-11-07 기준선 217줄이고
줄기만 한다. 줄마다 sha256 지문이 스크립트의 FROZEN에 있어야 해서 목록에
새 줄을 더하면 실패하고, 더는 걸리지 않는 줄을 남겨 두면 실패한다.
workflow docs-check.yml이 PR마다 경로 필터 없이 자기 시험과 검사를 돌린다.
코드에서 파일을 지우는 변경이 문서를 낡게 만들기 때문이다. 같은 커밋에서
지도 CLAUDE.md의 Spring Boot 버전 복사를 정본 가리키기로 고쳤다.

버린 대안: 예외 목록 하나에 「늘리지 않는다」는 약속만 두는 방식(테스트의
KNOWN_DEVIATIONS와 같은 꼴)은 brief가 요구한 「더하면 실패」를 기계로 막지
못한다. 기준선을 git 이력(merge-base)과 비교하는 방식은 얕은 checkout에서
깨진다. 검사를 link-check.yml에 더하는 방식은 그 workflow가 docs 경로에만
걸리고 repository-contract 테스트가 trigger를 고정한다. CI 재편 때 단계
workflow로 접는다.

위험·한계: 타입 이름 검사(지운 클래스 이름)는 넣지 않았다. 외부 타입과
구분하려면 git 전체 이력이 필요하다. 경로 검사는 루트 폴더로 시작하는
경로만 보므로 src/ 기준 상대 경로(adapter/outbound/...)는 보지 않는다.
leaf 개수 규칙은 설계 문서의 개수 같은 정당한 숫자도 잡을 수 있다(지금
generator 출력 예 하나가 예외 목록에 있다). 구조 정리가 src/messaging 등을
옮기면 예외 줄의 경로가 바뀌므로 그 병합에서 FROZEN을 함께 고쳐야 한다.
레지스트리 yaml 설명 칸의 언어는 보지 않는다.

검증: python3 -m unittest discover -s scripts/tests 42개 통과. 변이 시험:
기준선 확인·낡은 예외 확인·언어 판정·이력 인용 건너뛰기·소스 세트 이름·
끝부분 대조·상태 어휘를 하나씩 끄면 해당 시험이 실패했다.
python3 scripts/check-docs.py rc=0(language 181·reference 7·number 29가
모두 예외, head 0), check-work-docs.py rc=0.
2026-11-07 12:26:37 +09:00