Files
clean-architecture-backend-…/docs/adr/ADR-MONGO-ADV-001-capability-promotion.md
T
DongHyeonka 59dff0041c ci(docs): 문서 검사에 문체를 더하고 번역한 결정 기록의 머리 문구를 맞춘다
문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만
지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다.
그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데,
2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다.

- check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다·
  입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드,
  따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다.
- runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가
  울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다.
- 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지
  않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명,
  docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안).
- docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고,
  링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs
  docs-system.md 6.2절 다섯 칸)을 더했다.

버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다).

위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo
밖이라 고치지 않았다(총괄에게 알린다).

검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함),
check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시
worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건,
1건 실패했다.
2026-11-07 22:20:18 +09:00

5.8 KiB

결정 기록 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택(보완)
  • 작성일: 2026-08-13
  • 요약: MongoDB 고급 기능의 승격 기준을 정한 결정이다. 2026-09-25 보완이 있다.
  • 현재 정본: docs/mongodb/support-matrix.md

ADR-MONGO-ADV-001 — Advanced capability 승격

  • 상태: 채택
  • 날짜: 2026-08-13
  • 설계 출처: 설계 §2 (D-15), §3.2–§3.3. Advanced 확장 계획 Task 15
  • 2026-09-25 보완: ca-skeleton.persistence-mongo.advanced.*.enabled 바인딩(MongoAdvancedConfiguration/ MongoAdvancedSettings)은 아무것도 import하지 않아서 어떤 배포 속성도 flag에 닿지 않았다. propertyFor와 함께 지웠다. flag는 이제 entry point를 만드는 어댑터가 코드로 만든다. MongoAdvancedPromotionGate, MongoAdvancedPromotionEvidence, MongoVectorSearchBenchmarkGate, 그리고 search, vector, time series, GridFS 패키지(구현 없는 인터페이스)를 지웠다. 아래 증거 category는 리뷰 의무로 남는다. 그것을 검사하는 클래스는 없다.

배경

sharding, time series, CSFLE, Queryable Encryption, search, vector search, multi-tenancy는 하나같이 오후 한나절이면 demo에서 동작한다. 하지 않는 것은 운영에서 같은 방식으로 동작하는 것이고, 그 차이는 기능 시험으로 찾지 못한다:

  • sharding은 어떤 query가 효율적인지 바꾼다. shard key를 놓친 query는 scatter-gather가 되는데, shard 하나짜리 cluster에서는 모든 시험을 통과한다.
  • 암호화의 실패 방식은 KMS의 실패 방식이다 — 틀린 키, 거둬들인 권한, 교체 중 — 로컬 키 provider에 대고는 하나도 일어나지 않는다.
  • search와 vector search는 기능상 맞으면서 쓸모없을 수 있다: index는 결과를 돌려주는데 결과가 관련이 없다. recall은 통과·실패 단언에 보이지 않는다.
  • 테넌트마다 데이터베이스는 테넌트 수가 연결·파일 handle 예산이 받쳐 주는 수를 넘을 때까지 동작한다. 그것은 코드가 아니라 운영의 성질이다.

이 ADR이 막는 실패 방식은 그것이 돌 환경을 한 번도 건드리지 않은 초록 시험을 근거로 capability를 「끝남」으로 표시하는 것이다.

결정

모든 Advanced·Experimental capability는 자기 flag 뒤의 골라 쓰는 모듈이고, 승격에는 자신감이 아니라 증거가 필요하다.

켜기

MongoAdvancedCapabilityFlags가 모든 Advanced entry point의 생성을 막는다. 꺼진 capability는 런타임 경고를 내지 않는다 — 타입이 그것을 켜는 속성 이름을 대며 만들어지기를 거절한다(MongoAdvancedCapabilityFlags.propertyFor(capability)). classpath에 있다고 켜진 것이 아니고, stableNeverDependsOnAdvanced(ArchUnit)가 Stable surface에서 그것을 떼어 둔다.

승격 증거

MongoAdvancedPromotionGate.verify(evidence)는 모든 category를 요구한다:

category 뜻
stable-platform 같은 revision에서 Stable 릴리스 gate가 통과했다.
actual-topology capability가 실제 topology에서 돌았다 — 실제 sharded cluster, 실제 KMS, 실제 대상 배포. Atlas Local은 pull request용 편의이고 릴리스 증거가 아님을 명시한다(MongoAtlasCapabilityContractSuite.Environment.ATLAS_LOCAL).
security 권한을 리뷰했다. capability의 admin role은 애플리케이션 role과 따로다.
migration 들어가는 길을 적었고, capability가 되돌릴 수 없으면 돌아오는 길이 없다고 명시했다.
failure 부정 경우가 실패하면 닫힌다: 틀린 키, 빠진 권한, 교체, 준비되지 않은 index, 라우팅되지 않은 query.
runbook capability의 대표 사고를 위한 runbook이 있다.

capability별 추가 요구

  • search / vector search: 기능 성공만이 아니라 관련성과 성능 증거. MongoVectorSearchBenchmarkGate는 지연 시간·index 크기와 함께 recall을 요구한다. 지연 시간만 재는 gate는 빠른 틀린 답을 인증한다.
  • 테넌트마다 데이터베이스와 reshard 조율은 운영 규모 증거가 생길 때까지 Experimental로 남는다. 둘 다 작게는 맞고 크게는 한계가 없다.
  • reshard에는 명시한 ReshardApproval이 필요하다 — 이름 있는 승인자와 밝힌 시간 창. reshard는 collection을 다시 쓴다.

승격은 의존 경계를 바꾸지 않는다

Stable로 승격한 capability도 나중의 starter ADR이 의존 경계를 바꾸지 않는 한 골라 쓰는 모듈로 남는다. 승격은 증거에 대한 진술이지, 모든 서비스에 전이 의존을 더하라는 초대가 아니다.

결과

좋은 점. container 전용 시험을 근거로 운영에 닿는 capability는 없다. 증거 목록이 모든 capability에 같으므로, 승격은 흥정이 아니라 리뷰할 수 있는 것이 된다.

나쁜 점. 승격에는 실제 기반 시설 — sharded cluster, 실제 KMS, 대상 배포 — 에 대한 접근이 필요하다. 그것이 보장의 비용이다: 대안은 운영에서 알게 되는 것이고, 거기서는 암호화와 sharding 둘 다 되돌리기 비싸다.

검증

scripts/verify-mongodb-advanced.sh가 2026-08-15에 지워질 때까지 이 ADR을 강제했다. 그래서 이 ADR이 요구하는 승격 증거 category는 이제 어떤 자동 gate도 검사하지 않는다. 다시 만들 때까지 리뷰 의무다. 그 script가 감싸던 Gradle lane은 docs/mongodb/repository-adaptation.md §5를 본다.