Files
clean-architecture-backend-…/build-logic/AGENTS.md
T
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 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
2026-11-11 22:15:42 +09:00

5.4 KiB

build-logic — Gradle 정책 권위

registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 적는다. build-logic/, settings.gradle, build.gradle, gradle/modules.json을 고칠 때 읽는다. 루트 AGENTS.md HARD-STOP 5가 이 문서보다 먼저다. 게이트 고르기와 실행 위치는 docs/work/reference/gates.md다.

정본 넷

  • gradle/modules.json: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge, 그리고 별도 repo 라이브러리 edge(맨 위 library_groups, 행마다 allowed_libraries. 계층 leaf 행은 비워 둔다. 설명은 gradle/README.md). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 allowed_dependencies가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(verifyDocumentedLeafCount)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 build.gradle을 정규식으로 훑는 파서였다.
  • settings.gradle: ca.architecture-registry 설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 verifyCleanArchitectureDependencies가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다.
  • build-logic/: 아키텍처 코어(registry, 방향·순수성 task), 컨벤션, 테스트 레인 하나(strictTestLanes). leaf는 ca.java-library·ca.spring-library·ca.platform-module 중 자기 성격을 선언하고, 그 플러그인이 toolchain·락·정적분석·테스트 기본값을 준다. ca.architecture가 아키텍처 검증 태스크를 가진다. 기능별 검사(notification·mongo·messaging·graphql·JPA readiness 등)는 build-logic이 아니라 그 leaf의 테스트다.
  • build.gradle: 루트 라이프사이클(ci, prCheck, mainCheck, integrationCheck, performanceCheck, releaseCheck, qualityCheck, configContractCheck)과 그것을 workflow job에 묶는 strictLaneStages, 버전·리비전.

저장소 파일을 읽는 테스트

  • 테스트가 저장소 파일을 읽으면 그 파일을 그 leaf의 test task inputs로 선언한다.
  • 저장소 문서와 대조하는 테스트는 mainStage() 레인(document-contract 태그)으로 leaf mainCheck에서 돈다.
  • 문서가 아닌 저장소 파일(빌드 스크립트, workflow, Compose, 다른 leaf 소스)을 읽어야 merge 전에 막을 수 있는 계약은 그 파일만 입력으로 둔 별도 레인(app-bootstrap repository-contract)에 둔다.
  • 저장소 루트(ca.repository.root)는 이 두 레인에만 준다. 그래서 태그 없이 저장소를 읽는 테스트는 test에서 실패한다.
  • 문서를 파싱해 대조하는 Gradle 검사는 두지 않는다. 문서 검사는 Gradle 밖 scripts/check-docs.py·scripts/check-work-docs.py다.

lane 캐시와 성능 lane

  • TEST·ARCHITECTURE lane은 입력이 같으면 up-to-date·build cache를 쓴다. INTEGRATION·SYSTEM·PERFORMANCE lane과 mainStage() lane은 이미지·네트워크·시간·문서처럼 입력으로 잡히지 않는 것에 기대므로 매번 다시 돈다. hermetic lane이 저장소 파일을 읽으면 그 파일을 입력으로 선언해야 캐시가 거짓 통과를 내지 않는다.
  • PERFORMANCE lane은 상한을 매번 단언한다. 끄는 스위치가 없다. convention이 테스트 JVM에 performance.assertions.enabled=true를 넣고, 빌드(-P·GRADLE_OPTS)나 lane이 다른 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(rejectSkipped를 따로 쓰지 않아도). 사람이 손으로 돌리는 ./gradlew performanceCheck와 workflow가 같은 상한을 단언한다.
  • verifyEnvKeys는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의 ca.config-contract다.

단계 job의 모양

  • verifyStrictLaneStages --dry-run(PR)은 explicitOnly가 아닌 strict lane마다 build.gradle의 strictLaneStages가 선언한 단계 태스크 하나의 계획에 들어 있는지 본다(그래프 검사).
  • 단계마다 선언한 workflow job은 step의 run: ./gradlew <단계> <옵션> 줄을 가지고, 다른 step run:도 셸 문법 없는 ./gradlew 한 줄이며, 선언 밖의 if:, 선언한 조건이 !cancelled()·always()가 아닌데 needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 이 빌드 밖의 working-directory가 없다. workflow는 선언한 이벤트로, 선언한 필터 한 줄만 달고 시작하고, PR 단계 job 하나가 이 검사를 돌린다(형식 검사, 셸을 해석하지 않는다).
  • 단계를 더하거나 job을 바꾸면 strictLaneStages의 stage 줄과 workflow를 같은 커밋에서 고친다.

테스트

  • ./gradlew -p build-logic test --console=plain(저장소 루트에서). build-logic은 Spotless 대상이 아니다. 편집 훅도 이 폴더의 Java를 포맷하지 않는다.