문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시 없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는 거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다. 고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의 .md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일· 요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄 두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함). - 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거). - 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는 설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」. capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」, 2026-07-20 하네스 설계·계획과 production capability platform 설계는 「대체됨」이다. - 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신 docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다. docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와 코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록 충돌 가능성을 적었다. 버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이 파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는 안은 폴더와 같은 정보를 두 번 쓰게 한다. 위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지 아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을 끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다 (납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는 아직 머리 블록을 달지 않았다. 검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
23 KiB
23 KiB
기록 · 설계서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-11-06
- 요약: 오류 코드 레지스트리에 log_level 칸을 두지 않고 실패 종류·경로가 레벨을 정하게 한 설계 메모다.
- 현재 정본:
docs/registries/error-codes.yaml
error-codes.yaml의 log_level 칸 — 설계 메모
- 상태: 확정 (2026-11-06, 소유자 답 "권하는 안대로"). 결정은 10절이다. 아래 1~9절은 결정 전에 쓴 그대로 둔다.
- 기준 커밋:
06f520e6(refactor/maturity-review-2026-11) - 크기: 중간(brief). 이 메모가 고르는 안을 실제로 적용하는 일은 큼이다. 오류 코드 레지스트리는 공개 계약이라
파일 하나여도 큼이다(
docs/work/README.md2절). 그래서 이 메모는 대안 비교까지 하고 멈춘다. 코드와 yaml은 바꾸지 않았다. - 요청(총괄 brief 원문): "
docs/registries/error-codes.yaml의log_level칸은 읽는 코드가 없고, 값이 코드와 다른 곳이 있다(IDEMPOTENCY_UNAVAILABLE: 문서 WARN, 코드 ERROR). 이 칸을 어떻게 할지 설계 메모를 쓰고 소유자 결정을 묻는다." - 처음 나온 곳: 재리뷰 round6이 "규범인지 판단하지 않았다"로 남긴 항목
(
docs/reviews/2026-11-03-rereview/round6/02-idempotency-outbound.md:217).
1. 결론
권하는 안은 A — 칸을 지운다이다. 로그 레벨은 오류 코드 하나가 아니라 실패의 종류와 경로가 정하고, 그 규칙은
이미 코드 한 곳(ServerFailureLog)에 있다. 레지스트리 머리말은 그 규칙을 가리키기만 한다. 칸 값을 증상으로 적은
런북 2곳은 실제 로그 줄로 고친다.
칸과 별개로 동작 질문이 둘 남는다. 보안 필터가 5xx 두 코드를 WARN으로 남기는 것(결정 2), 문서가 ERROR로 의도한 401 세 코드(결정 3)다.
2. 지금 어떻게 되어 있나
2.1 칸을 읽는 곳
- 스키마:
docs/registries/error-codes.yaml:18log_level: ERROR | WARN | INFO. 60행 모두 값이 있다(ERROR 25, WARN 26, INFO 9). - 코드와 테스트: 읽는 곳이 없다.
src·scripts의 java·py·gradle·sh에서log_level·logLevel검색 결과 0건이다. - 테스트가 읽는 칸:
category·http_status·retryable·client_safe_message·runbook_link·owner_branch·compatibility_impact·required_test다(테스트 코드의get("<칸>")집계).log_level과owner_layer만 아무도 읽지 않는다. - 스키마 검사(
ContractRegistrySchemaGovernanceTest,RegistryGovernanceCatalog.java:217, 247-253)는 필수 칸만 본다. 모르는 칸을 막지 않는다. - 값의 이력:
git log -S log_level의 네 커밋(821fe00c,9da00eb7,c4a066df,bbe944bd)은 행을 넣거나 뺐다. 있던 행의 레벨 값이 바뀐 적은 없다(커밋 사이 코드별 값 비교 결과 차이 0). - 런북: 두 곳이 칸 값을 증상으로 적는다.
docs/runbooks/auth-token-invalid-signature.md:16: "log_level=ERROR— may indicate forged tokens"docs/runbooks/authz-tenant-mismatch.md:16: "log_level=ERROR"
- 경보:
docs/registries/metrics.yaml의 경보 기준은 모두 지표다(error_rate, p99 등). 로그 레벨을 세는 경보는 없다 (logback_events·level=error검색 0건). - 파생 서비스
tech-log-backend(a000f87): 자기error-codes.yaml96행에log_level을 채운다. 설계서가 새 행마다 이 칸을 채우라고 적는다(docs/superpowers/specs/2026-08-18-techlog-studio-backend-design.md:382). 그쪽에도 이 칸을 읽는 코드는 없다(git grep log_level, java·gradle·yaml·sh 0건).
2.2 코드가 로그 레벨을 정하는 방식
레벨은 오류 코드가 아니라 실패의 종류와 경로가 정한다.
요청 실패 ─┬─ 보안 필터(401·403·JWKS·인증 설정) ─ AuthErrorResponseWriter ─────────── 늘 WARN
├─ IllegalArgumentException ─────────── ServerFailureLog.refusedArgument ─── WARN
├─ ApiErrorCarrier ─ ServerFailureLog.of ─┬─ PersistenceFailureException ── ERROR (상태 무관)
│ ├─ DependencyFailureException ── ERROR (상태 무관)
│ ├─ 그 밖의 5xx ───────────────── ERROR
│ └─ 4xx ───────────────────────── 남기지 않음
├─ Spring MVC 예외 ─ handleExceptionInternal ── 5xx면 ERROR, 4xx면 남기지 않음
└─ 그 밖의 예외 ─ handleUnknown ── INTERNAL_ERROR로 답하고 ERROR
배경 작업 ─ outbox 실패 보고, executor 거절 ── ERROR
출처:
- 규칙:
src/shared-contract/src/main/java/dev/caskeleton/shared/error/ServerFailureLog.java:54-79. 4xx를 남기지 않는 이유는 같은 파일 25행 "A client-side carrier is not logged: it is an answer, not an incident"다. IAE WARN은 91-96행이다. - 네 전송이 같은 줄을 쓴다.
- carrier ERROR: web
GlobalExceptionHandler.java:173-176, gRPCGrpcExceptionHandlingInterceptor.java:135-136, GraphQLGraphQlWireErrorMapper.java:134-135, STOMPStompHandlerFailureLog.java:35-36 - IAE WARN: web
GlobalExceptionHandler.java:96-97, gRPC:139-140, GraphQL:137-138, STOMP:40-41
- carrier ERROR: web
- 보안 필터:
src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/AuthErrorResponseWriter.java:32log.warn("security failure: code={} …"). 인증 진입점과 접근 거부 처리기가 둘 다 이 writer를 쓴다. - Spring MVC:
GlobalExceptionHandler.java:397-401. 그 밖의 예외: 같은 파일 195-203행. - 배경 작업:
Slf4jOutboxRelayFailureReportAdapter.java의atError(),LoggingAbortPolicy.java:35. - 이 규칙은 리뷰를 거쳐 정한 설계다. 네 전송이 한 정책을 쓰게 했고(
ServerFailureLogJavadoc 첫 문단), IAE를 네 전송에서 같은 WARN 한 줄로 남기게 했다(RR6-01-06,docs/reviews/2026-11-03-rereview/README.md17절 r10-01).
그래서 레벨은 오류 코드 하나에 값 하나로 떨어지지 않는다.
- 같은
BAD_PARAMETER라도 IAE에서 오면 WARN이다. 타입 변환 실패에서 오면 남기지 않는다 (GlobalExceptionHandler.java:108-116). - 같은 409라도 영속성 실패면 ERROR다. 멱등 in-flight면 남기지 않는다.
2.3 60행 대조
방법: 행마다 main 코드에서 그 코드를 내는 곳을 찾았다(grep -rlw <CODE> src --include='*.java' 중 /main/). 그 경로에
2.2의 규칙을 대어 레벨을 정했다. 코드를 읽은 결과이고, 실행 탐침은 돌리지 않았다(이유는 6절 가정 4).
| 결과 | 행 | 코드 |
|---|---|---|
| 같다 | 14 | WARN: AUTH_TOKEN_MISSING, AUTH_TOKEN_MALFORMED, AUTH_TOKEN_EXPIRED, AUTH_KID_UNKNOWN. ERROR: DB_UNAVAILABLE, DB_IDLE_IN_TX_TIMEOUT, DB_COMPLETION_UNKNOWN, IDEMPOTENCY_COMPLETION_UNKNOWN, IDEMPOTENCY_RECOVERY_REQUIRED, ADAPTER_DISABLED, INTERNAL_ERROR, OUTBOX_PUBLISH_FAILED, OUTBOX_DEAD_LETTER, JOB_EXECUTOR_REJECTED |
| 문서 ERROR, 코드 WARN | 5 | AUTH_TOKEN_INVALID_SIGNATURE, AUTH_ISSUER_MISMATCH, AUTH_AUDIENCE_MISMATCH(401), AUTH_JWKS_UNAVAILABLE(503), INTERNAL_AUTH_MISCONFIGURATION(500). 보안 필터가 모두 WARN으로 남긴다 |
| 문서 WARN, 코드 ERROR | 10 | IDEMPOTENCY_UNAVAILABLE(503 carrier). 영속성 실패 9개: DB_SERIALIZATION_FAILURE, DB_DEADLOCK, DB_NULL_VIOLATION, DB_FK_VIOLATION, DB_UNIQUE_VIOLATION, DB_CHECK_VIOLATION, DB_OPTIMISTIC_CONFLICT, DB_LOCK_TIMEOUT(409), DB_QUERY_CANCELED(503). JPA 예외는 모두 PersistenceFailureException의 하위 타입이다(JpaPersistenceException.java:22) |
| 문서는 레벨, 코드는 남기지 않음 | 15 | IDEMPOTENT_IN_FLIGHT, IDEMPOTENT_REQUEST_MISMATCH, MAPPING_FAILED, VALIDATION_FAILED, PRECONDITION_FAILED, METHOD_NOT_ALLOWED, NOT_ACCEPTABLE, PAYLOAD_TOO_LARGE, URI_TOO_LONG, UNSUPPORTED_MEDIA_TYPE, ROUTE_NOT_FOUND, RATE_LIMIT_EXCEEDED, INVALID_TOKEN, FORBIDDEN, BATCH_PARTIAL_FAILURE |
| 경로마다 다름 | 3 | BAD_PARAMETER(문서 INFO; IAE면 WARN, 타입 변환이면 없음). AUTHZ_INSUFFICIENT_PERMISSION(문서 WARN; 필터면 WARN, controller method security면 handleForbidden이라 없음). UNAUTHENTICATED(문서 WARN; web은 없음, gRPC는 인증 정책이 예외를 던질 때만 WARN — GrpcAuthenticationInterceptor.java:55) |
| 템플릿 main에 내는 곳 없음 | 13 | AUTH_CLAIM_MAPPING_FAILED, AUTHZ_TENANT_MISMATCH, JVM_OOM, DEPENDENCY_TIMEOUT, DEPENDENCY_CONNECT_FAILED, DEPENDENCY_DNS_FAILED, DEPENDENCY_4XX_CLIENT, DEPENDENCY_5XX_SERVER, DEPENDENCY_CIRCUIT_OPEN, JOB_TIMEOUT, JOB_DEAD_LETTER, ACTUATOR_FORBIDDEN, LOCK_ACQUISITION_TIMEOUT |
- 내는 곳이 있는 47행 중 33행이 문서와 다르다. brief가 든
IDEMPOTENCY_UNAVAILABLE은 그중 하나다. DEPENDENCY_*: 파생 서비스의 어댑터가DependencyFailureException으로 던지면 ERROR가 된다. 그때는 문서가 WARN인DEPENDENCY_CIRCUIT_OPEN도 어긋난다.LOCK_ACQUISITION_TIMEOUT은 레벨과 별개의 문제가 있다(9절).
2.4 어긋남이 실제로 해를 끼치는 곳
- 런북 증상이 틀렸다.
auth-token-invalid-signature.md는log_level=ERROR를 증상으로 적는다. 실제 줄은 WARNsecurity failure: code=AUTH_TOKEN_INVALID_SIGNATURE …다. ERROR로 거르는 운영자는 이 사건을 못 본다. - 칸을 채우는 일이 헛수고다. 새 코드를 만드는 사람이 칸을 채워도 동작이 바뀌지 않는다. 파생 서비스는 96행에 값을 골라 적었다.
- 경보는 로그 레벨을 쓰지 않는다. 그래서 이 어긋남으로 경보가 빠지지는 않는다.
3. 선행 사례
| 출처 | 1차/2차 | 그들이 한 것 | 한계 | 가져올 것 |
|---|---|---|---|---|
이 repo client_safe_message 칸 (c4a066df, 소유자 결정 11) |
1차 | 행마다 다르던 문구를 Category별 문구 표 하나(ClientErrorMessages)로 코드에 두었다. 칸은 그 값과 같아야 한다고 테스트로 고정했다(OperationalErrorRegistryContractTest.everyRegistryClientMessageIsTheSharedCategoryMessage) |
문구가 category만으로 정해져서 고정이 쉬웠다 | 코드가 원본이고 칸은 테스트가 고정한다. 레벨은 코드 하나로 정해지지 않는다는 점이 다르다(2.2) |
이 repo category·http_status·retryable |
1차 | enum이 원본이다. yaml을 enum과 테스트로 대조한다(theEnumAndTheRegistryAgree) |
— | 레지스트리 칸은 코드가 읽거나 테스트가 고정한다는 이 repo의 관행 |
이 repo env-keys.yaml의 required_when (0a6dd0e4) |
1차 | 런타임이 강제한 적 없는 요구("app.redis.mode=sentinel")를 지우고 실제 동작에 맞췄다(docs/registries/env-keys.yaml:2269-2273) |
— | 강제하지 않는 레지스트리 문장을 규범처럼 두지 않는다. 실제 동작으로 고친다 |
| JBoss Logging Tools (Hibernate·WildFly가 씀) | 1차, https://jboss-logging.github.io/jboss-logging-tools/ | 메시지 id와 레벨을 코드의 annotation 한 곳에 둔다(@Message(id = …), @LogMessage(level = ERROR)). 보고서(id, 해결 문서 링크, 메시지, 레벨)는 annotation에서 만든다(AsciiDoc·XML) |
메시지마다 레벨이 하나인 모델이다. 경로마다 레벨이 다른 우리 설계에는 그대로 맞지 않는다 | 레벨을 문서로 보이고 싶으면 손으로 쓴 칸이 아니라 코드에서 뽑는다 |
Spring Framework AbstractHandlerExceptionResolver |
1차, spring-webmvc/src/main/java/org/springframework/web/servlet/handler/AbstractHandlerExceptionResolver.java(main) |
예외 처리 로그는 처리기 코드가 정한다. 기본은 남기지 않고, setWarnLogCategory로 켜면 WARN 한 레벨로 남긴다 |
오류 코드별 레벨 표는 없다 | 처리된 클라이언트 오류는 기본으로 남기지 않는다. ServerFailureLog의 "4xx는 답이지 사건이 아니다"와 같은 판단이다 |
4. 대안
A. 칸을 지운다
- 머리말 스키마에서
log_level줄을 뺀다. 대신 "로그 레벨은 오류 코드가 아니라 실패 종류와 경로가 정한다. 규칙은ServerFailureLogJavadoc과AuthErrorResponseWriter"라고 적는다. - 60행에서
log_level:줄을 지운다. - 런북 2곳의 증상 줄을 실제 로그 줄로 고친다.
docs/upgrade/에 파생 서비스 안내를 한 줄 더한다.- 선택(결정 1-b): 칸이 다시 생기지 않게 "행에
log_level이 없다"는 단언을 레지스트리 테스트에 둔다. 두면 파생 서비스도 자기 행에서 칸을 지워야 merge 뒤 테스트가 통과한다.
B. 칸을 남기고 코드에 맞춘 뒤 테스트로 고정한다
- 값 집합에
NONE(남기지 않음)과BY_PATH(경로마다 다름)를 더한다. 60행을 2.3 표대로 고친다. - 테스트는
ServerFailureLog규칙을 다시 구현한 표(코드 → 기대 레벨)와 yaml을 대조한다. - 문제: 레벨이 코드만으로 정해지지 않아서, 표가 규칙의 손 사본이 된다. 예외 종류(영속성·의존성 carrier)는 행에
없으므로, 테스트가 "
DB_*면 ERROR"를 이름 접두어로 짐작해야 한다. 템플릿 main에 내는 곳이 없는 13행은 기대값을 정할 근거가 없다.
C. 칸을 규범으로 만들고 코드가 읽는다
ApiErrorCode에logLevel()을 더한다.OperationalError는 값을 갖고, 파생 enum은 default 메서드로 지금 규칙을 쓴다.- 네 전송, 보안 필터, 배경 작업이 그 값으로 남긴다. yaml은 enum과 테스트로 대조한다.
- 동작이 바뀐다. 2.3의 33행이 지금과 다른 레벨이 된다.
- 문서가 INFO·WARN인 4xx 15행이 새로 로그를 남긴다. 404·400·429마다 한 줄씩이라, 스캐너·공격 트래픽이 로그 양을 정한다.
- 409 영속성 실패는 ERROR에서 WARN으로 내려간다.
ServerFailureLog의 "4xx는 남기지 않는다"와 RR6-01-06 결정을 뒤집는다. 다시 열 조건(docs/work/reference/decisions.md1절)에 맞는 새 근거가 없다.ApiErrorCode는 shared-contract의 공개 인터페이스다. 파생 서비스의 enum이 영향을 받는다.
버린 기준선: 주석만 달기
칸에 "참고용"이라 적고 IDEMPOTENCY_UNAVAILABLE 한 행만 고치는 안이다. 틀린 33행 중 1행만 고쳐지고 런북은 여전히
틀린 증상을 적는다. 버린다.
비교
| 대안 | 효과 | 비용 | 되돌리기 | 파생 서비스 영향 | 기존 결정과 충돌 |
|---|---|---|---|---|---|
| A 지움 | 틀린 값 33행과 틀린 런북 증상 2곳이 사라진다. 레벨의 원본이 코드 하나로 준다 | yaml 머리말·60줄, 런북 2곳, upgrade 1줄. 코드 변경 0 (1-b면 테스트 단언 1개) | 쉽다(revert) | 1-b 없으면 할 일 없음. 1-b면 자기 96행에서 칸을 지운다 | 없다. client_safe_message·env-keys 선례와 같은 방향 |
| B 맞추고 고정 | 칸이 맞는 값이 된다 | yaml 33행, 스키마, 새 테스트(규칙의 손 사본). 규칙을 바꿀 때마다 두 곳을 고친다 | 쉽다 | 같은 테스트가 파생 행도 읽으면 자기 행도 맞춰야 한다 | 없다. 다만 규칙 사본을 하나 더 만든다 |
| C 규범화 | 소유자가 코드마다 레벨을 고를 수 있다 | shared-contract 인터페이스, 전송 넷, 보안 필터, 배경 작업, 테스트. 로그 양이 는다 | 어렵다(공개 인터페이스, 운영 로그 모양) | ApiErrorCode 구현 enum, 로그 수집 규칙 |
ServerFailureLog 설계, RR6-01-06 |
5. 권하는 안: A
- 이 칸이 담으려던 정보("이 코드가 얼마나 시끄러운가")는 코드가 이미 실패 종류로 정한다. 그 규칙은 리뷰를 거쳐 네 전송에 하나로 모였다. 코드별 칸은 그 규칙을 담을 모양이 아니다(2.2).
- B는 그 규칙의 손 사본을 테스트에 하나 더 만든다. 사본은 고칠 곳만 늘린다. 내는 곳이 없는 13행에는 고정할 값도 없다.
- C는 코드가 맞고 문서가 틀린 상황에서 코드를 문서에 맞춘다. 문서 값은 행을 처음 넣을 때 적은 뒤 한 번도 고친 적이 없다(2.1). 레벨을 따져 본 리뷰를 거친 쪽은 코드다.
- 이 repo의 관행은 "칸은 코드가 읽거나 테스트가 고정한다"이다. 이 관행에 맞는 길은 A와 B인데, B는 고정할 값이 없다. 그래서 A다.
6. 반증할 수 있는 가정, 반론과 답
가정
- 템플릿과 파생 서비스 밖에서 이 칸을 읽는 도구가 없다. 틀렸다면: 로그 파이프라인이나 대시보드가 이 yaml을 읽고 있다면 칸 삭제가 그것을 깨뜨린다. 확인한 범위는 두 repo의 추적 파일이다. repo 밖 운영 도구는 모른다(결정 4).
- 레벨은 오류 코드 하나로 정해지지 않는다. 틀렸다면 B의 비용이 크게 준다. 확인:
GlobalExceptionHandler.java:96-97(IAE, WARN)과:108-116(타입 변환, 로그 없음)가 같은BAD_PARAMETER를 낸다. - 4xx를 남기지 않는 것은 의도다. 틀렸다면, 즉 소유자가 4xx를 줄 단위로 추적하길 원하면 C가 맞다. 근거:
ServerFailureLog.java:25의 문장. 4xx 양은http.server.requests의status=4xx지표로 이미 보인다 (metrics.yaml:18-40). - 2.3 표는 코드 읽기로 충분하다. 틀렸다면: 다른 경로가 같은 코드를 다른 레벨로 남기면 표 칸이 바뀐다. 결론
("대부분 다르다")은 33행 중 몇 행이 바뀌어도 유지된다. 탐침을 돌리지 않은 이유는 둘이다.
- 각 경로는 레벨을 바꾸는 분기가 없는
log.error/log.warn한 줄이다. - 기존 테스트가 같은 레벨을 고정한다:
GrpcExceptionHandlingInterceptorTest·StompHandlerFailureLogTest·GraphQlWireErrorMapperTest의Level.ERROR/Level.WARN단언,GlobalExceptionHandlerTest.anIllegalArgumentIsLoggedAtWarnByItsTypeWithoutItsMessage.
- 각 경로는 레벨을 바꾸는 분기가 없는
반론과 답
- "레벨을 문서에서 한눈에 보는 가치가 있다." 그 가치는 값이 맞을 때만 있다. 지금은 47행 중 33행이 틀렸다. 꼭 보이고 싶다면 JBoss Logging처럼 코드에서 뽑아야 한다. 그것은 레벨이 코드별 값이 된 뒤(C)에나 가능하다.
- "보안 쪽 ERROR(위조 토큰 의심)는 의도였다." 의도는 런북 문장에 남아 있지만 구현된 적이 없다. 401 서명 실패를 ERROR로 남기면 공격자가 ERROR 양을 정하게 된다. 감지가 필요하면 결정 3에서 따로 고른다.
- "칸을 지우면 파생 서비스가 upstream merge 때 할 일이 생긴다." 1-b를 두지 않으면 할 일이 없다. 1-b를 두면 지울 일이 생기지만, 같은 거짓 칸이 파생 서비스 96행에 남지 않는다.
7. 소유자가 정할 것
| # | 항목 | 선택지 | 권하는 안과 이유 | 정할 사람 |
|---|---|---|---|---|
| 1 | log_level 칸 |
A 지움 / B 코드 규칙에 맞추고 테스트로 고정 / C 규범화(코드가 읽음) | A. 5절 | 소유자 |
| 1-b | A일 때 칸이 다시 생기는 것을 막는 단언 | 둔다(파생 서비스도 자기 행에서 지운다) / 두지 않는다 | 둔다. 칸이 거짓인 것은 파생 서비스 행도 같다. upgrade 안내 "반드시 할 일"에 한 줄 | 소유자 |
| 2 | 보안 필터가 5xx 두 코드(AUTH_JWKS_UNAVAILABLE 503, INTERNAL_AUTH_MISCONFIGURATION 500)를 WARN으로 남기는 것 |
ERROR로 올림 / WARN 유지 | ERROR로 올림. 다른 모든 경로가 5xx를 ERROR로 남긴다. 둘 다 서버 쪽 고장(키 서버 장애, 설정 오류)이다. 1번과 관계없이 동작 변경이라 별도 개선 작업으로 한다 | 소유자 |
| 3 | 401 서명·issuer·audience 불일치(문서가 ERROR로 의도) | WARN 유지, 런북은 WARN 줄의 code로 찾게 고침 / ERROR로 올림 / WARN 유지 + 코드별 인증 실패 지표를 새로 둠 | WARN 유지. 클라이언트가 만드는 실패라 ERROR로 올리면 공격 트래픽이 ERROR 양을 정한다. 경보가 필요하면 세 번째 안이다. 지금은 코드별 인증 실패 지표가 없다(metrics.yaml) |
소유자 |
| 4 | repo 밖에서 이 칸을 읽는 도구 | 있음 / 없음 | 모름. 두 repo의 추적 파일에는 없다. 있으면 A를 다시 본다 | 소유자 |
8. 결정 뒤 할 일 (이 메모에서는 하지 않았다)
- A를 고르면:
docs/registries/error-codes.yaml머리말과 60행, 런북 2곳,docs/upgrade/안내 한 줄, (1-b면) 레지스트리 테스트 단언. 공개 계약 변경이라 크기는 큼이고docs/work/improve.md로 한다. 결정은docs/work/reference/decisions.md에 기록한다. - 결정 2를 고르면:
AuthErrorResponseWriter의 레벨 분기와 테스트(RED → GREEN). - B나 C를 고르면 이 메모의 4절을 계획서로 옮겨 다시 크기를 잡는다.
9. 이 조사 중 본 별개 문제 (범위 밖, 고치지 않았다)
LockAcquisitionTimeoutException은ApiErrorCarrier를 구현하지 않는다 (src/application-core/src/main/java/dev/caskeleton/application/lock/LockAcquisitionTimeoutException.java:13). inbound 어디에도 이 예외의 처리기가 없다(grep -rln LockAcquisitionTimeoutException src: persistence-jpa와 테스트뿐).- Javadoc은 "The web adapter maps it to 409"라고 적는다. 하지만 web은
handleUnknown을 거쳐INTERNAL_ERROR500으로 답할 것으로 읽힌다(GlobalExceptionHandler.java:195-203). LockAcquisitionTimeoutClassificationContractTest가 막으려는 "500 INTERNAL로 뭉개기"(D7)와 같은 모양이다. 그 테스트는 enum과 레지스트리만 보고 전송 경로는 보지 않는다.- 코드 읽기 결과이고 탐침은 돌리지 않았다. 결함 후보로
docs/work/improve.md절차에 넘긴다.
- Javadoc은 "The web adapter maps it to 409"라고 적는다. 하지만 web은
10. 결정 (2026-11-06)
소유자 답은 "권하는 안대로"다(총괄 세션 전달, 2026-11-06). 7절 각 항목은 이렇게 정해졌다.
| # | 결정 | 적용한 곳 |
|---|---|---|
| 1 | A. log_level 칸을 지운다. 레지스트리 머리말이 레벨을 정하는 코드(ServerFailureLog, AuthErrorResponseWriter)를 가리킨다 |
docs/registries/error-codes.yaml 머리말과 60행 |
| 1-b | 칸이 다시 생기지 않게 단언을 둔다. 파생 서비스는 자기 행에서도 지운다 | OperationalErrorRegistryContractTest.noRegistryRowCarriesALogLevel(태그 document-contract), docs/upgrade/2026-11-maturity-review.md 「반드시 할 일」 17·B-44 |
| 2 | 보안 필터는 5xx(AUTH_JWKS_UNAVAILABLE 503, INTERNAL_AUTH_MISCONFIGURATION 500)를 ERROR로 남긴다 |
AuthErrorResponseWriter(5xx ERROR, 4xx WARN), EnvelopeAuthenticationEntryPointTest, web README, 런북 2곳, upgrade 5절 |
| 3 | 401 서명·issuer·audience 불일치는 WARN으로 둔다. 런북은 WARN 줄의 code=로 찾게 고친다 |
docs/runbooks/auth-token-invalid-signature.md, 서명 실패 WARN을 고정한 테스트 |
| 4 | repo 밖에서 이 칸을 읽는 도구는 없는 것으로 본다 | — |
결정 색인: docs/work/reference/decisions.md 2.3절 「오류 코드 로그 레벨」.