Files
clean-architecture-backend-…/docs/superpowers/specs/2026-11-06-error-code-log-level-design.md
T
DongHyeonka e0beeca214 fix(error-codes)!: 레지스트리에서 log_level 칸을 지운다
문제: docs/registries/error-codes.yaml의 log_level 칸은 읽는 코드가 없다.
로그 레벨은 오류 코드가 아니라 실패의 종류와 경로가 정한다
(ServerFailureLog, AuthErrorResponseWriter). 그래서 그 코드를 내는 곳이 있는
47행 중 33행이 실제 레벨과 달랐고, 런북 2곳이 틀린 레벨을 증상으로 적었다.

고른 방법: 칸을 지우고, 머리말이 레벨을 정하는 코드를 가리킨다(설계 메모 안
A, 소유자 결정 2026-11-06). 칸이 다시 생기지 않게
OperationalErrorRegistryContractTest에 단언을 둔다. client_safe_message를
코드에 고정한 테스트가 있는 자리다. 모든 레지스트리의 공통 스키마를 보는
ContractRegistrySchemaGovernanceTest는 한 레지스트리의 칸 뜻을 다루지 않아
고르지 않았다. 런북은 실제 로그 줄을 증상으로 적는다. 결정 색인 2.3절과
설계 메모 10절에 결정을 남겼다.
버린 대안: 칸을 코드에 맞추고 테스트로 고정(B) — 규칙의 손 사본이 생기고,
템플릿이 내지 않는 13행은 고정할 값이 없다. 칸을 규범으로 만들어 코드가
읽기(C) — 4xx를 남기지 않는 설계를 뒤집고 로그 양이 는다.

위험·한계: 자기 error-codes.yaml 행에 log_level을 둔 파생 서비스는 merge
뒤 mainCheck(documentContractTest)가 실패한다. upgrade 안내 「반드시 할 일」
17과 B-44에 적었다. repo 밖에서 이 칸을 읽는 도구는 없는 것으로 본다(소유자
결정 4).

검증(desktop, 공유 잠금, 로그는 desktop ~/t3-loglevel-logs/):
- RED: 기준 yaml로 OperationalErrorRegistryContractTest 3건 중
  noRegistryRowCarriesALogLevel 1건 실패(log_level이 있는 행 목록 출력).
  rc=1, red-registry.log
- GREEN: :app-bootstrap:documentContractTest rc=0, 66건 실패 0
  (RunbookCoverageContractTest 포함). green-doc-contract.log
- :app-bootstrap:testQualityCheck :app-bootstrap:spotlessCheck rc=0.
  green-quality.log
- python3 scripts/check-work-docs.py rc=0, --links docs 깨진 링크 0

BREAKING CHANGE: error-codes.yaml 행에 log_level이 있으면
OperationalErrorRegistryContractTest가 실패한다. 파생 서비스는 자기 행에서
log_level: 줄을 지운다. 레벨을 바꾸려면 그 실패를 로그로 남기는 코드를 고친다.
2026-11-06 22:17:13 +09:00

23 KiB

error-codes.yaml의 log_level 칸 — 설계 메모

  • 상태: 확정 (2026-11-06, 소유자 답 "권하는 안대로"). 결정은 10절이다. 아래 1~9절은 결정 전에 쓴 그대로 둔다.
  • 기준 커밋: 06f520e6 (refactor/maturity-review-2026-11)
  • 크기: 중간(brief). 이 메모가 고르는 안을 실제로 적용하는 일은 큼이다. 오류 코드 레지스트리는 공개 계약이라 파일 하나여도 큼이다(docs/work/README.md 2절). 그래서 이 메모는 대안 비교까지 하고 멈춘다. 코드와 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:18 log_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.yaml 96행에 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, gRPC GrpcExceptionHandlingInterceptor.java:135-136, GraphQL GraphQlWireErrorMapper.java:134-135, STOMP StompHandlerFailureLog.java:35-36
    • IAE WARN: web GlobalExceptionHandler.java:96-97, gRPC :139-140, GraphQL :137-138, STOMP :40-41
  • 보안 필터: src/adapter/inbound/web/src/main/java/dev/caskeleton/adapter/inbound/web/auth/AuthErrorResponseWriter.java:32 log.warn("security failure: code={} …"). 인증 진입점과 접근 거부 처리기가 둘 다 이 writer를 쓴다.
  • Spring MVC: GlobalExceptionHandler.java:397-401. 그 밖의 예외: 같은 파일 195-203행.
  • 배경 작업: Slf4jOutboxRelayFailureReportAdapter.java의 atError(), LoggingAbortPolicy.java:35.
  • 이 규칙은 리뷰를 거쳐 정한 설계다. 네 전송이 한 정책을 쓰게 했고(ServerFailureLog Javadoc 첫 문단), IAE를 네 전송에서 같은 WARN 한 줄로 남기게 했다(RR6-01-06, docs/reviews/2026-11-03-rereview/README.md 17절 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를 증상으로 적는다. 실제 줄은 WARN security 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 줄을 뺀다. 대신 "로그 레벨은 오류 코드가 아니라 실패 종류와 경로가 정한다. 규칙은 ServerFailureLog Javadoc과 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.md 1절)에 맞는 새 근거가 없다.
  • 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. 반증할 수 있는 가정, 반론과 답

가정

  1. 템플릿과 파생 서비스 밖에서 이 칸을 읽는 도구가 없다. 틀렸다면: 로그 파이프라인이나 대시보드가 이 yaml을 읽고 있다면 칸 삭제가 그것을 깨뜨린다. 확인한 범위는 두 repo의 추적 파일이다. repo 밖 운영 도구는 모른다(결정 4).
  2. 레벨은 오류 코드 하나로 정해지지 않는다. 틀렸다면 B의 비용이 크게 준다. 확인: GlobalExceptionHandler.java:96-97(IAE, WARN)과 :108-116(타입 변환, 로그 없음)가 같은 BAD_PARAMETER를 낸다.
  3. 4xx를 남기지 않는 것은 의도다. 틀렸다면, 즉 소유자가 4xx를 줄 단위로 추적하길 원하면 C가 맞다. 근거: ServerFailureLog.java:25의 문장. 4xx 양은 http.server.requests의 status=4xx 지표로 이미 보인다 (metrics.yaml:18-40).
  4. 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_ERROR 500으로 답할 것으로 읽힌다(GlobalExceptionHandler.java:195-203).
    • LockAcquisitionTimeoutClassificationContractTest가 막으려는 "500 INTERNAL로 뭉개기"(D7)와 같은 모양이다. 그 테스트는 enum과 레지스트리만 보고 전송 경로는 보지 않는다.
    • 코드 읽기 결과이고 탐침은 돌리지 않았다. 결함 후보로 docs/work/improve.md 절차에 넘긴다.

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절 「오류 코드 로그 레벨」.