Merge pull request 'refactor(layout)!: Gradle 루트를 저장소 루트로 옮기고 src/에는 계층 코드만 둔다' (#10) from claude/t2b-relayout-e435ee into main
main / main (push) Failing after 16m36s
main / integration (push) Failing after 22m20s
main / build-logic (push) Successful in 2m8s
main / configuration-cache (push) Successful in 2m58s
main / links (push) Failing after 8s
main / vulnerabilities (push) Successful in 1m9s
main / http3-experimental (push) Successful in 2m22s
main / jpa-postgresql (16) (push) Skipped
main / jpa-postgresql (17) (push) Skipped
main / jpa-postgresql (18) (push) Skipped
main / httpclient-transport (apache) (push) Skipped
main / httpclient-transport (jdk) (push) Skipped
main / redis-topology (7.2, sentinel) (push) Skipped
main / redis-topology (7.2, standalone) (push) Skipped
main / redis-topology (7.4, sentinel) (push) Skipped
main / redis-topology (7.4, tls) (push) Skipped
main / redis-topology (8.2, sentinel) (push) Skipped
main / redis-topology (8.2, standalone) (push) Skipped
main / fileserver-nfs-ambiguity (push) Skipped
main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
main / compose-smoke (push) Skipped
main / redis-topology (7.2, cluster) (push) Skipped
main / redis-topology (7.4, cluster) (push) Skipped
main / redis-topology (7.4, standalone) (push) Skipped
main / redis-topology (8.2, cluster) (push) Skipped
main / redis-topology (8.2, tls) (push) Skipped
main / notification-chaos (push) Skipped
main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
main / object-storage-aws (push) Skipped
main / performance (push) Canceled after 0s

This commit was merged in pull request #10.
This commit is contained in:
2026-11-11 16:13:47 +00:00
1721 changed files with 1106 additions and 960 deletions
+1 -1
View File
@@ -12,7 +12,7 @@ model: inherit
## 순서 ## 순서
1. 루트 `AGENTS.md`의 HARD-STOP과 지도를 읽는다. 1. 루트 `AGENTS.md`의 HARD-STOP과 지도를 읽는다.
2. 바뀐 파일마다 registry `src/config/architecture/modules.json`의 `source_path`로 leaf를 찾고, 가장 가까운 `AGENTS.md`(leaf, family)를 읽는다. 2. 바뀐 파일마다 registry `gradle/modules.json`의 `source_path`로 leaf를 찾고, 가장 가까운 `AGENTS.md`(leaf, family)를 읽는다.
3. 운영 소스의 import를 본다: 순수성(`domain-core`·`application-*`·`shared-contract`의 framework import), inbound의 repository·Spring Data·entity 사용, inbound DTO가 core로 들어가는지, `dev.caskeleton.*` 주인 leaf가 `allowed_dependencies`(전이 포함)에 있는지. 3. 운영 소스의 import를 본다: 순수성(`domain-core`·`application-*`·`shared-contract`의 framework import), inbound의 repository·Spring Data·entity 사용, inbound DTO가 core로 들어가는지, `dev.caskeleton.*` 주인 leaf가 `allowed_dependencies`(전이 포함)에 있는지.
4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 가지 않았는지 본다(HARD-STOP 4). 이것은 import로 안 보이니 코드를 읽는다. 4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 가지 않았는지 본다(HARD-STOP 4). 이것은 import로 안 보이니 코드를 읽는다.
5. `build.gradle`·registry를 바꿨으면 새 edge가 registry에 있고 방향 그림(`app-bootstrap → adapter → application-core → domain-core`)을 거스르지 않는지 본다. 5. `build.gradle`·registry를 바꿨으면 새 edge가 registry에 있고 방향 그림(`app-bootstrap → adapter → application-core → domain-core`)을 거스르지 않는지 본다.
+1 -1
View File
@@ -23,6 +23,6 @@ GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 by
## 코드만 보고는 헷갈리는 것 ## 코드만 보고는 헷갈리는 것
- 저장소 파일을 읽는 테스트는 태그가 있어야 한다. 문서와 대조하면 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow·Compose를 읽으면 `repository-contract`(PR)다. 태그 없이 저장소를 읽으면 `test`에서 실패한다. 이유는 `src/build-logic/AGENTS.md` 「저장소 파일을 읽는 테스트」다. - 저장소 파일을 읽는 테스트는 태그가 있어야 한다. 문서와 대조하면 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow·Compose를 읽으면 `repository-contract`(PR)다. 태그 없이 저장소를 읽으면 `test`에서 실패한다. 이유는 `build-logic/AGENTS.md` 「저장소 파일을 읽는 테스트」다.
- 성능 lane에는 단언을 끄는 스위치가 없다. `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 하나라도 있으면 테스트 전에 실패한다. - 성능 lane에는 단언을 끄는 스위치가 없다. `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 하나라도 있으면 테스트 전에 실패한다.
- 테스트는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절). - 테스트는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절).
+6 -6
View File
@@ -6,13 +6,13 @@ paths:
- "src/**/application*.yml" - "src/**/application*.yml"
- "src/**/application*.yaml" - "src/**/application*.yaml"
- "src/**/config/module-defaults/**" - "src/**/config/module-defaults/**"
- "src/.env.example" - ".env.example"
- "src/.env.local.example" - ".env.local.example"
- "src/Dockerfile" - "Dockerfile"
- "compose.yaml" - "compose.yaml"
- "compose/**" - "compose/**"
- "src/**/compose/**" - "src/**/compose/**"
- "src/app-bootstrap/compose-lanes/**" - "src/bootstrap/app/compose-lanes/**"
--- ---
# 설정과 런타임 규칙 # 설정과 런타임 규칙
@@ -23,12 +23,12 @@ paths:
- 새 설정 그룹은 typed settings class로 만든다. 흩어진 `@Value`보다 configuration properties와 settings class를 쓴다. - 새 설정 그룹은 typed settings class로 만든다. 흩어진 `@Value`보다 configuration properties와 settings class를 쓴다.
- 새 settings class를 만들면 바인딩·값 검증 테스트를 더한다. - 새 settings class를 만들면 바인딩·값 검증 테스트를 더한다.
- capability 모듈의 설정 prefix는 하나다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact constructor다(`docs/manual/10-capabilities.md` 기준 4, Redis 예외 포함). - capability 모듈의 설정 prefix는 하나다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact constructor다(`docs/manual/10-capabilities.md` 기준 4, Redis 예외 포함).
- `src/.env.local`은 로컬 덮어쓰기다. 실제 `.env` 파일은 읽지도 고치지도 않는다(권한 설정이 막는다). 키 계약은 `src/.env.example`과 `docs/registries/env-keys.yaml`이다. - `.env.local`은 로컬 덮어쓰기다. 실제 `.env` 파일은 읽지도 고치지도 않는다(권한 설정이 막는다). 키 계약은 `.env.example`과 `docs/registries/env-keys.yaml`이다.
- `application.yml`은 환경마다 안전한 기본값과 분명한 자리표시자만 담는다. - `application.yml`은 환경마다 안전한 기본값과 분명한 자리표시자만 담는다.
## Docker·Compose ## Docker·Compose
- `src/Dockerfile`을 바꾸면 build context와 runtime env 요구사항을 함께 확인한다. - `Dockerfile`을 바꾸면 build context와 runtime env 요구사항을 함께 확인한다.
- container 안에서 필요한 profile, port, env 키를 문서나 예시 설정에 반영한다. - container 안에서 필요한 profile, port, env 키를 문서나 예시 설정에 반영한다.
- local 전용 경로와 운영 경로를 섞지 않는다. 개발 환경 compose는 루트 `compose.yaml` 하나다(「개발 환경」과 lane overlay의 차이는 `docs/work/reference/terms.md`). 테스트 환경(compose, 스크립트)은 그 lane을 가진 leaf 안에 둔다. 배포 매니페스트·프록시 설정·IaC는 이 repo에 두지 않는다(`docs/ci-cd/boundary.md`). - local 전용 경로와 운영 경로를 섞지 않는다. 개발 환경 compose는 루트 `compose.yaml` 하나다(「개발 환경」과 lane overlay의 차이는 `docs/work/reference/terms.md`). 테스트 환경(compose, 스크립트)은 그 lane을 가진 leaf 안에 둔다. 배포 매니페스트·프록시 설정·IaC는 이 repo에 두지 않는다(`docs/ci-cd/boundary.md`).
- Docker는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절). - Docker는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절).
+1 -1
View File
@@ -9,7 +9,7 @@ description: 이 백엔드 템플릿에 새 업무 기능(도메인 개념, 유
1. `docs/work/README.md`와 `docs/work/new-feature.md`를 끝까지 읽는다. 크기를 정한다. 새 capability 모듈, 새 leaf, 새 공개 계약(HTTP 경로·오류 코드·env 키)은 큼이다. 큼이면 만들기 전에 `docs/work/research-design.md`대로 소유자 검토를 받는다. 1. `docs/work/README.md`와 `docs/work/new-feature.md`를 끝까지 읽는다. 크기를 정한다. 새 capability 모듈, 새 leaf, 새 공개 계약(HTTP 경로·오류 코드·env 키)은 큼이다. 큼이면 만들기 전에 `docs/work/research-design.md`대로 소유자 검토를 받는다.
2. 받을 것을 확인한다: 기능 이름(PascalCase), 저장소 선택(어떤 persistence leaf, migration 번호대), 권한, 재전송될 수 있는 쓰기인지. 저장소 선택은 사람이 정한다. brief에 없으면 묻는다. 2. 받을 것을 확인한다: 기능 이름(PascalCase), 저장소 선택(어떤 persistence leaf, migration 번호대), 권한, 재전송될 수 있는 쓰기인지. 저장소 선택은 사람이 정한다. brief에 없으면 묻는다.
3. 배치를 정한다(`docs/manual/03-placement.md`). 이름이 템플릿 패키지(`src/application-core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않는지 본다. 3. 배치를 정한다(`docs/manual/03-placement.md`). 이름이 템플릿 패키지(`src/application/core/README.md` 「패키지 소유 (Package ownership)」)와 겹치지 않는지 본다.
4. 뼈대: 노트북에서는 `scripts/new-feature.sh <FeatureName> --no-format`. 포맷은 편집 훅이 파일마다 맞추고, 마지막에 desktop `./gradlew spotlessApply`로 한 번 더 본다. 4. 뼈대: 노트북에서는 `scripts/new-feature.sh <FeatureName> --no-format`. 포맷은 편집 훅이 파일마다 맞추고, 마지막에 desktop `./gradlew spotlessApply`로 한 번 더 본다.
5. 안쪽부터 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립(`docs/manual/02-new-feature.md`). 필요한 장만 더 읽는다: 저장 04, 재시도될 쓰기 05, 오류 06, 권한 07, 테스트 08, 이벤트 09, capability 10. 5. 안쪽부터 채운다: domain-core → application-core → outbound adapter → inbound adapter → app-bootstrap 조립(`docs/manual/02-new-feature.md`). 필요한 장만 더 읽는다: 저장 04, 재시도될 쓰기 05, 오류 06, 권한 07, 테스트 08, 이벤트 09, capability 10.
6. 동작은 테스트를 먼저 쓴다(`.claude/rules/java-tests.md`). 포트마다 fake 하나와 공유 계약(`XxxContract`)을 포트 소유 leaf의 testFixtures에 두고, 실제 adapter도 실 DB lane에서 같은 계약을 상속한다. 6. 동작은 테스트를 먼저 쓴다(`.claude/rules/java-tests.md`). 포트마다 fake 하나와 공유 계약(`XxxContract`)을 포트 소유 leaf의 testFixtures에 두고, 실제 adapter도 실 DB lane에서 같은 계약을 상속한다.
+54
View File
@@ -0,0 +1,54 @@
# feature-container-runtime-contract — .dockerignore for the repository-root build context
#
# The docker build context is the repository root, which is the Gradle root. The builder stage needs
# the Gradle build and the code, nothing else: not the documentation, the CI files, the development
# Compose environment or the scripts. So this file lets in only what the build reads (the first
# block), then takes the build noise back out of it (the rest). Rules apply in order and the last
# match wins.
# ---- What the builder reads ------------------------------------------------
# Everything at the top is out, then the Gradle build is let back in: the wrapper, the root build
# scripts and their settings lockfile, gradle/ (wrapper, version catalog, module registry, test-image
# list), the convention plugins, the code-check tool settings and the layer code.
*
!gradlew
!gradlew.bat
!gradle/
!gradle.properties
!settings.gradle
!settings-gradle.lockfile
!build.gradle
!build-logic/
!config/
!src/
# The env contract examples, which were in the context while it was src/. No real .env: see below.
!.env.example
!.env.local.example
# ---- Gradle build output ----------------------------------------------------
# Exclude all module build/ directories; the builder stage produces them inside the container.
**/build/
**/.gradle/
**/bin/
# ---- IDE / editor files -----------------------------------------------------
**/.idea/
**/*.iml
**/.vscode/
**/.project
**/.classpath
**/.settings/
# ---- Environment / secrets (NEVER bake secrets into image layers) -----------
**/.env
**/*.env
**/.env.lane
# ---- OS artifacts -----------------------------------------------------------
**/.DS_Store
**/Thumbs.db
# ---- Test reports and coverage ----------------------------------------------
**/test-results/
**/reports/
**/jacoco/
+3 -3
View File
@@ -1,8 +1,8 @@
# ============================================================================= # =============================================================================
# The public catalogue of every environment variable this application reads. # The public catalogue of every environment variable this application reads.
# #
# Generated from docs/registries/env-keys.yaml, which is the SSOT. Copy this file to src/.env and # Generated from docs/registries/env-keys.yaml, which is the SSOT. Copy this file to .env and
# fill in the values your deployment needs; src/.env is gitignored because it is operator input, # fill in the values your deployment needs; .env is gitignored because it is operator input,
# not a build input. # not a build input.
# #
# Secret-classified keys are left empty on purpose. An example that carries a working credential # Secret-classified keys are left empty on purpose. An example that carries a working credential
@@ -156,7 +156,7 @@ APP_REDIS_TIMEOUT_SCRIPT=1s
# reference empty and anonymous access not accepted, the application refuses to start while Redis # reference empty and anonymous access not accepted, the application refuses to start while Redis
# is on; with the advanced one empty, scripts run as the application account and startup warns. The # is on; with the advanced one empty, scripts run as the application account and startup warns. The
# Compose Redis lanes connect as the fixture accounts of compose/redis/acl/lane-fixture-accounts.acl (the # Compose Redis lanes connect as the fixture accounts of compose/redis/acl/lane-fixture-accounts.acl (the
# Redis comment in src/app-bootstrap/compose-lanes/compose-profile-contracts.json). # Redis comment in src/bootstrap/app/compose-lanes/compose-profile-contracts.json).
APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE= APP_REDIS_AUTHENTICATION_ADVANCED_CREDENTIAL_REFERENCE=
APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED=false APP_REDIS_AUTHENTICATION_ANONYMOUS_ACCESS_ACCEPTED=false
APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE= APP_REDIS_AUTHENTICATION_CREDENTIAL_REFERENCE=
@@ -1,8 +1,8 @@
# ============================================================================= # =============================================================================
# A local example for a service that selected some capabilities. Copy to src/.env.local and edit. # A local example for a service that selected some capabilities. Copy to .env.local and edit.
# #
# The default composition is web-only. A capability is on when its runtimeOnly line in # The default composition is web-only. A capability is on when its runtimeOnly line in
# app-bootstrap/build.gradle is uncommented, and each needs the infrastructure its Compose profile # src/bootstrap/app/build.gradle is uncommented, and each needs the infrastructure its Compose profile
# provides. The values below are what each one needs once selected; a missing required value is # provides. The values below are what each one needs once selected; a missing required value is
# refused at startup, naming the key. APP_*_ENABLED=false turns a selected capability off. # refused at startup, naming the key. APP_*_ENABLED=false turns a selected capability off.
# ============================================================================= # =============================================================================
@@ -17,7 +17,7 @@ APP_DATASOURCE_USERNAME=ca_skeleton
APP_DATASOURCE_PASSWORD= APP_DATASOURCE_PASSWORD=
APP_DATASOURCE_DDL_AUTO=validate APP_DATASOURCE_DDL_AUTO=validate
# Messaging (Kafka): on when app-bootstrap/build.gradle carries # Messaging (Kafka): on when src/bootstrap/app/build.gradle carries
# `runtimeOnly project(':adapter:outbound:messaging-kafka')`; APP_MESSAGING_ENABLED=false turns it off. # `runtimeOnly project(':adapter:outbound:messaging-kafka')`; APP_MESSAGING_ENABLED=false turns it off.
APP_MESSAGING_KAFKA_BROKERS=localhost:9092 APP_MESSAGING_KAFKA_BROKERS=localhost:9092
@@ -25,14 +25,14 @@ APP_MESSAGING_KAFKA_BROKERS=localhost:9092
APP_OUTBOX_ENABLED=false APP_OUTBOX_ENABLED=false
APP_OUTBOX_RELAY_ENABLED=false APP_OUTBOX_RELAY_ENABLED=false
# Mongo: on when its runtimeOnly line is in app-bootstrap/build.gradle. active-profile is required # Mongo: on when its runtimeOnly line is in src/bootstrap/app/build.gradle. active-profile is required
# and selects exactly one client. # and selects exactly one client.
APP_PERSISTENCE_MONGO_ACTIVE_PROFILE=standard-uri APP_PERSISTENCE_MONGO_ACTIVE_PROFILE=standard-uri
SPRING_MONGODB_URI=mongodb://localhost:27017/ca_skeleton SPRING_MONGODB_URI=mongodb://localhost:27017/ca_skeleton
# GraphQL: on when its runtimeOnly line is in app-bootstrap/build.gradle. The deployment mode must # GraphQL: on when its runtimeOnly line is in src/bootstrap/app/build.gradle. The deployment mode must
# match the runtime environment (local -> LOCAL). # match the runtime environment (local -> LOCAL).
APP_GRAPHQL_DEPLOYMENT_MODE=LOCAL APP_GRAPHQL_DEPLOYMENT_MODE=LOCAL
# Notification: on when its line and the persistence-jpa line are selected (it stores requests # Notification: on when its line and the persistence-jpa line are selected (it stores requests
# relationally). It then needs the eight key purposes and their ids listed in src/.env.example. # relationally). It then needs the eight key purposes and their ids listed in .env.example.
+5 -12
View File
@@ -7,7 +7,7 @@
# machine nothing else is using: the runner takes one job at a time, and `needs` puts them after # machine nothing else is using: the runner takes one job at a time, and `needs` puts them after
# every other heavy job (owner decision 2026-11-07). # every other heavy job (owner decision 2026-11-07).
# #
# Which lanes a stage means is decided by its Gradle task (src/build.gradle). The stage jobs # Which lanes a stage means is decided by its Gradle task (build.gradle). The stage jobs
# (`main`, `integration`, `performance`) run it as one line; `verifyStrictLaneStages` fails a pull # (`main`, `integration`, `performance`) run it as one line; `verifyStrictLaneStages` fails a pull
# request that changes that line, its condition, or adds a way for it to pass quietly. # request that changes that line, its condition, or adds a way for it to pass quietly.
name: main name: main
@@ -32,10 +32,6 @@ concurrency:
group: main-${{ github.ref }} group: main-${{ github.ref }}
cancel-in-progress: false cancel-in-progress: false
defaults:
run:
working-directory: src
env: env:
# Reuse would hand one lane a container another lane had already faulted. # Reuse would hand one lane a container another lane had already faulted.
TESTCONTAINERS_REUSE_ENABLE: "false" TESTCONTAINERS_REUSE_ENABLE: "false"
@@ -79,7 +75,7 @@ jobs:
steps: steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle - uses: ./.gitea/actions/setup-java-gradle
- run: bash ../scripts/ci/verify-configuration-cache.sh - run: bash scripts/ci/verify-configuration-cache.sh
# Every committed Markdown link, external URLs included. A documentation check, so the main stage # Every committed Markdown link, external URLs included. A documentation check, so the main stage
# (owner decision 2026-09-16); scripts/check-docs.py checks the relative links on every pull request. # (owner decision 2026-09-16); scripts/check-docs.py checks the relative links on every pull request.
@@ -95,7 +91,7 @@ jobs:
--no-progress --no-progress
--root-dir . --root-dir .
README.md README.md
src/README.md docs/build.md
'src/**/README.md' 'src/**/README.md'
'src/**/CLAUDE.md' 'src/**/CLAUDE.md'
'docs/**/*.md' 'docs/**/*.md'
@@ -110,7 +106,6 @@ jobs:
steps: steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- run: bash scripts/ci/trivy-scan.sh filesystem - run: bash scripts/ci/trivy-scan.sh filesystem
working-directory: .
# Experimental by design: the result is reported, never used to block anything. # Experimental by design: the result is reported, never used to block anything.
http3-experimental: http3-experimental:
@@ -182,7 +177,6 @@ jobs:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.gitea/actions/setup-java-gradle - uses: ./.gitea/actions/setup-java-gradle
- run: bash scripts/ci/redis-topology.sh ${{ matrix.topology }} ${{ matrix.redis }} - run: bash scripts/ci/redis-topology.sh ${{ matrix.topology }} ${{ matrix.redis }}
working-directory: .
# The one fileserver environment a pull request cannot provide: a real NFSv4 server. # The one fileserver environment a pull request cannot provide: a real NFSv4 server.
fileserver-nfs-ambiguity: fileserver-nfs-ambiguity:
@@ -272,7 +266,7 @@ jobs:
- uses: ./.gitea/actions/setup-java-gradle - uses: ./.gitea/actions/setup-java-gradle
- run: ./gradlew :adapter:outbound:objectstorage:objectStorageAwsQualificationTest - run: ./gradlew :adapter:outbound:objectstorage:objectStorageAwsQualificationTest
# Every blocking Compose runtime lane, on the qualification image (src/Dockerfile # Every blocking Compose runtime lane, on the qualification image (Dockerfile
# COMPOSITION=qualification: every capability module present). # COMPOSITION=qualification: every capability module present).
compose-smoke: compose-smoke:
if: ${{ github.event_name != 'push' }} if: ${{ github.event_name != 'push' }}
@@ -280,8 +274,7 @@ jobs:
timeout-minutes: 180 timeout-minutes: 180
steps: steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- run: bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json - run: bash scripts/run-compose-runtime-smoke.sh --matrix src/bootstrap/app/compose-lanes/compose-profile-contracts.json
working-directory: .
# Load, slow-client, shutdown, pool and resource bounds. Last, after every other heavy job of the # Load, slow-client, shutdown, pool and resource bounds. Last, after every other heavy job of the
# run, so the bounds are measured on a runner that is not building something else. # run, so the bounds are measured on a runner that is not building something else.
+1 -7
View File
@@ -1,6 +1,6 @@
# Pull-request stage. Everything here blocks a merge, and the branch protection requires one check: # Pull-request stage. Everything here blocks a merge, and the branch protection requires one check:
# `done`. Which leaves, lanes and checks the stage means is decided by the Gradle task `prCheck` # `done`. Which leaves, lanes and checks the stage means is decided by the Gradle task `prCheck`
# (src/build.gradle), not here; `verifyStrictLaneStages` fails when this job stops running it as one # (build.gradle), not here; `verifyStrictLaneStages` fails when this job stops running it as one
# line (docs/work/reference/gates.md). # line (docs/work/reference/gates.md).
# #
# The adapter container lanes are not here: they run in main.yml on every push to main (owner # The adapter container lanes are not here: they run in main.yml on every push to main (owner
@@ -18,10 +18,6 @@ concurrency:
group: pr-${{ github.ref }} group: pr-${{ github.ref }}
cancel-in-progress: true cancel-in-progress: true
defaults:
run:
working-directory: src
env: env:
TESTCONTAINERS_REUSE_ENABLE: "false" TESTCONTAINERS_REUSE_ENABLE: "false"
@@ -43,7 +39,6 @@ jobs:
steps: steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- run: bash scripts/ci/trivy-scan.sh filesystem - run: bash scripts/ci/trivy-scan.sh filesystem
working-directory: .
# The one required check. A job added above joins `needs` here, and the branch protection does # The one required check. A job added above joins `needs` here, and the branch protection does
# not change. # not change.
@@ -53,7 +48,6 @@ jobs:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- name: Require every job of this stage to have succeeded - name: Require every job of this stage to have succeeded
working-directory: .
env: env:
RESULTS: ${{ needs.gradle.result }} ${{ needs.vulnerabilities.result }} RESULTS: ${{ needs.gradle.result }} ${{ needs.vulnerabilities.result }}
run: | run: |
+2 -13
View File
@@ -24,10 +24,6 @@ concurrency:
group: release-${{ github.ref }} group: release-${{ github.ref }}
cancel-in-progress: false cancel-in-progress: false
defaults:
run:
working-directory: src
env: env:
TESTCONTAINERS_REUSE_ENABLE: "false" TESTCONTAINERS_REUSE_ENABLE: "false"
@@ -88,7 +84,6 @@ jobs:
steps: steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- run: python3 scripts/verify-httpclient-docs.py - run: python3 scripts/verify-httpclient-docs.py
working-directory: .
# One job per Stable PostgreSQL major: one job for three majors was one job for one major, because # One job per Stable PostgreSQL major: one job for three majors was one job for one major, because
# the platform starts only the first selected version. persistence-jpa's # the platform starts only the first selected version. persistence-jpa's
@@ -167,9 +162,6 @@ jobs:
pinned_reference: ${{ steps.push.outputs.pinned_reference }} pinned_reference: ${{ steps.push.outputs.pinned_reference }}
runs-on: ubuntu-latest runs-on: ubuntu-latest
timeout-minutes: 90 timeout-minutes: 90
defaults:
run:
working-directory: .
steps: steps:
- uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2 - uses: https://github.com/actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
# The tag is the release identity; a tag that does not parse stops the release here. A manual # The tag is the release identity; a tag that does not parse stops the release here. A manual
@@ -205,7 +197,7 @@ jobs:
SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)" SOURCE_DATE_EPOCH="$(git log -1 --format=%ct)"
export SOURCE_DATE_EPOCH export SOURCE_DATE_EPOCH
DOCKER_BUILDKIT=1 docker build \ DOCKER_BUILDKIT=1 docker build \
--file src/Dockerfile \ --file Dockerfile \
--tag "${IMAGE_REPOSITORY}:${RELEASE_VERSION}" \ --tag "${IMAGE_REPOSITORY}:${RELEASE_VERSION}" \
--tag "${IMAGE_REPOSITORY}:sha-${GITHUB_SHA}" \ --tag "${IMAGE_REPOSITORY}:sha-${GITHUB_SHA}" \
--build-arg RELEASE_VERSION="${RELEASE_VERSION}" \ --build-arg RELEASE_VERSION="${RELEASE_VERSION}" \
@@ -213,7 +205,7 @@ jobs:
--build-arg GIT_SHA="${GITHUB_SHA}" \ --build-arg GIT_SHA="${GITHUB_SHA}" \
--build-arg SOURCE_URL="${SOURCE_URL}" \ --build-arg SOURCE_URL="${SOURCE_URL}" \
--label org.opencontainers.image.created="$(git log -1 --format=%cI)" \ --label org.opencontainers.image.created="$(git log -1 --format=%cI)" \
src .
# The SBOM is printed and kept in the log before the blocking scan, so the inventory of an image # The SBOM is printed and kept in the log before the blocking scan, so the inventory of an image
# that is refused still exists. A vulnerable image is never pushed: the push comes after. # that is refused still exists. A vulnerable image is never pushed: the push comes after.
- name: Inventory and scan the release image - name: Inventory and scan the release image
@@ -249,9 +241,6 @@ jobs:
if: ${{ github.ref_type == 'tag' }} if: ${{ github.ref_type == 'tag' }}
runs-on: ubuntu-latest runs-on: ubuntu-latest
timeout-minutes: 30 timeout-minutes: 30
defaults:
run:
working-directory: .
env: env:
PINNED_REFERENCE: ${{ needs.app-image-release.outputs.pinned_reference }} PINNED_REFERENCE: ${{ needs.app-image-release.outputs.pinned_reference }}
steps: steps:
+1 -1
View File
@@ -9,6 +9,6 @@
# Public security and compatibility baselines require an explicit maintainer review. # Public security and compatibility baselines require an explicit maintainer review.
/docs/security/ @DongHyeonka /docs/security/ @DongHyeonka
/src/config/architecture/modules.json @DongHyeonka /gradle/modules.json @DongHyeonka
*.approved.json @DongHyeonka *.approved.json @DongHyeonka
*.approved.txt @DongHyeonka *.approved.txt @DongHyeonka
+1 -1
View File
@@ -79,7 +79,7 @@ mirror가 살아 있고 최신인지는 운영이 챙길 의존이다. 낡은 mi
Renovate가 저장소에 커밋된 보안 갱신 봇 설정이다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다 Renovate가 저장소에 커밋된 보안 갱신 봇 설정이다. 보안 갱신은 갱신 종류와 상관없이 자동 병합하지 않는다
(`renovate.json`의 `automerge: false`). Renovate는 strict lockfile을 다시 만들지 않는다. 관리자가 (`renovate.json`의 `automerge: false`). Renovate는 strict lockfile을 다시 만들지 않는다. 관리자가
`cd src && ./gradlew resolveAndLockAll --write-locks`로 잠금을 다시 만들고, 잠금 diff를 검토해 함께 `./gradlew resolveAndLockAll --write-locks`로 잠금을 다시 만들고, 잠금 diff를 검토해 함께
커밋한다. 의존성 선언과 모든 `gradle.lockfile`은 같이 움직이고, `verifyDependencyLocks`는 계속 릴리스를 커밋한다. 의존성 선언과 모든 `gradle.lockfile`은 같이 움직이고, `verifyDependencyLocks`는 계속 릴리스를
막는다. 막는다.
+1 -1
View File
@@ -5,7 +5,7 @@
## 검증 ## 검증
- [ ] 바꾼 모듈마다 `:<changed-leaf>:check`를 돌렸다. - [ ] 바꾼 모듈마다 `:<changed-leaf>:check`를 돌렸다.
- [ ] 저장소 구조·의존성·공개 경로를 건드렸으면 `cd src && ./gradlew architectureCheck verifyPublicPathSnapshot verifyDependencyLocks`를 돌렸다. - [ ] 저장소 구조·의존성·공개 경로를 건드렸으면 `./gradlew architectureCheck verifyPublicPathSnapshot verifyDependencyLocks`를 돌렸다.
- [ ] registry에 없는 production 모듈 의존을 더하지 않았다. - [ ] registry에 없는 production 모듈 의존을 더하지 않았다.
- [ ] 의존성을 바꿨으면 다시 만든 `gradle.lockfile`과 strict lock 검증을 함께 넣었다. - [ ] 의존성을 바꿨으면 다시 만든 `gradle.lockfile`과 strict lock 검증을 함께 넣었다.
- [ ] Trivy 예외(suppression)에는 소유자가 검토한 이유와 90일 안의 만료일이 있다. - [ ] Trivy 예외(suppression)에는 소유자가 검토한 이유와 90일 안의 만료일이 있다.
+19 -5
View File
@@ -1,5 +1,17 @@
.vscode/ .vscode/
src/**/bin/ src/**/bin/
# Gradle and IDE output. The wrapper jar is the one binary the build needs from the tree.
.gradle/
build/
!gradle/wrapper/gradle-wrapper.jar
.idea/
*.iml
.project
.classpath
.settings/
# jqwik property-test runtime state
.jqwik-database
.DS_Store
# Local Claude Code state (worktrees, settings.local.json, notes) stays out. The shared project # Local Claude Code state (worktrees, settings.local.json, notes) stays out. The shared project
# settings, path rules, skills and subagent definitions are committed: everyone who opens the repository gets them (CLAUDE.md). # settings, path rules, skills and subagent definitions are committed: everyone who opens the repository gets them (CLAUDE.md).
.claude/* .claude/*
@@ -10,16 +22,18 @@ src/**/bin/
# Operator input, not a build input. The examples beside it are the tracked contract; # Operator input, not a build input. The examples beside it are the tracked contract;
# verifyEnvKeys reads the registry, the profile YAMLs and .env.example, never a real one. # verifyEnvKeys reads the registry, the profile YAMLs and .env.example, never a real one.
src/.env* /.env*
!src/.env.example !/.env.example
!src/.env.local.example !/.env.local.example
# Written per run by the runtime-smoke wrapper; never committed. # Written per run by the runtime-smoke wrapper; never committed.
src/.env.lane /.env.lane
# bootRun's file log when APP_LOG_FILE_ENABLED=true: APP_LOG_FILE_PATH is relative to the repository root.
/logs/
# Local tool output (graphify knowledge graph, Playwright MCP snapshots). # Local tool output (graphify knowledge graph, Playwright MCP snapshots).
graphify-out/ graphify-out/
src/graphify-out/
.playwright-mcp/ .playwright-mcp/
# Python bytecode from running scripts/ checks; never committed. # Python bytecode from running scripts/ checks; never committed.
+6 -6
View File
@@ -1,6 +1,6 @@
# AGENTS.md — 백엔드 템플릿의 정본 # AGENTS.md — 백엔드 템플릿의 정본
Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 `src/gradle/libs.versions.toml`, 기본 패키지 `dev.caskeleton`). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다. 비전 전문은 `docs/vision.md`(소유자가 쓴다), 문제 정의는 `docs/problem-statement.md`다. Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 `gradle/libs.versions.toml`, 기본 패키지 `dev.caskeleton`). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다. 비전 전문은 `docs/vision.md`(소유자가 쓴다), 문제 정의는 `docs/problem-statement.md`다.
## HARD-STOP — 하나라도 어기면 동작해도 완료가 아니다 ## HARD-STOP — 하나라도 어기면 동작해도 완료가 아니다
@@ -14,11 +14,11 @@ Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버
## 지도 ## 지도
- Gradle 루트는 `src/`다. leaf 목록·경로·Gradle path·허용 의존의 정본은 registry `src/config/architecture/modules.json`이다. 문서는 leaf 개수를 적지 않는다. - Gradle 루트는 저장소 루트다. `src/`에는 계층 코드만 있다(`domain/`·`application/`·`adapter/`·`bootstrap/`·`shared-contract/`). leaf 목록·폴더·Gradle path·허용 의존의 정본은 registry `gradle/modules.json`이다. Gradle path는 폴더와 다르다(`:app-bootstrap`은 `src/bootstrap/app`). 문서는 leaf 개수를 적지 않는다.
- 방향: `app-bootstrap → adapter:inbound:*·adapter:outbound:* → application-core → domain-core`, 실행 모듈 → `shared-contract`. 개별 edge는 registry만 정한다. - 방향: `app-bootstrap → adapter:inbound:*·adapter:outbound:* → application-core → domain-core`, 실행 모듈 → `shared-contract`. 개별 edge는 registry만 정한다.
- 지역 규칙은 작업 파일과 가장 가까운 폴더의 `AGENTS.md`다(leaf, family, `src/build-logic`). 테스트·설정·Docker·문서처럼 폴더를 가로지르는 규칙은 `.claude/rules/`다. - 지역 규칙은 작업 파일과 가장 가까운 폴더의 `AGENTS.md`다(leaf, family, `build-logic`). 테스트·설정·Docker·문서처럼 폴더를 가로지르는 규칙은 `.claude/rules/`다.
- 저장소 루트와 `src/` 최상위에는 정해진 것만 둔다(허용 목록은 `scripts/check-repo-layout.py`). 계층이 아닌 라이브러리는 이 repo에 두지 않고 별도 repo에서 버전으로 받는다(`docs/work/reference/related-repos.md`). `src/composition/*`는 조립만 한다. - 저장소 루트와 `src/` 최상위에는 정해진 것만 둔다(허용 목록은 `scripts/check-repo-layout.py`). 계층이 아닌 라이브러리는 이 repo에 두지 않고 별도 repo에서 버전으로 받는다(`docs/work/reference/related-repos.md`). `src/bootstrap/`은 조립 계층이다(조립 루트 `app`과 조립만 하는 `composition:*` leaf).
- capability는 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 켜고 끈다. 기준은 `docs/manual/10-capabilities.md`. 문서 위치 규칙은 `docs/README.md`. - capability는 `src/bootstrap/app/build.gradle`의 `runtimeOnly` 한 줄로 켜고 끈다. 기준은 `docs/manual/10-capabilities.md`. 문서 위치 규칙은 `docs/README.md`.
## 맡은 일 ## 맡은 일
@@ -28,7 +28,7 @@ Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버
- 진입점은 `scripts/verify.sh <단계>`다. 단계 이름은 workflow와 같다(`pr`·`main`·`nightly`·`release`, 그리고 `docs`·`leaf`·`app`·`round`). Gradle·Docker가 드는 단계는 스크립트가 desktop으로 옮겨 잠금 아래에서 돌린다. - 진입점은 `scripts/verify.sh <단계>`다. 단계 이름은 workflow와 같다(`pr`·`main`·`nightly`·`release`, 그리고 `docs`·`leaf`·`app`·`round`). Gradle·Docker가 드는 단계는 스크립트가 desktop으로 옮겨 잠금 아래에서 돌린다.
- leaf 하나: `scripts/verify.sh leaf <gradle-path>`. 경로는 registry의 `gradle_path`다. 기억이나 폴더 이름으로 짐작하지 않는다. - leaf 하나: `scripts/verify.sh leaf <gradle-path>`. 경로는 registry의 `gradle_path`다. 기억이나 폴더 이름으로 짐작하지 않는다.
- 저장소 전체: `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`(그 표면을 바꿨을 때, `src/`에서), 단계 묶음은 `scripts/verify.sh pr` 등. 게이트 고르기는 `docs/work/reference/gates.md`. - 저장소 전체: `./gradlew architectureCheck`, `./gradlew :app-bootstrap:architectureTest`, `verifyPublicPathSnapshot`·`:app-bootstrap:verifyEnvKeys`(그 표면을 바꿨을 때), 단계 묶음은 `scripts/verify.sh pr` 등. 게이트 고르기는 `docs/work/reference/gates.md`.
- 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북에서 돈다). - 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북에서 돈다).
## 일하는 방식 ## 일하는 방식
+8 -8
View File
@@ -3,7 +3,7 @@
# feature-container-runtime-contract — multi-stage image build # feature-container-runtime-contract — multi-stage image build
# #
# Build requirements: # Build requirements:
# docker build -f src/Dockerfile src/ -t caskeleton:local \ # docker build -f Dockerfile . -t caskeleton:local \
# --build-arg RELEASE_VERSION=1.2.3 \ # --build-arg RELEASE_VERSION=1.2.3 \
# --build-arg BUILD_VERSION=1.2.3+a1b2c3d4e5f6 \ # --build-arg BUILD_VERSION=1.2.3+a1b2c3d4e5f6 \
# --build-arg GIT_SHA=a1b2c3d4e5f6 \ # --build-arg GIT_SHA=a1b2c3d4e5f6 \
@@ -29,7 +29,7 @@ FROM eclipse-temurin:21-jdk-jammy@sha256:801b7e1a9c4befaf82bf9a2a58025ef43a7694b
ARG RELEASE_VERSION ARG RELEASE_VERSION
ARG GIT_SHA ARG GIT_SHA
WORKDIR /build/src WORKDIR /build
# Copy the Gradle wrapper and every module's build descriptor + dependency lockfile FIRST, # Copy the Gradle wrapper and every module's build descriptor + dependency lockfile FIRST,
# so the expensive dependency-resolution layer is cached and only re-runs when a build.gradle # so the expensive dependency-resolution layer is cached and only re-runs when a build.gradle
@@ -99,8 +99,8 @@ RUN case "${COMPOSITION}" in \
# every Dockerfile names the exact Gradle-staged artifact path rather than selecting a JAR, and the # every Dockerfile names the exact Gradle-staged artifact path rather than selecting a JAR, and the
# input here is that same fixed path Gradle wrote. Nothing in this stage may pick a JAR by pattern. # input here is that same fixed path Gradle wrote. Nothing in this stage may pick a JAR by pattern.
RUN java -Djarmode=tools \ RUN java -Djarmode=tools \
-jar /build/src/app-bootstrap/build/docker/application.jar \ -jar /build/src/bootstrap/app/build/docker/application.jar \
extract --layers --destination /build/src/app-bootstrap/build/docker/extracted extract --layers --destination /build/src/bootstrap/app/build/docker/extracted
# ---- Stage 2: runtime image ------------------------------------------------- # ---- Stage 2: runtime image -------------------------------------------------
# JRE-only slim image (D3: no full JDK in production image). # JRE-only slim image (D3: no full JDK in production image).
@@ -176,10 +176,10 @@ WORKDIR /app
# #
# All four land in /app: the extracted application.jar is a thin JAR whose manifest Class-Path # All four land in /app: the extracted application.jar is a thin JAR whose manifest Class-Path
# points at ./lib, which is what the dependencies layer unpacks to. # points at ./lib, which is what the dependencies layer unpacks to.
COPY --from=builder --chown=app:app /build/src/app-bootstrap/build/docker/extracted/dependencies/ ./ COPY --from=builder --chown=app:app /build/src/bootstrap/app/build/docker/extracted/dependencies/ ./
COPY --from=builder --chown=app:app /build/src/app-bootstrap/build/docker/extracted/spring-boot-loader/ ./ COPY --from=builder --chown=app:app /build/src/bootstrap/app/build/docker/extracted/spring-boot-loader/ ./
COPY --from=builder --chown=app:app /build/src/app-bootstrap/build/docker/extracted/snapshot-dependencies/ ./ COPY --from=builder --chown=app:app /build/src/bootstrap/app/build/docker/extracted/snapshot-dependencies/ ./
COPY --from=builder --chown=app:app /build/src/app-bootstrap/build/docker/extracted/application/ ./ COPY --from=builder --chown=app:app /build/src/bootstrap/app/build/docker/extracted/application/ ./
USER app USER app
+30 -26
View File
@@ -1,33 +1,38 @@
# ca-skeleton — Clean Architecture Spring Boot 백엔드 템플릿 # ca-skeleton — Clean Architecture Spring Boot 백엔드 템플릿
ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드 템플릿이다. 새 서비스를 만드는 개발자가 이 저장소를 복사하고, 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 그대로 둔다. 사람과 AI 세션이 같은 규칙(`AGENTS.md`)과 같은 절차(`docs/work/`)로 일한다. 라이브러리 버전은 `src/gradle/libs.versions.toml`이 정한다. ca-skeleton은 Java 21과 Spring Boot로 만든 Gradle 멀티모듈 백엔드 템플릿이다. 새 서비스를 만드는 개발자가 이 저장소를 복사하고, 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 그대로 둔다. 사람과 AI 세션이 같은 규칙(`AGENTS.md`)과 같은 절차(`docs/work/`)로 일한다. 라이브러리 버전은 `gradle/libs.versions.toml`이 정한다.
## 프로젝트 구조 ## 프로젝트 구조
저장소 루트에는 정해진 것만 둔다. 허용 목록 밖의 최상위 항목은 `scripts/check-repo-layout.py`가 PR에서 막는다. 저장소 루트가 Gradle 루트다. 빌드 도구와 빌드 파일은 루트에, 코드는 `src/`에 둔다. 허용 목록 밖의 최상위 항목은 `scripts/check-repo-layout.py`가 PR에서 막는다.
| 폴더 | 하는 일 | 먼저 읽을 곳 | | 폴더·파일 | 하는 일 | 먼저 읽을 곳 |
| --- | --- | --- | | --- | --- | --- |
| `src/` | Gradle 루트. 모든 코드, 빌드 규칙, registry | [src/README.md](src/README.md) | | `src/` | 계층별 앱 코드. leaf(Gradle 프로젝트)만 있다 | 아래 표 |
| `settings.gradle`, `build.gradle`, `gradlew` | Gradle 빌드. 단계 태스크(`prCheck`·`mainCheck` 등)와 registry를 읽는 settings | [docs/build.md](docs/build.md) |
| `gradle/` | wrapper, 버전 카탈로그 `libs.versions.toml`, 모듈 registry `modules.json`, 시험 컨테이너 이미지 목록 `container-images.properties` | [gradle/README.md](gradle/README.md) |
| `build-logic/` | 빌드 규칙(convention plugin, registry 검사) | [build-logic/README.md](build-logic/README.md) |
| `config/` | 코드 검사 도구 설정(checkstyle, spotbugs) | — |
| `Dockerfile`, `.env.example` | 릴리스 이미지(빌드 context는 저장소 루트), env 계약 | [docs/build.md](docs/build.md) |
| `docs/` | 문서. 매뉴얼·계약·운영 문서·결정 기록·기록 | [docs/README.md](docs/README.md) | | `docs/` | 문서. 매뉴얼·계약·운영 문서·결정 기록·기록 | [docs/README.md](docs/README.md) |
| `scripts/` | Gradle 밖 스크립트. 첫 실행, 새 기능 생성, 저장소 배치·문서 검사 | `scripts/bootstrap-local.sh`, `scripts/new-feature.sh` | | `scripts/` | Gradle 밖 스크립트. 첫 실행, 새 기능 생성, 검증 진입점, 저장소 배치·문서 검사 | `scripts/bootstrap-local.sh`, `scripts/new-feature.sh`, `scripts/verify.sh` |
| `compose.yaml` | 개발 환경. 앱 컨테이너와 뒷단 서비스(profile로 고른다) | 파일 머리의 profile 표 | | `compose.yaml` | 개발 환경. 앱 컨테이너와 뒷단 서비스(profile로 고른다) | 파일 머리의 profile 표 |
| `compose/` | `compose.yaml`이 마운트하는 보조 파일(Keycloak realm, Redis ACL, MinIO 초기화) | [compose/redis/acl/README.md](compose/redis/acl/README.md) | | `compose/` | `compose.yaml`이 마운트하는 보조 파일(Keycloak realm, Redis ACL, MinIO 초기화) | [compose/redis/acl/README.md](compose/redis/acl/README.md) |
| `.github/` | workflow, 공용 action, PR 양식, 의존성 취약점 정책 | [.github/dependency-vulnerability-policy.md](.github/dependency-vulnerability-policy.md) | | `.gitea/` | workflow(`pr`·`main`·`release`)와 공용 action | [docs/work/reference/gates.md](docs/work/reference/gates.md) |
| `.github/` | CODEOWNERS, PR 양식, 의존성 취약점 정책 | [.github/dependency-vulnerability-policy.md](.github/dependency-vulnerability-policy.md) |
`src/` 아래 폴더는 계층 leaf, 조립, Gradle 표준 폴더로 나뉜다. leaf는 Gradle 프로젝트 하나이고, leaf 목록·경로·허용 의존은 registry `src/config/architecture/modules.json`이 정한다. `src/` 아래 폴더는 계층이다. 같은 계층의 leaf는 그 계층 폴더 아래에 있다. leaf 목록·폴더·Gradle path·허용 의존은 registry `gradle/modules.json`이 정한다. Gradle path는 폴더와 다르다(`:application-core`는 `src/application/core`, `:composition:outbox-relay`는 `src/bootstrap/outbox-relay`).
| 폴더 | 책임 | 기본 조립에 들어가나 | | 폴더 | 책임 | 기본 조립에 들어가나 |
| --- | --- | --- | | --- | --- | --- |
| `domain-core/` | 도메인 모델, 불변식, 도메인 이벤트, port. framework·transport·DB 타입을 쓰지 않는다 | 들어간다 | | `src/domain/core/` | 도메인 모델, 불변식, 도메인 이벤트, port. framework·transport·DB 타입을 쓰지 않는다 | 들어간다 |
| `application-core/` | command, 유스케이스, application 정책, 트랜잭션 port. inbound DTO와 persistence entity를 받지 않는다 | 들어간다 | | `src/application/core/` | command, 유스케이스, application 정책, 트랜잭션 port. inbound DTO와 persistence entity를 받지 않는다 | 들어간다 |
| `application-fileserver/`, `application-notification/`, `application-objectstorage/` | capability(부가 기능) 하나의 application 계층 | 그 capability를 켤 때 | | `src/application/fileserver/`, `src/application/notification/`, `src/application/objectstorage/` | capability(부가 기능) 하나의 application 계층 | 그 capability를 켤 때 |
| `shared-contract/` | 저장소 전체의 운영 계약(오류 코드, 로그 키, 런타임 환경). 업무 개념은 두지 않는다 | 들어간다 | | `src/shared-contract/` | 저장소 전체의 운영 계약(오류 코드, 로그 키, 런타임 환경). 업무 개념은 두지 않는다 | 들어간다 |
| `adapter/inbound/` | HTTP·gRPC·GraphQL·WebSocket·메시징 수신 경계. DTO, 검증, 인증, 오류 매핑 | `web`만 들어간다 | | `src/adapter/inbound/` | HTTP·gRPC·GraphQL·WebSocket·메시징 수신 경계. DTO, 검증, 인증, 오류 매핑 | `web`만 들어간다 |
| `adapter/outbound/` | port 뒤의 구현: 영속성(JPA·MongoDB), Redis, 메시징, 알림, 객체 저장소, 파일 서버, HTTP client, identifier, 공용 기반(support) | `support`·`identifier`만 들어간다 | | `src/adapter/outbound/` | port 뒤의 구현: 영속성(JPA·MongoDB), Redis, 메시징, 알림, 객체 저장소, 파일 서버, HTTP client, identifier, 공용 기반(support) | `support`·`identifier`만 들어간다 |
| `composition/` | 조립만 하는 leaf: 서비스 런타임 배선, outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼 | `service-runtime`·`outbox-relay`·`idempotency`·`durable-operation`이 들어간다. 뒤의 셋은 필요한 port가 생기기 전에는 아무것도 만들지 않는다 | | `src/bootstrap/app/` | Spring Boot 진입점과 조립 루트(composition root, 모든 모듈을 엮는 곳) | 들어간다 |
| `app-bootstrap/` | Spring Boot 진입점과 조립 루트(composition root, 모든 모듈을 엮는 곳) | 들어간다 | | `src/bootstrap/` 의 나머지 | 조립만 하는 `composition:*` leaf: 서비스 런타임 배선, outbox relay, 멱등성 executor, durable operation, 알림·파일 서버 플랫폼 | `service-runtime`·`outbox-relay`·`idempotency`·`durable-operation`이 들어간다. 뒤의 셋은 필요한 port가 생기기 전에는 아무것도 만들지 않는다 |
| `build-logic/`, `config/`, `gradle/` | 빌드 규칙(convention plugin), 빌드 전체 도구 설정과 registry, wrapper와 버전 카탈로그 | 빌드 도구 |
의존은 항상 바깥에서 안으로 흐른다. adapter가 core의 port에 의존하고, core는 adapter를 모른다. 의존은 항상 바깥에서 안으로 흐른다. adapter가 core의 port에 의존하고, core는 adapter를 모른다.
@@ -61,17 +66,17 @@ curl -fsS http://localhost:8080/api/healthcheck
docker compose --profile '*' down docker compose --profile '*' down
``` ```
환경 변수는 `src/.env`(로컬 실행 입력)와 `src/.env.example`(배포 환경 변수의 복사·검증 계약)에 있다. 키 목록과 설명은 [src/README.md](src/README.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)이다. 환경 변수는 `.env`(로컬 실행 입력)와 `.env.example`(배포 환경 변수의 복사·검증 계약)에 있다. 키 목록과 설명은 [docs/build.md](docs/build.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)이다.
## 기능 켜고 끄기 ## 기능 켜고 끄기
기본 조립(`bootJar`)은 web, 운영 관측(actuator·metrics·tracing·로그), core들, `support`·`identifier`뿐이다. 그래서 DB·Redis·Kafka 없이 뜬다. `cd src && ./gradlew :app-bootstrap:bootRun`으로 바로 실행할 수 있다. 기본 조립(`bootJar`)은 web, 운영 관측(actuator·metrics·tracing·로그), core들, `support`·`identifier`뿐이다. 그래서 DB·Redis·Kafka 없이 뜬다. `./gradlew :app-bootstrap:bootRun`으로 바로 실행할 수 있다.
DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src/app-bootstrap/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄씩으로 있다. DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src/bootstrap/app/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄씩으로 있다.
- 켜기: 그 줄의 주석을 풀고 필요한 env 키를 넣는다. 모듈이 classpath에 있으면 켜진다. - 켜기: 그 줄의 주석을 풀고 필요한 env 키를 넣는다. 모듈이 classpath에 있으면 켜진다.
- 끄기: 줄을 지운다. 기능·설정·의존성이 함께 빠진다. 줄을 둔 채 끄려면 그 모듈의 `enabled` 키를 `false`로 둔다. - 끄기: 줄을 지운다. 기능·설정·의존성이 함께 빠진다. 줄을 둔 채 끄려면 그 모듈의 `enabled` 키를 `false`로 둔다.
- 줄마다 필요한 env 키와 끄는 키: [src/README.md](src/README.md) 「기능 추가 = 한 줄 + env」 표. - 줄마다 필요한 env 키와 끄는 키: [docs/build.md](docs/build.md) 「기능 추가 = 한 줄 + env」 표.
- 기능마다 조립·검증 상태: [docs/capability-status.md](docs/capability-status.md). - 기능마다 조립·검증 상태: [docs/capability-status.md](docs/capability-status.md).
- capability 모듈이 지켜야 하는 규칙과 완료 기준 7개: [docs/manual/10-capabilities.md](docs/manual/10-capabilities.md). - capability 모듈이 지켜야 하는 규칙과 완료 기준 7개: [docs/manual/10-capabilities.md](docs/manual/10-capabilities.md).
@@ -91,19 +96,18 @@ DB, Redis, Kafka, 알림, 파일 서버 같은 부가 기능(capability)은 `src
| 예전 설계·계획·리뷰 찾기 | 기록 `docs/design/`, `docs/history/`, `docs/reviews/`. 쓴 때의 글이고 지금 동작은 각 머리 블록의 「현재 정본」을 읽는다 | | 예전 설계·계획·리뷰 찾기 | 기록 `docs/design/`, `docs/history/`, `docs/reviews/`. 쓴 때의 글이고 지금 동작은 각 머리 블록의 「현재 정본」을 읽는다 |
| 템플릿 변경을 파생 서비스에 받기 | `docs/upgrade/` | | 템플릿 변경을 파생 서비스에 받기 | `docs/upgrade/` |
각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `AGENTS.md`와 README에 있다(예: [domain-core](src/domain-core/README.md), [app-bootstrap](src/app-bootstrap/README.md)). 각 모듈의 규칙과 설계 근거는 그 모듈 폴더의 `AGENTS.md`와 README에 있다(예: [domain-core](src/domain/core/README.md), [app-bootstrap](src/bootstrap/app/README.md)).
## 검증 ## 검증
명령은 `src/`에서 돌린다. 일상 피드백은 바꾼 leaf 하나와 아키텍처 검사다. leaf의 Gradle 경로는 registry의 `gradle_path`에서 읽는다. 명령은 저장소 루트에서 돌린다. 일상 피드백은 바꾼 leaf 하나와 아키텍처 검사다. leaf의 Gradle 경로는 registry의 `gradle_path`에서 읽는다.
```bash ```bash
cd src
./gradlew :app-bootstrap:check --console=plain ./gradlew :app-bootstrap:check --console=plain
./gradlew architectureCheck --console=plain ./gradlew architectureCheck --console=plain
``` ```
`./gradlew test`는 모든 leaf의 `test`를 돌리므로 일상 명령으로 쓰지 않는다. PR·main·태그 단계에서 무엇이 도는지, 바꾼 것에 맞춰 무엇을 더 돌릴지는 [docs/work/reference/gates.md](docs/work/reference/gates.md)가 정한다. 게이트 태스크 하나하나의 설명은 [src/README.md](src/README.md) 「build.gradle — 빌드 / 검증 게이트」다. `./gradlew test`는 모든 leaf의 `test`를 돌리므로 일상 명령으로 쓰지 않는다. PR·main·태그 단계에서 무엇이 도는지, 바꾼 것에 맞춰 무엇을 더 돌릴지는 [docs/work/reference/gates.md](docs/work/reference/gates.md)가 정한다. 게이트 태스크 하나하나의 설명은 [docs/build.md](docs/build.md) 「build.gradle — 빌드 / 검증 게이트」다.
문서를 고쳤으면 저장소 루트에서 `python3 scripts/check-docs.py`를 돌린다. 규칙은 [docs/README.md](docs/README.md) 「문서 검사」다. 문서를 고쳤으면 저장소 루트에서 `python3 scripts/check-docs.py`를 돌린다. 규칙은 [docs/README.md](docs/README.md) 「문서 검사」다.
@@ -111,7 +115,7 @@ cd src
이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 이 목록이 템플릿 재사용 체크리스트의 정본이다. 이 저장소를 새 서비스의 출발점으로 쓸 때의 순서다. 이 목록이 템플릿 재사용 체크리스트의 정본이다.
1. `src/settings.gradle`의 `rootProject.name`을 새 서비스 이름으로 바꾼다. 1. `settings.gradle`의 `rootProject.name`을 새 서비스 이름으로 바꾼다.
2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다. 2. 패키지 루트 `dev.caskeleton`을 서비스 패키지로 바꾼다. Java 소스만이 아니라 `AutoConfiguration.imports`·`spring.factories`·빌드 스크립트·설정 파일·생성 명령 템플릿도 이 이름을 쓴다. 바꿀 파일은 이 명령으로 찾는다.
```bash ```bash
@@ -123,7 +127,7 @@ cd src
5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다. 5. 쓰는 capability의 `runtimeOnly` 줄만 켠다. 켜지 않은 capability leaf는 산출물에 들어가지 않으니 지우지 않아도 된다.
6. 라이브러리 패키지 `dev.cakit.*`은 바꾸지 않는다. 별도 repo에서 받는 라이브러리의 패키지이고, 2번이 바꾸는 `dev.caskeleton`과 이름이 겹치지 않게 정했다. 라이브러리 목록은 [관련 저장소](docs/work/reference/related-repos.md)다. 6. 라이브러리 패키지 `dev.cakit.*`은 바꾸지 않는다. 별도 repo에서 받는 라이브러리의 패키지이고, 2번이 바꾸는 `dev.caskeleton`과 이름이 겹치지 않게 정했다. 라이브러리 목록은 [관련 저장소](docs/work/reference/related-repos.md)다.
7. Docker 이미지 이름과 애플리케이션 이름(`spring.application.name`)을 새 서비스 기준으로 바꾼다. 7. Docker 이미지 이름과 애플리케이션 이름(`spring.application.name`)을 새 서비스 기준으로 바꾼다.
8. `src/.env.example`, `src/.env.local.example`, `application.yml`의 예시 값을 새 서비스의 실행 요구에 맞춘다. 운영 모듈에는 그 서비스의 entity, repository port, use case, adapter만 더한다. 8. `.env.example`, `.env.local.example`, `application.yml`의 예시 값을 새 서비스의 실행 요구에 맞춘다. 운영 모듈에는 그 서비스의 entity, repository port, use case, adapter만 더한다.
9. README와 운영 문서를 새 서비스 설명으로 고친다. 9. README와 운영 문서를 새 서비스 설명으로 고친다.
복사한 뒤 지워도 되는 것은 템플릿의 기록(`docs/design/`, `docs/history/`, `docs/reviews/`)이다. 서비스의 지금 동작을 설명하지 않는다. 지우면 그 기록을 가리키던 살아 있는 문서가 깨지므로 `python3 scripts/check-docs.py`와 링크 검사([docs/work/reference/gates.md](docs/work/reference/gates.md) 「링크 검사」)로 찾아 고친다. 템플릿을 upstream으로 두고 merge해 받으면 그 폴더에서 충돌이 날 수 있다(`docs/upgrade/2026-11-docs-records.md`). 복사한 뒤 지워도 되는 것은 템플릿의 기록(`docs/design/`, `docs/history/`, `docs/reviews/`)이다. 서비스의 지금 동작을 설명하지 않는다. 지우면 그 기록을 가리키던 살아 있는 문서가 깨지므로 `python3 scripts/check-docs.py`와 링크 검사([docs/work/reference/gates.md](docs/work/reference/gates.md) 「링크 검사」)로 찾아 고친다. 템플릿을 upstream으로 두고 merge해 받으면 그 폴더에서 충돌이 날 수 있다(`docs/upgrade/2026-11-docs-records.md`).
@@ -1,13 +1,13 @@
# build-logic — Gradle 정책 권위 # build-logic — Gradle 정책 권위
registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 적는다. `src/build-logic/`, `src/settings.gradle`, `src/build.gradle`, `src/config/architecture/modules.json`을 고칠 때 읽는다. 루트 `AGENTS.md` HARD-STOP 5가 이 문서보다 먼저다. 게이트 고르기와 실행 위치는 `docs/work/reference/gates.md`다. registry, settings, build-logic, 루트 라이프사이클이 정하는 것을 적는다. `build-logic/`, `settings.gradle`, `build.gradle`, `gradle/modules.json`을 고칠 때 읽는다. 루트 `AGENTS.md` HARD-STOP 5가 이 문서보다 먼저다. 게이트 고르기와 실행 위치는 `docs/work/reference/gates.md`다.
## 정본 넷 ## 정본 넷
- `src/config/architecture/modules.json`: 등록된 모든 leaf의 ID, repository-relative 소스 경로, Gradle path, 허용 production project dependency edge, 그리고 별도 repo 라이브러리 edge(맨 위 `library_groups`, 행마다 `allowed_libraries`. 계층 leaf 행은 비워 둔다. 설명은 `src/config/architecture/README.md`). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다. leaf 목록과 그 개수의 정본은 registry다. 문서는 개수를 적지 않는다. 산문에 적힌 숫자는 leaf가 더해지는 순간 틀린다. 그 숫자를 강제하던 태스크(`verifyDocumentedLeafCount`)는 지웠다. 문서에 적힌 수가 틀린 것은 결함이지만 빌드를 실패시킬 사유는 아니고, 그 태스크는 모든 지역 문서와 `build.gradle`을 정규식으로 훑는 파서였다. - `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`을 정규식으로 훑는 파서였다.
- `src/settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 `verifyCleanArchitectureDependencies`가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다. - `settings.gradle`: `ca.architecture-registry` 설정 플러그인이 registry를 읽어 project를 include·mapping한다. registry가 project 목록이 될 수 없는 경우(중복 ID, 저장소 밖 경로, 없는 디렉터리)만 여기서 실패한다. 허용되지 않는 edge 같은 아키텍처 규칙은 `verifyCleanArchitectureDependencies`가 답한다. settings에서 죽으면 실행할 수 있는 태스크가 하나도 없다.
- `src/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-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의 테스트다.
- `src/build.gradle`: 루트 라이프사이클(`ci`, `prCheck`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 그것을 workflow job에 묶는 `strictLaneStages`, 버전·리비전. - `build.gradle`: 루트 라이프사이클(`ci`, `prCheck`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck`, `qualityCheck`, `configContractCheck`)과 그것을 workflow job에 묶는 `strictLaneStages`, 버전·리비전.
## 저장소 파일을 읽는 테스트 ## 저장소 파일을 읽는 테스트
@@ -25,10 +25,10 @@ registry, settings, build-logic, 루트 라이프사이클이 정하는 것을
## 단계 job의 모양 ## 단계 job의 모양
- `verifyStrictLaneStages --dry-run`(PR)은 `explicitOnly`가 아닌 strict lane마다 `src/build.gradle`의 `strictLaneStages`가 선언한 단계 태스크 하나의 계획에 들어 있는지 본다(그래프 검사). - `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 하나가 이 검사를 돌린다(형식 검사, 셸을 해석하지 않는다). - 단계마다 선언한 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를 같은 커밋에서 고친다. - 단계를 더하거나 job을 바꾸면 `strictLaneStages`의 `stage` 줄과 workflow를 같은 커밋에서 고친다.
## 테스트 ## 테스트
- `./gradlew -p build-logic test --console=plain`(`src/`에서). build-logic은 Spotless 대상이 아니다. 편집 훅도 이 폴더의 Java를 포맷하지 않는다. - `./gradlew -p build-logic test --console=plain`(저장소 루트에서). build-logic은 Spotless 대상이 아니다. 편집 훅도 이 폴더의 Java를 포맷하지 않는다.
@@ -15,7 +15,7 @@ capability를 가진 leaf의 시험이고, 그 시험이 읽는 파일은 그
| `ca.java-library` / `ca.spring-library` / `ca.spring-config` | 평범한 라이브러리와 Spring 라이브러리를 위한 Java·품질 규약의 leaf 단위 조합 | | `ca.java-library` / `ca.spring-library` / `ca.spring-config` | 평범한 라이브러리와 Spring 라이브러리를 위한 Java·품질 규약의 leaf 단위 조합 |
| `ca.platform-module` | 플랫폼 성격의 Java 라이브러리 leaf(지금 `adapter:outbound:httpclient`)가 무엇인가: `java-library`. 이 규약을 쓰던 메시징·gRPC 플랫폼은 2026-11-08에 별도 repo `messaging-library`·`grpc-library`로 옮겼다(gRPC BOM 규약 `ca.grpc-platform-module`도 함께) | | `ca.platform-module` | 플랫폼 성격의 Java 라이브러리 leaf(지금 `adapter:outbound:httpclient`)가 무엇인가: `java-library`. 이 규약을 쓰던 메시징·gRPC 플랫폼은 2026-11-08에 별도 repo `messaging-library`·`grpc-library`로 옮겼다(gRPC BOM 규약 `ca.grpc-platform-module`도 함께) |
| `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-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` (주 빌드의 루트) | lane 장치의 나머지 절반: `verifyStrictLaneStages --dry-run`은 그 빌드의 `explicitOnly`가 아닌 strict lane이 `strictLaneStages`에 선언한 단계 태스크 어느 것의 계획에도 없으면 실패한다(계획은 Gradle 자신의 것). 단계마다 그것을 돌리는 workflow job(파일·이벤트·job·옵션·조건)도 선언하고, 그 job이 정해진 한 줄 모양인지 고정 문자열로 본다(`src/build-logic/AGENTS.md` 「단계 job의 모양」). 2026-11-08까지 이 자리에 workflow YAML과 bash를 해석하던 판독기(`WorkflowGradleInvocations`·`ShellScript`·`TaskSelectors`)가 있었고, workflow를 셋으로 접으면서 지웠다 | | `ca.strict-lane-stages` (주 빌드의 루트) | lane 장치의 나머지 절반: `verifyStrictLaneStages --dry-run`은 그 빌드의 `explicitOnly`가 아닌 strict lane이 `strictLaneStages`에 선언한 단계 태스크 어느 것의 계획에도 없으면 실패한다(계획은 Gradle 자신의 것). 단계마다 그것을 돌리는 workflow job(파일·이벤트·job·옵션·조건)도 선언하고, 그 job이 정해진 한 줄 모양인지 고정 문자열로 본다(`build-logic/AGENTS.md` 「단계 job의 모양」). 2026-11-08까지 이 자리에 workflow YAML과 bash를 해석하던 판독기(`WorkflowGradleInvocations`·`ShellScript`·`TaskSelectors`)가 있었고, workflow를 셋으로 접으면서 지웠다 |
| `ca.redis-topology-lane` | `main.yml`의 nightly `redis-topology` job(`scripts/ci/redis-topology.sh`)이 돌리는 Redis topology lane(모드 고르기, `-P` 속성 검증, 모드별 필수 클래스) | | `ca.redis-topology-lane` | `main.yml`의 nightly `redis-topology` job(`scripts/ci/redis-topology.sh`)이 돌리는 Redis topology lane(모드 고르기, `-P` 속성 검증, 모드별 필수 클래스) |
| `ca.api-surface` | 읽기 전용 공개 API surface 검증과 따로 둔 갱신 태스크. leaf의 `check`에 배선한다(소유자 결정 20). 다른 leaf의 import를 리뷰한 adopter 부분집합(`adopterBaseline`)에 묶을 수도 있다 | | `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.config-contract` | app-bootstrap의 `verifyEnvKeys`(지운 build-tools included build에서 옮겼다. 소유자 결정 4가 그 태스크를 app-bootstrap에 둔다) |
@@ -26,7 +26,7 @@ capability를 가진 leaf의 시험이고, 그 시험이 읽는 파일은 그
| 클래스 | 가지는 것 | | 클래스 | 가지는 것 |
| --- | --- | | --- | --- |
| `dev.caskeleton.buildlogic.ModuleRegistry` | `config/architecture/modules.json`을 읽고 검증하기 | | `dev.caskeleton.buildlogic.ModuleRegistry` | `gradle/modules.json`을 읽고 검증하기 |
| `dev.caskeleton.buildlogic.RequiredTestExecution` | 「이 빌드가 이름을 댄 시험은 실제로 돌았어야 한다」는 단 하나의 판정 | | `dev.caskeleton.buildlogic.RequiredTestExecution` | 「이 빌드가 이름을 댄 시험은 실제로 돌았어야 한다」는 단 하나의 판정 |
| `dev.caskeleton.buildlogic.JavaPublicTypes` | 공개 최상위 타입. 정규식으로 맞추지 않고 javac로 파싱한다 | | `dev.caskeleton.buildlogic.JavaPublicTypes` | 공개 최상위 타입. 정규식으로 맞추지 않고 javac로 파싱한다 |
@@ -44,7 +44,7 @@ JMH benchmark는 커뮤니티 플러그인 `me.champeau.jmh`를 쓴다. `ca.qual
| `ca.jpa-test-lanes` | `adapter/outbound/persistence-jpa/build.gradle`에 선언한 lane | | `ca.jpa-test-lanes` | `adapter/outbound/persistence-jpa/build.gradle`에 선언한 lane |
| `ca.test-jvm-agents`, `quarantineTest` | `ca.java-conventions`. quarantine 묶음에는 시험이 없었다 | | `ca.test-jvm-agents`, `quarantineTest` | `ca.java-conventions`. quarantine 묶음에는 시험이 없었다 |
| `ca.jmh-benchmarks` | `me.champeau.jmh` | | `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.jpa-evidence`, `ca.jpa-qualification`(+ `junit` 증거 읽기) | 소유자 결정 4: persistence-jpa `JpaReadinessRegistryTest`, 인용한 시나리오를 모두 요구하고 건너뛰기를 거절하는 readiness lane, `src/adapter/outbound/persistence-jpa/release/release-registry.json`을 묶는 leaf의 `jpaReleaseQualification` |
| build-tools `ca.config-contract` | 바꾸지 않고 여기로 옮겼다 | | build-tools `ca.config-contract` | 바꾸지 않고 여기로 옮겼다 |
| `ca.public-path-snapshot` | app-bootstrap `PublicPathSnapshotTest`(lane `publicPathSnapshotTest`, 루트 별칭 `verifyPublicPathSnapshot`) | | `ca.public-path-snapshot` | app-bootstrap `PublicPathSnapshotTest`(lane `publicPathSnapshotTest`, 루트 별칭 `verifyPublicPathSnapshot`) |
| `ca.archive-hygiene` | 치울 것이 없다: leaf 버전이 더는 revision을 싣지 않으니 낡은 추적 가능 jar가 생기지 않는다 | | `ca.archive-hygiene` | 치울 것이 없다: leaf 버전이 더는 revision을 싣지 않으니 낡은 추적 가능 jar가 생기지 않는다 |
@@ -54,7 +54,6 @@ JMH benchmark는 커뮤니티 플러그인 `me.champeau.jmh`를 쓴다. `ca.qual
## 규약 시험하기 ## 규약 시험하기
```bash ```bash
cd src
./gradlew -p build-logic test --console=plain ./gradlew -p build-logic test --console=plain
``` ```
@@ -22,7 +22,7 @@ import tools.jackson.databind.ObjectMapper;
import tools.jackson.databind.json.JsonMapper; import tools.jackson.databind.json.JsonMapper;
/** /**
* Typed representation of config/architecture/modules.json. * Typed representation of gradle/modules.json.
* *
* <p>{@code libraryGroups} are the Maven group prefixes of the libraries this repository's owner * <p>{@code libraryGroups} are the Maven group prefixes of the libraries this repository's owner
* publishes from other repositories (design-docs {@code repo-structure/05-library-repos.md} 10.2절, * publishes from other repositories (design-docs {@code repo-structure/05-library-repos.md} 10.2절,
@@ -30,11 +30,10 @@ public final class ArchitecturePlugin implements Plugin<Project> {
@Override @Override
public void apply(Project project) { public void apply(Project project) {
Project root = project.getRootProject(); Project root = project.getRootProject();
// The Gradle root (src/) owns the registry; the repository root is its parent, and every // The Gradle root is the repository root: it owns the registry, and every source_path in the
// source_path in the registry is relative to the repository root. // registry is relative to it.
File mainBuildDirectory = root.getProjectDir(); File repositoryRoot = root.getProjectDir();
File registryFile = new File(mainBuildDirectory, "config/architecture/modules.json"); File registryFile = new File(repositoryRoot, "gradle/modules.json");
File repositoryRoot = mainBuildDirectory.getParentFile();
ModuleRegistry registry = ModuleRegistry.read(registryFile, repositoryRoot); ModuleRegistry registry = ModuleRegistry.read(registryFile, repositoryRoot);
List<ModuleRegistry.Module> modules = registry.modulesForBuild("main"); List<ModuleRegistry.Module> modules = registry.modulesForBuild("main");
List<String> registryViolations = registryViolations(registry, modules); List<String> registryViolations = registryViolations(registry, modules);
@@ -58,7 +58,7 @@ public abstract class VerifyCleanArchitectureDependenciesTask extends DefaultTas
List<String> registryViolations = getRegistryViolations().get(); List<String> registryViolations = getRegistryViolations().get();
if (!registryViolations.isEmpty()) { if (!registryViolations.isEmpty()) {
throw new GradleException( throw new GradleException(
"config/architecture/modules.json declares impossible edges:\n " "gradle/modules.json declares impossible edges:\n "
+ String.join("\n ", registryViolations)); + String.join("\n ", registryViolations));
} }
@@ -66,7 +66,7 @@ public abstract class VerifyCleanArchitectureDependenciesTask extends DefaultTas
if (!unregistered.isEmpty()) { if (!unregistered.isEmpty()) {
throw new GradleException( throw new GradleException(
"These build scripts have no registry entry, so the build does not include them and no" "These build scripts have no registry entry, so the build does not include them and no"
+ " gate compiles or tests them. Register each in config/architecture/modules.json" + " gate compiles or tests them. Register each in gradle/modules.json"
+ " or delete it:\n " + " or delete it:\n "
+ String.join("\n ", unregistered)); + String.join("\n ", unregistered));
} }
@@ -143,7 +143,7 @@ public abstract class VerifyModuleDependencyDirectionTask extends DefaultTask {
+ new TreeSet<>(getAllowedLibraries().get()) + new TreeSet<>(getAllowedLibraries().get())
+ ".\nDirect and compile-visible production dependencies on a library of the groups " + ".\nDirect and compile-visible production dependencies on a library of the groups "
+ libraryGroups + libraryGroups
+ " must be listed in the module's allowed_libraries (config/architecture/modules.json)."); + " must be listed in the module's allowed_libraries (gradle/modules.json).");
} }
} }
} }
@@ -20,12 +20,12 @@ public final class ConfigContractPlugin implements Plugin<Project> {
task -> { task -> {
task.setGroup("verification"); task.setGroup("verification");
task.setDescription( task.setDescription(
"Verifies shipped configuration APP_ references, src/.env.example, and env-keys.yaml stay registered."); "Verifies shipped configuration APP_ references, .env.example, and env-keys.yaml stay registered.");
task.getEnvFile().fileValue(root.file(".env.example")); task.getEnvFile().fileValue(root.file(".env.example"));
task.getConfigurationFiles() task.getConfigurationFiles()
.from( .from(
root.fileTree( root.fileTree(
root.file("app-bootstrap/src/main/resources"), root.file("src/bootstrap/app/src/main/resources"),
tree -> { tree -> {
tree.include("application*.yml"); tree.include("application*.yml");
tree.include("config/*.yml"); tree.include("config/*.yml");
@@ -34,12 +34,14 @@ public final class ConfigContractPlugin implements Plugin<Project> {
// (read by ModuleDefaultsEnvironmentPostProcessor), or config/<name>.yml for // (read by ModuleDefaultsEnvironmentPostProcessor), or config/<name>.yml for
// the leaves that load their own. They are shipped configuration whenever the // the leaves that load their own. They are shipped configuration whenever the
// module is selected, so their APP_ references are held to the same registry. // module is selected, so their APP_ references are held to the same registry.
// The leaves live under src/ (the Gradle root is the repository root, which also
// holds docs, scripts and, on a developer checkout, .claude/worktrees).
root.fileTree( root.fileTree(
root.getProjectDir(), root.file("src"),
tree -> { tree -> {
tree.include("*/**/src/main/resources/config/*.yml"); tree.include("*/**/src/main/resources/config/*.yml");
tree.include("*/**/src/main/resources/config/module-defaults/*.yml"); tree.include("*/**/src/main/resources/config/module-defaults/*.yml");
tree.exclude("app-bootstrap/**"); tree.exclude("bootstrap/app/**");
tree.exclude("**/build/**"); tree.exclude("**/build/**");
})); }));
// What an operator edits or runs: the development Compose file and the lane // What an operator edits or runs: the development Compose file and the lane
@@ -52,26 +54,26 @@ public final class ConfigContractPlugin implements Plugin<Project> {
// by hand. // by hand.
task.getOperatorFiles() task.getOperatorFiles()
.from( .from(
root.file("../compose.yaml"), root.file("compose.yaml"),
root.fileTree( root.fileTree(
root.file("app-bootstrap/compose-lanes"), root.file("src/bootstrap/app/compose-lanes"),
tree -> { tree -> {
tree.include("*.yaml"); tree.include("*.yaml");
// The lane-only services: their APP_* variables belong to the smoke // The lane-only services: their APP_* variables belong to the smoke
// clients, not to this application. // clients, not to this application.
tree.exclude("lane-services.yaml"); tree.exclude("lane-services.yaml");
}), }),
root.file("app-bootstrap/src/main/resources/logback-spring.xml"), root.file("src/bootstrap/app/src/main/resources/logback-spring.xml"),
root.file("app-bootstrap/compose-lanes/compose-profile-contracts.json"), root.file("src/bootstrap/app/compose-lanes/compose-profile-contracts.json"),
root.file("../scripts/run-compose-runtime-smoke.sh")); root.file("scripts/run-compose-runtime-smoke.sh"));
task.getRegistryFile().fileValue(root.file("../docs/registries/env-keys.yaml")); task.getRegistryFile().fileValue(root.file("docs/registries/env-keys.yaml"));
// No module path here: the typed properties come from the configuration metadata on // No module path here: the typed properties come from the configuration metadata on
// the classpath the composition root wires (metadataClasspath), so this task knows no // the classpath the composition root wires (metadataClasspath), so this task knows no
// leaf by name (review 2026-11-03 RR-06-10). // leaf by name (review 2026-11-03 RR-06-10).
task.getProductionSources() task.getProductionSources()
.from( .from(
root.fileTree( root.fileTree(
root.getProjectDir(), root.file("src"),
tree -> { tree -> {
tree.include("**/src/main/**/*.java"); tree.include("**/src/main/**/*.java");
tree.include("**/src/main/**/*.yml"); tree.include("**/src/main/**/*.yml");
@@ -147,7 +147,7 @@ public final class EnvContractVerifier {
failUnlessEmpty( failUnlessEmpty(
difference(requiredPlaceholders, envKeys), difference(requiredPlaceholders, envKeys),
"shipped configuration references required env absent from src/.env.example: "); "shipped configuration references required env absent from .env.example: ");
List<EnvRegistryRow> registryRows = parseRegistryRows(registryFile); List<EnvRegistryRow> registryRows = parseRegistryRows(registryFile);
Set<String> registryAppKeys = new TreeSet<>(); Set<String> registryAppKeys = new TreeSet<>();
@@ -159,14 +159,14 @@ public final class EnvContractVerifier {
failUnlessEmpty( failUnlessEmpty(
difference(registryAppKeys, envKeys), difference(registryAppKeys, envKeys),
"docs/registries/env-keys.yaml registers APP_ keys absent from src/.env.example, so an " "docs/registries/env-keys.yaml registers APP_ keys absent from .env.example, so an "
+ "adopter copying the example never sees them: "); + "adopter copying the example never sees them: ");
Set<String> envAppKeys = new TreeSet<>(); Set<String> envAppKeys = new TreeSet<>();
envKeys.stream().filter(name -> name.startsWith("APP_")).forEach(envAppKeys::add); envKeys.stream().filter(name -> name.startsWith("APP_")).forEach(envAppKeys::add);
failUnlessEmpty( failUnlessEmpty(
difference(envAppKeys, registryAppKeys), difference(envAppKeys, registryAppKeys),
"src/.env.example declares APP_ keys absent from docs/registries/env-keys.yaml " ".env.example declares APP_ keys absent from docs/registries/env-keys.yaml "
+ "(registry is the SSOT for APP_ keys): "); + "(registry is the SSOT for APP_ keys): ");
failUnlessEmpty( failUnlessEmpty(
difference(applicationAppReferences, registryAppKeys), difference(applicationAppReferences, registryAppKeys),
@@ -268,7 +268,7 @@ public final class JavaConventionsPlugin implements Plugin<Project> {
// property rather than a JVM argument: a strict lane's own `jvmArgs` replace the argument list, // property rather than a JVM argument: a strict lane's own `jvmArgs` replace the argument list,
// and this used to be repeated in 28 lanes for that reason (review 2026-11-01 O-10b). // and this used to be repeated in 28 lanes for that reason (review 2026-11-01 O-10b).
// //
// The container images the lanes start come from config/testing/container-images.properties, // The container images the lanes start come from gradle/container-images.properties,
// each as `ca.test.image.<key>`, with the file as an input (review 2026-11-01 08-04). // each as `ca.test.image.<key>`, with the file as an input (review 2026-11-01 08-04).
File images = containerImageCatalog(project); File images = containerImageCatalog(project);
Map<String, String> containerImages = containerImages(images); Map<String, String> containerImages = containerImages(images);
@@ -303,7 +303,7 @@ public final class JavaConventionsPlugin implements Plugin<Project> {
public static final String CONTAINER_IMAGE_PROPERTY_PREFIX = "ca.test.image."; public static final String CONTAINER_IMAGE_PROPERTY_PREFIX = "ca.test.image.";
private static File containerImageCatalog(Project project) { private static File containerImageCatalog(Project project) {
File catalog = project.getRootProject().file("config/testing/container-images.properties"); File catalog = project.getRootProject().file("gradle/container-images.properties");
if (!catalog.isFile()) { if (!catalog.isFile()) {
throw new GradleException("Missing test container image catalog: " + catalog); throw new GradleException("Missing test container image catalog: " + catalog);
} }
@@ -11,8 +11,8 @@ public final class ArchitectureRegistrySettingsPlugin implements Plugin<Settings
@Override @Override
public void apply(Settings settings) { public void apply(Settings settings) {
try { try {
File repositoryRoot = settings.getSettingsDir().getParentFile().getCanonicalFile(); File repositoryRoot = settings.getSettingsDir().getCanonicalFile();
File registryFile = new File(settings.getSettingsDir(), "config/architecture/modules.json"); File registryFile = new File(settings.getSettingsDir(), "gradle/modules.json");
ModuleRegistrySettingsInstaller.install(settings, registryFile, repositoryRoot, "main"); ModuleRegistrySettingsInstaller.install(settings, registryFile, repositoryRoot, "main");
} catch (IOException exception) { } catch (IOException exception) {
throw new UncheckedIOException("failed to resolve architecture registry paths", exception); throw new UncheckedIOException("failed to resolve architecture registry paths", exception);
@@ -12,7 +12,7 @@ import org.gradle.api.file.DirectoryProperty;
* *
* <pre> * <pre>
* strictLaneStages { * strictLaneStages {
* workflowDirectory = layout.projectDirectory.dir('../.gitea/workflows') * workflowDirectory = layout.projectDirectory.dir('.gitea/workflows')
* stage ':prCheck', workflow: 'pr.yml', event: 'pull_request', job: 'gradle' * stage ':prCheck', workflow: 'pr.yml', event: 'pull_request', job: 'gradle'
* stage ':mainCheck', workflow: 'main.yml', event: 'push', filter: 'branches: [main]', * stage ':mainCheck', workflow: 'main.yml', event: 'push', filter: 'branches: [main]',
* job: 'main', options: '--continue' * job: 'main', options: '--continue'
@@ -214,6 +214,29 @@ class ModuleRegistryTest {
assertEquals(List.of("adapter/gamma/build.gradle"), unregistered); assertEquals(List.of("adapter/gamma/build.gradle"), unregistered);
} }
@Test
@DisplayName("Gradle 루트가 저장소 루트이면 included build와 점 폴더(다른 worktree)는 건너뛰고 src/의 미등록 스크립트만 찾는다")
void buildScriptsAreFoundFromTheRepositoryRootWithoutEnteringOtherCheckouts() throws Exception {
// given
Files.writeString(root.resolve("build.gradle"), "");
Files.writeString(root.resolve("src/alpha/build.gradle"), "");
Files.writeString(root.resolve("src/beta/build.gradle"), "");
Files.createDirectories(root.resolve("src/adapter/gamma"));
Files.writeString(root.resolve("src/adapter/gamma/build.gradle"), "");
Files.createDirectories(root.resolve("build-logic"));
Files.writeString(root.resolve("build-logic/settings.gradle"), "");
Files.writeString(root.resolve("build-logic/build.gradle"), "");
Files.createDirectories(root.resolve(".claude/worktrees/copy/src/delta"));
Files.writeString(root.resolve(".claude/worktrees/copy/src/delta/build.gradle"), "");
ModuleRegistry registry = read(valid());
// when
List<String> unregistered = registry.unregisteredBuildScripts(root.toFile());
// then
assertEquals(List.of("src/adapter/gamma/build.gradle"), unregistered);
}
private File write(String json) { private File write(String json) {
try { try {
Path file = root.resolve("modules.json"); Path file = root.resolve("modules.json");
@@ -31,8 +31,8 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
void aSecondCompositionRootIsGovernedByTheSameDependencyPolicy( void aSecondCompositionRootIsGovernedByTheSameDependencyPolicy(
@TempDir Path temporaryRoot) throws IOException { @TempDir Path temporaryRoot) throws IOException {
Path repository = temporaryRoot.resolve("repository"); Path repository = temporaryRoot.resolve("repository");
Path project = repository.resolve("src"); Path project = repository;
Files.createDirectories(project.resolve("config/architecture")); Files.createDirectories(project.resolve("gradle"));
Files.createDirectories(project.resolve("a")); Files.createDirectories(project.resolve("a"));
Files.createDirectories(project.resolve("example-app")); Files.createDirectories(project.resolve("example-app"));
@@ -54,20 +54,20 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
""", """,
UTF_8); UTF_8);
Files.writeString( Files.writeString(
project.resolve("config/architecture/modules.json"), project.resolve("gradle/modules.json"),
""" """
{ {
"modules": [ "modules": [
{ {
"id": "a", "id": "a",
"gradle_path": ":a", "gradle_path": ":a",
"source_path": "src/a", "source_path": "a",
"allowed_dependencies": [] "allowed_dependencies": []
}, },
{ {
"id": "example-app", "id": "example-app",
"gradle_path": ":example-app", "gradle_path": ":example-app",
"source_path": "src/example-app", "source_path": "example-app",
"allowed_dependencies": [] "allowed_dependencies": []
} }
] ]
@@ -230,8 +230,8 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
void aLayerModuleThatAllowsALibraryIsARegistryViolation(@TempDir Path temporaryRoot) void aLayerModuleThatAllowsALibraryIsARegistryViolation(@TempDir Path temporaryRoot)
throws IOException { throws IOException {
// given // given
Path project = temporaryRoot.resolve("repository").resolve("src"); Path project = temporaryRoot.resolve("repository");
Files.createDirectories(project.resolve("config/architecture")); Files.createDirectories(project.resolve("gradle"));
Files.createDirectories(project.resolve("domain-core")); Files.createDirectories(project.resolve("domain-core"));
Files.writeString( Files.writeString(
project.resolve("settings.gradle"), "rootProject.name = 'main'\ninclude 'domain-core'\n", UTF_8); project.resolve("settings.gradle"), "rootProject.name = 'main'\ninclude 'domain-core'\n", UTF_8);
@@ -240,7 +240,7 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
"plugins { id 'ca.architecture' }\nsubprojects { apply plugin: 'java-library' }\n", "plugins { id 'ca.architecture' }\nsubprojects { apply plugin: 'java-library' }\n",
UTF_8); UTF_8);
Files.writeString( Files.writeString(
project.resolve("config/architecture/modules.json"), project.resolve("gradle/modules.json"),
""" """
{ {
"library_groups": ["dev.cakit"], "library_groups": ["dev.cakit"],
@@ -248,7 +248,7 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
{ {
"id": "domain-core", "id": "domain-core",
"gradle_path": ":domain-core", "gradle_path": ":domain-core",
"source_path": "src/domain-core", "source_path": "domain-core",
"allowed_dependencies": [], "allowed_dependencies": [],
"allowed_libraries": ["dev.cakit.demo:demo-api"] "allowed_libraries": ["dev.cakit.demo:demo-api"]
} }
@@ -300,8 +300,8 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
private static Path libraryFixture(Path temporaryRoot, String declaration, String cLibraries) private static Path libraryFixture(Path temporaryRoot, String declaration, String cLibraries)
throws IOException { throws IOException {
Path repository = temporaryRoot.resolve("repository"); Path repository = temporaryRoot.resolve("repository");
Path project = repository.resolve("src"); Path project = repository;
Files.createDirectories(project.resolve("config/architecture")); Files.createDirectories(project.resolve("gradle"));
Files.createDirectories(project.resolve("c")); Files.createDirectories(project.resolve("c"));
Path maven = temporaryRoot.resolve("maven"); Path maven = temporaryRoot.resolve("maven");
pom(maven, "dev.cakit.demo", "demo-core", ""); pom(maven, "dev.cakit.demo", "demo-core", "");
@@ -339,7 +339,7 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
.formatted(maven.toUri(), declaration), .formatted(maven.toUri(), declaration),
UTF_8); UTF_8);
Files.writeString( Files.writeString(
project.resolve("config/architecture/modules.json"), project.resolve("gradle/modules.json"),
""" """
{ {
"library_groups": ["dev.cakit"], "library_groups": ["dev.cakit"],
@@ -347,7 +347,7 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
{ {
"id": "c", "id": "c",
"gradle_path": ":c", "gradle_path": ":c",
"source_path": "src/c", "source_path": "c",
"allowed_dependencies": [], "allowed_dependencies": [],
"allowed_libraries": %s "allowed_libraries": %s
} }
@@ -379,8 +379,8 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
private static Path fixture(Path temporaryRoot, boolean allowTransitiveA) throws IOException { private static Path fixture(Path temporaryRoot, boolean allowTransitiveA) throws IOException {
Path repository = temporaryRoot.resolve("repository"); Path repository = temporaryRoot.resolve("repository");
Path project = repository.resolve("src"); Path project = repository;
Files.createDirectories(project.resolve("config/architecture")); Files.createDirectories(project.resolve("gradle"));
for (String module : new String[] {"a", "b", "c"}) { for (String module : new String[] {"a", "b", "c"}) {
Files.createDirectories(project.resolve(module)); Files.createDirectories(project.resolve(module));
} }
@@ -409,26 +409,26 @@ class CleanArchitectureResolvedClasspathFunctionalTest {
String cAllowed = allowTransitiveA ? "[\"b\", \"a\"]" : "[\"b\"]"; String cAllowed = allowTransitiveA ? "[\"b\", \"a\"]" : "[\"b\"]";
Files.writeString( Files.writeString(
project.resolve("config/architecture/modules.json"), project.resolve("gradle/modules.json"),
""" """
{ {
"modules": [ "modules": [
{ {
"id": "a", "id": "a",
"gradle_path": ":a", "gradle_path": ":a",
"source_path": "src/a", "source_path": "a",
"allowed_dependencies": [] "allowed_dependencies": []
}, },
{ {
"id": "b", "id": "b",
"gradle_path": ":b", "gradle_path": ":b",
"source_path": "src/b", "source_path": "b",
"allowed_dependencies": ["a"] "allowed_dependencies": ["a"]
}, },
{ {
"id": "c", "id": "c",
"gradle_path": ":c", "gradle_path": ":c",
"source_path": "src/c", "source_path": "c",
"allowed_dependencies": %s "allowed_dependencies": %s
} }
] ]
@@ -53,7 +53,7 @@ class VerifyNoIgnoredSourcePackagesFunctionalTest {
Path project = fixture(temporaryRoot, "a"); Path project = fixture(temporaryRoot, "a");
source(project, "a/src/main/java/example/Ok.java"); source(project, "a/src/main/java/example/Ok.java");
Files.writeString( Files.writeString(
project.getParent().resolve(".git"), project.resolve(".git"),
"gitdir: " + temporaryRoot.resolve("missing-git-dir") + "\n", "gitdir: " + temporaryRoot.resolve("missing-git-dir") + "\n",
UTF_8); UTF_8);
@@ -65,10 +65,10 @@ class VerifyNoIgnoredSourcePackagesFunctionalTest {
.contains("verifyNoIgnoredSourcePackages: `git check-ignore` exited 128"); .contains("verifyNoIgnoredSourcePackages: `git check-ignore` exited 128");
} }
/** One registered leaf with an extra {@code integrationTest} source set, under {@code src/}. */ /** One registered leaf with an extra {@code integrationTest} source set, in the Gradle root. */
private static Path fixture(Path temporaryRoot, String leaf) throws IOException { private static Path fixture(Path temporaryRoot, String leaf) throws IOException {
Path project = temporaryRoot.resolve("repository").resolve("src"); Path project = temporaryRoot.resolve("repository");
Files.createDirectories(project.resolve("config/architecture")); Files.createDirectories(project.resolve("gradle"));
Files.createDirectories(project.resolve(leaf)); Files.createDirectories(project.resolve(leaf));
Files.writeString( Files.writeString(
project.resolve("settings.gradle"), project.resolve("settings.gradle"),
@@ -89,14 +89,14 @@ class VerifyNoIgnoredSourcePackagesFunctionalTest {
""", """,
UTF_8); UTF_8);
Files.writeString( Files.writeString(
project.resolve("config/architecture/modules.json"), project.resolve("gradle/modules.json"),
""" """
{ {
"modules": [ "modules": [
{ {
"id": "%1$s", "id": "%1$s",
"gradle_path": ":%1$s", "gradle_path": ":%1$s",
"source_path": "src/%1$s", "source_path": "%1$s",
"allowed_dependencies": [] "allowed_dependencies": []
} }
] ]
@@ -167,7 +167,7 @@ class EnvContractVerifierTest {
List.of("APP_REDIS_"), List.of("APP_REDIS_"),
List.of())); List.of()));
assertTrue(failure.getMessage().contains("required env absent from src/.env.example")); assertTrue(failure.getMessage().contains("required env absent from .env.example"));
assertTrue(failure.getMessage().contains("APP_REQUIRED_SECONDARY")); assertTrue(failure.getMessage().contains("APP_REQUIRED_SECONDARY"));
} }
@@ -190,7 +190,7 @@ class EnvContractVerifierTest {
List.of("APP_REDIS_"), List.of("APP_REDIS_"),
List.of())); List.of()));
assertTrue(failure.getMessage().contains("required env absent from src/.env.example")); assertTrue(failure.getMessage().contains("required env absent from .env.example"));
assertTrue(failure.getMessage().contains("APP_REQUIRED")); assertTrue(failure.getMessage().contains("APP_REQUIRED"));
} }
@@ -19,8 +19,7 @@ class PlatformModuleConventionTest {
writeCatalog(); writeCatalog();
// java-conventions refuses a build without the container image catalog (review 2026-11-01 // java-conventions refuses a build without the container image catalog (review 2026-11-01
// 08-04); a fixture build that starts no container still has to carry one, even empty. // 08-04); a fixture build that starts no container still has to carry one, even empty.
Files.createDirectories(projectDir.resolve("config/testing")); Files.writeString(projectDir.resolve("gradle/container-images.properties"), "");
Files.writeString(projectDir.resolve("config/testing/container-images.properties"), "");
Files.writeString( Files.writeString(
projectDir.resolve("settings.gradle"), projectDir.resolve("settings.gradle"),
""" """
@@ -4,6 +4,7 @@ import static org.assertj.core.api.Assertions.assertThat;
import java.nio.file.Files; import java.nio.file.Files;
import java.nio.file.Path; import java.nio.file.Path;
import java.util.List;
import java.util.stream.Stream; import java.util.stream.Stream;
import org.gradle.testkit.runner.BuildResult; import org.gradle.testkit.runner.BuildResult;
import org.gradle.testkit.runner.GradleRunner; import org.gradle.testkit.runner.GradleRunner;
@@ -16,8 +17,10 @@ import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.MethodSource; import org.junit.jupiter.params.provider.MethodSource;
/** /**
* A two-project build: a root that declares two stages, and a leaf with strict lanes. The workflows * A two-project build: a root that declares two stages, and a leaf with strict lanes. Most tests keep
* live where the real repository keeps them, one directory above the Gradle root. * the Gradle root one directory below the workflows (a build in {@code src/}, as this template had
* it until 2026-11-11); the repository-root tests move the same build up, as the template has it
* now, where this build's directory is {@code .}.
*/ */
class StrictLaneStagesFunctionalTest { class StrictLaneStagesFunctionalTest {
private static final String PR_WORKFLOW = private static final String PR_WORKFLOW =
@@ -338,6 +341,52 @@ class StrictLaneStagesFunctionalTest {
assertThat(result.getOutput()).contains("stage :integrationCheck: option -x is not one of"); assertThat(result.getOutput()).contains("stage :integrationCheck: option -x is not one of");
} }
@Test
@DisplayName("Gradle 루트가 저장소 루트이면 working-directory 없는 단계 job으로 통과한다")
void aBuildAtTheRepositoryRootPassesWithJobsThatRunInTheRepositoryRoot() throws Exception {
// given
moveBuildToRepositoryRoot();
// when
BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").build();
// then
assertThat(result.getOutput()).contains("every strict lane is in a stage its workflow job runs");
}
@Test
@DisplayName("Gradle 루트가 저장소 루트인데 job이 src에서 돌면 이 빌드의 폴더 . 을 대며 실패한다")
void aBuildAtTheRepositoryRootRefusesAJobThatRunsInSrc() throws Exception {
// given
moveBuildToRepositoryRoot();
workflow("pr.yml", PR_WORKFLOW);
// when
BuildResult result = runner(":verifyStrictLaneStages", "--dry-run").buildAndFail();
// then
assertThat(result.getOutput())
.contains("pr.yml job gradle runs in src, not in this build's directory .");
}
/** The same build at the repository root, beside .gitea/, with workflows that set no directory. */
private void moveBuildToRepositoryRoot() throws Exception {
for (String file :
List.of(
"settings.gradle", "build.gradle", "leaf/build.gradle", "leaf/src/test/java/LaneTest.java")) {
Path target = repository.resolve(file);
Files.createDirectories(target.getParent());
Files.writeString(
target,
Files.readString(gradleRoot.resolve(file))
.replace("'../.gitea/workflows'", "'.gitea/workflows'"));
}
gradleRoot = repository;
String sourceDirectory = "defaults:\n run:\n working-directory: src\n";
workflow("pr.yml", PR_WORKFLOW.replace(sourceDirectory, ""));
workflow("main.yml", MAIN_WORKFLOW.replace(sourceDirectory, ""));
}
private void leafLanes(String lanes) throws Exception { private void leafLanes(String lanes) throws Exception {
Files.writeString( Files.writeString(
gradleRoot.resolve("leaf/build.gradle"), gradleRoot.resolve("leaf/build.gradle"),
+3 -3
View File
@@ -151,7 +151,7 @@ tasks.register('testQualityCheck') {
tasks.register('verifyFeatureScaffold', Exec) { tasks.register('verifyFeatureScaffold', Exec) {
group = 'verification' group = 'verification'
description = 'Generates features with scripts/new-feature.sh in a scratch copy and runs the gates they must pass.' description = 'Generates features with scripts/new-feature.sh in a scratch copy and runs the gates they must pass.'
workingDir = rootProject.projectDir.parentFile workingDir = rootProject.projectDir
commandLine 'bash', 'scripts/verify-feature-scaffold.sh' commandLine 'bash', 'scripts/verify-feature-scaffold.sh'
} }
@@ -196,7 +196,7 @@ tasks.register('mainCheck') {
// The checks outside Gradle that the pull-request stage runs. Each is a script with its own tests // The checks outside Gradle that the pull-request stage runs. Each is a script with its own tests
// (scripts/tests); these tasks only give them a stage, so pr.yml and scripts/verify.sh run the same // (scripts/tests); these tasks only give them a stage, so pr.yml and scripts/verify.sh run the same
// one line. Repository root as working directory: that is where the scripts expect to start. // one line. Repository root as working directory: that is where the scripts expect to start.
def repositoryRoot = rootProject.projectDir.parentFile def repositoryRoot = rootProject.projectDir
tasks.register('verifyComposeProfiles', Exec) { tasks.register('verifyComposeProfiles', Exec) {
group = 'verification' group = 'verification'
description = 'Renders every Compose lane and checks it renders exactly what it declares.' description = 'Renders every Compose lane and checks it renders exactly what it declares.'
@@ -241,7 +241,7 @@ tasks.register('prCheck') {
// through its category aggregate; no workflow line names it. The performance lane runs only // through its category aggregate; no workflow line names it. The performance lane runs only
// nightly, after the other heavy jobs, on a runner nothing else is using (owner decision 2026-11-07). // nightly, after the other heavy jobs, on a runner nothing else is using (owner decision 2026-11-07).
strictLaneStages { strictLaneStages {
workflowDirectory = layout.projectDirectory.dir('../.gitea/workflows') workflowDirectory = layout.projectDirectory.dir('.gitea/workflows')
stage ':prCheck', workflow: 'pr.yml', event: 'pull_request', job: 'gradle' stage ':prCheck', workflow: 'pr.yml', event: 'pull_request', job: 'gradle'
stage ':mainCheck', workflow: 'main.yml', event: 'push', filter: 'branches: [main]', job: 'main', stage ':mainCheck', workflow: 'main.yml', event: 'push', filter: 'branches: [main]', job: 'main',
options: '--continue' options: '--continue'
+6 -6
View File
@@ -21,7 +21,7 @@
# mail mailpit (STARTTLS 필수) SMTP 발송 # mail mailpit (STARTTLS 필수) SMTP 발송
# #
# 이 파일이 마운트하는 보조 파일은 compose/ 아래에 있다. compose lane(테스트)은 이 파일을 바탕으로 # 이 파일이 마운트하는 보조 파일은 compose/ 아래에 있다. compose lane(테스트)은 이 파일을 바탕으로
# 쓰고, lane에만 필요한 overlay·smoke client·스키마 적용은 src/app-bootstrap/compose-lanes/에 있다. # 쓰고, lane에만 필요한 overlay·smoke client·스키마 적용은 src/bootstrap/app/compose-lanes/에 있다.
# 경로는 모두 이 파일이 있는 저장소 루트 기준이다. # 경로는 모두 이 파일이 있는 저장소 루트 기준이다.
# #
# auth profile은 keycloak client secret 파일이 있어야 뜬다. lane은 실행마다 만들고 지운다. 손으로 띄울 # auth profile은 keycloak client secret 파일이 있어야 뜬다. lane은 실행마다 만들고 지운다. 손으로 띄울
@@ -63,7 +63,7 @@ x-local-minio-image: &local-minio-image "${LOCAL_MINIO_IMAGE:-pgsty/minio@sha256
services: services:
app: app:
build: build:
context: src/ context: .
dockerfile: Dockerfile dockerfile: Dockerfile
args: args:
RELEASE_VERSION: "${RELEASE_VERSION:-0.0.1}" RELEASE_VERSION: "${RELEASE_VERSION:-0.0.1}"
@@ -76,12 +76,12 @@ services:
# The composition is in the tag, so a lane's qualification image is never reused as the # The composition is in the tag, so a lane's qualification image is never reused as the
# default one (Compose reuses a matching tag instead of building). # default one (Compose reuses a matching tag instead of building).
image: caskeleton:${BUILD_VERSION:-0.0.1_local_0000000}-${COMPOSITION:-default} image: caskeleton:${BUILD_VERSION:-0.0.1_local_0000000}-${COMPOSITION:-default}
# Optional, because src/.env is operator input and a fresh clone does not have one. Before this # Optional, because .env is operator input and a fresh clone does not have one. Before this
# was marked optional, untracking that file made `docker compose config` fail outright on a # was marked optional, untracking that file made `docker compose config` fail outright on a
# clone. The tracked contract is src/.env.example; copy it. A compose lane does not depend on it: # clone. The tracked contract is .env.example; copy it. A compose lane does not depend on it:
# its values go into a generated `environment:` block, which outranks every env_file. # its values go into a generated `environment:` block, which outranks every env_file.
env_file: env_file:
- path: ./src/.env - path: ./.env
required: false required: false
ports: ports:
- "${APP_SERVER_PORT:-8080}:8080" - "${APP_SERVER_PORT:-8080}:8080"
@@ -147,7 +147,7 @@ services:
# ---- PostgreSQL -------------------------------------------------------------- # ---- PostgreSQL --------------------------------------------------------------
# Published on the loopback interface only, so a host-side run (`./gradlew :app-bootstrap:bootRun`, # Published on the loopback interface only, so a host-side run (`./gradlew :app-bootstrap:bootRun`,
# IDE) reaches the same database the containerised app reaches over the internal network. The # IDE) reaches the same database the containerised app reaches over the internal network. The
# port is the one src/.env.example's APP_DATASOURCE_URL names. # port is the one .env.example's APP_DATASOURCE_URL names.
db: db:
profiles: profiles:
- jpa - jpa
+1 -1
View File
@@ -49,7 +49,7 @@ Redis ACL 파일은 완전한 `user` 줄만 받는다. 주석도, 줄 이어 쓰
## 누가 `lane-fixture-accounts.acl`을 읽나 ## 누가 `lane-fixture-accounts.acl`을 읽나
- Redis 구성(topology) lane: `src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}` - Redis 구성(topology) lane: `src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}`
- Redis를 켜는 애플리케이션 Compose lane: `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`의 - Redis를 켜는 애플리케이션 Compose lane: `src/bootstrap/app/compose-lanes/compose-profile-contracts.json`의
`local-redis`, `all-adapters` `local-redis`, `all-adapters`
- 개발 환경의 `redis` 서비스(루트 `compose.yaml`) - 개발 환경의 `redis` 서비스(루트 `compose.yaml`)
+5 -4
View File
@@ -98,6 +98,7 @@ capability(부가 기능) 하나의 지원 범위, 설정, 보안, 운영, 마
| 문서 | 무엇 | | 문서 | 무엇 |
| --- | --- | | --- | --- |
| [build.md](build.md) | 빌드 스크립트(`build.gradle`의 게이트 태스크)와 환경 변수(`.env.example`) 참조(2026-11-11 재배치 전에는 `src` 폴더의 README였다) |
| [capability-status.md](capability-status.md) | capability마다 코드가 있나·조립되나·실제 제공자로 검증됐나, 그리고 지운 코드의 표(「제거된 코드」) | | [capability-status.md](capability-status.md) | capability마다 코드가 있나·조립되나·실제 제공자로 검증됐나, 그리고 지운 코드의 표(「제거된 코드」) |
| [storage-capability-boundary.md](storage-capability-boundary.md) | 파일 서버와 객체 저장소가 각각 맡는 경계 | | [storage-capability-boundary.md](storage-capability-boundary.md) | 파일 서버와 객체 저장소가 각각 맡는 경계 |
| [vision.md](vision.md) | 비전: 누구의 어떤 문제를 푸나, 성공하면 무엇이 달라지나, 속도보다 먼저 지킬 것(세 문장, 소유자가 쓴다. 에이전트는 읽기만 한다) | | [vision.md](vision.md) | 비전: 누구의 어떤 문제를 푸나, 성공하면 무엇이 달라지나, 속도보다 먼저 지킬 것(세 문장, 소유자가 쓴다. 에이전트는 읽기만 한다) |
@@ -175,8 +176,8 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것
`grep -rn '<바꾼 이름>' docs src --include=*.md`. `grep -rn '<바꾼 이름>' docs src --include=*.md`.
- 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·태스크는 `capability-status.md` 「제거된 코드」나 - 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·태스크는 `capability-status.md` 「제거된 코드」나
`upgrade/`에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 `> 이력` 으로 시작하는 인용 블록 안에 쓴다. `upgrade/`에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 `> 이력` 으로 시작하는 인용 블록 안에 쓴다.
- 숫자·버전을 복사하지 않는다. Spring Boot 버전은 `src/gradle/libs.versions.toml`, leaf 목록과 개수는 - 숫자·버전을 복사하지 않는다. Spring Boot 버전은 `gradle/libs.versions.toml`, leaf 목록과 개수는
registry(`src/config/architecture/modules.json`)를 가리킨다. registry(`gradle/modules.json`)를 가리킨다.
- 루트 README는 「프로젝트 구조」(최상위 폴더와 `src/` 폴더가 하는 일)와 「문서 지도」(매뉴얼·계약·운영·결정·기록이 - 루트 README는 「프로젝트 구조」(최상위 폴더와 `src/` 폴더가 하는 일)와 「문서 지도」(매뉴얼·계약·운영·결정·기록이
어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs `conventions/docs-system.md` 6.1절이고, 어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs `conventions/docs-system.md` 6.1절이고,
`readme` 검사가 그 목록(`scripts/check-docs.py`의 `README_SECTIONS`)을 본다. `readme` 검사가 그 목록(`scripts/check-docs.py`의 `README_SECTIONS`)을 본다.
@@ -192,7 +193,7 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것
| `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) | | `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) |
| `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 | | `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 |
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 | | `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`, `.gitea/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`src/gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 | | `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가. Spring Boot 버전은 이름 바로 뒤(「Spring Boot」나 「Boot」 뒤의 세 자리 버전), `Spring Boot` 칸이 있는 표 행의 세 자리 버전, 정본(`gradle/libs.versions.toml`의 `springBoot`)과 같은 버전 문자열(굵은 글씨·표 칸·코드 안 포함)을 잡는다. 결정 기록, 제거 표, `upgrade/`는 보지 않는다 |
| `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 | | `map` | 이 README의 「문서 지도」가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 | | `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
| `link` | 살아 있는 문서의 마크다운 상대 링크가 이 트리의 파일·폴더를 가리키는가. 코드 블록·인라인 코드·`> 이력` 인용 블록은 보지 않는다 | | `link` | 살아 있는 문서의 마크다운 상대 링크가 이 트리의 파일·폴더를 가리키는가. 코드 블록·인라인 코드·`> 이력` 인용 블록은 보지 않는다 |
@@ -212,5 +213,5 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것
## 여기에 없는 것 ## 여기에 없는 것
- 실행되는 검증 스크립트는 문서가 아니다. `scripts/`(workflow가 부르는 것은 `scripts/ci/`)에 있다. - 실행되는 검증 스크립트는 문서가 아니다. `scripts/`(workflow가 부르는 것은 `scripts/ci/`)에 있다.
- 모듈 레지스트리·Gradle 정책은 `src/config/architecture/modules.json` 과 `src/build.gradle` 이 소유한다. - 모듈 레지스트리·Gradle 정책은 `gradle/modules.json` 과 `build.gradle` 이 소유한다.
- 각 모듈의 지역 규칙은 해당 모듈의 `src/**/AGENTS.md` 가 소유한다. - 각 모듈의 지역 규칙은 해당 모듈의 `src/**/AGENTS.md` 가 소유한다.
@@ -4,7 +4,7 @@
- 상태: 채택 - 상태: 채택
- 작성일: 2026-09-07 - 작성일: 2026-09-07
- 요약: 공유 테스트 코드는 java-test-fixtures 한 가지 방식으로 둔다는 결정이다. - 요약: 공유 테스트 코드는 java-test-fixtures 한 가지 방식으로 둔다는 결정이다.
- 현재 정본: `src/build-logic/README.md` - 현재 정본: `build-logic/README.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->
# ADR-BUILD-001: 공유 시험 코드의 표준은 `java-test-fixtures`다 # ADR-BUILD-001: 공유 시험 코드의 표준은 `java-test-fixtures`다
@@ -11,7 +11,7 @@
- 상태: 채택 - 상태: 채택
- 날짜: 2026-08-30 - 날짜: 2026-08-30
- 범위: `:grpc:*`, `:grpc-advanced:*`, `src/config/architecture/modules.json` - 범위: `:grpc:*`, `:grpc-advanced:*`, `gradle/modules.json`
## 배경 ## 배경
@@ -16,7 +16,7 @@
> **대체됨.** 정규식 `.proto` 검증기와 Buf 규칙의 Java 재구현은 지웠다. schema는 이제 `:grpc:grpc-contract` > **대체됨.** 정규식 `.proto` 검증기와 Buf 규칙의 Java 재구현은 지웠다. schema는 이제 `:grpc:grpc-contract`
> (`src/grpc/grpc-contract/src/main/proto`)에 있고 Gradle protobuf 플러그인(`com.google.protobuf`, 버전은 > (`src/grpc/grpc-contract/src/main/proto`)에 있고 Gradle protobuf 플러그인(`com.google.protobuf`, 버전은
> `src/gradle/libs.versions.toml`에 고정. protoc와 protobuf-java runtime은 둘 다 `protobufGrpc`)이 컴파일한다. 생성된 > `gradle/libs.versions.toml`에 고정. protoc와 protobuf-java runtime은 둘 다 `protobufGrpc`)이 컴파일한다. 생성된
> 소스는 그 leaf에서만 Spotless, Checkstyle, Error Prone에서 뺀다. `buf lint`와 `buf breaking` > 소스는 그 leaf에서만 Spotless, Checkstyle, Error Prone에서 뺀다. `buf lint`와 `buf breaking`
> (`src/grpc/grpc-contract/buf.yaml`, STANDARD lint, FILE breaking)은 CI의 `.github/workflows/ci-quality-gates.yml` > (`src/grpc/grpc-contract/buf.yaml`, STANDARD lint, FILE breaking)은 CI의 `.github/workflows/ci-quality-gates.yml`
> job `grpc-proto-buf`에서 돈다. proto organization은 `caskeleton`이다(예전에는 `hyeonworks`). 아래 글은 원래 결정의 > job `grpc-proto-buf`에서 돈다. proto organization은 `caskeleton`이다(예전에는 `hyeonworks`). 아래 글은 원래 결정의
@@ -19,7 +19,7 @@
## 배경 ## 배경
실시간 연결 플랫폼 설계는 스스로를 `modules/websocket` 아래 Gradle 모듈 열여덟 개로 모델링하고, 모듈마다 순수성 등급과 허용 의존 실시간 연결 플랫폼 설계는 스스로를 `modules/websocket` 아래 Gradle 모듈 열여덟 개로 모델링하고, 모듈마다 순수성 등급과 허용 의존
집합을 선언한다. 이 저장소의 `src/config/architecture/modules.json`은 leaf 목록을 가진 실패하면 닫히는 registry다. leaf 열여덟 개를 집합을 선언한다. 이 저장소의 `gradle/modules.json`은 leaf 목록을 가진 실패하면 닫히는 registry다. leaf 열여덟 개를
더하는 것은 자기 결정이 필요한 크기의 registry 변경이고, HARD-STOP #5가 그것을 은근슬쩍 하는 것을 금지한다. 더하는 것은 자기 결정이 필요한 크기의 registry 변경이고, HARD-STOP #5가 그것을 은근슬쩍 하는 것을 금지한다.
이 저장소의 앞선 플랫폼 셋 — JPA, GraphQL, HTTP 플랫폼 — 이 같은 상황을 만났고 같은 방식으로 풀었다. 이 저장소의 앞선 플랫폼 셋 — JPA, GraphQL, HTTP 플랫폼 — 이 같은 상황을 만났고 같은 방식으로 풀었다.
@@ -30,7 +30,7 @@
| R1 | `dev.caskeleton.application.notification` (직속) | public type 100개 | | R1 | `dev.caskeleton.application.notification` (직속) | public type 100개 |
| Platform | `dev.caskeleton.application.notification.platform..` | 신규 | | Platform | `dev.caskeleton.application.notification.platform..` | 신규 |
`application-core/CLAUDE.md`는 R1을 "R1 canonical"이라 부르고, `src/application/core/CLAUDE.md`는 R1을 "R1 canonical"이라 부르고,
`docs/notification/migration-guide.md`는 R0 → platform 이행만 설명하며 R1의 처분을 전혀 다루지 않는다. `docs/notification/migration-guide.md`는 R0 → platform 이행만 설명하며 R1의 처분을 전혀 다루지 않는다.
`Channel`, plan, dispatch, receipt/evidence 모델이 두 namespace에 중복 존재하고 둘 사이에 production `Channel`, plan, dispatch, receipt/evidence 모델이 두 namespace에 중복 존재하고 둘 사이에 production
bridge도 import도 없다. bridge도 import도 없다.
@@ -45,7 +45,7 @@ bridge도 import도 없다.
이유는 능력이 아니라 증거다. platform은 durable acceptance, fenced claim, event ledger, projection, 이유는 능력이 아니라 증거다. platform은 durable acceptance, fenced claim, event ledger, projection,
reconciliation을 실제 PostgreSQL 레인으로 증명한다(NOTIF-ADR-001~003). R1은 fake로 증명된 R1 계약이며 reconciliation을 실제 PostgreSQL 레인으로 증명한다(NOTIF-ADR-001~003). R1은 fake로 증명된 R1 계약이며
스스로 그렇게 선언한다 — `application-core/CLAUDE.md`가 "R1 application contract proven with fakes. 스스로 그렇게 선언한다 — `src/application/core/CLAUDE.md`가 "R1 application contract proven with fakes.
It does not claim PostgreSQL schema/locking, provider protocol, cryptographic verifier, or runtime It does not claim PostgreSQL schema/locking, provider protocol, cryptographic verifier, or runtime
wiring qualification"(fake로 증명한 R1 애플리케이션 계약이다. PostgreSQL schema·locking, provider 프로토콜, 암호 wiring qualification"(fake로 증명한 R1 애플리케이션 계약이다. PostgreSQL schema·locking, provider 프로토콜, 암호
검증기, 런타임 배선 검증은 주장하지 않는다)이라고 적어 둔 그대로다. 검증기, 런타임 배선 검증은 주장하지 않는다)이라고 적어 둔 그대로다.
+20 -20
View File
@@ -1,9 +1,9 @@
# src — 빌드 스크립트 / 환경 변수 참조 # 빌드 스크립트 / 환경 변수 참조
`src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [AGENTS.md](../AGENTS.md), 저장소 루트가 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [AGENTS.md](../AGENTS.md),
모듈별 규칙은 각 모듈의 `AGENTS.md` 가 SSOT이다. 모듈별 규칙은 각 모듈의 `AGENTS.md` 가 SSOT이다.
이 문서는 [build.gradle](build.gradle) 과 [.env.example](.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과 이 문서는 [build.gradle](../build.gradle) 과 [.env.example](../.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과
결정 근거**를 모아둔 참조용 기록이다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조" 결정 근거**를 모아둔 참조용 기록이다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조"
포인터만 남기고, "왜 이렇게 했나"는 여기서 풀어 설명한다. 포인터만 남기고, "왜 이렇게 했나"는 여기서 풀어 설명한다.
@@ -51,8 +51,8 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
app 기동(Flyway 포함) → health smoke를 순서대로 실행한다(예전 `./gradlew bootstrap`, 리뷰 app 기동(Flyway 포함) → health smoke를 순서대로 실행한다(예전 `./gradlew bootstrap`, 리뷰
BUILD-O3-5로 build-logic 플러그인에서 스크립트로 옮김). BUILD-O3-5로 build-logic 플러그인에서 스크립트로 옮김).
DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`(`db`는 `jpa` profile)이 소유하며, app startup Flyway가 DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`(`db`는 `jpa` profile)이 소유하며, app startup Flyway가
끝나 public health endpoint가 준비되어야 다음 단계로 넘어간다. `src/.env.example`은 커밋된 끝나 public health endpoint가 준비되어야 다음 단계로 넘어간다. `.env.example`은 커밋된
env 계약이고 `src/.env`는 로컬 실행 입력이다. `verifyEnvKeys`는 example/registry/shipped YAML을 env 계약이고 `.env`는 로컬 실행 입력이다. `verifyEnvKeys`는 example/registry/shipped YAML을
함께 검사한다. 함께 검사한다.
### 추적 가능한 버전과 의존성 잠금 ### 추적 가능한 버전과 의존성 잠금
@@ -94,7 +94,7 @@ archive task 자체는 timestamp 비보존·재현 가능한 file order·고정
### `verifyCleanArchitectureDependencies` ### `verifyCleanArchitectureDependencies`
- **하는 일.** [config/architecture/modules.json](config/architecture/modules.json)의 - **하는 일.** [gradle/modules.json](../gradle/modules.json)의
`allowed_dependencies`를 읽고, 실제 Gradle 프로젝트 의존(`api` / `implementation` / `allowed_dependencies`를 읽고, 실제 Gradle 프로젝트 의존(`api` / `implementation` /
`compileOnly` / `runtimeOnly`)이 그 범위를 벗어나면 빌드를 실패시킨다. `compileOnly` / `runtimeOnly`)이 그 범위를 벗어나면 빌드를 실패시킨다.
- **JSON registry가 의존 방향의 SSOT이다.** 새 모듈이나 새 production 의존 edge를 추가하면 - **JSON registry가 의존 방향의 SSOT이다.** 새 모듈이나 새 production 의존 edge를 추가하면
@@ -102,7 +102,7 @@ archive task 자체는 timestamp 비보존·재현 가능한 file order·고정
같은 registry를 읽고, 등록되지 않은 leaf나 허용되지 않은 edge를 fail-closed로 거부한다. 같은 registry를 읽고, 등록되지 않은 leaf나 허용되지 않은 edge를 fail-closed로 거부한다.
조립 루트가 받는 모듈의 별도 membership 검사는 없다. `app-bootstrap`의 `allowed_dependencies` 조립 루트가 받는 모듈의 별도 membership 검사는 없다. `app-bootstrap`의 `allowed_dependencies`
밖의 모듈은 방향 게이트가 막고, 무엇이 실제로 실리는지는 `app-bootstrap/build.gradle`의 의존성이 밖의 모듈은 방향 게이트가 막고, 무엇이 실제로 실리는지는 `src/bootstrap/app/build.gradle`의 의존성이
정한다. 정한다.
세 opt-in inbound transport의 test-only composition, 실제 wire 경계, positive-count/zero-skip 증거는 세 opt-in inbound transport의 test-only composition, 실제 wire 경계, positive-count/zero-skip 증거는
@@ -131,7 +131,7 @@ Checkstyle은 파싱된 파일에 같은 질문을 하고, leaf 단위로 돈다
태스크는 app-bootstrap에 유지, `build-tools` included build는 비워서 삭제). 태스크는 app-bootstrap에 유지, `build-tools` included build는 비워서 삭제).
- **하는 일.** `docs/registries/env-keys.yaml`, app-bootstrap의 `application*.yml` + `config/*.yml`, - **하는 일.** `docs/registries/env-keys.yaml`, app-bootstrap의 `application*.yml` + `config/*.yml`,
capability 모듈이 싣는 `config/*.yml`·`config/module-defaults/*.yml`(기본 조립에 없어도 검사한다), capability 모듈이 싣는 `config/*.yml`·`config/module-defaults/*.yml`(기본 조립에 없어도 검사한다),
`src/.env.example`을 lock-step(서로 어긋나지 않게) 으로 유지한다. `env-keys.yaml` 이 `APP_` 키의 SSOT 이고, drift 가 생기면 빌드를 `.env.example`을 lock-step(서로 어긋나지 않게) 으로 유지한다. `env-keys.yaml` 이 `APP_` 키의 SSOT 이고, drift 가 생기면 빌드를
실패시킨다. 실패시킨다.
- **막으려는 것 3가지.** (1) 필수 env 가 조용히 누락되는 것, (2) 더 이상 쓰지 않는 stale env 키가 - **막으려는 것 3가지.** (1) 필수 env 가 조용히 누락되는 것, (2) 더 이상 쓰지 않는 stale env 키가
`.env.example` 에 남는 것, (3) 실제로 쓰는 `APP_` 키가 registry 에 등록되지 않고 빠져나가는 것. `.env.example` 에 남는 것, (3) 실제로 쓰는 `APP_` 키가 registry 에 등록되지 않고 빠져나가는 것.
@@ -143,15 +143,15 @@ Checkstyle은 파싱된 파일에 같은 질문을 하고, leaf 단위로 돈다
- **C.** `.env.example` 의 모든 `APP_` 키는 registry 에 `- name: <KEY>` 행이 있어야 한다. - **C.** `.env.example` 의 모든 `APP_` 키는 registry 에 `- name: <KEY>` 행이 있어야 한다.
- **`SPRING_*` 키는 왜 registry 추적 대상이 아닌가.** `SPRING_*` 는 Spring Boot 가 정의한 native 키라 - **`SPRING_*` 키는 왜 registry 추적 대상이 아닌가.** `SPRING_*` 는 Spring Boot 가 정의한 native 키라
프로젝트가 소유한 계약이 아니다. 그래서 C 검사는 일부러 `APP_` prefix 로만 범위를 좁혔다. 프로젝트가 소유한 계약이 아니다. 그래서 C 검사는 일부러 `APP_` prefix 로만 범위를 좁혔다.
- **비고.** `src/.env.example`이 커밋된 환경 계약이고 `src/.env`는 로컬 실행용 입력이다. - **비고.** `.env.example`이 커밋된 환경 계약이고 `.env`는 로컬 실행용 입력이다.
### `verifyPublicPathSnapshot` ### `verifyPublicPathSnapshot`
- **하는 일.** deny-by-default public path 표면이 승인 없이 바뀌면 빌드를 실패시킨다. - **하는 일.** deny-by-default public path 표면이 승인 없이 바뀌면 빌드를 실패시킨다.
- **배경.** 이 앱은 deny-by-default이다. 즉 `SECURITY_PUBLIC_PATHS` 가 먹이는 명시적 `permitAll()` - **배경.** 이 앱은 deny-by-default이다. 즉 `SECURITY_PUBLIC_PATHS` 가 먹이는 명시적 `permitAll()`
경로를 **제외한** 모든 요청은 인증을 요구한다 경로를 **제외한** 모든 요청은 인증을 요구한다
(`app-bootstrap/src/main/resources/config/security.yml` → `SecuritySettings.publicPaths()` → (`src/bootstrap/app/src/main/resources/config/security.yml` → `SecuritySettings.publicPaths()` →
`SecurityConfig`). 설정 분할 이전에는 이 SSOT 가 `src/.env` 였고 문서만 그대로 남아 있었다. `SecurityConfig`). 설정 분할 이전에는 이 SSOT 가 `.env` 였고 문서만 그대로 남아 있었다.
스냅샷 플러그인이 실제로 읽는 파일은 `config/security.yml`이다 스냅샷 플러그인이 실제로 읽는 파일은 `config/security.yml`이다
(`build-logic/.../publicpath/PublicPathSnapshotPlugin.java`). (`build-logic/.../publicpath/PublicPathSnapshotPlugin.java`).
이 public 표면이 바뀌는 순간이 곧 보호되던 엔드포인트가 조용히 공개로 노출되는 지점이다. 이 public 표면이 바뀌는 순간이 곧 보호되던 엔드포인트가 조용히 공개로 노출되는 지점이다.
@@ -207,7 +207,7 @@ drift하기 시작하면 그때 자동화한다. 진짜 항목을 상대로, 진
## .env — 환경 변수 레퍼런스 ## .env — 환경 변수 레퍼런스
`spring-dotenv` 가 `src/.env` 를 읽어 외부화 설정을 주입한다(`bootRun` 의 working dir 가 `src/` 라 `spring-dotenv` 가 `.env` 를 읽어 외부화 설정을 주입한다(`bootRun` 의 working dir 가 저장소 루트라
이 파일이 잡힌다). 아래는 섹션별 키 설명이다. 따로 표기가 없으면 `restart-only`(값 변경 시 재기동 이 파일이 잡힌다). 아래는 섹션별 키 설명이다. 따로 표기가 없으면 `restart-only`(값 변경 시 재기동
필요)로 간주한다. 필요)로 간주한다.
@@ -253,10 +253,10 @@ drift하기 시작하면 그때 자동화한다. 진짜 항목을 상대로, 진
기본 조립(`bootJar`)에는 web, 관측(actuator·metrics·tracing·로그), `domain-core`·`application-core`· 기본 조립(`bootJar`)에는 web, 관측(actuator·metrics·tracing·로그), `domain-core`·`application-core`·
`shared-contract`, `adapter:outbound:support`·`adapter:outbound:identifier`만 들어 있다. DB·Redis· `shared-contract`, `adapter:outbound:support`·`adapter:outbound:identifier`만 들어 있다. DB·Redis·
Kafka 없이 기동한다. 나머지 기능은 `app-bootstrap/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄로 Kafka 없이 기동한다. 나머지 기능은 `src/bootstrap/app/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄로
있다. 있다.
- **켜기:** 그 줄의 주석을 풀고, 아래 env를 `src/.env`에 넣는다. 모듈이 classpath에 있으면 켜진다. - **켜기:** 그 줄의 주석을 풀고, 아래 env를 `.env`에 넣는다. 모듈이 classpath에 있으면 켜진다.
- **끄기:** 줄을 지운다. 모듈의 bean·설정·의존성이 함께 빠진다. 줄은 두고 잠시 끄려면 "끄는 키"를 - **끄기:** 줄을 지운다. 모듈의 bean·설정·의존성이 함께 빠진다. 줄은 두고 잠시 끄려면 "끄는 키"를
`false`로 준다(모든 키의 기본값은 `true`). `false`로 준다(모든 키의 기본값은 `true`).
- **줄을 바꾼 뒤:** strict lock을 갱신한다. - **줄을 바꾼 뒤:** strict lock을 갱신한다.
@@ -296,9 +296,9 @@ Kafka 없이 기동한다. 나머지 기능은 `app-bootstrap/build.gradle`에
### Compose와 런타임 스모크 ### Compose와 런타임 스모크
- **Docker Compose 최소 버전은 `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`의 - **Docker Compose 최소 버전은 `src/bootstrap/app/compose-lanes/compose-profile-contracts.json`의
`minimumComposeVersion`이다.** 정본 스크립트가 검증한다. lane은 저장소 루트 `compose.yaml`(개발 환경)을 바탕으로 쓰고, lane에만 `minimumComposeVersion`이다.** 정본 스크립트가 검증한다. lane은 저장소 루트 `compose.yaml`(개발 환경)을 바탕으로 쓰고, lane에만
필요한 overlay·smoke client·스키마 적용은 `src/app-bootstrap/compose-lanes/`에 있다. 필요한 overlay·smoke client·스키마 적용은 `src/bootstrap/app/compose-lanes/`에 있다.
- 진입점은 둘뿐이고, 그 둘만이 증거다. 워크플로에 명령 일부를 인라인하면 one-shot 없이 도는 레인이 - 진입점은 둘뿐이고, 그 둘만이 증거다. 워크플로에 명령 일부를 인라인하면 one-shot 없이 도는 레인이
초록으로 보고된다. 초록으로 보고된다.
@@ -308,7 +308,7 @@ Kafka 없이 기동한다. 나머지 기능은 `app-bootstrap/build.gradle`에
# 동적: 계약의 blocking 레인을 zero-skip으로. create → up --wait → 필수 one-shot → # 동적: 계약의 blocking 레인을 zero-skip으로. create → up --wait → 필수 one-shot →
# 컨테이너 재시작·OOM 0 확인 → sanitized evidence → 고유 project teardown # 컨테이너 재시작·OOM 0 확인 → sanitized evidence → 고유 project teardown
./scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json ./scripts/run-compose-runtime-smoke.sh --matrix src/bootstrap/app/compose-lanes/compose-profile-contracts.json
``` ```
`--lane <id>`는 실패 재현용이고, 레인 하나가 초록인 것은 matrix가 통과했다는 증거가 아니다. `--lane <id>`는 실패 재현용이고, 레인 하나가 초록인 것은 matrix가 통과했다는 증거가 아니다.
@@ -357,7 +357,7 @@ app:
- `ACTIVE`는 exact destination/provider/operation-catalog binding을 요구한다. 현재 유일한 - `ACTIVE`는 exact destination/provider/operation-catalog binding을 요구한다. 현재 유일한
buffered-classic readiness card가 `NOT_IMPLEMENTED`이므로 provider resource 생성 전에 buffered-classic readiness card가 `NOT_IMPLEMENTED`이므로 provider resource 생성 전에
fail-closed한다. 아직 운영 HTTP provider를 활성화할 수 있다는 뜻이 아니다. fail-closed한다. 아직 운영 HTTP provider를 활성화할 수 있다는 뜻이 아니다.
- 기존 `APP_OUTBOUND_HTTP_*`와 `app.outbound.http.*`는 canonical 설정이 아니다. 루트 `src/.env`, - 기존 `APP_OUTBOUND_HTTP_*`와 `app.outbound.http.*`는 canonical 설정이 아니다. 루트 `.env`,
`app-bootstrap`의 application YAML, env-key registry에서 제거됐으며 canonical composition에 `app-bootstrap`의 application YAML, env-key registry에서 제거됐으며 canonical composition에
입력하면 상태와 무관하게 기동을 거부한다. 입력하면 상태와 무관하게 기동을 거부한다.
- 그 키를 시연하던 샘플 모듈의 YAML은 2026-11-07 샘플과 함께 지웠다. 이제 저장소 어디에도 남아 있지 않다. - 그 키를 시연하던 샘플 모듈의 YAML은 2026-11-07 샘플과 함께 지웠다. 이제 저장소 어디에도 남아 있지 않다.
@@ -381,7 +381,7 @@ app:
**파일 출력 + rolling** **파일 출력 + rolling**
- **`APP_LOG_FILE_ENABLED`** — `true` 면 rolling JSON 파일 appender 를 붙인다. - **`APP_LOG_FILE_ENABLED`** — `true` 면 rolling JSON 파일 appender 를 붙인다.
- **`APP_LOG_FILE_PATH`** — `bootRun` working dir(`src/`) 기준 상대 경로 또는 절대 경로. - **`APP_LOG_FILE_PATH`** — `bootRun` working dir(저장소 루트) 기준 상대 경로 또는 절대 경로. 기본값 `logs/…`는 git이 무시한다.
- **`APP_LOG_FILE_MAX_SIZE`** — 파일 1개 최대 크기(단위 `KB` | `MB` | `GB`). - **`APP_LOG_FILE_MAX_SIZE`** — 파일 1개 최대 크기(단위 `KB` | `MB` | `GB`).
- **`APP_LOG_FILE_MAX_HISTORY`** — 보관할 rolled archive 개수. 1 이상 정수. - **`APP_LOG_FILE_MAX_HISTORY`** — 보관할 rolled archive 개수. 1 이상 정수.
- **`APP_LOG_FILE_TOTAL_SIZE_CAP`** — 전체 rolled 파일 용량 상한(단위 `KB` | `MB` | `GB`, `0` = 비활성). - **`APP_LOG_FILE_TOTAL_SIZE_CAP`** — 전체 rolled 파일 용량 상한(단위 `KB` | `MB` | `GB`, `0` = 비활성).
@@ -511,7 +511,7 @@ Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 한다(
### 프로파일과 데이터베이스 ### 프로파일과 데이터베이스
프로파일마다 데이터스토어가 다르고, 그 차이는 `app-bootstrap/src/main/resources/application-*.yml` 프로파일마다 데이터스토어가 다르고, 그 차이는 `src/bootstrap/app/src/main/resources/application-*.yml`
가 소유한다. 가 소유한다.
| 프로파일 | 데이터스토어 | 스키마 소유자 | 외부 인프라 | | 프로파일 | 데이터스토어 | 스키마 소유자 | 외부 인프라 |
+3 -3
View File
@@ -8,8 +8,8 @@ real provider."
| Column | The question | Who decides it | | Column | The question | Who decides it |
| --- | --- | --- | | --- | --- | --- |
| **IMPLEMENTED** | Does this repository contain the capability? | `src/config/architecture/modules.json` — the leaf is registered | | **IMPLEMENTED** | Does this repository contain the capability? | `gradle/modules.json` — the leaf is registered |
| **WIRED** | Present when selected: does the module assemble itself — own `AutoConfiguration.imports`, own settings, on when present, off with `enabled=false` — once a service adds its one `runtimeOnly` line to `app-bootstrap/build.gradle`? | the leaf's `META-INF/spring/...AutoConfiguration.imports`, the commented line in `app-bootstrap/build.gradle`, and an activation test in the leaf (present = on, `enabled=false` = off) | | **WIRED** | Present when selected: does the module assemble itself — own `AutoConfiguration.imports`, own settings, on when present, off with `enabled=false` — once a service adds its one `runtimeOnly` line to `src/bootstrap/app/build.gradle`? | the leaf's `META-INF/spring/...AutoConfiguration.imports`, the commented line in `src/bootstrap/app/build.gradle`, and an activation test in the leaf (present = on, `enabled=false` = off) |
| **QUALIFIED** | Has it been proven against a real provider, by something CI runs? | a strict test lane against a real provider **and** a workflow that executes it | | **QUALIFIED** | Has it been proven against a real provider, by something CI runs? | a strict test lane against a real provider **and** a workflow that executes it |
The third column is the one that rots quietly, because a lane can exist and be invoked by nothing. The third column is the one that rots quietly, because a lane can exist and be invoked by nothing.
@@ -20,7 +20,7 @@ Each row below names the lane *and* the workflow, so "qualified" can be checked
The default composition — what `bootJar` builds — is web, observability, `domain-core`, The default composition — what `bootJar` builds — is web, observability, `domain-core`,
`application-core`, `shared-contract`, `adapter:outbound:support` and `adapter:outbound:identifier`. `application-core`, `shared-contract`, `adapter:outbound:support` and `adapter:outbound:identifier`.
Every **yes** row in WIRED below is absent from it until a service uncomments that row's Every **yes** row in WIRED below is absent from it until a service uncomments that row's
`runtimeOnly` line in `app-bootstrap/build.gradle`. A module on the classpath is on; its enabled key `runtimeOnly` line in `src/bootstrap/app/build.gradle`. A module on the classpath is on; its enabled key
defaults to `true`, and `false` turns a present module fully off. `./gradlew defaults to `true`, and `false` turns a present module fully off. `./gradlew
:app-bootstrap:qualificationBootJar` packages the main runtime plus every capability, for compose :app-bootstrap:qualificationBootJar` packages the main runtime plus every capability, for compose
lanes and CI; it is not a deployment artifact. lanes and CI; it is not a deployment artifact.
+1 -1
View File
@@ -41,7 +41,7 @@
## 파생 프로젝트가 할 일 ## 파생 프로젝트가 할 일
1. Template 전용 표의 항목을 삭제한다. 삭제는 대부분 파일 삭제 + `config/architecture/modules.json` 1. Template 전용 표의 항목을 삭제한다. 삭제는 대부분 파일 삭제 + `gradle/modules.json`
에서 leaf 항목 제거로 끝난다 — 레지스트리가 leaf 목록의 SSOT이고, 개수를 따로 적어 둔 곳은 없다. 에서 leaf 항목 제거로 끝난다 — 레지스트리가 leaf 목록의 SSOT이고, 개수를 따로 적어 둔 곳은 없다.
2. `docs/ci-cd/boundary.md`의 경계를 그대로 유지한 채 자기 GitOps 저장소를 연결한다. 2. `docs/ci-cd/boundary.md`의 경계를 그대로 유지한 채 자기 GitOps 저장소를 연결한다.
3. `.trivyignore.yaml`과 CODEOWNERS는 그대로 쓴다. 3. `.trivyignore.yaml`과 CODEOWNERS는 그대로 쓴다.
@@ -4,7 +4,7 @@
- 상태: 대체됨 - 상태: 대체됨
- 작성일: 2026-07-20 - 작성일: 2026-07-20
- 요약: 중복된 하네스 규칙을 레지스트리 기반 정책 엔진으로 바꾸려던 설계다. - 요약: 중복된 하네스 규칙을 레지스트리 기반 정책 엔진으로 바꾸려던 설계다.
- 현재 정본: `src/config/architecture/modules.json` - 현재 정본: `gradle/modules.json`
- 대체됨: `docs/design/2026-07-25-harness-free-mode-b-amendment.md` - 대체됨: `docs/design/2026-07-25-harness-free-mode-b-amendment.md`
<!-- 머리 블록 끝 --> <!-- 머리 블록 끝 -->

Some files were not shown because too many files have changed in this diff Show More