Files
clean-architecture-backend-…/src/build-logic
DongHyeonka c91cc3fb10 docs(core): core·조립·빌드·플랫폼 모듈 문서를 한국어로 옮긴다
문제: core 계층(application·domain·shared-contract), app-bootstrap,
composition, registry, build-logic, optional 빌드의 모듈 문서가 영어다.
세션이 처음 읽는 지역 규칙인데 소유자는 2026-11-07에 살아 있는 문서를
모두 한국어로 쓰기로 정했다. leaf CLAUDE.md 셋은 Spring Boot 버전을
4.0.0으로 복사해 두었는데 실제 버전(libs.versions.toml)과 다르다.

방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·표 구조는 원문으로
둔다. 버전은 `src/gradle/libs.versions.toml`을 가리키는 말로 바꾼다.
다른 문서·코드가 제목으로 가리키는 절(application-core의
Naming convention·Package ownership·Canonical use case shape·Allowed
transactional shapes, shared-contract의 Responsibility·Forbidden,
messaging의 발행 재시도 절)은 영어 원제를 괄호로 남겨 그 참조가
계속 찾아지게 한다. 참조하는 쪽을 고치는 것은 이 작업 범위 밖이다.
코드와 어긋난 주장은 코드에 맞춘다: TransactionPort 구현을
`adapter-persistence`에서 `adapter:outbound:persistence-jpa`의
`SpringTransaction`으로, registry README의 빈 의존 목록 예를
persistence-mongo(실제 목록은 application-core·shared-contract)에서
domain-core·shared-contract·messaging-core-api로 고친다.
TemplatePackageOwnershipDocumentTest는 표 머리 문자열로 표를 찾으므로
머리 상수를 한국어 머리(`| 패키지 (...) |`)로 맞춘다. 표와 기계 사본을
대조하는 계약은 그대로다.

위험: 영어 원제를 괄호로 남긴 제목은 참조하는 문서가 한국어 제목으로
바뀌면 괄호를 지울 수 있다. 본문의 짧은 이력 번호(07-08, 06-01,
11-M9)는 뜻을 바꾸지 않으려고 그대로 옮겼다.

검증: python3 scripts/check-docs.py rc=0(번역한 파일의 language 줄 8개,
number 줄 3개 지움), check-work-docs.py rc=0, --links(gates.md 범위)
깨진 링크 0, unittest discover scripts/tests 43개 통과.
2026-11-07 17:07:16 +09:00
..

build-logic

이 저장소의 Gradle 규약을 담은 included build다: 아키텍처 핵심, 모든 leaf가 적용하는 규약, 시험 lane 장치 하나. capability 하나에 대한 검사(알림, Mongo, 메시징, GraphQL, JPA)는 여기 없다 — 그것은 그 capability를 가진 leaf의 시험이고, 그 시험이 읽는 파일은 그 시험 태스크의 입력으로 선언한다.

여기 있는 것

