ci(repo)!: 최상위 폴더 허용 목록 검사를 더한다

문제: src/ 아래 계층이 아닌 폴더가 2026-07-24의 둘에서 두 달 사이
여덟으로 늘었고, 루트에는 compose 파일과 infra/가 쌓였다. 어느 커밋도
최상위 모양을 묻지 않았고 리뷰 기준에도 그 칸이 없었다.

고른 방법(소유자 결정 2026-11-07, 설계 10.3절): scripts/check-repo-layout.py
- 저장소 루트와 src/ 바로 아래의 추적 항목이 허용 목록 안에 있는가
- registry source_path가 허용된 src/ 폴더 아래인가
- (경고) compose·스크립트·compose 보조 파일을 아무 추적 파일도 가리키지
  않는가
를 본다. ci-quality-gates.yml quality-gates job에 한 단계로 붙인다.
Gradle 밖 스크립트다(문서·배치를 파싱하는 Gradle 검사를 두지 않는 정책).
버린 대안: registry에서 허용 폴더를 파생하기. 새 vendored 폴더를 registry
에 등록하는 것만으로 통과해, 막으려는 drift를 막지 못한다.

위험·한계: 참조 0 경고는 경로를 변수로 조립하는 workflow를 따라가지
못해 경고로만 둔다. 리뷰 기준·playbook 문장은 매뉴얼 보강 작업이 넣는다.

검증:
- 노트북·desktop: python3 scripts/check-repo-layout.py rc=0, 경고 0
- 일부러 infra/, src/messaging/, 고아 compose/orphan.sh를 둔 임시 저장소:
  rc=1, 실패 3건과 경고 1건
- desktop(트리 c7cacf54): :app-bootstrap:repositoryContractTest
  :app-bootstrap:documentContractTest rc=0, :verifyStrictLaneStages --dry-run rc=0
