문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 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건 실패했다.
4.4 KiB
결정 기록 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-13
- 요약: MongoDB 플랫폼의 경계를 정한 결정이다.
- 현재 정본:
docs/mongodb/repository-adaptation.md
ADR-MONGO-001 — MongoDB 플랫폼 경계
- 상태: 채택
- 날짜: 2026-08-13
- 설계 출처:
docs/superpowers/specs/2026-08-11-mongodb-document-persistence-platform-design.md§1, §2 (D-01, D-04, D-05), §5, §6
배경
팀이 MongoDB를 감쌀 때 흔한 실패 방식이 둘 있다.
첫째는 납작하게 만들기다: 공용 CommonMongoRepository<T, ID>와 범용 CRUD 창구. 모든 collection이 id 전략, 일관성 profile,
query surface를 같이 쓰게 강요한다. MongoDB의 단일 문서 원자성, aggregation 모델, change stream에 더는 닿을 수 없고, 다른 것이
필요한 첫 collection은 cast나 새는 제네릭을 받는다.
둘째는 제한 없는 노출이다: driver와 runCommand를 어디서나 쓸 수 있다. 그러면 어느 서비스든 요청 스레드에서 collection을
지우거나, 한계 없는 pipeline을 돌리거나, admin 명령을 낼 수 있고, 구조로 잡을 것이 없으니 어떤 리뷰도 잡지 못한다.
결정
도메인이 자기 문서를 가지고, 플랫폼이 가로지르는 결정을 가진다. 노출 plane 넷:
| plane | 내용 | client |
|---|---|---|
| D1 표준 문서 영속 | Spring Data repository, 타입 있는 query, 대응 manifest, 원자 update 기본 장치, 낙관적 revision | Stable API V1, apiStrict=true |
| D2 고급 문서 연산 | MongoTemplate, 트랜잭션·세션, bulk, aggregation, keyset cursor, change stream |
Stable API V1, apiStrict=true |
| D3 명시적 Mongo capability | native BSON, time series, search·vector, CSFLE·QE, shard를 아는 연산 | 따로 둔 capability client |
| D4 admin plane | collection, validator, index, migration, shard, repair | 따로 둔 admin client와 credential |
구체적으로:
CommonMongoRepository<T, ID>가 없다. aggregate마다 자기 repository를 선언한다.- D1·D2는
apiStrict=true인 Stable API V1에서 돈다. 그래서 버전 있는 API 밖의 명령은 다음 서버 업그레이드 때가 아니라 개발 때 실패한다. - D3는 raw client로 빠져나가는 길이 아니다. 모든 호출이 정해진 허가 순서를 지난다: capability 등록 → 데이터베이스 profile → collection 허용 목록 → operation 이름 → timeout → 일관성 profile → 결과 한계 → trace → 가리기 → 명령 category → admin 명령 거절 → 실행.
- D4는 따로 둔 credential을 가진 따로 둔 client다. 애플리케이션 plane 경로는 그것에 닿지 않는다.
PolicyAwareMongoNativeGateway는 capability와 관계없이 admin category 명령을 거절한다. - Advanced와 Experimental capability는 골라 쓰는 모듈이고, Stable surface의 전이 의존이 되지 않는다.
결과
좋은 점. MongoDB의 뜻에 계속 닿을 수 있다. 잘못된 사용은 리뷰로 찾지 않고 구조로 거절한다. 서버 업그레이드가 D1·D2 동작을 소리 없이 바꿀 수 없다. admin 연산은 자기 감사 흔적과 credential을 가진다.
나쁜 점. 모든 operation에 등록된 이름과 profile이 필요해서, 새 query에는 0이 아니라 약간의 설정이 든다. 정말 새 capability는 쓰기 전에 등록이 필요하다. 둘 다 일부러다: 비용은 operation마다 한 번, 리뷰 때 낸다.
버린 대안 — 「driver를 내놓고 코드 리뷰에 기댄다」. 리뷰는 모든 서비스의 모든 query로 늘어나지 못하고, 중요한 연산
(한계 없는 pipeline, dropCollection, 사용자 입력에 대한 anchor 없는 정규식)은 diff에서 눈에 띄지 않는다.
저장소에 맞추기
설계는 modules/mongodb/ 아래 Gradle 모듈 19개를 가정한다. 이 저장소의 실패하면 닫히는 registry는 정확히 19개의 leaf identity를
선언하므로, 그 모듈들은 :adapter:outbound:persistence-mongo 안의 패키지 경계가 됐고 ArchUnit이 강제한다.
docs/mongodb/repository-adaptation.md를 본다.