Files
clean-architecture-backend-…/docs/improvement/04-code-structure.md
T
DongHyeonka 3b66358e52 docs(improvement): 리뷰·개선 작업 매뉴얼을 만든다
문제: 이 repo를 리뷰하거나 결함 수정·리팩터링·성능 최적화·구조 변경을 할 때
기준으로 삼을 문서가 없다. docs/manual/은 새 기능을 만드는 순서이고, 리뷰
기준으로 써 온 공용 가이드는 프론트 repo에만 있으며 AGENTS.md·CLAUDE.md가
가리키지 않는다. 2026-11-01부터 쌓인 소유자 결정과 반복 결함 패턴은 리뷰
문서 여러 곳에 흩어져 있다.

방법: docs/improvement/에 README, 01~09장, 결함 패턴 부록을 둔다. 규칙은
다시 쓰지 않고 정본(AGENTS.md, modules.json, application-core/CLAUDE.md,
TESTING_STRATEGY.md, src/build.gradle, 리뷰 문서의 결정 절)을 가리킨다.
정본이 없는 것 — 작업 종류별 절차, 이 repo의 28개 관점 점검 항목과 결함
정의, 반복 결함 패턴, 성능 측정 조건, 무거운 실행 위치, 결정 색인, 세션
분업과 리뷰 반복 종료 조건 — 만 매뉴얼이 정본이 된다. AGENTS.md에
「리뷰·개선 작업 기준」 절, CLAUDE.md에 그 요약을 두고 docs/README.md와
docs/manual/README.md에서 가리킨다. 프론트 매뉴얼과 같은 장 번호를 쓴다.
버린 대안: docs/reviews/ 안에 두기(결과 보관소와 기준서가 섞인다), 공용
가이드 복사(갈라진 복사본이 된다), 소유자 환경 규칙을 AGENTS.md에 직접
쓰기(파생 프로젝트가 정책 문서를 고쳐야 한다).

위험·한계: 매뉴얼을 정본과 대조하는 자동 검사는 없다(문서 파서를 두지
않는 repo 방침). 08장 결정 표는 색인이고 원문과 다르면 원문이 맞다. 저장소
밖 문서(공용 가이드, 커밋 규칙)는 lychee가 따라갈 수 없어 링크 대신 코드
표기로 썼다. 근거를 찾지 못한 것 하나(측정 스크립트를 scripts/perf/로
넣기)는 [제안]으로 표시했다.

검증: 인용한 저장소 경로·리뷰 ID·클래스 이름·태스크 이름·상대 링크·절
번호를 스크립트로 전수 대조했다(로컬, 읽기만). 남은 불일치는 저장소 밖
가이드 경로, 자리표시자, 제안 경로, 원래 있던 문장뿐이다. CLAUDE.md는
DeveloperExperienceContractTest가 요구하는 architectureTest 명령을 그대로
둔다. 문서 대조 lane은 이 커밋을 push한 뒤 desktop에서 돌린다.
2026-11-05 21:59:44 +09:00

16 KiB

04. 코드 구조 기준

핵심

계층·경계 규칙의 정본은 AGENTS.md다. 이 장은 그 규칙을 다시 쓰지 않는다. 대신 지난 리뷰에서 반복해 나온 결함을 코드 구조 기준으로 바꿔 적는다. 같은 결함이 영역을 바꿔 가며 다시 나왔기 때문이다(1101 README 4절 "반복되는 원인").

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).