- check-work-docs.py rc=0
- 업그레이드 안내 B-50~B-52의 근거 칸을 커밋 해시로 채운다

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 10.3
BREAKING CHANGE: 저장소 루트나 src/에 허용 목록 밖의 최상위 폴더를 둔 파생 서비스는 PR 게이트가 실패한다. docs/upgrade/2026-11-maturity-review.md B-53.
This commit is contained in:
DongHyeonka
2026-11-07 13:09:05 +09:00
parent 1ed683ffdb
commit e13a29024f
6 changed files with 223 additions and 5 deletions
+4 -3
View File
@@ -132,9 +132,10 @@
| # | 무엇이 바뀌었나 | 파생 서비스 증상 | 할 일 | 근거 |
|---|---|---|---|---|
| B-49 | 샘플 모듈 삭제: `src/sample-portfolio`, `src/Dockerfile.sample`, registry `sample-portfolio` 행, 루트 `build.gradle`의 샘플 태스크·단계(`sampleWebContractCheck`, `:sample-portfolio:*` 의존, strict lane 단계 `:sample-portfolio:check`), `ci-quality-gates.yml`의 `sample-portfolio` job, `SampleRuntimeDefaultsContractTest`, spotbugs 제외의 샘플 클래스. 샘플에만 있던 검사(OpenAPI 스냅숏 `openapiCheckSnapshot`, Date 헤더, 가상 스레드 MDC 전파)도 함께 없어졌다 | 샘플을 고쳐 쓰던 서비스: 병합 때 "수정 대 삭제" 충돌. 샘플을 이미 지운 서비스: 충돌 없음 | 샘플을 이미 지웠으면 할 일 없음. 고쳐 쓰고 있으면 자기 leaf로 옮기고 registry 행·빌드 줄을 자기 것으로 둔다. 위 검사가 필요하면 자기 기능 leaf에 둔다 | `ab5982e9` |
| B-50 | `infra/`에서 15개 삭제. 쓰는 곳이 없던 12개(`infra/httpclient/**`, `infra/jpa/postgres/README.md`, `infra/jpa/toxiproxy/`, `infra/messaging/{kafka,postgres,toxiproxy,tls}/`, `infra/notification/toxiproxy/`)와 운영 인프라 셋(`infra/fileserver/nginx/nginx.conf`, `infra/fileserver/kubernetes/pvc-certification-job.yaml`, `infra/jpa/roles/runtime-roles.sql`). `release.yml`의 `fileserver-pvc-certification` job도 지웠고, fileserver 지원 표에서 "Kubernetes ReadWriteOnce PVC — Limited" 주장을 「주장하지 않음」으로 옮겼다 | 그 파일을 배포에 쓰던 서비스: 병합이 파일을 지운다. 고쳐 쓰던 서비스: "수정 대 삭제" 충돌 | 그 파일은 자기 인프라 repo로 옮긴다. 지켜야 할 조건은 `docs/fileserver/operations.md` 「운영 환경이 지켜야 할 조건」, `docs/fileserver/storage-certification.md`, `docs/jpa/security.md` 「역할과 권한」·「서버 설정」에 있다 | 커밋 「쓰지 않는 파일과 운영 인프라 파일을 지운다」 |
| B-51 | compose 정리. 루트 `docker-compose.yml`·`docker-compose.local.yml`·`docker-compose.infra.yml`을 개발 환경 `compose.yaml` 하나로 합쳤다(app은 `local` 런타임, 뒷단 서비스는 capability profile `jpa`·`redis`·`kafka`·`mongo`·`objectstorage`·`auth`·`mail`). 보조 파일은 `compose/`(keycloak realm·entrypoint, minio init, Redis ACL, mailpit 인증서 폴더). 테스트 lane fixture는 그 lane을 가진 leaf로 옮겼다: `docker-compose.dev.yml`·`docker-compose.prod-smoke.yml`·`docker-compose.tls.yml`·fileserver overlay·smoke 스크립트·스키마 적용 스크립트·lane 계약 JSON(`src/config/runtime/compose-profile-contracts.json`) → `src/app-bootstrap/compose-lanes/`, Redis topology compose → `src/adapter/outbound/redis-sdk/compose/`, NFS compose → `src/adapter/outbound/fileserver/compose/nfs/`. `infra/`는 없어졌다. lane 계약의 `composeProfile`(문자열)은 `composeProfiles`(목록)로 바뀌었고 `appMemoryLimit`이 생겼다. smoke는 lane 중 컨테이너가 재시작하거나 메모리로 죽으면 실패한다. `scripts/bootstrap-local.sh`는 인자를 받지 않는다 | `docker compose -f docker-compose.yml -f docker-compose.local.yml …`을 쓰던 스크립트·문서가 "no such file"로 실패. 옛 compose 파일에 서비스를 더했으면 수정 대 삭제 충돌. lane 계약을 고쳐 쓰던 서비스는 `composeProfile` 키를 smoke 스크립트가 읽지 않는다 | 명령을 `docker compose …`(루트 `compose.yaml`)와 profile로 바꾼다. 더한 서비스는 `compose.yaml`에 capability profile을 달아 옮기고, lane 전용이면 `src/app-bootstrap/compose-lanes/lane-services.yaml`에 둔다. 경로를 적은 workflow·문서를 위 새 경로로 고친다 | 커밋 「compose 파일을 개발 환경 하나와 lane fixture로 나눈다」 |
| B-52 | `src/` 배치 정리. 들여온 플랫폼 넷을 `src/platforms/` 아래로 옮겼다: `src/messaging` → `src/platforms/messaging`, `src/grpc` → `src/platforms/grpc`, `src/grpc-advanced` → `src/platforms/grpc-advanced`, `src/optional-platforms` → `src/platforms/optional-build`(빌드 이름 `optional-platforms`는 그대로). registry `source_path`만 바뀌고 Gradle 경로(`:messaging:*`, `:grpc:*`)는 그대로다. optional 빌드는 `./gradlew -p platforms/optional-build …`로 부른다. `src/config/`에서 기능 하나가 주인인 데이터를 그 leaf의 `release/`로 옮겼다: `config/jpa/*` → `adapter/outbound/persistence-jpa/release/`, `config/messaging/**` → `adapter/outbound/messaging/release/`, `config/mongodb/release-contracts.json` → `adapter/outbound/persistence-mongo/release/` | `-p optional-platforms`를 부르는 workflow·스크립트가 "Project directory … does not exist"로 실패. 옮긴 폴더를 고쳐 쓰던 서비스는 이름 바뀜 충돌(Git이 이동으로 알아보면 자동 병합). `rootProject.file('config/jpa/…')`처럼 옛 경로를 읽던 자기 빌드 줄은 파일 없음 | workflow·스크립트의 `-p`와 경로를 새 위치로 고친다. 자기 leaf를 `src/messaging` 아래에 더했다면 `src/platforms/messaging` 아래로 옮기고 registry `source_path`를 고친다 | 커밋 「들여온 플랫폼을 src/platforms 아래로 묶는다」 |
| B-50 | `infra/`에서 15개 삭제. 쓰는 곳이 없던 12개(`infra/httpclient/**`, `infra/jpa/postgres/README.md`, `infra/jpa/toxiproxy/`, `infra/messaging/{kafka,postgres,toxiproxy,tls}/`, `infra/notification/toxiproxy/`)와 운영 인프라 셋(`infra/fileserver/nginx/nginx.conf`, `infra/fileserver/kubernetes/pvc-certification-job.yaml`, `infra/jpa/roles/runtime-roles.sql`). `release.yml`의 `fileserver-pvc-certification` job도 지웠고, fileserver 지원 표에서 "Kubernetes ReadWriteOnce PVC — Limited" 주장을 「주장하지 않음」으로 옮겼다 | 그 파일을 배포에 쓰던 서비스: 병합이 파일을 지운다. 고쳐 쓰던 서비스: "수정 대 삭제" 충돌 | 그 파일은 자기 인프라 repo로 옮긴다. 지켜야 할 조건은 `docs/fileserver/operations.md` 「운영 환경이 지켜야 할 조건」, `docs/fileserver/storage-certification.md`, `docs/jpa/security.md` 「역할과 권한」·「서버 설정」에 있다 | `a025f244` |
| B-51 | compose 정리. 루트 `docker-compose.yml`·`docker-compose.local.yml`·`docker-compose.infra.yml`을 개발 환경 `compose.yaml` 하나로 합쳤다(app은 `local` 런타임, 뒷단 서비스는 capability profile `jpa`·`redis`·`kafka`·`mongo`·`objectstorage`·`auth`·`mail`). 보조 파일은 `compose/`(keycloak realm·entrypoint, minio init, Redis ACL, mailpit 인증서 폴더). 테스트 lane fixture는 그 lane을 가진 leaf로 옮겼다: `docker-compose.dev.yml`·`docker-compose.prod-smoke.yml`·`docker-compose.tls.yml`·fileserver overlay·smoke 스크립트·스키마 적용 스크립트·lane 계약 JSON(`src/config/runtime/compose-profile-contracts.json`) → `src/app-bootstrap/compose-lanes/`, Redis topology compose → `src/adapter/outbound/redis-sdk/compose/`, NFS compose → `src/adapter/outbound/fileserver/compose/nfs/`. `infra/`는 없어졌다. lane 계약의 `composeProfile`(문자열)은 `composeProfiles`(목록)로 바뀌었고 `appMemoryLimit`이 생겼다. smoke는 lane 중 컨테이너가 재시작하거나 메모리로 죽으면 실패한다. `scripts/bootstrap-local.sh`는 인자를 받지 않는다 | `docker compose -f docker-compose.yml -f docker-compose.local.yml …`을 쓰던 스크립트·문서가 "no such file"로 실패. 옛 compose 파일에 서비스를 더했으면 수정 대 삭제 충돌. lane 계약을 고쳐 쓰던 서비스는 `composeProfile` 키를 smoke 스크립트가 읽지 않는다 | 명령을 `docker compose …`(루트 `compose.yaml`)와 profile로 바꾼다. 더한 서비스는 `compose.yaml`에 capability profile을 달아 옮기고, lane 전용이면 `src/app-bootstrap/compose-lanes/lane-services.yaml`에 둔다. 경로를 적은 workflow·문서를 위 새 경로로 고친다 | `50cd7154` |
| B-52 | `src/` 배치 정리. 들여온 플랫폼 넷을 `src/platforms/` 아래로 옮겼다: `src/messaging` → `src/platforms/messaging`, `src/grpc` → `src/platforms/grpc`, `src/grpc-advanced` → `src/platforms/grpc-advanced`, `src/optional-platforms` → `src/platforms/optional-build`(빌드 이름 `optional-platforms`는 그대로). registry `source_path`만 바뀌고 Gradle 경로(`:messaging:*`, `:grpc:*`)는 그대로다. optional 빌드는 `./gradlew -p platforms/optional-build …`로 부른다. `src/config/`에서 기능 하나가 주인인 데이터를 그 leaf의 `release/`로 옮겼다: `config/jpa/*` → `adapter/outbound/persistence-jpa/release/`, `config/messaging/**` → `adapter/outbound/messaging/release/`, `config/mongodb/release-contracts.json` → `adapter/outbound/persistence-mongo/release/` | `-p optional-platforms`를 부르는 workflow·스크립트가 "Project directory … does not exist"로 실패. 옮긴 폴더를 고쳐 쓰던 서비스는 이름 바뀜 충돌(Git이 이동으로 알아보면 자동 병합). `rootProject.file('config/jpa/…')`처럼 옛 경로를 읽던 자기 빌드 줄은 파일 없음 | workflow·스크립트의 `-p`와 경로를 새 위치로 고친다. 자기 leaf를 `src/messaging` 아래에 더했다면 `src/platforms/messaging` 아래로 옮기고 registry `source_path`를 고친다 | `8d69e599` |
| B-53 | 새 PR 검사 `python3 scripts/check-repo-layout.py`(`ci-quality-gates.yml`): 저장소 루트와 `src/` 최상위의 추적 항목이 허용 목록 안에 있어야 하고, registry `source_path`가 허용된 `src/` 폴더 아래여야 한다 | 자기 최상위 폴더(예: `infra/`, `src/<서비스 전용 폴더>`)를 둔 서비스는 PR 게이트가 실패한다 | 그 폴더가 정말 필요하면 스크립트의 `ROOT_ALLOWED`·`SRC_ALLOWED`와 자기 `CLAUDE.md` 지도에 같은 변경으로 더한다. 아니면 그 내용을 주인 leaf나 `docs/`로 옮긴다 | 커밋 「최상위 폴더 허용 목록 검사를 더한다」 |
## 4. DB 마이그레이션
+1
View File
@@ -74,6 +74,7 @@
| 생성 명령 | JPA adapter를 만들지 않음(서비스 전용 persistence leaf가 기본), 생성된 쓰기 API는 역할 매핑 전 403 | 위임 | `1101` 15절(r2-10) |
| `@SystemInvoked` | bean으로 등록돼 있으면 기동 실패, inbound adapter가 직접 부르지 못하게 ArchUnit | 위임 | `1103` 4절(RR-01-02) |
| 시스템 호출 경로 | 사용자가 닿는 전송(web·GraphQL·gRPC·WebSocket)만 `@SystemInvoked`에 닿지 못한다. 메시지 소비자·스케줄러는 `@SystemCaller(reason)` 표시로 허용 | 위임 | `1103` 9.1절(RR-01-12), 10절 r5-b |
| 배치 규칙 검사 | 저장소 루트와 `src/` 최상위 허용 목록을 `scripts/check-repo-layout.py`로 PR에서 막는다. 리뷰 기준에도 넣는다(매뉴얼 보강 작업) | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 10.3절 |
| `src/` 배치 | 들여온 플랫폼 넷(`messaging`, `grpc`, `grpc-advanced`, optional 빌드)을 `src/platforms/` 아래로 묶는다. registry `source_path`만 바꾸고 Gradle 경로는 그대로 둔다. `build-logic`·`gradle`·`config`는 Gradle 루트 표준이라 남기고, `composition`은 조립 계층이라 옮기지 않는다. `config/`에서 기능 하나가 주인인 데이터 파일은 그 leaf로 보낸다. Gradle 루트를 저장소 루트로 옮길지는 CI 재편 때 다시 본다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.1절 |
| 개발 compose 파일 | 저장소 루트에 `compose.yaml` 하나. 뒷단 서비스는 capability 이름 profile로 고르고, 마운트하는 보조 파일은 `compose/`에 둔다. 테스트 lane fixture는 그 lane을 가진 leaf로 보낸다(compose lane → app-bootstrap `compose-lanes/`, Redis topology → redis-sdk, NFS → fileserver). `docker-compose.dev.yml`은 `dev` 배포 프로필이 뜨는지 보는 lane fixture로 app-bootstrap에 둔다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 |
| 인프라 실행 파일 | nginx 설정, Kubernetes PVC job, DB 역할 SQL은 이 repo에서 지우고, 기능이 운영 환경에 요구하는 조건만 그 기능 문서에 적는다. 아무도 쓰지 않는 `infra/` 파일도 지운다 | 소유자(2026-11-07) | design-docs `repo-structure/README.md` 3.1절, `repo-structure/01-backend-layout.md` 6.3절 |
+3 -1
View File
@@ -23,6 +23,7 @@
| `verifyStrictLaneStages --dry-run` | `explicitOnly`가 아닌 strict lane이 workflow가 실행하는 단계에 속하는가 | PR(두 빌드 각각) | `ci-quality-gates.yml`, optional 빌드는 `-p platforms/optional-build` |
| `-p platforms/optional-build ci` | gRPC 플랫폼 빌드 | PR | `ci-quality-gates.yml` |
| `bash scripts/verify-compose-profile-contracts.sh` | compose lane이 선언대로 렌더링되는가(저장소 루트에서) | PR | `ci-quality-gates.yml` |
| `python3 scripts/check-repo-layout.py` | 저장소 루트와 `src/` 최상위에 허용 목록 밖의 항목이 없는가, registry 경로가 허용 폴더 안인가. 아무도 가리키지 않는 compose·스크립트 파일은 경고 | PR | `ci-quality-gates.yml` |
| `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + 생성 명령 왕복(`verifyFeatureScaffold`) + 모든 leaf의 `mainCheck`(document-contract lane 등) | main | `integration-main.yml`: `./gradlew :mainCheck --continue --warning-mode=fail` |
| `integrationCheck` | 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `integration-main.yml`, optional 빌드도 |
| `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 | main·nightly | `integration-main.yml`, optional 빌드도. 5절 |
@@ -81,7 +82,7 @@ python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(
| brief의 말 | 돌릴 것 |
| --- | --- |
| pull request 단계 게이트 | (가)의 `# PR` 줄과 `verify-compose-profile-contracts.sh`, (나)에서 `pull_request`로 켜지는 것, (다) |
| pull request 단계 게이트 | (가)의 `# PR` 줄과 `verify-compose-profile-contracts.sh`·`check-repo-layout.py`, (나)에서 `pull_request`로 켜지는 것, (다) |
| main 단계 | (가)의 `# main push` 줄과 `run-compose-runtime-smoke.sh`, (나)에서 main `push`로 켜지는 것 |
| 라운드 끝 | 위 둘 전부와 (가)의 `# 태그` 두 줄 |
@@ -112,6 +113,7 @@ cd src
./gradlew -p platforms/optional-build releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain
cd ..
bash scripts/verify-compose-profile-contracts.sh
python3 scripts/check-repo-layout.py
bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
```