플러그인 가지는 것
ca.architecture-registry (settings) 프로젝트 포함, 디렉터리 대응, 다른 모든 읽는 쪽이 같이 쓰는 파싱된 registry
ca.architecture verifyCleanArchitectureDependencies(모듈별 방향), verifyApplicationCoreDependencyPurity(domain-core, shared-contract, application-*), verifyNoIgnoredSourcePackages, architectureCheck
ca.java-conventions Java toolchain·컴파일러 기준, 의존성 잠금, Mockito 시험 agent, leaf별 mainCheck lifecycle, leaf 버전(릴리스 버전만)과 sourceRevision(JavaConventionsPlugin.sourceRevision. 루트 verifyReleaseProvenance가 검사하는 것도 이것이다)
ca.quality-conventions Java leaf가 같이 쓰는 Spotless, Checkstyle, Error Prone, SpotBugs·FindSecBugs 배선
ca.java-library / ca.spring-library / ca.spring-config 평범한 라이브러리와 Spring 라이브러리를 위한 Java·품질 규약의 leaf 단위 조합
ca.platform-module / ca.grpc-platform-module 들여온 플랫폼 leaf(messaging:*, grpc:*, grpc-advanced:*)가 무엇인가: java-library, 그리고 원래 gRPC BOM을 쓰던 leaf에는 그 BOM
ca.strict-test-lane 「이름 댄 시험이 돌았고 건너뛴 것이 없다」를 보는 유일한 장치: tag·이름·자기 source set으로 고른 Test lane이 아무것도 실행하지 않거나, requires 클래스를 빠뜨리거나, (rejectSkipped이면) 무엇이든 건너뛰면 실패한다. performance() lane은 언제나 건너뛰기를 거절하고 performance.assertions.enabled=true로 돈다. 빌드(-P, GRADLE_OPTS)나 lane이 다른 값을 넣으면 시험이 돌기 전에 실패한다. mainStage()는 tag로 고른 lane을 test에서 빼 leaf의 mainCheck로 옮긴다. explicitOnly(reason)는 바깥 입력이 필요한 lane을 모든 묶음 태스크에서 빼고, 묶음 태스크가 그 이유를 출력한다. 시험 source set을 더 두려면 leaf에 Gradle jvm-test-suite suite로 선언한다(testing { suites { … } }). suite 이름을 딴 lane은 그 suite 자신의 Test 태스크를 엄격하게 만들고, ca.java-conventions는 모든 suite에 BOM의 JUnit을 준다
ca.strict-lane-stages (strict lane이 있는 각 빌드의 루트: 주 빌드와 optional-platforms) lane 장치의 나머지 절반: verifyStrictLaneStages --dry-run은 그 빌드의 explicitOnly가 아닌 strict lane이 workflow가 실행하는 선언된 단계 어느 것의 태스크 계획에도 없거나, 선언된 단계를 실행하는 workflow가 없으면 실패한다. workflow는 함께 읽고(WorkflowGradleInvocations.readAll. 그래서 재사용 workflow는 그것을 부르는 쪽으로 판정한다) run: 스크립트는 bash로 파싱한다(ShellScript: 따옴표, 주석, heredoc 본문, 치환, 복합 명령을 셸이 읽듯 읽는다. 그래서 heredoc이나 문자열 안의 cd는 데이터다). Gradle이 태스크를 하나도 돌리지 않는 명령은 세지 않는다 — --dry-run/-m(-qm 같은 묶음 안도), -v/--version, -h/-?/--help, --status, --stop, --foreground(-qv 같은 묶음 안도) — Gradle이 거절하는 명령도 세지 않는다: 뒤 글자가 값을 받는 짧은 옵션 묶음(-mx: 묶음에서는 첫 글자만 값을 받는다), 값을 받지 않는 옵션에 준 값(-m=yes). 읽는 방식은 Gradle 9.0의 파서를 따른다. GradleCommandLineTest는 옵션 표를 build-logic을 돌리는 Gradle의 --help와 맞춘다 — 옵션을 더하는 업그레이드는(9.2가 --task-graph를 더하듯) 그 옵션을 자리에 넣기 전까지 실패한다 — 그리고 --stop과 --foreground를 뺀 태스크 없는 옵션마다 launcher를 돌린다(둘은 Gradle BuildActionsFactory에서 빌드가 아니라 daemon 동작을 돌려준다). 어떤 옵션이 값을 받는지는 round 9에 9.0.0으로 탐침했고 다시 돌리지 않는다. 다른 빌드를 위한 명령도 세지 않는다(명령이 시작하는 빌드는 그 step의 working-directory, 또는 job이나 workflow의 defaults.run.working-directory에서 시작해, 같은 run: 셸이 그 앞에서 반드시 돌린 cd <리터럴 상대 경로>마다 옮기고 — 혼자 있는 목록이거나 같은 && 목록에서 그 명령 앞에 있을 때 — 그다음 -p로 이은 곳이다. 플러그인은 이 빌드 자신의 디렉터리를 .github/workflows를 가진 저장소 아래 어디에 있는지로 읽는다). 세지 않는 그 밖의 명령은 모두 세 이유 중 하나를 댄다. 실패해도 step이 실패하지 않을 수 있다: || true, || :, || exit <0 아닌 값>이 아닌 모든 ||, pipefail 없는 pipe의 왼쪽(shell: bash나 최상위 set -o pipefail이면 켜진다), !, &, if/while 조건, 스크립트의 마지막 명령이 아닌 목록에서 && 앞부분, set +e 뒤, EXIT나 ERR 동작이 상태 0으로 exit할 수 있는 trap 뒤(EXIT trap 안의 맨 exit는 상태를 지키지만 ERR trap 안에서는 아니다), continue-on-error. 돌지 않을 수 있다: || 뒤, 스크립트의 마지막 명령이 아닌 목록에서 && 뒤, if/while/for/case 안이나 함수 본문 안, 최상위 exit·exec <command>·set -n 뒤, 다른 곳 — 복합 명령, and-or 목록, 스크립트가 부르는 함수 — 에서 스크립트를 상태 0으로 끝낼 수 있는 것(exit 0, || 바로 뒤가 아닌 맨 exit, exit "$code"), 스크립트를 바꿔치는 것, 명령 실행을 멈추는 것(set -o noexec) 뒤, always()/success()/!cancelled()가 아닌 if: 아래, 누가 또는 무엇이 요청해야만 시작하는 이벤트(workflow_dispatch, repository_dispatch, issue_comment, types: [labeled]인 pull request, workflow_run, …. push, pull_request, pull_request_target, merge_group, schedule, release는 센다)로만 시작하는 workflow 안, 변경 흐름 트리거가 모두 paths나 paths-ignore 필터를 가진 workflow 안(그 경로 밖의 변경은 workflow를 시작하지 않는다. 소유자 결정 2026-11-06), 요청이나 경로 필터 없이 릴리스 흐름에서만 시작하는 workflow 안의 :releaseCheck가 아닌 단계 — 릴리스 흐름은 release, 또는 tags/tags-ignore가 있고 branches/branches-ignore가 없는 push로, 브랜치 push로는 시작하지 않는다(소유자 결정 2026-11-07. :releaseCheck가 태그 전용 단계다) — 센 job 어느 것도 uses: ./.github/workflows/<file>로 부르지 않는 재사용(workflow_call만 있는) workflow 안, 그리고 그런 if:나 continue-on-error를 가진 job을 직접 또는 다른 job을 거쳐 needs하는 job 안(자기 if:가 always()나 !cancelled()이면 예외). 이 검사가 읽지 않는다(실패하면 step이 실패하지만, 일부러 거짓 실패로 둔다): || exit 1, || { …; exit 1; }, { }나 ( ) 안, $( ), bash -c, 다른 명령의 인자인 gradlew(timeout 60 ./gradlew), 읽는 쪽이 따라가지 않는 디렉터리 이동 뒤(cd "$VAR", cd -, cd ~, 절대 경로, pushd/popd, builtin cd, eval/source, 복합 명령이나 함수 본문 안의 cd, ||로 이은 것, pipe나 background로 돌린 것, 다른 명령과 같은 && 목록에 있는 cd의 뒤 줄 — 짐작하지 않는다), shell:이 bash나 sh가 아닌 step, runs-on이 Windows runner일 수 있는 job에서 shell:이 없는 step(기본 셸이 pwsh다. Windows label, ${{ matrix.os }} 같은 표현식, linux나 macos가 없는 self-hosted label 집합. Linux·macOS runner의 기본은 bash -e, container: job의 기본은 sh -e이고 둘을 같이 읽는다). step을 실패시키는 exit — exit 1, cmd || exit — 와 부르지 않는 함수, ( ) subshell, $( ) 안의 exit는 그 뒤의 명령이 세지는 것을 막지 않는다. 실패 메시지는 단계 이름을 대지만 그 단계를 실행하지 않는 모든 명령을 그 이유나 그것이 시작하는 다른 빌드와 함께 대고, 단계를 혼자 있는 줄의 ./gradlew로 돌리라고 말한다. 명령이 -x로 뺀 lane은 덮인 것이 아니다 — Gradle이 태스크·프로젝트 이름을 맞추는 방식(약어 포함)으로 맞춘다(TaskSelectors, Gradle 내부 NameMatcher의 사본). uses: step의 run: 입력은 명령이 아니다. 계획은 Gradle 자신의 것이다. workflow는 YAML folding을 적용해 run: step을 읽는다(review 2026-11-01 08-01, 2026-11-03 RR-06-03/04, 2026-11-04 RR2-04-04, cd에 대한 소유자 결정 2026-11-04, round 9의 RR5-02-01/02/03, 2026-11-05 RR6-04-01..06, 2026-11-06 RR7-05-01, 릴리스 흐름에 대한 소유자 결정 2026-11-07)
ca.redis-topology-lane redis-sdk-topology workflow가 돌리는 Redis topology lane(모드 고르기, -P 속성 검증, 모드별 필수 클래스)
ca.api-surface 읽기 전용 공개 API surface 검증과 따로 둔 갱신 태스크. leaf의 check에 배선한다(소유자 결정 20). 다른 leaf의 import를 리뷰한 adopter 부분집합(adopterBaseline)에 묶을 수도 있다
ca.config-contract app-bootstrap의 verifyEnvKeys(지운 build-tools included build에서 옮겼다. 소유자 결정 4가 그 태스크를 app-bootstrap에 둔다)
ca.bootrun-dotenv bootRun의 .env

