문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 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.7 KiB
결정 기록 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-24
- 요약: GraphQL context는 inbound에 두고 객체 권한 판단은 application-core로 옮긴다는 결정이다.
- 현재 정본:
src/adapter/inbound/graphql/README.md
ADR-GQL-001 — GraphQL 문맥은 inbound에 머물고, 객체 인가는 application-core로 옮기며, persisted operation 저장소는 inbound SPI로 남는다
- 상태: 채택
- 날짜: 2026-08-24
- 리뷰:
docs/reviews/2026-08-14-graphql-module-code-review.mdGQL-026
배경
GraphQL leaf 자신의 문서는 경계를 넘는 것 셋을 적었다: application, JPA, Mongo, HTTP client로 deadline을 전파하는
GraphQlRequestContext, 전송 계층 안에서 정하는 객체 인가, 외부 durable 저장소가 구현하는 persisted operation
registry.
그중 둘은 의존 방향을 뒤집는다. application-core나 outbound 어댑터가 adapter:inbound:graphql에 있는 타입을
구현하면, inbound가 application에 의존한다는 registry edge는 만족되지만 실제 컴파일 의존은 반대로 간다.
셋째는 엉뚱한 계층의 업무 규칙이다: actor가 객체를 볼 수 있는지는 도메인에 대한 판단이고, GraphQL은 이 골격이 싣는 전송 계층 넷 중 하나다.
결정
세 문제가 같은 문제가 아니므로 답도 셋이다.
GraphQL 문맥은 inbound 안에 머문다. 타입으로 실려 다니지 않고 application command 필드 — actor, tenant,
deadline — 로 명시해 대응시킨다. leaf 밖의 어떤 것도 GraphQlRequestContext를 참조하지 않고, 경계 시험은 leaf
밖에서 grep이 아무것도 돌려주지 않는 것이다.
객체 인가는 application-core로 옮긴다. ObjectAccessPolicy, ObjectAccessRequest, ObjectAccessDecision은
전송 중립이고 다른 애플리케이션 정책과 함께 있다. GraphQL leaf의 ApplicationObjectAuthorization이 그것을 부르는
다리다. 셋 중 이것이 실제 계층 결함이었고, 적어 두지 않고 고친다.
persisted operation 저장소는 inbound가 가진 SPI로 남는다. GraphQlPersistedOperationRegistry는
advanced/persisted에 남고, GraphQL 밖의 어떤 leaf도 그것을 구현하지 않는다.
결과
변호가 필요한 것은 셋째 결정이다. 보고된 위험을 없애지 않고 그 자리에 두기 때문이다.
위험은 조건부다: leaf 밖의 무엇이 그 인터페이스를 구현할 때만 방향이 뒤집힌다. 그런 것은 없다. 템플릿은 메모리 registry를 싣고 durable registry는 싣지 않는다. persisted operation 저장소를 아예 싣지 않기 때문이다.
대안은 중립 계약 보유자가 가진 범용 운영 key-value 저장소 포트를 들이고, GraphQL 어댑터는 키와 값 대응만 가지는 것이었다. 그 포트는 인터페이스 정확히 하나, 구현 0개, 짐작으로 정한 쓰는 쪽 하나를 가졌을 것이다 — 아무도 말하지 않은 요구에서 모양을 짐작한 새 추상이다. 이 저장소는 있었지만 아무것도 닿지 않던 통제를 지우는 데 수정 한 바퀴를 통째로 썼다. 없는 저장소를 위해 포트를 지어내는 것이 그런 것을 다음에 또 쓰는 길이다.
그래서 결정은 SPI를 있는 곳에 두고, durable 저장소를 실제로 만들 때 옮기는 것이다. 그때 옮기는 일은 leaf 하나와 새 어댑터 하나에 걸친 이름 바꾸기이고, 그때까지 틀린 추상을 끌고 다니는 것보다 싸다. 그동안 일어나면 안 되는 것은 outbound leaf가 inbound 인터페이스를 구현하는 것이다. 그때가 방향이 실제로 뒤집히는 순간이고, 그것은 계층 변경이 아니라 구현처럼 보이는 diff의 커밋에서 일어날 것이다.
조립 루트가 이것들을 배선하고, 자기 업무·저장 정책은 가지지 않는다.
강제
verifyCleanArchitectureDependencies와 modules.json이 leaf의 domain-core, application-core, shared-contract
edge를 지킨다. ObjectAccessPolicyTest가 application 쪽 정책을, ApplicationObjectAuthorizationTest가 다리를 덮는다.
이 ADR이 기대는 조건 — GraphQL leaf 밖의 어떤 것도 persisted operation SPI를 구현하지 않는다 — 은 저장소 전체에
대한 주장이다. 그래서 leaf 안이 아니라 조립 루트에서, app-bootstrap architecture suite의 다른 GraphQL 경계 규칙
옆에서 검사한다.