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
View File
@@ -57,6 +57,10 @@ jobs:
run: ./gradlew :verifyStrictLaneStages --dry-run --stacktrace
- name: Verify Compose profile contracts render exactly as declared
run: bash scripts/verify-compose-profile-contracts.sh
# The repository root and src/ hold only the entries on the allow list (owner decision
# 2026-11-07): a new top-level folder is a decision, not a side effect of a feature commit.
- name: Refuse a top-level folder outside the allow list
run: python3 scripts/check-repo-layout.py
optional-platforms:
runs-on: ubuntu-latest
+1 -1
View File
@@ -54,7 +54,7 @@ brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이
## 5. 코드만 보고는 헷갈리는 곳
- **최상위 폴더는 정해진 것만 둔다.** 저장소 루트는 `compose.yaml`(개발 환경)·`compose/`(그 보조 파일)·`docs/`·`scripts/`·`src/`(Gradle 루트)다. `src/` 아래는 계층 leaf 폴더, `composition/`(조립), `platforms/`(들여온 제품: `messaging`·`grpc`·`grpc-advanced`와 optional 빌드 `optional-build`), Gradle 루트 표준(`build-logic`·`gradle`·`config`)이다. 테스트 환경 파일은 그 lane을 가진 leaf 안에 둔다.
- **최상위 폴더는 정해진 것만 둔다.** 저장소 루트는 `compose.yaml`(개발 환경)·`compose/`(그 보조 파일)·`docs/`·`scripts/`·`src/`(Gradle 루트)다. `src/` 아래는 계층 leaf 폴더, `composition/`(조립), `platforms/`(들여온 제품: `messaging`·`grpc`·`grpc-advanced`와 optional 빌드 `optional-build`), Gradle 루트 표준(`build-logic`·`gradle`·`config`)이다. 테스트 환경 파일은 그 lane을 가진 leaf 안에 둔다. `scripts/check-repo-layout.py`(PR 게이트)가 허용 목록 밖의 최상위 항목을 막는다.
- **leaf 목록은 registry 하나다.** 문서는 leaf 개수를 적지 않는다(적힌 수는 leaf가 늘면 틀린다). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 registry의 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다.
- **`src/platforms/messaging/*`는 Clean Architecture 계층이 아니다.** 자기 API·SPI·adapter·조립 경계를 가진, 들여온(vendored) 메시징 제품이다. `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 이 애플리케이션은 `adapter:outbound:messaging`의 bridge로만 닿는다. 이유와 지역 규칙은 `src/platforms/messaging/CLAUDE.md`다.
- **`composition:*` leaf는 조립만 한다.** outbox relay, 멱등성 executor, durable operation처럼 bootstrap에서 떼어 낸 조립이다. 각각 `runtimeOnly` 한 줄로 고른다.
+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
```
+210
View File
@@ -0,0 +1,210 @@
#!/usr/bin/env python3
"""저장소 루트와 src/ 최상위에 허용 목록 밖의 항목이 생기면 실패한다.
왜: src/ 아래 계층이 아닌 폴더가 2026-07-24의 둘에서 두 달 사이 여덟으로 늘었고, 어느 커밋도 최상위
모양을 묻지 않았다. 루트에는 개발 환경·테스트 fixture·운영 인프라가 섞인 compose 파일과 infra/ 폴더가
쌓였다(2026-11-07 저장소 정리, design-docs repo-structure/01-backend-layout.md). 소유자는 배치 규칙을
리뷰 기준에 두고, 이 허용 목록 검사로도 막기로 정했다(같은 날, repo-structure/README.md 3.1절).
무엇을 보나:
1. 저장소 루트의 추적 파일·폴더가 ROOT_ALLOWED 안에 있는가.
2. src/ 바로 아래의 추적 파일·폴더가 SRC_ALLOWED 안에 있는가.
3. registry(src/config/architecture/modules.json)의 모든 source_path가 허용된 src/ 폴더 아래에 있는가.
4. (경고만) 개발 환경·테스트 fixture 파일(compose 파일, 셸 스크립트, compose/ 아래 보조 파일)을 다른
추적 파일이 하나도 가리키지 않으면 이름을 출력한다. 아무도 읽지 않는 파일이 소리 없이 남는 것이
infra/ 12개가 쌓인 방식이다. 경로를 변수로 조립하는 workflow는 이 검사가 따라가지 못하므로 경고로만 둔다.
추적 파일만 본다(git ls-files). build 출력과 IDE 폴더는 처음부터 대상이 아니다.
새 최상위 항목이 정말 필요하면 아래 목록과 루트 CLAUDE.md 5절 「최상위 폴더는 정해진 것만 둔다」를 같은
변경에서 고친다. 최상위 폴더를 만들거나 옮기는 일은 파일 하나여도 큰 일이다(docs/work/README.md 2절).
Gradle 밖에 둔다: 빌드는 저장소 배치를 판단하지 않는다(scripts/check-work-docs.py와 같은 자리).
python3 scripts/check-repo-layout.py
"""
from __future__ import annotations
import json
import subprocess
import sys
from pathlib import Path, PurePosixPath
REPO_ROOT = Path(__file__).resolve().parent.parent
REGISTRY = "src/config/architecture/modules.json"
# 저장소 루트: 문서·스크립트·CI·개발 환경과 Gradle 루트(src)뿐이다.
ROOT_ALLOWED = {
# 폴더
".claude": "에이전트 세션 설정(추적되는 settings.json)",
".github": "workflow와 공용 action",
"compose": "compose.yaml이 마운트하는 보조 파일",
"docs": "문서",
"scripts": "Gradle 밖 검사·실행 스크립트",
"src": "Gradle 루트",
# 파일
".gitattributes": "Git 설정",
".gitignore": "Git 설정",
".tool-versions": "JDK 버전 고정",
".trivyignore.yaml": "취약점 검사 예외",
"AGENTS.md": "규칙 정본",
"CLAUDE.md": "작업 지도",
"README.md": "저장소 소개",
"compose.yaml": "개발 환경(하나뿐)",
"renovate.json": "의존성 갱신 봇 설정",
"skills-lock.json": "에이전트 스킬 고정",
"testcontainers.properties.example": "Testcontainers 로컬 설정 예",
}
# src/ 바로 아래: 계층·조립 leaf, 들여온 제품 묶음, Gradle 루트 표준 폴더와 빌드 파일.
SRC_ALLOWED = {
# 계층과 조립
"domain-core": "계층",
"shared-contract": "계층",
"application-core": "계층",
"application-fileserver": "계층(capability)",
"application-notification": "계층(capability)",
"application-objectstorage": "계층(capability)",
"adapter": "계층(adapter leaf 묶음)",
"composition": "조립(Clean Architecture의 Main)",
"app-bootstrap": "조립 루트",
# 들여온 제품
"platforms": "들여온 제품(messaging, grpc, grpc-advanced)과 optional 빌드",
# Gradle 루트 표준
"build-logic": "빌드 규칙(included build)",
"config": "빌드 전체 도구 설정(registry, checkstyle, spotbugs, 테스트 이미지)",
"gradle": "wrapper와 버전 카탈로그",
# 파일
".dockerignore": "이미지 빌드 context",
".env.example": "env 계약",
".env.local.example": "로컬 env 예",
".gitignore": "Git 설정",
"Dockerfile": "릴리스 이미지",
"README.md": "빌드·env 안내",
"build.gradle": "루트 빌드",
"gradle.properties": "Gradle 설정",
"gradlew": "wrapper",
"gradlew.bat": "wrapper",
"settings-gradle.lockfile": "settings 잠금",
"settings.gradle": "settings",
}
# 아무도 가리키지 않으면 경고할 파일: 개발 환경과 테스트 fixture.
FIXTURE_SUFFIXES = (".sh", ".acl", ".json", ".yaml", ".yml")
FIXTURE_PREFIXES = ("compose/", "scripts/", "src/app-bootstrap/compose-lanes/")
HISTORY_PREFIXES = (
"docs/reviews/",
"docs/superpowers/",
"docs/evidence/",
"docs/study/",
"docs/adr/",
)
def tracked_files() -> list[str]:
result = subprocess.run(
["git", "ls-files", "-z"],
cwd=REPO_ROOT,
check=True,
capture_output=True,
)
return [path for path in result.stdout.decode("utf-8").split("\0") if path]
def top_level(paths: list[str], prefix: str) -> set[str]:
names = set()
for path in paths:
if not path.startswith(prefix):
continue
rest = path[len(prefix):]
names.add(rest.split("/", 1)[0])
return names
def registry_violations() -> list[str]:
modules = json.loads((REPO_ROOT / REGISTRY).read_text(encoding="utf-8"))["modules"]
problems = []
for module in modules:
source = PurePosixPath(module["source_path"])
parts = source.parts
if len(parts) < 2 or parts[0] != "src" or parts[1] not in SRC_ALLOWED:
problems.append(
f"{REGISTRY}: {module['id']} source_path {source} is not under an allowed src/ folder"
)
return problems
def is_fixture(path: str) -> bool:
if path.endswith(("README.md", ".gitignore")):
return False
name = PurePosixPath(path).name
if path.startswith(FIXTURE_PREFIXES) and name.endswith(FIXTURE_SUFFIXES):
return True
return "compose" in name and name.endswith((".yaml", ".yml"))
def unreferenced_fixtures(paths: list[str]) -> list[str]:
this_script = str(Path(__file__).resolve().relative_to(REPO_ROOT))
readable = [
p for p in paths if not p.startswith(HISTORY_PREFIXES) and p != this_script
]
texts = {}
for path in readable:
file = REPO_ROOT / path
try:
if file.stat().st_size > 2_000_000:
continue
texts[path] = file.read_text(encoding="utf-8")
except (UnicodeDecodeError, OSError):
continue
lonely = []
for path in sorted(p for p in paths if is_fixture(p)):
pure = PurePosixPath(path)
# The file's own path or name, or its folder when a compose file mounts the whole folder
# (./compose/redis/acl). A one-segment folder such as compose/ names too much to count.
needles = {path, pure.name}
if len(pure.parent.parts) >= 2:
needles.add(str(pure.parent))
referenced = any(
other != path and any(needle in text for needle in needles)
for other, text in texts.items()
)
if not referenced:
lonely.append(path)
return lonely
def main() -> int:
paths = tracked_files()
failures = []
for name in sorted(top_level(paths, "") - ROOT_ALLOWED.keys()):
failures.append(f"repository root: '{name}' is not in ROOT_ALLOWED")
for name in sorted(top_level(paths, "src/") - SRC_ALLOWED.keys()):
failures.append(f"src/: '{name}' is not in SRC_ALLOWED")
failures.extend(registry_violations())
for path in unreferenced_fixtures(paths):
print(f"warning: no tracked file refers to {path}")
if failures:
for failure in failures:
print(f"FAIL: {failure}", file=sys.stderr)
print(
"check-repo-layout: a new top-level entry changes the repository's shape. If it is "
"wanted, add it to the allow list in scripts/check-repo-layout.py and to CLAUDE.md "
"section 5 in the same change.",
file=sys.stderr,
)
return 1
print(
f"check-repo-layout: OK — {len(top_level(paths, ''))} root entries, "
f"{len(top_level(paths, 'src/'))} src/ entries, registry paths inside allowed folders"
)
return 0
if __name__ == "__main__":
sys.exit(main())