플러그인이 아니라 평범한 클래스로 둔 것. settings와 project는 플러그인을 서로 다른 방식으로 읽어 들이고, 각각을 부르는 쪽이 둘 이상이기 때문이다:

클래스 가지는 것
dev.caskeleton.buildlogic.ModuleRegistry config/architecture/modules.json을 읽고 검증하기
dev.caskeleton.buildlogic.RequiredTestExecution 「이 빌드가 이름을 댄 시험은 실제로 돌았어야 한다」는 단 하나의 판정
dev.caskeleton.buildlogic.JavaPublicTypes 공개 최상위 타입. 정규식으로 맞추지 않고 javac로 파싱한다

JMH benchmark는 커뮤니티 플러그인 me.champeau.jmh를 쓴다. ca.quality-conventions는 benchmark와 생성된 코드에서 Error Prone, -Werror, SpotBugs, Checkstyle을 끄기만 한다.

지운 것과 그것을 대신하는 것

지운 것 대신하는 것
ca.runtime-membership 방향 게이트: allowed_dependencies 밖의 것은 조립 루트에 닿을 수 없다
ca.evidence, ca.conditional-transport-qualification, ca.strict-qualification requires + rejectSkipped를 쓴 strictTestLanes lane. 루트 conditionalTransportQualification과 verifyMessagingContracts는 그 lane을 묶기만 한다
ca.dependency-policy leaf 안의 componentSelection 거절 규칙(notification: YAML dataformat, messaging: Jackson 2와 모든 YAML 모듈)과 registry(web-advanced는 허용된 소비자가 없다). rejectAll() 제약도 써 봤지만 실패하지 않는다: Spring의 의존성 관리가 거절한 버전을 덮어쓴다
ca.graphql-platform GraphQL leaf의 graphqlStableTest lane과 GraphQlProductionClassesTest
ca.jpa-test-lanes adapter/outbound/persistence-jpa/build.gradle에 선언한 lane
ca.test-jvm-agents, quarantineTest ca.java-conventions. quarantine 묶음에는 시험이 없었다
ca.jmh-benchmarks me.champeau.jmh
build-tools ca.jpa-evidence, ca.jpa-qualification(+ junit 증거 읽기) 소유자 결정 4: persistence-jpa JpaReadinessRegistryTest, 인용한 시나리오를 모두 요구하고 건너뛰기를 거절하는 readiness lane, config/jpa/release-registry.json을 묶는 leaf의 jpaReleaseQualification
build-tools ca.config-contract 바꾸지 않고 여기로 옮겼다
ca.public-path-snapshot app-bootstrap PublicPathSnapshotTest(lane publicPathSnapshotTest, 루트 별칭 verifyPublicPathSnapshot)
ca.archive-hygiene 치울 것이 없다: leaf 버전이 더는 revision을 싣지 않으니 낡은 추적 가능 jar가 생기지 않는다
ca.developer-bootstrap scripts/bootstrap-local.sh
JpaAdopterApiSurfaceTest(persistence-jpa의 정규식 import 검사) ca.api-surface adopterBaseline

규약 시험하기

cd src
./gradlew -p build-logic test --console=plain

lane과 registry 규약은 플러그인 소스를 읽는 대신 Gradle TestKit으로 실제 빌드에 대고 시험한다. 중요한 성질 — 아무것도 찾지 못한 lane은 실패한다, lane은 클래스와 lane 정책(rejectSkipped, requires, tag, category)이 바뀌지 않았고 서버를 띄우지 않을 때만 결과를 다시 쓴다, 잘못된 registry는 어떤 프로젝트도 포함하기 전에 거절된다 — 이 스크립트의 글이 아니라 런타임 동작이기 때문이다. 그중 시험 둘은 Gradle 문서를 그대로 읽으면 틀렸기 때문에 있다: tag 필터가 아무것도 맞추지 못할 때 failOnNoDiscoveredTests가 동작하지 않고, 이름을 댄 시험 중 일부만 없을 때 failOnNoMatchingTests가 동작하지 않는다.