# 04. 코드 구조 기준 ## 핵심 계층·경계 규칙의 정본은 `AGENTS.md`다. 이 장은 그 규칙을 다시 쓰지 않는다. 대신 **지난 리뷰에서 반복해 나온 결함을 코드 구조 기준으로 바꿔** 적는다. 같은 결함이 영역을 바꿔 가며 다시 나왔기 때문이다(`1101` README 4절 "반복되는 원인"). ```text AGENTS.md (HARD-STOP·모듈 책임·금지된 지름길) ── 무엇을 어기면 안 되나 leaf CLAUDE.md, application-core/CLAUDE.md ── 그 계층의 모양 docs/manual/ ── 새 기능을 만들 때의 판단 이 장 (P1~P11) ── 고치거나 리뷰할 때 반복해서 틀린 곳 ``` ## 1. 계층·경계 — 정본을 가리킨다 | 무엇 | 정본 | 지키는 장치 | | --- | --- | --- | | HARD-STOP 7개 | `AGENTS.md` 「Prime Directive」 | 의존 방향 게이트, ArchUnit(`architectureCheck`) | | family 책임과 금지 | `AGENTS.md` 「모듈 책임」, leaf `CLAUDE.md` 「Allowed」「Forbidden」 | 위와 같음 | | 금지된 지름길(controller의 repository 호출, application의 JPA 엔티티 반환 …) | `AGENTS.md` 「금지된 지름길」 | ArchUnit | | 유스케이스 모양, 허용 트랜잭션 모양 | `src/application-core/CLAUDE.md` 「Canonical use case shape」「Allowed transactional shapes」 | `ApplicationBoundaryArchitectureTest` 등 | | 이름 규칙 | `src/application-core/CLAUDE.md` 「Naming convention」 | `NamingConventionTest` | | `@Configuration` 분해 기준(대략 `@Bean` 8개, 서로 무관한 포트 묶음 둘이면 나눔) | `src/app-bootstrap/CLAUDE.md` 「Decomposition threshold」 | 리뷰 | | 설정: typed settings, prefix 하나, `StrictSettingsBinder`, compact constructor 검증 | `AGENTS.md` 「설정과 런타임」, capability 기준 4 | settings 바인딩 테스트 | | 오류 모델·HTTP 계약 | `docs/manual/06-errors.md`, `docs/web/http-contract.md` | 계약 테스트 | | 멱등성·결과 불명 | `docs/manual/05-idempotency.md`, `docs/adr/ADR-JPA-003-completion-unknown.md` | 공유 계약 `IdempotencyStoreContract` | | 권한 | `docs/manual/07-authorization.md` | ArchUnit, 기동 rule | | outbox·이벤트 | `docs/manual/09-outbox-events.md` | 공유 계약, ArchUnit | 리뷰가 이 표의 규칙 위반을 찾으면 정본의 문장을 근거로 적는다. 정본이 틀렸다고 보이면 정본을 고치는 변경을 따로 낸다. ## 2. 반복 결함 패턴 → 기준 각 패턴은 **규칙 · 왜(지난 결함) · 리뷰에서 볼 것 · 막는 장치** 순서다. 부록의 카탈로그와 번호가 다르다: 부록은 테스트·게이트·작업 과정 패턴까지 모은 목록이고(A1~A16), 이 장은 그중 코드 구조에 해당하는 것만 다룬다. 테스트 패턴은 05장, 게이트 패턴은 07장에 있다. ### P1. 갈라진 복사본 (부록 A1) - **규칙**: 규칙·표·정규식·상수·이미지 참조는 한 곳에 둔다. 두 곳이 꼭 필요하면 하나를 정본으로 명시하고, 다른 하나가 정본과 같은지 보는 대조 테스트를 둔다. 정본 없이 복사하지 않는다. - **왜**: `TenantId` 3벌의 문법이 셋 다 달랐다(`1101/01-03`). SQLState 분류표 2벌이 이미 갈라졌다(`1101/04-06`). MinIO 이미지 참조가 네 곳에 있었다(`1101/05-09`). 이벤트 ID 문법이 다섯 곳에 있었다(`1101/01-07`). GraphQL client가 page 규칙 복사본을 가졌다(`1103/RR-01-14`). gRPC 빌드가 마이그레이션 버전 정규식을 한 벌 더 가졌다 (`1103` README 16절 r9-c). - **볼 것**: 새로 쓴 상수·정규식·표가 이미 어딘가에 있는지 grep. 같은 판정을 두 클래스가 하는지. - **장치**: 정본을 가져다 쓰기(예: 버전 판정 정본 `VersionedMigrationFiles`를 grpc 빌드가 Sync 태스크로 가져옴 — `1103` README 16절 r9-c), 대조 테스트(예: `TemplatePackageOwnershipDocumentTest`, messaging Flyway 정책 사본의 대조 테스트 — `1103` README 17절 r10-03). 테스트 lane의 컨테이너 이미지는 `src/config/testing/container-images.properties` 한 곳이다. MinIO qualification 이미지만 objectstorage leaf가 따로 소유한다(그 파일 머리말). ### P2. 문서와 코드 불일치 (부록 A2) - **규칙**: 동작을 바꾸는 변경은 그 동작을 설명하는 모든 문서를 같은 변경에서 고친다. 대상: 계약(`docs/web/http-contract.md`), 레지스트리(`docs/registries/`), runbook, 매뉴얼, leaf README·`CLAUDE.md`, Javadoc, 업그레이드 안내. 고친 뒤 옛 표현을 grep으로 찾아 남은 곳을 없앤다. - **왜**: runbook·`error-codes.yaml`이 없는 헤더와 polling을 말했다(`1101/02-01`). 수정 뒤 매뉴얼 세 곳이 코드와 반대가 됐다(`1103/RR-01-03`). 같은 응답의 클라이언트 안내가 계약 표·매뉴얼·runbook에서 서로 달랐다(`1103/RR5-01-01`). 고친 설명이 가이드 밖 세 곳에 옛 문장으로 남았다(`1103/RR6-03-05`). 실패 메시지와 문서가 이유를 사실과 반대로 적었다 (`1103/RR6-04-05`). - **볼 것**: diff가 바꾼 동작의 키워드(오류 코드, 설정 키, 상태 이름)로 `docs/`와 `src/**/README.md`·`CLAUDE.md`를 grep. - **장치**: 일부만 있다. runbook 숫자와 상수를 비교하는 document-contract lane(`1103` README 10절 r5-c RR-02-14), runbook SQL을 실 PG에서 그대로 실행하는 lane(`1103` README 6절 r4-e). 나머지는 리뷰가 본다 — 이 repo는 문서 전체를 파싱하는 검사를 일부러 두지 않는다(`docs/testing/TESTING_STRATEGY.md` 8절). ### P3. 선언과 실행이 떨어져 있다 (부록 A3) - **규칙**: 선언(설정 키, 레지스트리 행, 지표 이름, 옵션)마다 그것을 실행하는 코드가 있어야 한다. 실행 코드가 없으면 선언을 지운다. "동작하지 않는 옵션은 설정 키 자체를 두지 않는다"(capability 기준 3). - **왜**: 바인딩되지만 동작하지 않는 HTTP client 설정 키(`1101/05-15`), 검증만 통과하고 처리 코드가 없는 `operation-ledger-enabled`(`1101/03-11`), 레지스트리는 `required: true`인데 코드는 빈 값을 허용한 JWT audience (`1101/02-03`), 어떤 코드도 내보내지 않는 `docs/registries/metrics.yaml`의 `redis.capability.*` 6개(`1103` README 6.1절). 기동 rule을 non-static `@Bean`으로 쓰거나 필드 주입으로 만들면 선언한 설정 bean이 조용히 바인딩되지 않았다 (`1103/RR-06-01`, `1103/RR2-04-03`). - **볼 것**: 새 설정 키의 읽는 곳, 새 레지스트리 행의 내보내는 곳, 문서가 말한 옵션의 분기. - **장치**: `StrictSettingsBinder`(모르는 키·오타 거부), `verifyEnvKeys`, 레지스트리와 코드를 대조하는 테스트(`ErrorCodeRegistryMappingTest`, `HeaderRegistryRuntimeAlignmentTest` 등). ### P4. 결과 불명을 "확실함"으로 기록한다 (부록 A4) - **규칙**: 외부 효과(DB 커밋, 알림 발송, broker 전송)의 결과를 모르면 "결과 불명"으로 기록·응답한다. 결과 불명을 자동으로 다시 실행하지 않는다. 반대로 확실히 실패한 것을 결과 불명으로 부풀리지도 않는다. - **왜**: 결과 불명 처리를 정한 문서(ADR-JPA-003, 알림 evidence 모델)가 있었지만 경계마다 다시 구현되며 갈라졌다 (`1101` README 4절 원인 1). 알림 attempt를 "시작 안 함(확정)"으로 저장한 채 provider를 불렀다(`1101/05-01`). 커밋 중 끊김을 재시도 가능으로 답했다(`1101/04-01`). 재시도 가능한 거부를 확정 거부로 바꿔 DEAD로 보냈다(`1101/06-01`). 반대 방향: Redis 연결 실패를 결과 불명으로 보고했다(`1101/05-17`). 멱등성 complete 단계의 저장소 실패를 "실행 전 거부"로 적었다(`1103/RR-02-03`). - **볼 것**: 외부 호출 전후의 상태 기록 순서, 예외를 retryable·terminal·unknown으로 나누는 분기, 응답 코드의 `retryable`. - **장치**: 멱등성 공유 계약(`IdempotencyStoreContract` — PostgreSQL·Redis store가 같은 판정, `1103` README 15절 결정 ①), `PersistenceExceptionTranslator`의 커밋 단계 분류. ### P5. 중복·경쟁을 코드 순서로 막는다 (부록 A5) - **규칙**: 유일성은 DB 유일 제약이 막고, adapter는 그 제약 위반만 기능 예외로 바꾼다. 여러 인스턴스가 집는 작업은 트랜잭션 안의 claim + lease로 소유권을 정한다. "조회 후 insert", "찾고 없으면 넣기"는 쓰지 않는다. - **왜**: 포스터 제목 중복 규칙이 동시 요청에서 깨졌다(`1101/09-02`). upsert가 찾고 넣기였다(`1101/04-08`). `SKIP LOCKED` claim이 트랜잭션 없이 돌아 잠금이 바로 풀렸다(`1101/04-02`). ledger claim에 lease가 없었다(`1101/03-10`). counter 첫 생성이 겹치면 두 번째 쓰기가 409였다(`1103/RR-03-01`). - **볼 것**: 존재 확인 뒤 쓰기, 트랜잭션 밖 잠금, 프로세스 메모리에 둔 소유권(`1101/04-13`). - **정본·장치**: `docs/manual/04-persistence.md`, 가이드 31절 "비용이 작은 개선부터 비교". `CallerTransaction` (store는 호출자 트랜잭션을 요구), 동시 요청 통합 테스트(`CreatePosterConcurrencyIntegrationTest`). ### P6. 이름만 보는 허용·거부 (부록 A9) - **규칙**: 위험한 기능(데모 계정, 비밀 검사 면제 등)은 거부 목록이 아니라 **허용 목록**으로 연다. 허용 목록의 각 값은 실제로 그 값으로 동작해야 한다. - **왜**: 데모 계정 거부가 정확히 `prod`에서만이라 `production`·`staging`·프로필 없음에서 열렸다(`1103/RR-07-02` → `1103` README 4절 결정: `local`·`test`·`demo` 허용 목록). 그 허용 목록의 `test`·`demo`로는 sample이 뜨지 않았다 (`1103/RR2-04-02`). 비밀이 아닌 값까지 `fixture-` 검사에 막혔다(`1103/RR2-04-01` → 비밀로 분류된 키만). - **볼 것**: 프로필·환경 이름 문자열 비교, 허용 목록의 각 값으로 실제 기동하는 테스트가 있는지. - **장치**: `SampleDemoProfilesStartupSystemTest`(허용 프로필마다 기동). ### P7. 글로만 있는 규칙 (부록 A10) - **규칙**: "하지 마라"는 주석·Javadoc·문서는 규칙을 지키지 못한다(통제 M0~M1, 02장 5절). 위반하면 데이터·권한이 깨지는 규칙은 기동 실패·ArchUnit·타입으로 막는다. - **왜**: `@SystemInvoked` 유스케이스를 bean으로 등록하지 말라는 것이 주석뿐이었다. 탐침 테스트로 bean 기동이 됐다(`1103/RR-01-02` = `RR-07-01` → 기동 실패 + ArchUnit). JPA 양방향 연관관계 금지를 막는 장치가 없었고, 문서와 fixture는 오히려 양방향을 가르쳤다(`1101/04-03` → `JpaArchitectureRules`). capability 완료 기준 5(fake와 실제 adapter가 같은 계약)가 영역 전체에서 지켜지지 않았다(`1101/05-16`). - **볼 것**: Javadoc·문서의 "must not", "하지 않는다", "금지", "반드시"가 붙은 문장마다 막는 장치가 있는지. - **장치**: 이유를 요구하는 표시(`@SystemCaller(reason)` — `1103` README 10절 r5-b), 기동 rule, ArchUnit. ### P8. 로그로 새는 입력값·원인 (부록 A8) - **규칙**: 클라이언트 탓 실패(입력 오류)는 WARN 한 줄로 남기고 입력값을 싣지 않는다. 서버 실패는 전송마다 같은 실패 로그 줄(`ServerFailureLog`)을 쓰고, 원인 체인의 SQL·입력값을 로그 메시지에 그대로 붙이지 않는다. 클라이언트가 보낸 식별자는 규칙 밖이면 서버가 새 값으로 바꾼다. - **왜**: gRPC 서비스가 던진 raw status 설명(입력값 포함)이 로그에 남았다(`1103/RR6-01-05`). STOMP가 `IllegalArgumentException`을 ERROR로, 메시지(입력값)까지 남겼다(`1103/RR6-01-06`). STOMP가 persistence 실패의 SQL 원인까지 로그에 썼다(`1103` README 16절 r9-a). `X-Correlation-Id` 규칙이 요청 ID와 달라 로그 주입이 열렸다(`1101/02-11` → 15절 결정 "규칙 밖이면 서버가 교체"). - **볼 것**: 새 `log.warn`/`log.error`의 인자, 예외 메시지에 사용자 입력을 넣는 곳, 전송별 예외 처리기. - **정본·장치**: `src/shared-contract/src/main/java/dev/caskeleton/shared/error/ServerFailureLog.java`(`refusedArgument` 포함), 비밀 하드코딩 금지(`AGENTS.md` 「설정과 런타임」), 비밀 분류 `docs/registries/secrets-classification.yaml`. ### P9. 샘플·fixture가 운영 경로와 다르게 조립된다 (부록 A11) - **규칙**: 샘플은 운영과 같은 자동 설정과 런타임 기본값을 쓴다. 무엇을 빼면 이유와 대체 장치를 같은 곳에 적는다. "새 기능의 모양"이라고 둔 fixture는 실제로 기동되는 모양이어야 한다. - **왜**: 샘플이 보안 자동 설정을 통째로 빼서 `@RequiresPermission`이 동작하지 않았다(`1101/07-03`). 샘플의 런타임 기본값이 기본 조합과 달랐다(`1101/09-08`). onboarding fixture의 유스케이스가 기동에 실패하는 모양이었다(`1101/01-02`). `Dockerfile.sample`이 빌드되지 않았다(`1101/07-04`). - **볼 것**: 샘플 `@SpringBootApplication(exclude=…)`, 샘플 `application.yml`과 기본 조합의 차이. - **장치**: sample 전체 기동 lane(`:sample-portfolio:systemTest`, `mainCheck`), sample 실서버 계약(`sampleWebContractCheck`). ### P10. 타이밍에 기댄 약속 (부록 A14) - **규칙**: "스레드를 남기지 않는다", "시간 안에 끊는다" 같은 약속은 join·종료 대기·전용 스레드로 보장한다. 공용 풀이나 "보통은 끝나 있다"에 기대지 않는다. - **왜**: `ClientRuntimeRegistry.close()`가 종료 신호만 기다려, 부하가 높으면 돌아온 뒤에도 스레드가 살아 있었다 (`1103` README 16.1절). JDK read-idle watchdog이 공용 `ForkJoinPool`에서 돌아, 공용 풀이 막히면 300ms 설정이 2,699ms가 됐다(`1103/RR3-03-01`). 전체 시간 예산이 진행 중 attempt를 끊지 못했다(`1101/05-06`). - **볼 것**: `awaitTermination` 뒤 스레드 생존 확인, 시간 제한을 거는 실행기가 공용인지. - **장치**: 부하·자원 한계 lane(`httpClientPerformanceTest` 등, `performanceCheck`). ### P11. 상한 없는 자원 (부록 A16) - **규칙**: 연결 수·구독 수·동시 호출·본문 크기·트랜잭션 시간·큐 길이에는 상한이 있고, 그 값이 코드나 설정에 드러난다. 상한을 넘으면 정해진 응답(예: WebSocket 1013, gRPC 즉시 닫기)을 준다. - **왜**: WebSocket 연결·구독·연결 수명 상한이 없었다(`1101/03-06`). gRPC 서버가 io.grpc 기본값으로 떴다(`1101/03-09`). 기본 트랜잭션에 시간 제한이 없었다(`1101/04-10`). JSON 아닌 본문 상한이 없었다(`1101/02-09`). - **정한 값**: `1101` README 15절(gRPC 스레드 32·큐 256·동시 100·deadline 10s, WebSocket `max-connections` 1000, 트랜잭션 30초). JSON 아닌 본문 상한은 엔드포인트가 직접 둔다(같은 절). ## 3. 코드에 결정을 드러내는 법 결함을 고칠 때 "왜 이 모양인가"가 코드 가까이에 남아야 다음 리뷰가 같은 질문을 다시 하지 않는다(가이드 39.2). | 경우 | 이 repo에서 남기는 곳 | 예 | | --- | --- | --- | | 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc | notification `TenantId`의 차이와 이유(`1101` README 15절 01-03) | | 정적 분석 제외 | 제외 항목 옆 이유 | `src/config/spotbugs/exclude-test.xml`(`1103` README 14절), 메서드 하나로 좁힌 FindSecBugs 제외(`1103` README 6.1절) | | 규칙의 예외 경로 | 이유를 요구하는 표시 | `@SystemCaller(reason)` | | 복사본을 남긴 이유 | 가까운 `CLAUDE.md` | `src/messaging/CLAUDE.md` 「공용 다이제스트 헬퍼를 복사해 두는 이유」 | | 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` | `docs/adr/ADR-JPA-003-completion-unknown.md` | ## 지금 이해하면 되는 것 - 계층 규칙은 `AGENTS.md`와 leaf `CLAUDE.md`가 정본이다. 이 장은 반복해서 틀린 곳(P1~P11)을 기준으로 바꾼 것이다. - 고칠 때마다 "같은 원인의 다른 자리"와 "그 동작을 설명하는 문서"를 함께 찾는다(P1·P2·P4). - "하지 마라"는 주석이 아니라 장치로 막는다(P7).