문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
132 lines
12 KiB
Markdown
132 lines
12 KiB
Markdown
# 결함 패턴
|
|
|
|
이 repo의 리뷰에서 반복해서 나온 결함을 **모양**으로 묶은 목록이다. 리뷰를 시작하기 전에 훑어보고, 고칠 때는 「막는 기준」을 따른다. 리뷰 README의 「반복되는 원인」에 이 번호(A1~)를 붙인다. 패턴마다 근거가 된 지난 발견은 [evidence.md](../evidence.md) 「결함 패턴의 근거」에 있다.
|
|
|
|
계층·경계 규칙 자체의 정본은 `AGENTS.md`(HARD-STOP, 의존 방향)와 family·leaf의 책임·금지 절을 담은 가장 가까운 `src/**/AGENTS.md`다. 이 문서는 그 규칙을 다시 쓰지 않고, 고치거나 리뷰할 때 반복해서 틀린 곳만 적는다.
|
|
|
|
## 패턴
|
|
|
|
### A1. 갈라진 복사본
|
|
|
|
- **모양**: 같은 규칙·표·정규식·상수·이미지 참조가 여러 곳에 있고 이미 다르다.
|
|
- **막는 기준**: 규칙·표·정규식·상수·이미지 참조는 한 곳에 둔다. 두 곳이 꼭 필요하면 하나를 정본으로 명시하고, 다른 하나가 정본과 같은지 보는 대조 테스트를 둔다.
|
|
- **볼 것**: 새로 쓴 상수·정규식·표가 이미 어딘가에 있는지 grep. 같은 판정을 두 클래스가 하는지.
|
|
- **장치**: 정본을 가져다 쓰기(예: 마이그레이션 버전 판정 정본 `VersionedMigrationFiles`), 대조 테스트(`TemplatePackageOwnershipDocumentTest`). 테스트 lane의 컨테이너 이미지는 `gradle/container-images.properties` 한 곳이다(MinIO qualification 이미지만 objectstorage leaf 소유).
|
|
|
|
### A2. 문서와 코드 불일치
|
|
|
|
- **모양**: 계약·runbook·매뉴얼·README·Javadoc·실패 메시지가 현재 동작과 다르다.
|
|
- **막는 기준**: 동작을 바꾸는 변경은 그 동작을 설명하는 모든 문서를 같은 변경에서 고친다. 대상: `docs/web/http-contract.md`, `docs/registries/`, runbook, 매뉴얼, leaf README·`CLAUDE.md`, Javadoc, 업그레이드 안내. 고친 뒤 옛 표현을 grep으로 찾아 남은 곳을 없앤다.
|
|
- **볼 것**: diff가 바꾼 동작의 키워드(오류 코드, 설정 키, 상태 이름)로 `docs/`, `src/**/README.md`, `src/**/CLAUDE.md`를 grep.
|
|
- **장치**: 일부만 있다. runbook 숫자와 상수를 비교하는 document-contract lane, runbook SQL을 실 PostgreSQL에서 그대로 실행하는 lane. 나머지는 리뷰가 본다. 이 repo는 문서 전체를 파싱하는 검사를 일부러 두지 않는다(`docs/testing/TESTING_STRATEGY.md` 8절).
|
|
|
|
### A3. 선언과 실행이 떨어져 있다
|
|
|
|
- **모양**: 설정 키는 바인딩되지만 동작하지 않는다. 선언한 설정 bean이 조용히 바인딩되지 않는다. 레지스트리 행·지표를 아무 코드도 쓰지 않는다.
|
|
- **막는 기준**: 선언(설정 키, 레지스트리 행, 지표 이름, 옵션)마다 그것을 실행하는 코드가 있어야 한다. 실행 코드가 없으면 선언을 지운다. 동작하지 않는 옵션은 설정 키 자체를 두지 않는다(`AGENTS.md` capability 기준 3).
|
|
- **볼 것**: 새 설정 키를 읽는 곳, 새 레지스트리 행을 내보내는 곳, 문서가 말한 옵션의 분기. 기동 rule이 `static @Bean`이고 필드 주입이 없는지.
|
|
- **장치**: `StrictSettingsBinder`(모르는 키·오타 거부), `verifyEnvKeys`, 레지스트리와 코드를 대조하는 테스트(`ErrorCodeRegistryMappingTest`, `HeaderRegistryRuntimeAlignmentTest` 등).
|
|
|
|
### A4. 결과 불명을 "확실함"으로 기록한다
|
|
|
|
- **모양**: 외부 효과의 결과를 모르는데 "시작 안 함", "재시도 가능", "확정 거부"로 기록한다. 또는 반대로 확실한 실패를 결과 불명으로 부풀린다.
|
|
- **막는 기준**: 외부 효과(DB 커밋, 알림 발송, broker 전송)의 결과를 모르면 "결과 불명"으로 기록·응답한다. 결과 불명을 자동으로 다시 실행하지 않는다. 확실히 실패한 것을 결과 불명으로 부풀리지 않는다.
|
|
- **볼 것**: 외부 호출 전후의 상태 기록 순서, 예외를 retryable·terminal·unknown으로 나누는 분기, 응답의 `retryable`.
|
|
- **장치**: 멱등성 공유 계약(`IdempotencyStoreContract` — PostgreSQL·Redis store가 같은 판정), `PersistenceExceptionTranslator`의 커밋 단계 분류, `docs/adr/ADR-JPA-003-completion-unknown.md`.
|
|
|
|
### A5. 중복·경쟁을 코드 순서로 막는다
|
|
|
|
- **모양**: 조회 후 insert, 찾고 없으면 넣기, 트랜잭션 없는 `SKIP LOCKED`, lease 없는 claim, 프로세스 메모리에 둔 소유권.
|
|
- **막는 기준**: 유일성은 DB 유일 제약이 막고, adapter는 그 제약 위반만 기능 예외로 바꾼다. 여러 인스턴스가 집는 작업은 트랜잭션 안의 claim + lease로 소유권을 정한다.
|
|
- **볼 것**: 존재 확인 뒤 쓰기, 트랜잭션 밖 잠금, 메모리 안 소유권.
|
|
- **장치**: `CallerTransaction`(store는 호출자 트랜잭션을 요구), 동시 요청 통합 테스트(실 DB lane에서 동시 요청 N개 → 행 1개). 정본: `docs/manual/04-persistence.md`.
|
|
|
|
### A6. 주장하는 것을 보지 않는 테스트
|
|
|
|
- **모양**: 이름이 말한 성질을 단언하지 않는다. 지키려는 코드를 지워도 통과한다. 시간 제한 대기의 결과를 버린다. 계약 케이스를 skip한다.
|
|
- **막는 기준**: [review-criteria.md](review-criteria.md) 7절 점검표. 변이로 확인한다. skip은 0이거나 설계 이유를 적는다.
|
|
- **장치**: 포트당 fake와 공유 계약 상속(`.claude/rules/java-tests.md` 규칙 6), `rejectSkipped`.
|
|
|
|
### A7. 거짓 통과 게이트
|
|
|
|
- **모양**: 어떤 단계도 돌리지 않는 lane·검사, 캐시가 옛 결과로 통과, 실패를 막지 못하는 workflow 명령을 실행으로 셈, 시간 단언을 끈 채 돈 performance lane.
|
|
- **막는 기준**: [gates.md](gates.md) 6절. 게이트 장치를 바꾸면 일부러 망가뜨린 입력으로 실패하는 것을 본다.
|
|
- **장치**: `verifyStrictLaneStages --dry-run`, lane 정책 값의 캐시 입력 선언, `testQualityCheck`, 성능 lane 단언 강제(strict lane convention이 `performance.assertions.enabled=true`를 넣고 다른 값·skip은 실패). 캐시에서 가져온 결과는 현재 통과의 증거가 아니다(필요하면 `--rerun`).
|
|
|
|
### A8. 로그로 새는 입력값·원인
|
|
|
|
- **모양**: 클라이언트 입력이나 SQL 원인이 로그 메시지에 실린다. 서버 실패를 남기지 않거나 클라이언트 실패를 ERROR로 남긴다.
|
|
- **막는 기준**: 클라이언트 탓 실패(입력 오류)는 WARN 한 줄로 남기고 입력값을 싣지 않는다. 서버 실패는 전송마다 같은 실패 로그 줄(`ServerFailureLog`)을 쓰고, 원인 체인의 SQL·입력값을 메시지에 붙이지 않는다. 클라이언트가 보낸 식별자가 규칙 밖이면 서버가 새 값으로 바꾼다.
|
|
- **볼 것**: 새 `log.warn`·`log.error`의 인자, 예외 메시지에 사용자 입력을 넣는 곳, 전송별 예외 처리기.
|
|
- **장치**: `src/shared-contract/src/main/java/dev/caskeleton/shared/error/ServerFailureLog.java`(`refusedArgument` 포함), 비밀 분류 `docs/registries/secrets-classification.yaml`.
|
|
|
|
### A9. 이름만 보는 허용·거부
|
|
|
|
- **모양**: 프로필·환경 이름 하나가 다르면 위험한 기능이 열린다. 허용한 값으로는 실제로 동작하지 않는다.
|
|
- **막는 기준**: 위험한 기능(데모 계정, 비밀 검사 면제 등)은 거부 목록이 아니라 허용 목록으로 연다. 허용 목록의 값마다 실제로 그 값으로 동작해야 한다.
|
|
- **볼 것**: 프로필·환경 이름 문자열 비교, 허용 값마다 실제로 기동하는 테스트가 있는지.
|
|
- **장치**: `SampleDemoProfilesStartupSystemTest`(허용 프로필마다 기동).
|
|
|
|
### A10. 글로만 있는 규칙
|
|
|
|
- **모양**: "하지 마라", "반드시"가 주석·Javadoc·문서에만 있고 막는 장치가 없다(통제 M0~M1).
|
|
- **막는 기준**: 위반하면 데이터·권한이 깨지는 규칙은 기동 실패, ArchUnit, 타입으로 막는다.
|
|
- **볼 것**: "must not", "하지 않는다", "금지", "반드시"가 붙은 문장마다 막는 장치가 있는지.
|
|
- **장치**: 이유를 요구하는 표시(`@SystemCaller(reason)`), 기동 rule, ArchUnit.
|
|
|
|
### A11. 샘플·fixture가 운영과 다르게 조립된다
|
|
|
|
- **모양**: 따로 조립한 앱(fixture·데모)이 자동 설정을 빼거나 런타임 기본값이 다르다. "따라 할 모양"으로 둔 fixture가 기동하지 않는다.
|
|
- **막는 기준**: 따로 조립한 앱은 운영과 같은 자동 설정과 런타임 기본값을 쓴다. 무엇을 빼면 이유와 대체 장치를 같은 곳에 적는다. 새 기능의 모양으로 둔 fixture는 실제로 기동되는 모양이어야 한다.
|
|
- **볼 것**: 그 앱의 `@SpringBootApplication(exclude=…)`, 그 앱의 `application.yml`과 기본 조합의 차이.
|
|
- **장치**: 기본 조합 전체 기동 lane(app-bootstrap `systemTest`, PR `check`). 이 모양이 처음 나온 샘플 모듈은 2026-11-07에 지웠다.
|
|
|
|
### A12. 수정이 새 결함을 만든다
|
|
|
|
- **모양**: 고친 커밋에서 새 Important·회귀가 나온다. 두 수정이 한 트리에서 처음 만나 새 결함이 생긴다.
|
|
- **막는 기준**: 수정 보고에 「새로 가정하는 것」을 쓰고 확인 리뷰가 그 칸부터 본다. 수정 묶음 크기 상한을 지킨다([improve.md](../improve.md) 4.4절). 합친 트리를 라운드 끝 게이트로 따로 검증한다.
|
|
- **장치**: 확인 리뷰(수정 diff만), [gates.md](gates.md) 3절.
|
|
|
|
### A13. 합치는 과정의 누락
|
|
|
|
- **모양**: 색인을 손으로 옮기다 발견이 빠진다. 손으로 푼 충돌이 한쪽 변경을 지운다.
|
|
- **막는 기준**: 색인은 영역 문서에서 기계로 대조한다. 두 묶음이 같은 파일을 건드리지 않게 나눈다([delegate.md](../delegate.md) 「나누는 법」).
|
|
- **장치**: `python3 scripts/check-review-index.py docs/reviews/<폴더>`.
|
|
|
|
### A14. 타이밍에 기댄 약속
|
|
|
|
- **모양**: "스레드를 남기지 않는다", "시간 안에 끊는다"가 공용 풀이나 "보통은 끝나 있다"에 기댄다.
|
|
- **막는 기준**: 그런 약속은 join·종료 대기·전용 스레드로 보장한다.
|
|
- **볼 것**: `awaitTermination` 뒤 스레드 생존 확인, 시간 제한을 거는 실행기가 공용인지.
|
|
- **장치**: 부하·자원 한계 lane(`httpClientPerformanceTest` 등, `performanceCheck`).
|
|
|
|
### A15. 사라지는 외부 공급원
|
|
|
|
- **모양**: 고정한 컨테이너 이미지를 더는 받을 수 없어 다른 lane 결과까지 가린다.
|
|
- **막는 기준**: 테스트 이미지는 한 곳에 digest로 고정하고, pull 실패는 따로 구분되는 메시지로 실패하게 한다.
|
|
- **장치**: `gradle/container-images.properties`, `PinnedImageUnavailableException`, main 단계 `--continue`.
|
|
|
|
### A16. 상한 없는 자원
|
|
|
|
- **모양**: 연결·구독·동시 호출·본문 크기·트랜잭션 시간·큐 길이에 상한이 없거나 코드에 드러나지 않는다.
|
|
- **막는 기준**: 상한이 있고 그 값이 코드나 설정에 드러난다. 상한을 넘으면 정해진 응답(예: WebSocket 1013, gRPC 즉시 닫기)을 준다.
|
|
- **정한 값**: [decisions.md](decisions.md) 「전송 상한 기본값」, JPA 기본 트랜잭션 제한 30초. JSON 아닌 본문 상한은 엔드포인트가 직접 둔다.
|
|
|
|
## 코드에 결정을 드러내는 곳
|
|
|
|
고칠 때 "왜 이 모양인가"를 코드 가까이에 남긴다. 다음 리뷰가 같은 질문을 다시 하지 않게 하려는 것이다.
|
|
|
|
| 경우 | 남기는 곳 |
|
|
| --- | --- |
|
|
| 규칙을 일부러 다르게 둔 타입 | 그 타입의 Javadoc |
|
|
| 정적 분석 제외 | 제외 항목 옆 이유(`config/spotbugs/exclude-test.xml` 등) |
|
|
| 규칙의 예외 경로 | 이유를 요구하는 표시(`@SystemCaller(reason)`) |
|
|
| 복사본을 남긴 이유 | 가까운 `AGENTS.md`. 복사본을 둔 leaf의 `build.gradle`이나 그 폴더의 `AGENTS.md`에 적는다 |
|
|
| 되돌리기 비싼 선택 | `docs/adr/ADR-<영역>-<번호>-<제목>.md` |
|
|
|
|
## 패턴을 더하는 법
|
|
|
|
- 새 라운드에서 **두 건 이상**이 같은 모양이면 행을 더한다. 한 건이면 그 라운드 README에만 둔다.
|
|
- 모양은 원인 추측이 아니라 코드에서 실제로 본 모양을 쓴다. 근거 ID는 [evidence.md](../evidence.md)에 쓴다.
|
|
- 번호는 다시 매기지 않는다. 지운 패턴은 행을 남기고 "합침 → A<n>"으로 적는다.
|