Merge pull request 'refactor!: 확인 리뷰 수정과 저장소 구조·문서 체계 정리를 합친다' (#2) from refactor/maturity-review-2026-11 into main

This commit was merged in pull request #2.
This commit is contained in:
2026-11-07 07:51:45 +00:00
1760 changed files with 16368 additions and 26894 deletions
+7
View File
@@ -0,0 +1,7 @@
{
"permissions": {
"deny": [
"Agent"
]
}
}
+25 -27
View File
@@ -57,20 +57,10 @@ jobs:
run: ./gradlew :verifyStrictLaneStages --dry-run --stacktrace
- name: Verify Compose profile contracts render exactly as declared
run: bash scripts/verify-compose-profile-contracts.sh
sample-portfolio:
# The sample is excluded from production architecture/runtime membership policy, but it is still
# the reference implementation adopters copy. Compile/test/OpenAPI drift must therefore block PRs.
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
# `qualityCheck` too: the root one covers the production leaves only, so the sample — the code
# adopters copy first — was analysed by no stage, and its SpotBugs exclusions matched nothing
# (review 2026-11-03 RR-06-05).
- name: Verify the standalone sample application
working-directory: src
run: ./gradlew :sample-portfolio:check :sample-portfolio:qualityCheck --stacktrace
# The repository root and src/ hold only the entries on the allow list (owner decision
# 2026-11-07): a new top-level folder is a decision, not a side effect of a feature commit.
- name: Refuse a top-level folder outside the allow list
run: python3 scripts/check-repo-layout.py
optional-platforms:
runs-on: ubuntu-latest
@@ -79,15 +69,15 @@ jobs:
- uses: ./.github/actions/setup-gradle-java
- name: Verify the optional gRPC platform build
working-directory: src
run: ./gradlew -p optional-platforms ci --stacktrace
run: ./gradlew -p platforms/optional-build ci --stacktrace
# The optional build's own lane-reachability check: the main build's cannot see these lanes
# (review 2026-11-03 RR-06-03).
- name: Require every optional-platform strict lane to be in an executed stage
working-directory: src
run: ./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run --stacktrace
run: ./gradlew -p platforms/optional-build :verifyStrictLaneStages --dry-run --stacktrace
# gRPC schema policy (owner decision 18). protoc compiles src/grpc/grpc-contract inside the
# optional-platforms build above; lint and breaking-change policy belong to Buf, configured by
# gRPC schema policy (owner decision 18). protoc compiles src/platforms/grpc/grpc-contract inside
# the optional-platforms build above; lint and breaking-change policy belong to Buf, configured by
# buf.yaml next to the schema. Buf is a native binary rather than a Maven artifact, so it runs here
# and not inside Gradle — and nothing in the repository re-implements its rules.
grpc-proto-buf:
@@ -102,28 +92,38 @@ jobs:
version: 1.73.0
setup_only: true
- name: Lint the gRPC schema
working-directory: src/grpc/grpc-contract
working-directory: src/platforms/grpc/grpc-contract
run: buf lint
- name: Refuse a breaking change to the gRPC schema
working-directory: src/grpc/grpc-contract
working-directory: src/platforms/grpc/grpc-contract
env:
# Pull request: the target branch. Push: the commit this push replaced.
BASELINE: ${{ github.event_name == 'pull_request' && format('origin/{0}', github.base_ref) || github.event.before }}
run: |
set -euo pipefail
baseline_commit="$(git rev-parse --verify --quiet "${BASELINE}^{commit}" || true)"
if [[ -z "${baseline_commit}" ]] \
|| ! git cat-file -e "${baseline_commit}:src/grpc/grpc-contract/buf.yaml" 2>/dev/null; then
# The module moved from src/grpc to src/platforms/grpc on 2026-11-07. A baseline from
# before the move holds it at the old path, and comparing against that path keeps the
# breaking check running across the move instead of skipping it once.
baseline_dir=""
if [[ -n "${baseline_commit}" ]]; then
for candidate in src/platforms/grpc/grpc-contract src/grpc/grpc-contract; do
if git cat-file -e "${baseline_commit}:${candidate}/buf.yaml" 2>/dev/null; then
baseline_dir="${candidate}"
break
fi
done
fi
if [[ -z "${baseline_dir}" ]]; then
# The first change that introduces the module has nothing to be compatible with.
echo "::notice::grpc-proto-buf: baseline ${BASELINE} has no src/grpc/grpc-contract/buf.yaml; breaking check skipped."
echo "::notice::grpc-proto-buf: baseline ${BASELINE} has no grpc-contract/buf.yaml; breaking check skipped."
exit 0
fi
buf breaking --against "../../../.git#ref=${baseline_commit},subdir=src/grpc/grpc-contract"
buf breaking --against "../../../../.git#ref=${baseline_commit},subdir=${baseline_dir}"
release-gate:
needs:
- quality-gates
- sample-portfolio
- optional-platforms
- grpc-proto-buf
if: always()
@@ -134,14 +134,12 @@ jobs:
- name: Require every current blocking job to succeed
env:
QUALITY_RESULT: ${{ needs.quality-gates.result }}
SAMPLE_RESULT: ${{ needs.sample-portfolio.result }}
OPTIONAL_PLATFORMS_RESULT: ${{ needs.optional-platforms.result }}
GRPC_PROTO_BUF_RESULT: ${{ needs.grpc-proto-buf.result }}
run: |
set -euo pipefail
for result in \
"${QUALITY_RESULT}" \
"${SAMPLE_RESULT}" \
"${OPTIONAL_PLATFORMS_RESULT}" \
"${GRPC_PROTO_BUF_RESULT}"; do
if [[ "${result}" != "success" ]]; then
+28
View File
@@ -0,0 +1,28 @@
name: docs-check
# Document language, record head blocks, references and copied numbers (scripts/check-docs.py).
# It runs on every pull request, not on a docs/** path filter: deleting a file or a Gradle project
# in code is exactly what makes a living document point at nothing, and that change touches no
# document. The checker is plain Python outside Gradle, because the build does not parse documents.
on:
pull_request:
push:
branches: ["main"]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- name: Test the document checker
run: python3 -m unittest discover -s scripts/tests
- name: Check documents
run: python3 scripts/check-docs.py
+2 -2
View File
@@ -26,7 +26,7 @@ jobs:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
- name: Start the NFSv4 certification environment
run: docker compose -f infra/fileserver/nfs/compose.yml up -d --wait
run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d --wait
- name: Run the network-filesystem ambiguity suite
working-directory: src
run: >-
@@ -35,7 +35,7 @@ jobs:
--stacktrace
- name: Tear down the NFS environment
if: always()
run: docker compose -f infra/fileserver/nfs/compose.yml down -v
run: docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml down -v
fileserver-process-kill-matrix:
runs-on: ubuntu-latest
+2 -4
View File
@@ -24,10 +24,8 @@ on:
- 'src/.env'
- 'docs/registries/env-keys.yaml'
- 'src/Dockerfile'
- 'docker-compose.yml'
- 'infra/fileserver/nginx/**'
- 'infra/fileserver/kubernetes/**'
- 'infra/fileserver/nfs/**'
- 'compose.yaml'
- 'src/app-bootstrap/compose-lanes/fileserver.yaml'
- '.github/workflows/fileserver-pr.yml'
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
+8 -9
View File
@@ -60,7 +60,7 @@ concurrency:
jobs:
# The main-branch stage of the Gradle gates (`:mainCheck`): the environment contract, full-boot
# qualification, the sample web contract, the public-path baseline, the conditional transport
# qualification, the public-path baseline, the conditional transport
# lanes, the messaging contract lanes and each leaf's document-contract lanes. API surfaces are
# in the pull-request `check` (owner decision 20). The rest left the pull-request gate (review
# 2026-09-24 BUILD, item 12); none of them is deleted.
@@ -189,13 +189,12 @@ jobs:
# never catches. This job replaced `web-load-abuse-and-shutdown`, which despite its name ran
# `:adapter:inbound:web:test` and `webJettyCompatTest` — two lanes the pull-request and main stages
# already run — and never the load lanes (review 2026-11-01 08-01), and `httpclient-performance`.
# No assertions switch: the strict-lane convention asserts every performance lane's bounds, so this
# job and a person on a workstation run the same command and get the same bounds.
performance-check:
runs-on: ubuntu-latest
timeout-minutes: 120
env:
# A project property rather than a command-line flag, so the run command stays a plain,
# verifiable task invocation while the machine-dependent bounds are still asserted.
GRADLE_OPTS: -Dorg.gradle.project.performance.assertions.enabled=true
TESTCONTAINERS_REUSE_ENABLE: "false"
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
@@ -208,7 +207,7 @@ jobs:
- name: Run every optional-platform performance-category strict lane
if: always()
working-directory: src
run: ./gradlew -p optional-platforms performanceCheck --continue --stacktrace
run: ./gradlew -p platforms/optional-build performanceCheck --continue --stacktrace
- name: Publish the performance lane reports
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
@@ -235,7 +234,7 @@ jobs:
# `grpc-operation-ledger-jpa:integrationTest`, which certifies the atomic
# `INSERT ... ON CONFLICT DO NOTHING` claim that durable mutation idempotency rests on against a
# real PostgreSQL. It was registered in Gradle, listed in `strictTestLanes`, and invoked by
# nothing: `-p optional-platforms ci` reaches `checkAll`, `qualityCheck` and the dependency
# nothing: `-p platforms/optional-build ci` reaches `checkAll`, `qualityCheck` and the dependency
# verifier, none of which runs a lane whose category is INTEGRATION, and release.yml's gRPC gate
# names only the three grpc-testkit lanes.
#
@@ -251,13 +250,13 @@ jobs:
- uses: ./.github/actions/setup-gradle-java
- name: Certify the gRPC operation ledger against real PostgreSQL
working-directory: src
run: ./gradlew -p optional-platforms integrationCheck --stacktrace
run: ./gradlew -p platforms/optional-build integrationCheck --stacktrace
- name: Publish the optional-platform lane reports
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: grpc-optional-platform-integration-reports
path: src/optional-platforms/**/build/reports/tests/
path: src/platforms/grpc*/**/build/reports/tests/
if-no-files-found: warn
# Dynamic half of the compose-profile contract. Every blocking lane the matrix declares runs on
@@ -273,7 +272,7 @@ jobs:
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- name: Run every blocking Compose runtime lane
run: bash scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json
run: bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
- name: Publish sanitized runtime-smoke evidence
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
@@ -15,7 +15,7 @@ name: messaging-certification
on:
pull_request:
paths:
- "src/messaging/**"
- "src/platforms/messaging/**"
- ".github/workflows/messaging-certification.yml"
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
@@ -47,5 +47,5 @@ jobs:
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: messaging-broker-certification-evidence
path: src/messaging/messaging-kafka/build/messaging-certification/
path: src/platforms/messaging/messaging-kafka/build/messaging-certification/
if-no-files-found: warn
+1 -1
View File
@@ -30,7 +30,7 @@ on:
- 'src/config/architecture/modules.json'
- 'src/.env'
- 'docs/notification/**'
- 'infra/notification/**'
- 'src/app-bootstrap/compose-lanes/smoke/notification-smoke.sh'
- '.github/workflows/notification-platform.yml'
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
-1
View File
@@ -123,7 +123,6 @@ jobs:
'^src/config/architecture/modules\.json$' \
'^docs/jpa/' \
'^docs/adr/ADR-JPA-' \
'^infra/jpa/' \
"${common}"
# The servlet system contract on both containers the template supports (Tomcat, Jetty). Real
+5 -5
View File
@@ -1,6 +1,6 @@
# Redis SDK topology evidence.
#
# The lanes in infra/redis-sdk answer what the deterministic in-memory gateway cannot — Sentinel
# The lanes in src/adapter/outbound/redis-sdk/compose answer what the deterministic in-memory gateway cannot — Sentinel
# promotion behaviour, Cluster redirects, ACL coverage. docs/redis/support-matrix.md records which
# lane produced which evidence, and RedisSupportMatrixTest refuses an evidence claim that does not
# name the test class behind it.
@@ -34,7 +34,7 @@ on:
- "src/adapter/outbound/redis-runtime/**"
- "src/adapter/outbound/redis-sdk/**"
- "src/adapter/outbound/cache-redis/**"
- "infra/redis-sdk/**"
- "compose/redis/**"
- ".github/workflows/redis-sdk-topology.yml"
# Every Gradle job here installs its toolchain through this composite action, so a change to
# it changes what this gate runs.
@@ -122,7 +122,7 @@ jobs:
- name: Start the topology
env:
REDIS_VERSION: ${{ matrix.redis_version }}
run: docker compose -f "infra/redis-sdk/${{ matrix.topology }}/compose.yml" up -d --wait
run: docker compose -f "src/adapter/outbound/redis-sdk/compose/${{ matrix.topology }}/compose.yml" up -d --wait
- name: Record the image digest
id: image
run: |
@@ -161,7 +161,7 @@ jobs:
# however loudly the file is named "test".
tls)
port=6390
docker compose -f ../infra/redis-sdk/tls/compose.yml cp redis:/tls/ca.crt "$RUNNER_TEMP/redis-lane-ca.pem"
docker compose -f adapter/outbound/redis-sdk/compose/tls/compose.yml cp redis:/tls/ca.crt "$RUNNER_TEMP/redis-lane-ca.pem"
extra="-Predis.topology.trust-material=$RUNNER_TEMP/redis-lane-ca.pem"
tasks="$runtime"
;;
@@ -199,4 +199,4 @@ jobs:
retention-days: 90
- name: Stop the topology
if: always()
run: docker compose -f "infra/redis-sdk/${{ matrix.topology }}/compose.yml" down -v
run: docker compose -f "src/adapter/outbound/redis-sdk/compose/${{ matrix.topology }}/compose.yml" down -v
+5 -31
View File
@@ -132,7 +132,7 @@ jobs:
- uses: ./.github/actions/setup-gradle-java
- name: Run the gRPC Stable certification lanes
working-directory: src
run: ./gradlew -p optional-platforms releaseCheck --stacktrace
run: ./gradlew -p platforms/optional-build releaseCheck --stacktrace
# The operation ledger's real-PostgreSQL lane ran only on main and nightly
# (integration-main.yml), so a tag could be cut from a main whose ledger lane was red. It needs
# Docker, which a release runner has (review 2026-11-01 03-12).
@@ -140,15 +140,15 @@ jobs:
working-directory: src
env:
TESTCONTAINERS_REUSE_ENABLE: "false"
run: ./gradlew -p optional-platforms integrationCheck --stacktrace
run: ./gradlew -p platforms/optional-build integrationCheck --stacktrace
- name: Publish the gRPC release evidence
if: always()
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # actions/upload-artifact@v4.6.2
with:
name: grpc-release-evidence
path: |
src/grpc/grpc-testkit/build/reports/tests/
src/grpc/grpc-operation-ledger-jpa/build/reports/tests/
src/platforms/grpc/grpc-testkit/build/reports/tests/
src/platforms/grpc/grpc-operation-ledger-jpa/build/reports/tests/
if-no-files-found: warn
# Each gate runs as its own single-line `./gradlew <task>` step so that a failure names the gate
@@ -160,10 +160,6 @@ jobs:
defaults:
run:
working-directory: src
env:
# A project property rather than a command-line flag, so each run command stays a plain,
# verifiable task invocation while the machine-dependent bounds are still asserted.
GRADLE_OPTS: -Dorg.gradle.project.performance.assertions.enabled=true
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
- uses: ./.github/actions/setup-gradle-java
@@ -198,7 +194,7 @@ jobs:
# docs/jpa/support-matrix.md recorded all three as covered. start() now fails closed on a
# multi-version selection, so this matrix is the only way the Stable majors get covered.
#
# config/jpa/release-registry.json is the gate-task source: jpaReleaseQualification (persistence-jpa
# persistence-jpa release/release-registry.json is the gate-task source: jpaReleaseQualification (persistence-jpa
# build.gradle) depends on its blocking gates, so a gate naming a missing task fails when the task
# graph is built, and JpaReleaseRenderingTest holds this matrix and the promotion list below to the
# registry's Stable majors. Editing one without the other fails the persistence-jpa unit lane.
@@ -330,27 +326,6 @@ jobs:
:composition:fileserver-platform:test --tests '*FileserverDocumentationCoverageTest'
--stacktrace
fileserver-pvc-certification:
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # actions/checkout@v4.2.2
# This job checks the manifest, and only the manifest; it applies nothing to a cluster. The
# cluster result comes from an operator running infra/fileserver/kubernetes/
# pvc-certification-job.yaml and recording it in docs/fileserver/storage-certification.md,
# where the absence of a cluster result is stated rather than hidden behind a green check.
- name: Check the certification manifest still says what the claim depends on
run: |
set -euo pipefail
manifest=infra/fileserver/kubernetes/pvc-certification-job.yaml
test -f "$manifest"
grep -q 'kind: PersistentVolumeClaim' "$manifest"
grep -q 'kind: Job' "$manifest"
# ReadWriteMany is explicitly not claimed; a manifest that quietly widened the access
# mode would certify a topology the support matrix says is uncertified.
grep -q 'ReadWriteOnce' "$manifest"
! grep -q 'ReadWriteMany' "$manifest"
fileserver-sensitive-telemetry-scan:
runs-on: ubuntu-latest
timeout-minutes: 20
@@ -376,7 +351,6 @@ jobs:
- jpa-registry-and-docs
- fileserver-full-verification
- fileserver-documentation-gate
- fileserver-pvc-certification
- fileserver-sensitive-telemetry-scan
# Job-level, because a job that declares `permissions:` replaces the workflow set entirely: this
# job and app-image-signing are the only ones that write anything anywhere, and
+8 -1
View File
@@ -1,6 +1,9 @@
.vscode/
src/**/bin/
.claude/
# Local Claude Code state (worktrees, settings.local.json, notes) stays out. The shared project
# settings file is committed: it denies the Agent tool for everyone (AGENTS.md 「Superpowers Workflow」).
.claude/*
!.claude/settings.json
# 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.
@@ -15,3 +18,7 @@ src/.env.lane
graphify-out/
src/graphify-out/
.playwright-mcp/
# Python bytecode from running scripts/ checks; never committed.
__pycache__/
*.pyc
+33 -24
View File
@@ -4,7 +4,7 @@
이 저장소는 단순한 예제 블로그 애플리케이션이 아니라, Java 21 + 버전 카탈로그에 고정된 Spring Boot 4.x + Gradle 멀티모듈 기반의 Clean Architecture 템플릿이다.
기본 패키지는 `dev.caskeleton`이며, 예시 도메인은 production 모듈이 아니라 `sample-portfolio` 모듈(WorkLog 엔지니어링 작업 기록 게시판)에 격리한다. 새 프로젝트를 시작할 때는 도메인 이름, 패키지, 엔티티, 유스케이스를 교체할 수 있지만, 모듈 경계와 의존성 방향은 유지해야 한다.
기본 패키지는 `dev.caskeleton`이다. 업무 기능의 예시는 `scripts/new-feature.sh`의 출력과 `docs/manual/`이다. 새 프로젝트를 시작할 때는 도메인 이름, 패키지, 엔티티, 유스케이스를 교체할 수 있지만, 모듈 경계와 의존성 방향은 유지해야 한다.
## Prime Directive
@@ -22,8 +22,9 @@
6. 관련 검증 없이, 또는 실행하지 못한 이유를 밝히지 않고 완료를 주장한다.
7. 결론의 범위와 위험에 맞는 증거 없이 repository/corpus 전체 결론을 내린다.
root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어긋나면 이 `AGENTS.md` 목록이
우선한다. 자동 강제 범위는 아래 Gradle 정책 권위와 ArchUnit/Test가 담당한다.
root `CLAUDE.md`는 작업을 시작할 때 읽는 지도이고, 이 목록을 한 줄씩 가리킨다. 두 문서가 어긋나면
이 `AGENTS.md` 목록이 우선한다. 일의 종류별 절차는 `docs/work/`에 있다. 자동 강제 범위는 아래 Gradle
정책 권위와 ArchUnit/Test가 담당한다.
## Superpowers Workflow
@@ -35,8 +36,10 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
- `superpowers:brainstorming`: 기능 설계, 구조 변경, 동작 변경, 새 문서 정책 수립 전에 사용한다.
- `superpowers:writing-plans`: 승인된 설계가 있고 작업이 여러 단계로 나뉠 때 사용한다.
- `superpowers:executing-plans`: 작성된 계획을 현재 세션에서 순차 실행할 때 사용한다.
- `superpowers:subagent-driven-development`: 계획을 작업 단위로 나누어 독립 에이전트에게 맡길 때 사용한다.
- `superpowers:dispatching-parallel-agents`: 서로 독립적인 조사나 구현을 병렬로 진행할 때 사용한다.
- `superpowers:subagent-driven-development`, `superpowers:dispatching-parallel-agents`: 이 저장소에서는
쓰지 않는다. 세션 안의 하위 에이전트(Agent 도구)는 `.claude/settings.json`이 막는다. 일을 나눠
맡길 때는 사람이 열어 보고 멈출 수 있는 별도 세션에 맡긴다(`docs/work/delegate.md`). 다른 스킬이
하위 에이전트를 띄우라고 하면 그 단계는 같은 세션이 직접 한다.
- `superpowers:test-driven-development`: 기능 추가와 버그 수정을 테스트 우선으로 진행할 때 사용한다.
- `superpowers:systematic-debugging`: 버그, 실패한 테스트, 예상 밖 동작을 다룰 때 사용한다.
- `superpowers:verification-before-completion`: 완료, 수정됨, 통과함을 주장하기 전에 사용한다.
@@ -73,13 +76,17 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
`INTEGRATION`·`SYSTEM`·`PERFORMANCE` lane과 `mainStage()` lane은 이미지·네트워크·시간·문서처럼
입력으로 잡히지 않는 것에 기대므로 매번 다시 돈다. hermetic lane이 저장소 파일을 읽으면 그 파일을
입력으로 선언해야 캐시가 거짓 통과를 내지 않는다.
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(소유자 결정 4). 구현은 build-logic의
- `PERFORMANCE` lane은 상한을 매번 단언한다. 끄는 스위치가 없다: convention이 테스트 JVM에
`performance.assertions.enabled=true`를 넣고, 빌드(`-P`·`GRADLE_OPTS`)나 lane이 다른 값을 주면
테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다(`rejectSkipped`를 따로 쓰지 않아도).
사람이 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다.
- `verifyEnvKeys`는 app-bootstrap 태스크로 유지한다(2026-09-25 소유자 결정). 구현은 build-logic의
`ca.config-contract`다. `src/build-tools/` included build는 비워서 삭제했다.
- `src/build.gradle`: 루트 라이프사이클(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`,
`releaseCheck`, `qualityCheck`, `configContractCheck`)과 버전/리비전. `verifyStrictLaneStages
--dry-run`(PR 게이트)은 그 빌드에서 `explicitOnly`가 아닌 strict lane이 workflow가 실제로 실행하는
단계(main 빌드: `ci`·`sample-portfolio:check`·`mainCheck`·`integrationCheck`·`performanceCheck`·
`releaseCheck`, optional-platforms 빌드: `-p optional-platforms`로 부르는 `ci`·`integrationCheck`·
단계(main 빌드: `ci`·`mainCheck`·`integrationCheck`·`performanceCheck`·
`releaseCheck`, optional-platforms 빌드: `-p platforms/optional-build`로 부르는 `ci`·`integrationCheck`·
`performanceCheck`·`releaseCheck`) 중 하나에 들어 있는지, 그리고 workflow의 접힌(`>`) run 블록이 빈
줄 때문에 옵션을 별개 명령으로 떼어 내지 않는지 검사한다. 두 빌드가 각자 검사를 돌린다. `-x`로 뺀
lane(Gradle처럼 축약 이름도 맞춰 본다)은 덮이지 않는다. Gradle이 작업을 돌리지 않는 명령(`--dry-run`·
@@ -91,8 +98,11 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
`&&` 목록의 뒤쪽, `if`·`while`·`for`·`case`·함수 본문 안, 최상위 `exit`·`exec`·`set -n` 뒤, 조건부이거나
부른 함수 안의 `exit 0`(인자 없는 `exit`, 값을 모르는 `exit` 포함)·`exec`·`set -n` 뒤, 상태
함수(`always()`·`success()`·`!cancelled()`)가 아닌 `if:` 아래, 요청으로만
시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), 세는 job이 부르지 않는
`workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는 job.
시작하는 workflow(`workflow_dispatch`·`repository_dispatch`·`issue_comment` 등), `paths`·`paths-ignore`
필터가 붙은 change trigger로만 시작하는 workflow(그 경로 밖 변경에는 돌지 않는다), 태그 push(`branches`
없는 `tags`)나 `release`로만 시작하는 workflow(`releaseCheck` 밖의 단계), 세는 job이
부르지 않는 `workflow_call` 재사용 workflow, 조건부이거나 `continue-on-error`인 job을 `needs`로 기다리는
job.
(3) 실패하면 단계도 실패하지만 검사가 읽지 않는다: `|| exit 1`, `{ }`·`( )`·`$( )`·`bash -c` 안, 다른
명령의 인자인 `gradlew`, 따라갈 수 없는 `cd`(`cd "$VAR"`·`cd -`·`pushd`·조건부·서브셸 등) 뒤,
`bash`·`sh`가 아닌 `shell:`, Windows일 수 있는 runner의 기본 셸(`pwsh`). 실패 메시지는 명령마다 이유를
@@ -105,6 +115,8 @@ root `CLAUDE.md`는 이 목록의 동기화된 요약이다. 두 문서가 어
변경한 경계와 런타임·보안·데이터 영향에 맞춰 설계·리뷰·검증 강도를 높인다.
commit 정책은 모든 플랫폼에서 `human-only`이며 agent는 stage/commit/amend/push하지 않는다.
예외는 하나다: brief가 허용한 것만(commit과 push는 따로) 그 작업의 자기 브랜치에 한다. main 병합,
다른 브랜치 push, force push는 하지 않는다(`docs/work/README.md` 「커밋」).
## 강제 수준
@@ -136,7 +148,6 @@ commit 정책은 모든 플랫폼에서 `human-only`이며 agent는 stage/commit
file server, HTTP client, identifier 능력을 port 뒤에서 구현한다. adapter 간 허용 edge는
registry만 따른다.
- `shared-contract`: skeleton-wide 운영 계약. business/domain 개념 저장 금지.
- `sample-portfolio`: 샘플/fixture consumer. production leaf가 의존하면 안 된다.
- `app-bootstrap`: Spring Boot entrypoint와 composition root. 비즈니스 유스케이스 금지.
## 의존성 방향
@@ -147,7 +158,6 @@ family 수준 기본 방향:
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
runtime modules -> shared-contract
sample-portfolio -> registered runtime leaves (fixture consumer only)
```
개별 edge는 `src/config/architecture/modules.json`의 `allowed_dependencies`가 유일한 목록이다.
@@ -159,8 +169,8 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
1. 요구사항을 읽고 소유 계층을 판단한다.
2. 구조나 동작이 바뀌면 `superpowers:brainstorming`으로 설계를 먼저 확정한다.
3. 여러 단계의 작업이면 `docs/superpowers/specs/`에 설계 문서를 남긴다.
4. 구현 전 `docs/superpowers/plans/`에 실행 계획을 작성한다.
3. 여러 단계의 작업이면 `docs/design/`에 설계 문서를 남긴다. 맨 위에 머리 블록(상태·작성일·요약·현재 정본)을 단다.
4. 실행 계획이 필요하면 구현 전 `docs/history/plans/`에 둔다. 계획서도 머리 블록을 단다. 머리 블록 형식은 `docs/README.md`다.
5. 동작 변경은 테스트를 먼저 작성한다.
6. 새 비즈니스 개념은 `domain-core`에 먼저 둔다.
7. 유스케이스는 `application-core` command와 use case/service method로 표현한다.
@@ -169,8 +179,7 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
10. focused test를 먼저 돌리고, 가능한 경우 전체 Gradle test를 돌린다.
단계별 판단 지점(배치·저장 포트·트랜잭션·멱등성·오류·권한)은 `docs/manual/`, 뼈대는
`scripts/new-feature.sh <FeatureName>`이 계층 leaf에 만든다. `sample-portfolio`는 모든 계층을 한 leaf에
두는 지울 수 있는 샘플이라 배치 예시가 아니다. 실제 기능은 계층 leaf별로 나눈다.
`scripts/new-feature.sh <FeatureName>`이 계층 leaf에 만든다. 실제 기능은 계층 leaf별로 나눈다.
## 테스트 전략
@@ -187,7 +196,7 @@ Gradle 의존성 검증도 같은 registry를 읽는다. root 문서나 기억
1. 이름은 lowerCamelCase 행동 문장(`<상황/주체><결과>`)이다. 이름에 적은 성질은 반드시 단언한다.
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만 쓰고, 한국어로
쓴다(소유자 결정 5). 기존 영어 `@DisplayName`은 그 테스트를 고칠 때 한국어로 바꾼다.
쓴다(2026-09-25 소유자 결정). 기존 영어 `@DisplayName`은 그 테스트를 고칠 때 한국어로 바꾼다.
3. 본문 문장이 3개 이상이면 `// given` `// when` `// then` 주석과 구역 사이 빈 줄을 둔다. 준비할
것이 없으면 `// given`은 생략한다. `// when`은 정확히 하나다. 두 번 필요하면 테스트를 나눈다.
예외 테스트는 `catchThrowable`로 when을 분리한다(기존 `assertThatThrownBy`는 손댈 때
@@ -220,10 +229,10 @@ cd src
./gradlew qualityCheck # SpotBugs + FindSecBugs (leaf check에는 없다)
./gradlew testQualityCheck # 같은 분석을 테스트 source set에(config/spotbugs/exclude-test.xml, main 단계·optional 빌드는 ci)
./gradlew ci # PR 게이트 = leaf check + architecture + quality
./gradlew mainCheck # main 단계 = env 계약·전체 기동(샘플 포함)·public path·전송/메시징 레인·leaf 문서 대조 레인·기능 생성 왕복(verifyFeatureScaffold)·테스트 코드 정적 분석(testQualityCheck)
./gradlew mainCheck # main 단계 = env 계약·전체 기동·public path·전송/메시징 레인·leaf 문서 대조 레인·기능 생성 왕복(verifyFeatureScaffold)·테스트 코드 정적 분석(testQualityCheck)
./gradlew integrationCheck # 실제 컨테이너 integration 레인 전체(main·nightly, Docker 필요)
./gradlew performanceCheck # 부하·종료·자원 한계 레인(main·nightly)
./gradlew verifyStrictLaneStages --dry-run # 이 빌드의 strict lane이 workflow가 실행하는 단계에 속하는지(optional 빌드는 -p optional-platforms로 따로)
./gradlew performanceCheck # 부하·종료·자원 한계 레인(main·nightly). 상한은 항상 단언, 끄면 실패
./gradlew verifyStrictLaneStages --dry-run # 이 빌드의 strict lane이 workflow가 실행하는 단계에 속하는지(optional 빌드는 -p platforms/optional-build로 따로)
./gradlew verifyPublicPathSnapshot
./gradlew :app-bootstrap:verifyEnvKeys
```
@@ -237,7 +246,7 @@ leaf의 `check`는 그 leaf만 검사한다. 저장소 전체 질문은 이름
Redis, Kafka, JPA 같은 부가 기능은 "의존성을 붙이면 켜지고, 떼면 사라지는 모듈"로 제공한다.
각 서비스는 `app-bootstrap/build.gradle`에 필요한 모듈만 `runtimeOnly` 한 줄로 고른다.
설계 근거는 `docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md`.
설계 근거는 `docs/design/2026-09-25-capability-module-packaging-design.md`.
템플릿 기본 조립은 web에서 쓰는 부분뿐이다: `adapter:inbound:web`, 운영 관측(actuator·metrics·
tracing·로그), `domain-core`·`application-core`·`shared-contract`, `adapter:outbound:support`·
@@ -252,7 +261,7 @@ capability 모듈 완료 기준 (7개 모두 충족해야 "포장 완료"):
자체를 두지 않는다.
4. 설정 prefix는 하나만 쓴다. 바인딩은 `StrictSettingsBinder`, 값 검증은 설정 record의 compact
constructor에서 한다.
예외(리뷰 05-18): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`·
예외(2026-11-03 정함): Redis는 `app.redis.*`(redis-runtime, setter+`validate()`)·`app.capabilities.*`·
`app.rate-limit.*` 세 트리를 유지한다. 키를 바꾸면 운영 env가 깨진다. 새 Redis 설정은 이 셋 중
하나에 넣고 네 번째 트리는 만들지 않는다. 이유는 `src/adapter/outbound/cache-redis/CLAUDE.md`.
5. 포트 소유 모듈 testFixtures의 포트 계약 테스트(추상 클래스)를 fake와 실제 어댑터가 모두
@@ -292,10 +301,10 @@ Docker/runtime 규칙:
1. `src/settings.gradle`의 `rootProject.name`을 새 프로젝트명으로 바꾼다.
2. Java package `dev.caskeleton`을 새 organization/project package로 바꾼다.
gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`(`src/grpc/grpc-contract/src/main/proto/caskeleton/`의
gRPC 플랫폼을 쓰면 proto 조직 이름 `caskeleton`(`src/platforms/grpc/grpc-contract/src/main/proto/caskeleton/`의
디렉터리, 각 `.proto`의 `package`·`java_package`)도 함께 바꾸고 `buf lint`로 확인한다.
3. `CaSkeletonApplication` 이름을 새 애플리케이션 이름으로 바꾼다.
4. production 모듈에는 목표 도메인의 entity, repository port, use case, adapter만 추가하고, 예시 코드는 `sample-portfolio`에 격리한다.
4. production 모듈에는 목표 도메인의 entity, repository port, use case, adapter만 추가한다.
5. 모듈 이름과 경계는 유지한다.
6. Docker image/application 이름을 새 프로젝트 기준으로 수정한다.
7. `.env`, `.env.local`, `application.yml`의 예시 값을 새 런타임 요구사항에 맞춘다.
+51 -159
View File
@@ -1,136 +1,45 @@
# CLAUDE.md
# CLAUDE.md — 이 repo의 지도
Repository guidance for the Java 21 + Spring Boot 4.0.8 Clean Architecture template.
이 파일은 세션이 처음 읽는 지도다. 규칙을 담지 않고, 어떤 일이면 무엇을 읽을지 가리킨다.
## Prime Directive
## 1. 이 repo
Preserve architecture before optimizing for speed. The following seven HARD-STOP conditions are a
synchronized summary of the canonical local policy in `AGENTS.md`:
- Java 21 + Spring Boot Gradle 멀티모듈(버전은 `src/gradle/libs.versions.toml`) Clean Architecture 백엔드 템플릿이다. 서비스는 이 repo를 받아 도메인을 채운다.
- Gradle 루트는 `src/`다. Gradle 명령은 `src/`에서 실행한다.
- 규칙의 정본은 `AGENTS.md`다. leaf 목록·경로·허용 의존의 정본은 `src/config/architecture/modules.json`(registry)이다. 각 leaf의 지역 규칙은 가장 가까운 `src/**/CLAUDE.md`가 정한다.
1. `domain-core` gains framework, transport, database, or cloud dependencies.
2. A controller directly uses a repository, Spring Data interface, or persistence entity.
3. An inbound DTO leaks into `application-core` or `domain-core`.
4. Business rules move into mappers, filters, configuration, settings, or controllers.
5. Project dependencies violate `src/config/architecture/modules.json` or the Gradle dependency
gate.
6. Completion is claimed without the relevant verification or a named reason it could not run.
7. A repository/corpus conclusion is made without evidence proportional to its scope and risk.
## 2. HARD-STOP — 하나라도 어기면 완료가 아니다
If this summary drifts from `AGENTS.md`, `AGENTS.md` wins and this summary must be resynchronized.
정본은 `AGENTS.md` 「Prime Directive」다. 두 문서가 다르면 `AGENTS.md`가 맞다.
## Gradle policy authorities
1. `domain-core`가 framework·transport·database·cloud 의존성을 가진다.
2. controller가 repository·Spring Data interface·persistence entity를 직접 쓴다.
3. inbound DTO가 `application-core`나 `domain-core`로 들어간다.
4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 간다.
5. 프로젝트 의존성이 registry나 Gradle 의존성 검증을 어긴다.
6. 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
7. 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다.
- `src/config/architecture/modules.json`: every registered leaf identity, repository-relative source
paths, Gradle paths and allowed production project dependency edges. There is no runtime
membership list: what a composition root may take is its `allowed_dependencies`, and the direction
gate refuses any other edge. The registry owns the leaf list and its size; no document restates
the count, because a number written in prose drifts the moment a leaf is added.
- `src/settings.gradle`: fail-closed registry validation, project inclusion, and directory mapping.
- `src/build-logic/`: the architecture core (registry, direction and purity tasks), the conventions,
and one test-lane mechanism (`strictTestLanes`). Feature-specific checks are the owning leaf's
tests; a test that reads repository files declares them as that leaf's test `inputs`, and a test
that compares a leaf with repository documents is a `mainStage()` lane (tag `document-contract`)
in that leaf's `mainCheck`; a merge-blocking contract over non-document repository files is a
pull-request lane whose inputs are exactly those files (app-bootstrap `repository-contract`).
`TEST`/`ARCHITECTURE` lanes are cacheable; `INTEGRATION`/`SYSTEM`/`PERFORMANCE` and main-stage
lanes rerun every time.
- `verifyEnvKeys` stays an app-bootstrap task (owner decision 4); its implementation is build-logic's
`ca.config-contract`. The `src/build-tools/` included build was emptied and removed.
- `src/build.gradle`: the root lifecycle (`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`,
`releaseCheck` and the named repository-wide gates). `verifyStrictLaneStages --dry-run` (pull
request; the main build and, as `-p optional-platforms`, the optional build each run their own)
fails when a non-`explicitOnly` strict lane is in no stage a workflow executes — a lane the
command removes with `-x` (abbreviations matched as Gradle does) is not covered; a command after
which Gradle runs no task (`--dry-run`, `-v`, `--help`, `--status`, `--stop`, …, bundles such as
`-qm` included), a short-option bundle Gradle rejects (`-mx`) and a command for another build do
not count, nor does one that does not gate for one of three reasons: (1) its failure may not fail
its step (an `||` other than `|| exit <non-zero>`, a pipe without pipefail, an `if` condition,
after `set +e` or an `exit 0` trap, `continue-on-error`, …); (2) it may not run (inside
`if`/`for`/`case` or a function, after a top-level or conditional `exit 0`, `exec` or `set -n`,
under a non-status `if:`, in a workflow only a request starts or a `workflow_call` one no counted
job calls, in a job that `needs` a conditional job, …); (3) the check does not read it although
its failure would fail the step (`|| exit 1`, inside `{ }`, `( )`, `$( )` or `bash -c`, after a
`cd` it cannot follow, a `shell:` other than bash or sh, a runner that may be Windows with its
`pwsh` default, …) — the failure names each command's reason and says to put the stage command
on a line of its own; the build a command runs is its `working-directory`, then the
`cd <relative path>` the same shell surely ran before it, joined with `-p` — or a folded workflow
`run:` block splits an option off its command.
## 3. 맡은 일 → 읽을 문서
Commit policy is `human-only`: agents do not stage, commit, amend, or push implementation changes.
먼저 [docs/work/README.md](docs/work/README.md)를 읽는다. 크기 정하기, 모든 작업의 공통 단계, 커밋 규칙이 거기 있다. 그다음 맡은 일의 playbook 하나를 끝까지 읽는다.
## Proportional workflow
| 맡은 일 | playbook |
| --- | --- |
| 새 업무 기능, 새 capability 모듈 | [docs/work/new-feature.md](docs/work/new-feature.md) → `docs/manual/` |
| 리뷰, 결함 수정, 리팩터링, 성능, 구조·테스트 구조 개선 | [docs/work/improve.md](docs/work/improve.md) |
| 바꾸기 전에 대안 비교와 소유자 결정 | [docs/work/research-design.md](docs/work/research-design.md) |
| 매뉴얼·안내 문서 쓰기 | [docs/work/docs-writing.md](docs/work/docs-writing.md) |
| 게이트 실행, desktop 검증, 릴리스, 파생 서비스 | [docs/work/operate.md](docs/work/operate.md) |
| 큰 일을 나눠 다른 세션에 맡기기 | [docs/work/delegate.md](docs/work/delegate.md) |
- Low risk: work in the owning leaf, follow its nearest guidance, and run the focused check.
- Medium risk: use the relevant Superpowers design, planning, TDD, debugging, and review workflows
in proportion to the affected boundaries.
- High risk: make architecture and behavior decisions explicit, use staged architecture/spec/quality
review, and run architecture-wide verification authorized by the task.
brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이 먼저다. playbook은 brief에 없는 공통 절차를 채운다.
Risk comes from change surface and runtime, security, data, or public-contract impact, not file
count.
## 4. 검증 명령과 실행 위치
## Module families
`src/config/architecture/modules.json` owns the complete leaf list. Root guidance summarizes
families; the nearest `src/**/CLAUDE.md` owns local rules. No task enforces this any more:
`verifyDocumentedLeafCount` was deleted along with the other documentation-drift parsers. A stated
count that disagrees with the registry is a defect, not a build failure — so do not state one.
| Family | Responsibility | Stable dependency direction |
| --- | --- | --- |
| `domain-core` | Pure domain model, invariants, events, ports | Java stdlib and registered value-only contracts |
| `application-core` | Commands, use cases, application policies, transaction ports | `domain-core`, `shared-contract` |
| `adapter:inbound:*` | HTTP, gRPC, GraphQL, WebSocket transport boundaries | application/domain/shared contracts |
| `adapter:outbound:persistence-*` | JPA/PostgreSQL and MongoDB persistence adapters | application/domain/shared contracts as registered |
| `adapter:outbound:*` | support, messaging, cache, notification, storage, file, HTTP client, identifier capabilities | application/domain/shared and registered support edge |
| `shared-contract` | Skeleton-wide operational contracts | Java stdlib only |
| `messaging:*` | Vendored messaging platform: a product with its own API, SPI, adapters and composition boundary, not a layer of this application | `messaging:*` only — it depends on no `domain-core`, `application-core`, or `shared-contract` type |
| `sample-portfolio` | Fixture/reference consumer | registered runtime leaves; never a production dependency |
| `app-bootstrap` | Spring Boot entrypoint and composition root | registered runtime leaves |
The `messaging:*` family is the one entry that is not a Clean Architecture layer, and it is listed so
that the exception is stated rather than inferred from a directory. It is a vendored library — its
own `*-api` leaves are its ports, its broker leaves are its adapters, its starter is its composition
root — and the messaging module review (`docs/reviews/2026-08-14-messaging-module-code-review.md`
MSG-023 §6.2) chose that layout deliberately over folding it into `adapter:outbound:*`. This
application reaches it through the application-owned anti-corruption bridge in
`adapter:outbound:messaging` (MSG-015). The canonical bridge is the only path: the legacy outbox
append port and the legacy Kafka publishing seam were deleted (owner decision 7).
Never infer an individual leaf's Gradle path, allowed dependency, or test command from this table.
Read its `gradle_path` and `allowed_dependencies` from `src/config/architecture/modules.json`; runtime
composition is established by actual Gradle dependencies/auto-configuration, not a registry
`runtime_memberships` field that does not exist.
## Layer workflow
For a full use case, work in this order:
```text
domain-core
-> application-core
-> adapter:outbound:* (or persistence/identifier)
-> adapter:inbound:*
-> app-bootstrap wiring
```
Layer-only work stays inside that registered leaf plus its tests. If a required fix crosses a layer
or writable scope, stop and request context rather than expanding silently.
## Testing
- `domain-core`: pure JUnit unit tests.
- `application-core`: use-case tests with hand-rolled fakes; no web or persistence context.
- inbound adapters: focused transport slice/contract tests.
- persistence adapters: mapping/port contract tests; use a real datastore only when vendor semantics
require it.
- other outbound adapters: port contract tests with fake external systems; no real network.
- identifier: pure deterministic unit tests.
- bootstrap/settings: binding, validation, wiring, and architecture tests.
From `src/`, read the owning leaf's `gradle_path` from
`config/architecture/modules.json` and run `./gradlew <gradle-path>:test --console=plain`.
Architecture-wide commands:
- **실행 위치**: 소유자 환경에서는 Gradle·Docker·테스트·게이트를 desktop에서만 돌린다. 절차는 [docs/work/operate.md](docs/work/operate.md) 4.1절이다.
- **leaf 하나**: registry에서 그 leaf의 `gradle_path`를 읽고 `./gradlew <gradle-path>:test --console=plain` 또는 `:check`를 돌린다. 기억이나 디렉터리 이름으로 Gradle path를 짐작하지 않는다.
- **저장소 전체 질문**:
```bash
./gradlew architectureCheck --console=plain
@@ -139,45 +48,28 @@ Architecture-wide commands:
./gradlew :app-bootstrap:verifyEnvKeys --console=plain
```
A leaf's `check` covers that leaf only — compile, its tests, Spotless, Checkstyle, Error Prone.
Repository-wide questions have their own names: `architectureCheck` (dependency direction, purity
of domain-core/shared-contract/application-*, Git-carryable sources, ArchUnit), `qualityCheck`
(SpotBugs, FindSecBugs over production code), `testQualityCheck` (the same over every test source
set, against `config/spotbugs/exclude-test.xml`), `configContractCheck` (the environment contract), `integrationCheck` (the
declared strict integration lanes; a lane that needs an input the build was not given is left out
and named), `performanceCheck` (the declared performance lanes; main and nightly). `ci` (pull
request) is leaf checks (API surfaces included, owner decision 20) + architectureCheck +
qualityCheck, and the workflow also runs `verifyStrictLaneStages --dry-run`; `mainCheck` (main branch) is configContractCheck +
qualificationCheck (which includes testQualityCheck) + the sample web contract + the sample full boot (`:sample-portfolio:systemTest`)
+ the public-path snapshot + the transport and messaging qualification lanes + the feature
generator round trip (`verifyFeatureScaffold`) + every leaf's `mainCheck` (document-contract lanes
and any lane the leaf adds). `releaseCheck` is the tag-only checks: release provenance and the
public-path snapshot.
- 공개 경로 검사와 env 키 검사는 그 표면이 바뀌었을 때 돌린다. 전체 `test`·`check`·`ci`는 brief가 시킬 때 돌린다.
- 게이트 목록(`ci`, `mainCheck`, `integrationCheck`, `performanceCheck`, `releaseCheck` 등)과 바꾼 것에 맞는 게이트는 [docs/work/reference/gates.md](docs/work/reference/gates.md)다.
- `docs/work/`, 이 파일, `AGENTS.md`, `src/**/CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`를 돌린다(분량, 본문 이력 ID 0, 상대 링크).
- 문서(`.md`)나 문서가 가리키는 경로·Gradle 프로젝트를 바꿨으면 `python3 scripts/check-docs.py`를 돌린다(언어, 기록의 머리 블록, 참조, 복사한 숫자). PR마다 `docs-check` workflow가 같은 검사를 돈다. 규칙은 [docs/README.md](docs/README.md)다.
Test-writing rules (behavior-sentence names that assert what they promise, `@DisplayName` in Korean
only when the name cannot say it (owner decision 5), given/when/then comments, one `// when`, one
fake per port in the port owner's testFixtures, fake and adapter sharing one abstract contract test)
are canonical in `AGENTS.md`.
## 5. 코드만 보고는 헷갈리는 곳
Use public-path and env-key checks only when their surfaces changed. Full `test`, `check` or `ci`
requires the controller's workflow authorization.
- **최상위 폴더는 정해진 것만 둔다.** 저장소 루트는 `compose.yaml`(개발 환경)·`compose/`(그 보조 파일)·`docs/`·`scripts/`·`src/`(Gradle 루트)다. `src/` 아래는 계층 leaf 폴더, `composition/`(조립), `platforms/`(들여온 제품: `messaging`·`grpc`·`grpc-advanced`와 optional 빌드 `optional-build`), Gradle 루트 표준(`build-logic`·`gradle`·`config`)이다. 테스트 환경 파일은 그 lane을 가진 leaf 안에 둔다. `scripts/check-repo-layout.py`(PR 게이트)가 허용 목록 밖의 최상위 항목을 막는다.
- **leaf 목록은 registry 하나다.** 문서는 leaf 개수를 적지 않는다(적힌 수는 leaf가 늘면 틀린다). runtime membership 목록은 없다. 조립 루트가 받을 수 있는 모듈은 registry의 `allowed_dependencies`가 정하고, 방향 게이트가 그 밖의 edge를 막는다.
- **`src/platforms/messaging/*`는 Clean Architecture 계층이 아니다.** 자기 API·SPI·adapter·조립 경계를 가진, 들여온(vendored) 메시징 제품이다. `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 이 애플리케이션은 `adapter:outbound:messaging`의 bridge로만 닿는다. 이유와 지역 규칙은 `src/platforms/messaging/CLAUDE.md`다.
- **`composition:*` leaf는 조립만 한다.** outbox relay, 멱등성 executor, durable operation처럼 bootstrap에서 떼어 낸 조립이다. 각각 `runtimeOnly` 한 줄로 고른다.
- **capability는 한 줄로 켜고 끈다.** 기본 조립은 web inbound, 운영 관측, core들, support·identifier뿐이다. JPA도 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 켠다. 규칙은 `AGENTS.md` 「부가 기능(capability) 모듈 규칙」이다.
- **gRPC 플랫폼 라이브러리는 다른 빌드다.** `src/platforms/grpc/*`·`src/platforms/grpc-advanced/*`(registry의 `"build": "optional-grpc"`)는 `-p platforms/optional-build`로 돈다. `adapter:inbound:grpc`는 애플리케이션 adapter라 주 빌드에 있다.
- **새 기능의 예시는 `scripts/new-feature.sh`의 출력이다.** 샘플 모듈은 2026-11-07에 지웠다. 기법 예시는 `docs/manual/`이 실제 코드(fileserver, durable operation)를 가리킨다.
- **성능 lane에는 단언을 끄는 스위치가 없다.** convention이 상한을 매번 단언하고, `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 있으면 테스트 전에 실패한다. 손으로 돌리든 workflow든 같다(`AGENTS.md` 「Gradle 정책 권위」).
- **저장소 파일을 읽는 테스트는 태그가 있다.** 문서와 대조하는 테스트는 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow를 읽는 테스트는 `repository-contract`(PR)다. 문서를 고치면 그 문서를 읽는 테스트를 찾는다.
- **커밋 정책은 `human-only`다.** brief가 허용한 것만 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 자세한 것은 [docs/work/README.md](docs/work/README.md) 4절이다.
- **문서 위치 규칙은 [docs/README.md](docs/README.md)다.** 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`, 리뷰는 `docs/reviews/`, 고치지 않는 기록(계획서·납품 패키지·증거·학습)은 `docs/history/`, 파생 서비스용 변경 안내는 `docs/upgrade/`다. 기록은 맨 위 머리 블록만 고친다.
## Capability modules
## 6. 소유자 환경
Optional features (JPA, Redis, Kafka, notification, Mongo, object storage, HTTP client, GraphQL,
WebSocket, gRPC, file server) are modules that turn on when present and disappear when removed. A
service selects them with one `runtimeOnly` line each in `app-bootstrap/build.gradle`; the template's
default composition is the web inbound adapter, observability, the cores, and support/identifier. The
seven completion criteria for a capability module are canonical in `AGENTS.md`.
## Advisory and reporting
Use dependency-DAG/topological reasoning and 3–5 materially distinct alternatives when that many
exist; use fewer when the option set is smaller. Judgment findings include falsifiable assumptions
and counterarguments. Deterministic compile, dependency, secret, or failed-test findings use
Rule → Evidence → Fix without manufactured debate.
Citation verification is profile-based: none for `review-lite`, blocking citations for
`review-standard`, and all material citations for `audit-deep`/`regulated`. Durable reports are
triggered by high risk, at least 3 blocking findings, an architecture decision, explicit user request,
or the regulated profile. Otherwise a concise result is allowed.
- 이 repo 소유자의 기계·세션 도구에 묶인 규칙은 두 곳에만 있다: [docs/work/operate.md](docs/work/operate.md) 4.1절(실행 위치)과 [docs/work/delegate.md](docs/work/delegate.md) 4.3절(세션). 공용 정본은 design-docs `conventions/delegation-loop.md` 11절이다.
- Agent 도구(세션 안의 하위 에이전트)는 이 repo의 `.claude/settings.json`이 막는다. 일을 나눌 때는 delegate.md대로 별도 세션에 맡긴다.
- 작업 사고 순서의 정본은 design-docs `conventions/work-thinking-order.md`, 커밋·PR 형식은 `conventions/commit-and-pr.md`다.
- 보고 말투와 형식은 소유자의 전역 `~/.claude/CLAUDE.md`를 따른다.
+14 -20
View File
@@ -1,6 +1,6 @@
# ca-skeleton — Clean Architecture Spring Boot 템플릿
ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 `dev.caskeleton`이며, 예시 도메인은 production 모듈이 아니라 `sample-portfolio` 모듈(WorkLog 작업 기록 게시판)에 격리합니다.
ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Gradle 멀티모듈 기반의 Clean Architecture 백엔드 템플릿입니다. fork해서 도메인·패키지·엔티티·유스케이스만 교체하면 새 서비스를 시작할 수 있고, 모듈 경계와 의존 방향은 그대로 유지합니다. 기본 패키지는 `dev.caskeleton`입니다. 업무 기능의 예시는 생성 명령 `scripts/new-feature.sh`의 출력과 [docs/manual/](docs/manual/README.md)입니다.
이 문서는 전체 구조와 첫 실행만 다룹니다. 모듈별 상세 규칙과 설계 근거는 각 모듈의 README와 `CLAUDE.md`가, 빌드·환경 변수 상세는 [src/README.md](src/README.md)가 소유합니다.
@@ -12,7 +12,6 @@ ca-skeleton은 Java 21과 버전 카탈로그에 고정된 Spring Boot 4.x, Grad
app-bootstrap -> adapter:inbound:* -> application-core -> domain-core
app-bootstrap -> adapter:outbound:* -> application-core -> domain-core
모든 런타임 모듈 -> shared-contract
sample-portfolio -> 등록된 런타임 리프 (fixture 소비자 전용)
```
family 수준의 책임은 다음과 같습니다.
@@ -26,7 +25,6 @@ family 수준의 책임은 다음과 같습니다.
| `adapter:outbound:*` | support(공유 베이스)·messaging·cache·notification·object storage·file·HTTP client·identifier 능력을 port 뒤에서 구현. 기본 조립에는 support·identifier만 들어 있고, 나머지는 `app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄로 고릅니다 |
| `shared-contract` | skeleton 전역 운영 계약. business/domain 개념 저장 금지 |
| `app-bootstrap` | Spring Boot entrypoint와 composition root |
| `sample-portfolio` | WorkLog 예시 도메인(fixture/reference). production이 의존하지 않음 |
등록된 leaf 목록과 각 leaf의 Gradle path·소스 경로·허용 production 의존 edge는
[src/config/architecture/modules.json](src/config/architecture/modules.json)이 SSOT입니다. focused
@@ -38,10 +36,10 @@ test는 해당 Gradle path에서 `./gradlew <gradle-path>:test --console=plain`
전제조건은 Temurin 21(루트 [.tool-versions](.tool-versions)에 고정)과 Docker Engine 또는 Docker Desktop입니다. Gradle은 저장소 wrapper를 씁니다. 첫 실행 진입점은 하나입니다.
```bash
scripts/bootstrap-local.sh # 다른 Compose overlay는 scripts/bootstrap-local.sh <profile>
scripts/bootstrap-local.sh
```
`scripts/bootstrap-local.sh`는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 각 단계가 `bootstrap N/4` 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
`scripts/bootstrap-local.sh`는 compile 검사, PostgreSQL Compose 기동, 애플리케이션 이미지 build·기동, `GET /api/healthcheck` HTTP smoke를 순서대로 실행합니다. 쓰는 compose 파일은 저장소 루트의 `compose.yaml` 하나입니다. 각 단계가 `bootstrap N/4` 줄을 찍고 실패하면 그 단계에서 멈추므로 실패 단계가 드러납니다. 기동을 확인하려면 health endpoint를 호출합니다.
```bash
curl -fsS http://localhost:8080/api/healthcheck
@@ -50,9 +48,13 @@ curl -fsS http://localhost:8080/api/healthcheck
로컬 스택을 내릴 때는 저장소 루트에서 실행합니다.
```bash
docker compose -f docker-compose.yml -f docker-compose.local.yml down
docker compose --profile '*' down
```
`--profile '*'`가 없으면 profile이 달린 `db`가 남습니다. compose는 켜진 profile의 서비스만 내립니다.
Redis·Kafka·MongoDB 같은 뒷단 서비스는 `compose.yaml`의 profile로 고릅니다(`docker compose --profile redis up -d --wait`). profile 목록은 그 파일 머리에 있습니다.
`src/.env.example`은 배포 환경 변수의 추적 가능한 복사/검증 계약이고 `src/.env`는 로컬 실행 입력입니다. 전체 환경 변수 목록과 조정 시점은 [src/README.md](src/README.md)와 [docs/registries/env-keys.yaml](docs/registries/env-keys.yaml)에 있습니다.
### 기본 조립과 부가 기능
@@ -91,10 +93,10 @@ H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 v
애플리케이션 이름 등 나머지 rename 단계는 위 체크리스트를 따릅니다.
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 예시 코드는 `sample-portfolio`에만 둡니다.
3. `CaSkeletonApplication`을 새 애플리케이션 이름으로 바꾸고, 목표 도메인의 엔티티·repository port·유스케이스·adapter를 production 모듈에 추가합니다. 새 업무 기능은 `scripts/new-feature.sh <FeatureName>`으로 만듭니다.
4. 모듈 이름과 경계는 그대로 유지합니다.
검증은 먼저 composition root의 빠른 테스트와 sample-off 계약을 확인합니다. 루트에서
검증은 먼저 composition root의 빠른 테스트와 아키텍처 검사를 확인합니다. 루트에서
`./gradlew test`를 호출하면 등록된 모든 하위 프로젝트의 `test`를 실행하므로 일상적인 로컬
피드백 명령으로 사용하지 않습니다. 저장소 전체 qualification은 CI 또는 명시적인 `ci` task가
담당합니다.
@@ -102,18 +104,16 @@ H2 실행은 wiring과 애플리케이션 동작만 검증하고, migration과 v
```bash
cd src
./gradlew :app-bootstrap:test
./gradlew :sample-portfolio:check
./gradlew architectureCheck
```
병합 전 저장소 전체 검증이 필요하면 `./gradlew ci`를 실행합니다.
`sample-portfolio`는 템플릿이 유지하는 fixture/reference 모듈이라 production 모듈이 의존하지 않고, runtime에 sample bean이나 endpoint를 넣지 않습니다. 다운스트림 fork에서 fixture가 더 필요 없을 때만 sample-off 테스트를 통과시킨 뒤 정리합니다.
## 아키텍처 규칙과 검증
애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. 8개 HARD-STOP 조건의 정본 로컬
정책 권위는 [AGENTS.md](AGENTS.md)이며, [CLAUDE.md](CLAUDE.md)는 동기화된 요약입니다.
애플리케이션이 동작하더라도 아래를 어기면 병합하지 않습니다. HARD-STOP 7개 조건의 정본 로컬
정책 권위는 [AGENTS.md](AGENTS.md)이며, [CLAUDE.md](CLAUDE.md)는 작업을 시작할 때 읽는 지도입니다.
일의 종류별 절차는 [docs/work/](docs/work/README.md)에 있습니다.
- `domain-core`는 Spring·JPA·Servlet·HTTP·DB·cloud SDK 타입을 import하지 않습니다.
- controller는 repository를 직접 호출하거나 persistence entity를 반환하지 않습니다.
@@ -134,8 +134,7 @@ cd src
## 수동 전용 Gradle 태스크
아래 세 태스크는 **어떤 워크플로도 실행하지 않으며, 그게 의도다.** 자동 실행이 틀린 이유를 각각
적어 둔다.
아래 태스크는 **어떤 워크플로도 실행하지 않으며, 그게 의도다.** 자동 실행이 틀린 이유를 적어 둔다.
여기 적힌 태스크 이름이 실재하는지 검사하던 `verifyReadmeCommands`는 삭제했다. 그건 이 문서의
```bash 블록을 직접 파싱해 `./gradlew`·`docker compose`·`make` 토큰을 실제 태스크 그래프와 대조하는
@@ -145,16 +144,11 @@ Markdown 명령 파서였고, 그 결과 "README에 무엇을 쓸 수 있는가"
```bash
cd src
./gradlew :grpc:grpc-testkit:grpcPerformanceTest
./gradlew :sample-portfolio:openapiCheckSnapshot -PapproveOpenApiChange
```
- `grpcPerformanceTest` — latency percentile·saturation·drain budget을 **측정**한다. 공유 CI
runner의 측정값은 흔들리고, 흔들리는 게이트는 결국 꺼진다. leaf `build.gradle`이 이 태스크의
태그를 `test`에서 제외하는 이유도 같다. 성능 회귀가 의심될 때 사람이 이름으로 부른다.
- `openapiCheckSnapshot` — 드리프트 검사 자체는 이미 자동으로 돈다. 이 태스크가 감싸는
`OpenApiDriftContractTest`는 `:sample-portfolio:test`의 일부이고, 그건 `check` 안이며 stage 1에서
실행된다. 이 태스크의 고유한 역할은 `-PapproveOpenApiChange`로 **커밋된 스냅샷을 다시 만드는 것**
— 의도된 API 변경을 사람이 승인하는 지점이다. 자동으로 돌리면 승인이 승인이 아니게 된다.
## 더 알아보기
+426
View File
@@ -0,0 +1,426 @@
# =============================================================================
# 개발 환경 — 이 repo의 compose 파일은 이것 하나다.
#
# docker compose up -d --wait app # 앱 컨테이너(기본 조립, local 런타임)
# docker compose up -d --wait db # 뒷단 서비스 하나만(이름을 대면 그 profile이 켜진다)
# docker compose --profile jpa --profile redis up -d --wait # 뒷단 서비스 묶음
# docker compose --profile '*' down # 내린다. 데이터까지 지우려면 down -v
#
# 내릴 때 --profile '*'를 붙인다. 붙이지 않으면 compose는 켜진 profile의 서비스만 내리므로, 이름으로
# 띄운 db 같은 profile 서비스가 남는다.
#
# 뒷단 서비스는 capability 이름의 profile로 고른다. profile을 대지 않으면 app만 뜬다.
#
# profile 서비스 쓰는 기능
# jpa db (PostgreSQL 16) JPA
# redis redis (ACL 계정) Redis
# kafka kafka Kafka 발행
# mongo mongo, mongo-rs-init MongoDB
# objectstorage minio, minio-init 객체 저장소
# auth keycloak JWT 발급자
# mail mailpit (STARTTLS 필수) SMTP 발송
#
# 이 파일이 마운트하는 보조 파일은 compose/ 아래에 있다. compose lane(테스트)은 이 파일을 바탕으로
# 쓰고, lane에만 필요한 overlay·smoke client·스키마 적용은 src/app-bootstrap/compose-lanes/에 있다.
# 경로는 모두 이 파일이 있는 저장소 루트 기준이다.
#
# auth profile은 keycloak client secret 파일이 있어야 뜬다. lane은 실행마다 만들고 지운다. 손으로 띄울
# 때는 compose/keycloak/secrets/graphql-smoke-client-secret에 아무 값이나 한 줄 넣는다(그 폴더는
# Git이 무시한다). mail profile도 같다: compose/mailpit/tls/에 server.crt·server.key가 있어야 한다.
#
# Graceful-shutdown sync table (feature-container-runtime-contract D5):
# App shutdown timeout : 30s (APP_SERVER_SHUTDOWN_TIMEOUT — SSOT: docs/registries/
# env-keys.yaml, owner feature-env-driven-runtime-configuration)
# Async executor wait : 19s (AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS)
# Container preStop : 5s (handled by the orchestrator / stop_grace_period offset)
# stop_grace_period : 60s (30s app drain + 19s async + 5s preStop + 6s safety margin)
#
# The drain and the async wait are consecutive, not concurrent: Spring finishes the lifecycle
# phase (the web server's graceful drain) before it destroys the executor, which then waits for
# its queue. A 40s grace let the container be killed 9s into that wait (07-07).
# DeveloperExperienceContractTest fails when this value is below the sum.
#
# Memory limit (D4):
# The container memory limit MUST be set for -XX:MaxRAMPercentage=75 to be meaningful.
# Default 512m suits a small service; adjust per deployment. A compose lane that boots every
# capability at once raises it for itself (compose-profile-contracts.json, appMemoryLimit).
# =============================================================================
# The local MinIO runtime, used by the server below and by the lane's object storage smoke client.
#
# It is the image the MinIO qualification lanes measured, by the same digest:
# src/adapter/outbound/objectstorage/src/test/resources/object-storage/minio-provider-evidence.json
# records it with the conditional-write findings, and ComposeMinioImageMatchesEvidenceTest in that
# leaf fails when this default (or the lane file's copy) and the evidence disagree. Change them
# together.
#
# Source: pgsty/minio, a community fork on Docker Hub, after Docker Hub's minio/minio and quay.io
# stopped serving MinIO images (review 05-09). cgr.dev/chainguard/minio measured the same but was
# not chosen; the evidence file's rejectedCandidates says why. LOCAL_MINIO_IMAGE points this runtime
# at a mirror; the lanes take OBJECT_STORAGE_MINIO_IMAGE, digest-checked.
x-local-minio-image: &local-minio-image "${LOCAL_MINIO_IMAGE:-pgsty/minio@sha256:b6bfe7239bfc83fb90d31612d9704d86039dd714f7904b3f1ad68f211e602372}"
services:
app:
build:
context: src/
dockerfile: Dockerfile
args:
RELEASE_VERSION: "${RELEASE_VERSION:-0.0.1}"
BUILD_VERSION: "${BUILD_VERSION:-0.0.1+0000000}"
GIT_SHA: "${GIT_SHA:-0000000}"
SOURCE_URL: "${SOURCE_URL:-https://example.invalid/ca-tmpl}"
# default = the composition a service ships. scripts/run-compose-runtime-smoke.sh sets
# qualification: every capability module present, each lane switching on what it tests.
COMPOSITION: "${COMPOSITION:-default}"
# 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).
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
# 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:
# its values go into a generated `environment:` block, which outranks every env_file.
env_file:
- path: ./src/.env
required: false
ports:
- "${APP_SERVER_PORT:-8080}:8080"
# Management (health, info, prometheus — answered without authentication) on loopback only:
# published on every interface it reaches the whole LAN (07-13). The smoke lanes read it from
# inside the container, so they need no host port at all.
- "127.0.0.1:9001:9001"
environment:
# Explicit, not inherited. A Compose profile selects services; it says nothing about which
# environment the application believes it is in. The dev and prod-smoke lane overlays set
# their own.
SPRING_PROFILES_ACTIVE: "local"
TZ: "UTC"
LANG: "C.UTF-8"
LC_ALL: "C.UTF-8"
# Graceful shutdown — fallback matches the env-keys.yaml SSOT default (30s).
# Override via .env or docker compose --env-file if you need a different value.
APP_SERVER_SHUTDOWN_TIMEOUT: "${APP_SERVER_SHUTDOWN_TIMEOUT:-30s}"
APP_SERVER_SHUTDOWN: "graceful"
# The `db` service below, on the internal network. The default composition does not read
# these; a service that selects the relational capability does.
APP_DATASOURCE_URL: "jdbc:postgresql://db:5432/${POSTGRES_DB:-ca_skeleton}"
APP_DATASOURCE_USERNAME: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
APP_DATASOURCE_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
# ---- Read-only root filesystem (D2) -------------------------------------
# The application must write only to the tmpfs mounts declared below.
# /tmp — Tomcat basedir (see -Dserver.tomcat.basedir=/tmp in Dockerfile).
# /var/tmp/heap — heap dump landing zone (see -XX:HeapDumpPath=/var/tmp/heap).
read_only: true
tmpfs:
- /tmp:mode=1777,size=128m
- /var/tmp/heap:mode=1777,size=512m
# No volume: the shipped composition keeps nothing on disk. A capability that does brings its
# mount in its own overlay, added with -f when the capability is selected, so this file never
# names one (07-08).
# ---- Memory limit (D4) --------------------------------------------------
# Must be set so -XX:MaxRAMPercentage=75 can compute a meaningful heap bound.
mem_limit: 512m
memswap_limit: 512m
# ---- Graceful shutdown (D5) ---------------------------------------------
# stop_grace_period = app drain (30s, env-keys SSOT) + async wait (19s) + preStop (5s)
# + margin (6s) = 60s.
stop_grace_period: 60s
# ---- Health check -------------------------------------------------------
# The actuator readiness probe on the management port (9001). It answers under every runtime
# (local, dev, prod), unlike the public health path, whose base path differs by runtime.
healthcheck:
test:
- "CMD"
- "wget"
- "--no-verbose"
- "--tries=1"
- "--spider"
- "http://localhost:9001/actuator/health/readiness"
interval: 5s
timeout: 3s
start_period: 60s
retries: 12
restart: unless-stopped
networks:
- caskeleton-infra
# ---- PostgreSQL --------------------------------------------------------------
# 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
# port is the one src/.env.example's APP_DATASOURCE_URL names.
db:
profiles:
- jpa
image: postgres:16-alpine
environment:
POSTGRES_DB: "${POSTGRES_DB:-ca_skeleton}"
POSTGRES_USER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
POSTGRES_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
TZ: "UTC"
volumes:
- type: volume
source: caskeleton-db-data
target: /var/lib/postgresql/data
ports:
- "127.0.0.1:5433:5432"
networks:
- caskeleton-infra
healthcheck:
test:
[
"CMD-SHELL",
"pg_isready -U ${APP_DATASOURCE_USERNAME:-ca_skeleton} -d ${POSTGRES_DB:-ca_skeleton}",
]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
# ---- MongoDB -----------------------------------------------------------------
# A replica set of one. Single-node is still a replica set: transactions and change streams need
# one, and a standalone mongod that "works for reads" is a deployment that discovers the
# difference at the first transaction.
mongo:
profiles:
- mongo
image: mongo:8.0.16
command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
volumes:
- type: volume
source: caskeleton-mongo-data
target: /data/db
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
interval: 10s
timeout: 5s
retries: 10
start_period: 20s
mongo-rs-init:
profiles:
- mongo
image: mongo:8.0.16
depends_on:
mongo:
condition: service_healthy
# Idempotent: rs.initiate() on an already-initiated set returns an error this swallows, so the
# stack can be re-run against a surviving volume without a manual reset.
command:
- mongosh
- --host
- mongo
- --quiet
- --eval
- >-
try { rs.initiate({_id:'rs0',members:[{_id:0,host:'mongo:27017'}]}) }
catch (e) { if (!/already initialized/i.test(e.message)) { throw e } }
networks:
- caskeleton-infra
restart: "no"
# ---- Kafka -------------------------------------------------------------------
kafka:
profiles:
- kafka
image: apache/kafka:3.8.0
environment:
KAFKA_NODE_ID: "1"
KAFKA_PROCESS_ROLES: "broker,controller"
KAFKA_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://kafka:9092"
KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka:9093"
KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
networks:
- caskeleton-infra
healthcheck:
test:
["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server kafka:9092"]
interval: 10s
timeout: 10s
retries: 12
start_period: 30s
# ---- Redis -------------------------------------------------------------------
# Authenticated the way a deployment authenticates, with the lanes' test-fixture accounts:
# compose/redis/acl/lane-fixture-accounts.acl, the same file the Redis topology lanes use, mounted
# as it is rather than copied. It is not a deployment file — its passwords are public and it carries
# a lane-only `+@all` account (compose/redis/acl/README.md). Its first line turns the passwordless
# `default` user off, so the application connects as the named accounts the lane contract gives it
# (compose-profile-contracts.json, $redisComment).
#
# This Redis was open and the lanes declared app.redis.authentication.anonymous-access-accepted.
# The application then logged that trade, and the missing advanced account, as two startup
# warnings — correctly, because in production both are risks — and every Redis lane failed its
# "startup is silent" check. Quieting the warning would hide the same trade in production; the
# lane now authenticates the way a deployment does instead.
#
# The passwords are the file's fixture values (compose/redis/acl/README.md); this container is
# on the internal network only and publishes no port.
redis:
profiles:
- redis
image: redis:7.4
command:
- redis-server
- --appendonly
- "no"
- --save
- ""
- --aclfile
- /etc/redis/acl/lane-fixture-accounts.acl
volumes:
- type: bind
source: ./compose/redis/acl
target: /etc/redis/acl
read_only: true
networks:
- caskeleton-infra
healthcheck:
test:
# As the application account: with `default` off, an unauthenticated PING answers NOAUTH.
- "CMD-SHELL"
- "[ \"$$(redis-cli --user ca-skeleton-application --pass fixture-application --no-auth-warning ping)\" = PONG ]"
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
# ---- Mailpit — the reference SMTP relay ----------------------------------------
mailpit:
profiles:
- mail
image: axllent/mailpit:v1.21
environment:
MP_SMTP_AUTH_ACCEPT_ANY: "1"
# MP_SMTP_AUTH_ALLOW_INSECURE is deliberately absent, and Mailpit refuses to start with both:
# "TLS cannot be required with --smtp-auth-allow-insecure". It existed to permit credentials
# over a plaintext connection, which is exactly what requiring STARTTLS removes the need for —
# any AUTH now happens inside the TLS session.
# STARTTLS, required. Not a hardening extra: SmtpProviderProperties.TlsMode has two members and
# neither is plaintext, so the platform cannot describe an unencrypted relay at all. A stack
# that wanted a plaintext Mailpit would be asking for a transport the type refuses to express,
# and the honest way to satisfy it is to give the relay a certificate.
MP_SMTP_TLS_CERT: /run/mailpit-tls/server.crt
MP_SMTP_TLS_KEY: /run/mailpit-tls/server.key
MP_SMTP_REQUIRE_STARTTLS: "true"
volumes:
# Generated per run by the qualification wrapper for the host name `mailpit`, and removed on
# teardown, exactly like the PostgreSQL lane certificate. A committed test certificate is a
# private key in Git.
- type: bind
source: ./compose/mailpit/tls
target: /run/mailpit-tls
read_only: true
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "/mailpit", "readyz"]
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
# ---- MinIO -------------------------------------------------------------------
minio:
profiles:
- objectstorage
image: *local-minio-image
command: ["server", "/data"]
environment:
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
volumes:
- type: volume
source: caskeleton-minio-data
target: /data
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "mc", "ready", "local"]
interval: 10s
timeout: 5s
retries: 10
start_period: 10s
# Bucket and policy bootstrap. Not a substitute for the round trip: creating a bucket proves the
# server accepts an admin command, not that an object survives being written and read back.
minio-init:
profiles:
- objectstorage
# The client from the same supplier as the server. cgr.dev/chainguard/minio-client was not used:
# it has no shell, and the bootstrap below is a shell script.
image: "${LOCAL_MINIO_MC_IMAGE:-pgsty/mc@sha256:ce62c9053c69ce12a527a322345b5ad9f44b5f8a7b8189f82e516f2e3f30f1d8}"
depends_on:
minio:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/minio/bucket-bootstrap.sh"]
environment:
MINIO_ENDPOINT: "http://minio:9000"
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
volumes:
- type: bind
source: ./compose/minio/init
target: /opt/minio
read_only: true
networks:
- caskeleton-infra
restart: "no"
# ---- Keycloak ----------------------------------------------------------------
keycloak:
profiles:
- auth
image: quay.io/keycloak/keycloak:26.0
# The wrapper reads the client secret from a mounted file and execs kc.sh. The realm artifact
# carries only a ${...} reference, so no secret value is in Git, in the rendered config, or on a
# command line.
entrypoint: ["/bin/bash", "/opt/keycloak-entrypoint/entrypoint.sh"]
environment:
KC_BOOTSTRAP_ADMIN_USERNAME: "${KEYCLOAK_ADMIN:-admin}"
KC_BOOTSTRAP_ADMIN_PASSWORD: "${KEYCLOAK_ADMIN_PASSWORD:-admin}"
KC_HEALTH_ENABLED: "true"
volumes:
- type: bind
source: ./compose/keycloak/entrypoint.sh
target: /opt/keycloak-entrypoint/entrypoint.sh
read_only: true
- type: bind
source: ./compose/keycloak/realms
target: /opt/keycloak/data/import
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
healthcheck:
test:
- "CMD-SHELL"
- "exec 3<>/dev/tcp/127.0.0.1/9000 && echo -e 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && cat <&3 | grep -q '\"status\": \"UP\"'"
interval: 10s
timeout: 5s
retries: 20
start_period: 30s
networks:
caskeleton-infra:
driver: bridge
volumes:
caskeleton-db-data:
driver: local
caskeleton-mongo-data:
driver: local
caskeleton-minio-data:
driver: local
secrets:
keycloak-graphql-smoke-client-secret:
file: ./compose/keycloak/secrets/graphql-smoke-client-secret
@@ -1,6 +1,6 @@
# Keycloak realm artifact
`realms/ca-skeleton-realm.json` is imported by the `keycloak` service in `docker-compose.infra.yml`
`realms/ca-skeleton-realm.json` is imported by the `keycloak` service in the root `compose.yaml`
and is the same realm every GraphQL qualification lane authenticates against.
## The client secret is a reference, never a value
@@ -42,9 +42,10 @@ a fork that copied one of them got an open account and a green lane.
## Who loads `lane-fixture-accounts.acl`
The Redis topology lanes (`../standalone`, `../sentinel`, `../cluster`, `../tls`) and the
The Redis topology lanes (`src/adapter/outbound/redis-sdk/compose/{standalone,sentinel,cluster,tls}`), the
application's Compose lanes that switch Redis on (`local-redis`, `all-adapters` in
`src/config/runtime/compose-profile-contracts.json`). Both mount this directory read-only; neither
`src/app-bootstrap/compose-lanes/compose-profile-contracts.json`), and the development stack's
`redis` service (root `compose.yaml`). They all mount this directory read-only; neither
keeps a copy, because a second copy of these lines is a second place for a password or a key
pattern to drift.
-579
View File
@@ -1,579 +0,0 @@
# =============================================================================
# Shared infrastructure, owned here and nowhere else.
#
# Environment overlays (local, dev, prod-smoke) describe how the application runs. This file
# describes what it runs against. Keeping the two apart is why `local` could stop meaning "the app
# plus a database" and start meaning "the app, with whichever services the lane asked for".
#
# Every service carries a Compose profile, so nothing here starts unless a lane names it. A profile
# selects services; it never implies a Spring profile. The lane definitions live in
# src/config/runtime/compose-profile-contracts.json, and scripts/verify-compose-profile-contracts.sh
# checks this file against them.
# =============================================================================
# The local MinIO runtime, used by the server and by the object-storage smoke client below.
#
# It is the image the MinIO qualification lanes measured, by the same digest:
# src/adapter/outbound/objectstorage/src/test/resources/object-storage/minio-provider-evidence.json
# records it with the conditional-write findings, and ComposeMinioImageMatchesEvidenceTest in that
# leaf fails when this default and the evidence disagree. Change both together.
#
# Source: pgsty/minio, a community fork on Docker Hub, after Docker Hub's minio/minio and quay.io
# stopped serving MinIO images (review 05-09). cgr.dev/chainguard/minio measured the same but was
# not chosen; the evidence file's rejectedCandidates says why. LOCAL_MINIO_IMAGE points this runtime
# at a mirror; the lanes take OBJECT_STORAGE_MINIO_IMAGE, digest-checked.
x-local-minio-image: &local-minio-image "${LOCAL_MINIO_IMAGE:-pgsty/minio@sha256:b6bfe7239bfc83fb90d31612d9704d86039dd714f7904b3f1ad68f211e602372}"
services:
# ---- PostgreSQL --------------------------------------------------------------
db:
profiles:
- local-jpa
- local-messaging-outbox
- local-fileserver
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- shared-infra
- prod-smoke
- all-adapters
image: postgres:16-alpine
environment:
POSTGRES_DB: "${POSTGRES_DB:-ca_skeleton}"
POSTGRES_USER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
POSTGRES_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
TZ: "UTC"
volumes:
- type: volume
source: caskeleton-db-data
target: /var/lib/postgresql/data
ports:
- "127.0.0.1:5433:5432"
networks:
- caskeleton-infra
healthcheck:
test:
[
"CMD-SHELL",
"pg_isready -U ${APP_DATASOURCE_USERNAME:-ca_skeleton} -d ${POSTGRES_DB:-ca_skeleton}",
]
interval: 10s
timeout: 5s
retries: 5
start_period: 30s
# ---- MongoDB -----------------------------------------------------------------
# A replica set of one. Single-node is still a replica set: transactions and change streams need
# one, and a standalone mongod that "works for reads" is a deployment that discovers the
# difference at the first transaction.
mongo:
profiles:
- local-mongo
- all-adapters
image: mongo:8.0.16
command: ["mongod", "--replSet", "rs0", "--bind_ip_all"]
volumes:
- type: volume
source: caskeleton-mongo-data
target: /data/db
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
interval: 10s
timeout: 5s
retries: 10
start_period: 20s
mongo-rs-init:
profiles:
- local-mongo
- all-adapters
image: mongo:8.0.16
depends_on:
mongo:
condition: service_healthy
# Idempotent: rs.initiate() on an already-initiated set returns an error this swallows, so the
# lane can be re-run against a surviving volume without a manual reset.
command:
- mongosh
- --host
- mongo
- --quiet
- --eval
- >-
try { rs.initiate({_id:'rs0',members:[{_id:0,host:'mongo:27017'}]}) }
catch (e) { if (!/already initialized/i.test(e.message)) { throw e } }
networks:
- caskeleton-infra
restart: "no"
# ---- Kafka -------------------------------------------------------------------
kafka:
profiles:
- local-messaging
- local-messaging-outbox
- all-adapters
image: apache/kafka:3.8.0
environment:
KAFKA_NODE_ID: "1"
KAFKA_PROCESS_ROLES: "broker,controller"
KAFKA_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://kafka:9092"
KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka:9093"
KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
networks:
- caskeleton-infra
healthcheck:
test:
["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server kafka:9092"]
interval: 10s
timeout: 10s
retries: 12
start_period: 30s
# ---- Redis — local compose contract for the shipped Redis runtime ----------------
# Authenticated the way a deployment authenticates, with the lanes' test-fixture accounts:
# infra/redis-sdk/acl/lane-fixture-accounts.acl, the same file the Redis topology lanes use, mounted
# as it is rather than copied. It is not a deployment file — its passwords are public and it carries
# a lane-only `+@all` account (infra/redis-sdk/acl/README.md). Its first line turns the passwordless
# `default` user off, so the application connects as the named accounts the lane contract gives it
# (compose-profile-contracts.json, $redisComment).
#
# This Redis was open and the lanes declared app.redis.authentication.anonymous-access-accepted.
# The application then logged that trade, and the missing advanced account, as two startup
# warnings — correctly, because in production both are risks — and every Redis lane failed its
# "startup is silent" check. Quieting the warning would hide the same trade in production; the
# lane now authenticates the way a deployment does instead.
#
# The passwords are the file's fixture values (infra/redis-sdk/acl/README.md); this container is
# on the lane's internal network only and publishes no port.
redis:
profiles:
- local-redis
- all-adapters
image: redis:7.4
command:
- redis-server
- --appendonly
- "no"
- --save
- ""
- --aclfile
- /etc/redis/acl/lane-fixture-accounts.acl
volumes:
- type: bind
source: ./infra/redis-sdk/acl
target: /etc/redis/acl
read_only: true
networks:
- caskeleton-infra
healthcheck:
# As the application account: with `default` off, an unauthenticated PING answers NOAUTH.
test:
- "CMD-SHELL"
- "[ \"$$(redis-cli --user ca-skeleton-application --pass fixture-application --no-auth-warning ping)\" = PONG ]"
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
# ---- Mailpit — the reference SMTP provider for notification serving ----------
mailpit:
profiles:
- local-notification-serving
- local-notification-handoff
- all-adapters
image: axllent/mailpit:v1.21
environment:
MP_SMTP_AUTH_ACCEPT_ANY: "1"
# MP_SMTP_AUTH_ALLOW_INSECURE is deliberately absent, and Mailpit refuses to start with both:
# "TLS cannot be required with --smtp-auth-allow-insecure". It existed to permit credentials
# over a plaintext connection, which is exactly what requiring STARTTLS removes the need for —
# any AUTH now happens inside the TLS session.
# STARTTLS, required. Not a hardening extra: SmtpProviderProperties.TlsMode has two members and
# neither is plaintext, so the platform cannot describe an unencrypted relay at all. A lane that
# wanted a plaintext Mailpit would be asking for a transport the type refuses to express, and
# the honest way to satisfy it is to give the relay a certificate.
MP_SMTP_TLS_CERT: /run/mailpit-tls/server.crt
MP_SMTP_TLS_KEY: /run/mailpit-tls/server.key
MP_SMTP_REQUIRE_STARTTLS: "true"
volumes:
# Generated per run by the qualification wrapper for the host name `mailpit`, and removed on
# teardown, exactly like the PostgreSQL lane certificate. A committed test certificate is a
# private key in Git.
- type: bind
source: ./infra/mailpit/tls
target: /run/mailpit-tls
read_only: true
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "/mailpit", "readyz"]
interval: 5s
timeout: 3s
retries: 12
start_period: 5s
# ---- MinIO -------------------------------------------------------------------
minio:
profiles:
- shared-infra
- prod-smoke
image: *local-minio-image
command: ["server", "/data"]
environment:
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
volumes:
- type: volume
source: caskeleton-minio-data
target: /data
networks:
- caskeleton-infra
healthcheck:
test: ["CMD", "mc", "ready", "local"]
interval: 10s
timeout: 5s
retries: 10
start_period: 10s
# Bucket and policy bootstrap. Not a substitute for the round trip: creating a bucket proves the
# server accepts an admin command, not that an object survives being written and read back.
minio-init:
profiles:
- shared-infra
- prod-smoke
# The client from the same supplier as the server. cgr.dev/chainguard/minio-client was not used:
# it has no shell, and the bootstrap below is a shell script.
image: "${LOCAL_MINIO_MC_IMAGE:-pgsty/mc@sha256:ce62c9053c69ce12a527a322345b5ad9f44b5f8a7b8189f82e516f2e3f30f1d8}"
depends_on:
minio:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/minio/bucket-bootstrap.sh"]
environment:
MINIO_ENDPOINT: "http://minio:9000"
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
volumes:
- type: bind
source: ./infra/minio/init
target: /opt/minio
read_only: true
networks:
- caskeleton-infra
restart: "no"
# ---- Keycloak ----------------------------------------------------------------
keycloak:
profiles:
- local-graphql
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- shared-infra
- prod-smoke
- all-adapters
image: quay.io/keycloak/keycloak:26.0
# The wrapper reads the client secret from a mounted file and execs kc.sh. The realm artifact
# carries only a ${...} reference, so no secret value is in Git, in the rendered config, or on a
# command line.
entrypoint: ["/bin/bash", "/opt/keycloak-entrypoint/entrypoint.sh"]
environment:
KC_BOOTSTRAP_ADMIN_USERNAME: "${KEYCLOAK_ADMIN:-admin}"
KC_BOOTSTRAP_ADMIN_PASSWORD: "${KEYCLOAK_ADMIN_PASSWORD:-admin}"
KC_HEALTH_ENABLED: "true"
volumes:
- type: bind
source: ./infra/keycloak/entrypoint.sh
target: /opt/keycloak-entrypoint/entrypoint.sh
read_only: true
- type: bind
source: ./infra/keycloak/realms
target: /opt/keycloak/data/import
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
healthcheck:
test:
- "CMD-SHELL"
- "exec 3<>/dev/tcp/127.0.0.1/9000 && echo -e 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && cat <&3 | grep -q '\"status\": \"UP\"'"
interval: 10s
timeout: 5s
retries: 20
start_period: 30s
# ---- Capability schema streams ------------------------------------------------
# Two pre-start one-shots, in this order, because a capability stream is an operator sequence
# rather than a property.
#
# Install: each stream under db/migration/jpa keeps its own Flyway history table — they all declare
# a V1, so one Flyway pointed at all of them fails outright — and each registers itself
# INSTALLED_INACTIVE.
#
# Promote: an operator sanctions the installed schema, and the application refuses to start until
# that has happened. That is the fail-closed half of the same design, so it cannot be folded into
# the install step without making "the tables exist" and "this is sanctioned" the same event.
#
# They are also two images because they must be: flyway/flyway ships no psql, so the promotion
# could not have run in the migration container at all.
#
# Both run before `up`, not with the smoke clients after it — the application is what they are a
# precondition for. The lane contract's preStartServices carries that ordering.
db-migrate-capabilities:
profiles:
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- local-fileserver
- all-adapters
image: flyway/flyway:11.1.0
depends_on:
db:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/capability-streams/apply-capability-streams.sh"]
environment:
PGHOST: "db"
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
volumes:
- type: bind
source: ./infra/postgres/apply-capability-streams.sh
target: /opt/capability-streams/apply-capability-streams.sh
read_only: true
# The whole migration tree, not just db/migration/jpa: the application's own postgresql stream
# has to be installed first, or the capability tables arrive in a schema whose flyway_schema_history
# does not exist yet and the application refuses to start — which is its baseline-on-migrate: false
# policy working as designed.
- type: bind
source: ./src/adapter/outbound/persistence-jpa/src/main/resources/db/migration
target: /flyway/sql
read_only: true
# Each capability stream from the leaf that owns it, beside rather than inside /flyway/sql: a
# bind mount nested in that read-only one would need its mount point created in the source
# tree. They moved out of persistence-jpa with their capabilities, and the mount above stopped
# reaching them — the script then refused with "no such stream".
- type: bind
source: ./src/adapter/outbound/persistence-notification/src/main/resources/db/migration/jpa/notification-platform
target: /flyway/streams/notification-platform
read_only: true
- type: bind
source: ./src/adapter/outbound/persistence-fileserver/src/main/resources/db/migration/jpa/fileserver
target: /flyway/streams/fileserver
read_only: true
networks:
- caskeleton-infra
restart: "no"
db-promote-capabilities:
profiles:
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- local-fileserver
- all-adapters
image: postgres:16-alpine
depends_on:
db:
condition: service_healthy
entrypoint: ["/bin/sh", "/opt/capability-streams/promote-capability-streams.sh"]
environment:
PGHOST: "db"
PGUSER: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
PGPASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
PGDATABASE: "${POSTGRES_DB:-ca_skeleton}"
CAPABILITY_STREAMS: "${CAPABILITY_STREAMS:-}"
volumes:
- type: bind
source: ./infra/postgres/promote-capability-streams.sh
target: /opt/capability-streams/promote-capability-streams.sh
read_only: true
networks:
- caskeleton-infra
restart: "no"
# The GraphQL transport, as a request. auth-smoke proves a token can be obtained and that public
# health answers; this proves /graphql is guarded and that an authenticated query executes.
graphql-smoke:
profiles:
- local-graphql
- all-adapters
image: curlimages/curl:8.10.1
depends_on:
keycloak:
condition: service_healthy
# uid 0 for the mounted 0600 client secret, same as auth-smoke.
user: "0:0"
entrypoint: ["/bin/sh", "/opt/graphql-smoke/graphql-smoke.sh"]
environment:
APP_BASE_URL: "http://app:8080"
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
# Spring for GraphQL serves its own endpoint through a router function rather than an
# annotated controller, so the presentation base-path prefix does not apply to it.
GRAPHQL_PATH: "${GRAPHQL_PATH:-/graphql}"
volumes:
- type: bind
source: ./infra/graphql/smoke
target: /opt/graphql-smoke
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
restart: "no"
# ---- One-shot smoke clients --------------------------------------------------
# Never `up --wait` targets. Each is run with `run --rm` and must exit zero; a missing, skipped or
# non-zero one fails its lane rather than being treated as "not applicable".
auth-smoke:
profiles:
- local-graphql
- shared-infra
- prod-smoke
- all-adapters
image: curlimages/curl:8.10.1
depends_on:
keycloak:
condition: service_healthy
# The client secret is written on the host at mode 0600 by the qualification wrapper and mounted
# in. The Keycloak image happens to run as the same uid the wrapper writes as; this image runs as
# uid 100, so it read "Permission denied" and the lane failed on the smoke client rather than on
# anything it was checking. Compose ignores the secret's uid/gid/mode options outside swarm, so
# the container reads it as root instead. The two alternatives are both worse: loosening the host
# file to world-readable leaves a credential readable by every process on the machine, and passing
# the value as an environment variable puts it in `docker compose config` output and in ps.
user: "0:0"
entrypoint: ["/bin/sh", "/opt/auth-smoke/auth-smoke.sh"]
environment:
# The same issuer URL the application is given. A token obtained from one URL and validated
# against another proves nothing, and localhost means a different host inside each container.
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
APP_BASE_URL: "http://app:8080"
# Supplied per runtime, because the same endpoint has two addresses: application-local.yml
# pins presentation.api-base-path to /api and the shipped default is /v1. The qualification
# wrapper exports the value that matches the lane's Spring runtime.
APP_HEALTH_PATH: "${APP_HEALTH_PATH:-/v1/healthcheck}"
volumes:
- type: bind
source: ./infra/keycloak/smoke
target: /opt/auth-smoke
read_only: true
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
restart: "no"
# The server image, not the mc client image: the mc image ships no sed, grep or cmp, and the round-trip
# client needs a digest tool. See infra/minio/smoke/object-storage-smoke.sh for how that went
# unnoticed. The lane already pulls this image for the server itself.
object-storage-smoke:
profiles:
- shared-infra
- prod-smoke
image: *local-minio-image
depends_on:
minio-init:
condition: service_completed_successfully
entrypoint: ["/bin/sh", "/opt/minio-smoke/object-storage-smoke.sh"]
environment:
MINIO_ENDPOINT: "http://minio:9000"
MINIO_ROOT_USER: "${MINIO_ROOT_USER:-caskeleton}"
MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD:-caskeleton-local}"
MINIO_BUCKET: "${MINIO_BUCKET:-ca-skeleton-objects}"
volumes:
- type: bind
source: ./infra/minio/smoke
target: /opt/minio-smoke
read_only: true
networks:
- caskeleton-infra
restart: "no"
notification-smoke:
profiles:
- local-notification-ingest
- local-notification-serving
- local-notification-handoff
- all-adapters
image: curlimages/curl:8.10.1
depends_on:
keycloak:
condition: service_healthy
# uid 0 for the same reason auth-smoke uses it: the mounted client secret is mode 0600 on the
# host and this image otherwise runs as uid 100, which reads "Permission denied". The lane then
# fails on the smoke client rather than on anything it was checking.
user: "0:0"
entrypoint: ["/bin/sh", "/opt/notification-smoke/notification-smoke.sh"]
environment:
APP_BASE_URL: "http://app:8080"
MAILPIT_BASE_URL: "http://mailpit:8025"
# ingest | serving | handoff-verify — which phase of the lane this invocation is.
#
# No default, deliberately. It defaulted to `ingest`, and local-notification-serving therefore
# ran the ingest assertions — "accepted, and nothing was delivered" — against an application in
# SERVING mode. The lane passed while testing the opposite of what it is named for, and would
# have kept passing for as long as the check happened to run before the dispatch worker. An
# unset value now renders empty and the client refuses it.
# `:-` and not a value: an explicit empty default keeps Compose from warning about an unset
# variable on every lane that never runs this client, while still rendering empty so the
# client refuses it.
NOTIFICATION_SMOKE_PHASE: "${NOTIFICATION_SMOKE_PHASE:-}"
# Submission and template publication are authenticated like every other non-public path, so
# this client obtains a token the same way auth-smoke does — client credentials against the
# same issuer URL the application validates against.
APP_BASE_PATH: "${APP_BASE_PATH:-/api}"
KEYCLOAK_ISSUER: "http://keycloak:8080/realms/ca-skeleton"
KEYCLOAK_CLIENT_ID: "ca-skeleton-api"
volumes:
- type: bind
source: ./infra/notification/smoke
target: /opt/notification-smoke
read_only: true
# The handoff lane runs this client twice in one project and the second run needs the request
# id the first accepted, so the state lives in a named volume that outlives a `run --rm`
# container and is removed with the project by the teardown's --volumes.
#
# Its own path, not a subdirectory of the script mount above: a volume nested inside a
# read-only bind cannot be created, because the runtime has to mkdir the mountpoint in a
# filesystem it was just told is read-only.
- type: volume
source: caskeleton-notification-smoke-state
target: /opt/notification-smoke-state
secrets:
- keycloak-graphql-smoke-client-secret
networks:
- caskeleton-infra
restart: "no"
networks:
caskeleton-infra:
driver: bridge
volumes:
caskeleton-notification-smoke-state:
driver: local
caskeleton-db-data:
driver: local
caskeleton-mongo-data:
driver: local
caskeleton-minio-data:
driver: local
secrets:
# Written per run at mode 0600 by the qualification wrapper and removed on teardown. The realm
# artifact references it by name; the value never reaches Git, a rendered config, a command line,
# or an evidence file.
keycloak-graphql-smoke-client-secret:
file: ./infra/keycloak/secrets/graphql-smoke-client-secret
-64
View File
@@ -1,64 +0,0 @@
# =============================================================================
# feature-container-runtime-contract — local infrastructure override
#
# Merge with base (and optionally dev):
# docker compose -f docker-compose.yml -f docker-compose.local.yml up
#
# Local intent:
# - Wires the app environment to point at the shared `db` service, which lives in
# docker-compose.infra.yml and starts only for lanes whose Compose profile names it.
# - Declares no depends_on: a depends_on aimed at a profiled service makes every lane that does
# not enable that profile fail to render at all, and ordering is the runtime-smoke wrapper's
# job — it knows which services a lane actually starts.
# - Keeps read-only filesystem and memory limits from the base compose.
# - Publishes the DB 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 `caskeleton-local` network.
# =============================================================================
services:
app:
# Optional, because src/.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
# clone — the environment override that exists for convenience became a hard prerequisite for
# rendering the stack at all. The tracked contract is src/.env.example; copy it.
env_file:
- path: ./src/.env
required: false
# Wire the app to the local Postgres service on the internal network.
environment:
# Explicit, not inherited. A Compose profile selects services; it says nothing about which
# environment the application believes it is in, and the two drifting is how a dev stack ends
# up running local's settings.
SPRING_PROFILES_ACTIVE: "local"
TZ: "UTC"
LANG: "C.UTF-8"
LC_ALL: "C.UTF-8"
# fallback matches env-keys.yaml SSOT default (30s); base compose grace is 60s.
APP_SERVER_SHUTDOWN_TIMEOUT: "${APP_SERVER_SHUTDOWN_TIMEOUT:-30s}"
APP_SERVER_SHUTDOWN: "graceful"
# Database connection — points to the local `db` service below.
# Override with your actual DB credentials in a local .env file.
APP_DATASOURCE_URL: "jdbc:postgresql://db:5432/${POSTGRES_DB:-ca_skeleton}"
APP_DATASOURCE_USERNAME: "${APP_DATASOURCE_USERNAME:-ca_skeleton}"
APP_DATASOURCE_PASSWORD: "${APP_DATASOURCE_PASSWORD:-ca_skeleton}"
healthcheck:
test:
- "CMD"
- "wget"
- "--no-verbose"
- "--tries=1"
- "--spider"
- "http://localhost:8080/api/healthcheck"
interval: 5s
timeout: 3s
start_period: 20s
retries: 12
networks:
- caskeleton-infra
networks:
# Defined in docker-compose.infra.yml, where the services that share it live.
caskeleton-infra:
external: false
-107
View File
@@ -1,107 +0,0 @@
# =============================================================================
# feature-container-runtime-contract — base docker-compose service definition
#
# Usage:
# docker compose up # base only
# docker compose -f docker-compose.yml -f docker-compose.dev.yml up # dev override
# docker compose -f docker-compose.yml -f docker-compose.local.yml up # local override
#
# Graceful-shutdown sync table (feature-container-runtime-contract D5):
# App shutdown timeout : 30s (APP_SERVER_SHUTDOWN_TIMEOUT — SSOT: docs/registries/
# env-keys.yaml, owner feature-env-driven-runtime-configuration)
# Async executor wait : 19s (AsyncExecutorConfig.AWAIT_TERMINATION_SECONDS)
# Container preStop : 5s (handled by the orchestrator / stop_grace_period offset)
# stop_grace_period : 60s (30s app drain + 19s async + 5s preStop + 6s safety margin)
#
# The drain and the async wait are consecutive, not concurrent: Spring finishes the lifecycle
# phase (the web server's graceful drain) before it destroys the executor, which then waits for
# its queue. A 40s grace let the container be killed 9s into that wait (07-07).
# DeveloperExperienceContractTest fails when this value is below the sum.
#
# Ownership: env-driven-config owns the app shutdown *value* (30s); this contract owns the
# *relationship* (stop_grace_period >= app timeout + async wait + preStop + margin). The grace is therefore
# sized UP to the env-keys SSOT value (30s) — you do not shrink the app drain window to fit an
# arbitrary grace. This resolves the earlier 20s/35s drift, which had assumed an app-timeout
# value this branch does not own (env-keys.yaml is the SSOT and sets 30s).
#
# Memory limit (D4):
# The container memory limit MUST be set for -XX:MaxRAMPercentage=75 to be meaningful.
# Default 512m suits a small service; adjust per deployment.
# =============================================================================
services:
app:
build:
context: src/
dockerfile: Dockerfile
args:
RELEASE_VERSION: "${RELEASE_VERSION:-0.0.1}"
BUILD_VERSION: "${BUILD_VERSION:-0.0.1+0000000}"
GIT_SHA: "${GIT_SHA:-0000000}"
SOURCE_URL: "${SOURCE_URL:-https://example.invalid/ca-tmpl}"
# default = the composition a service ships. scripts/run-compose-runtime-smoke.sh sets
# qualification: every capability module present, each lane switching on what it tests.
COMPOSITION: "${COMPOSITION:-default}"
# 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).
image: caskeleton:${BUILD_VERSION:-0.0.1_local_0000000}-${COMPOSITION:-default}
# Generated per run by scripts/run-compose-runtime-smoke.sh and removed on teardown. Seven values
# have no inline default on purpose — the datasource address and credential, the application
# name, and the JWT issuer and audience — so a lane has to supply them, and a lane that borrowed
# the developer's own src/.env would be reproducible only on that developer's machine. Optional,
# so an ordinary `docker compose up` is unaffected.
env_file:
- path: ./src/.env.lane
required: false
ports:
- "${APP_SERVER_PORT:-8080}:8080"
# Management (health, info, prometheus — answered without authentication) on loopback only:
# published on every interface it reaches the whole LAN (07-13). The smoke lanes read it from
# inside the container, so they need no host port at all.
- "127.0.0.1:9001:9001"
environment:
TZ: "UTC"
LANG: "C.UTF-8"
LC_ALL: "C.UTF-8"
# Graceful shutdown — fallback matches the env-keys.yaml SSOT default (30s).
# Override via .env or docker compose --env-file if you need a different value.
APP_SERVER_SHUTDOWN_TIMEOUT: "${APP_SERVER_SHUTDOWN_TIMEOUT:-30s}"
APP_SERVER_SHUTDOWN: "graceful"
# ---- Read-only root filesystem (D2) -------------------------------------
# The application must write only to the tmpfs mounts declared below.
# /tmp — Tomcat basedir (see -Dserver.tomcat.basedir=/tmp in Dockerfile).
# /var/tmp/heap — heap dump landing zone (see -XX:HeapDumpPath=/var/tmp/heap).
read_only: true
tmpfs:
- /tmp:mode=1777,size=128m
- /var/tmp/heap:mode=1777,size=512m
# No volume: the shipped composition keeps nothing on disk. A capability that does brings its
# mount in its own overlay file under infra/<capability>/compose/, added with -f when the
# capability is selected, so this file never names one (07-08).
# ---- Memory limit (D4) --------------------------------------------------
# Must be set so -XX:MaxRAMPercentage=75 can compute a meaningful heap bound.
mem_limit: 512m
memswap_limit: 512m
# ---- Graceful shutdown (D5) ---------------------------------------------
# stop_grace_period = app drain (30s, env-keys SSOT) + async wait (19s) + preStop (5s)
# + margin (6s) = 60s.
stop_grace_period: 60s
# ---- Health check -------------------------------------------------------
# Targets the actuator readiness probe on the management port (9001).
# The warning that used to stand here — that this probe would report UNHEALTHY until two
# parallel branches merged — outlived the branches. src/Dockerfile removed its copy and said
# why: "a stale warning about a healthcheck is the kind of comment that gets a real red
# container ignored."
healthcheck:
test:
- "CMD"
- "wget"
- "--no-verbose"
- "--tries=1"
- "--spider"
- "http://localhost:9001/actuator/health/readiness"
interval: 30s
timeout: 5s
start_period: 60s
retries: 3
restart: unless-stopped
+102 -10
View File
@@ -1,7 +1,8 @@
# docs
저장소의 모든 문서는 이 디렉터리 아래에 있다. 어떤 문서를 어디에 두는지가 유일한 규칙이고,
파일 목록은 디렉터리를 직접 읽는다. 개수를 여기에 적으면 다음 문서가 추가되는 순간 틀린 글이 된다.
저장소의 모든 문서는 이 디렉터리 아래에 있다. 규칙은 둘이다: 어떤 문서를 어디에 두는지(아래 표),
문서의 수명에 따라 무엇을 어떤 언어로 고치는지(「문서 수명과 언어」). 파일 목록은 디렉터리를 직접 읽는다.
개수를 여기에 적으면 다음 문서가 추가되는 순간 틀린 글이 된다.
## 어댑터별 운영 문서
@@ -24,30 +25,121 @@
| --- | --- |
| `adr/` | 아키텍처 결정 기록 |
| `architecture/` | 공개 API 표면 스냅숏 |
| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`) |
| `evidence/` | 작업 단계별 증거·체크포인트 |
| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 총괄)의 절차서. 루트 `CLAUDE.md` 다음에 읽는다 |
| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` |
| `registries/` | env 키·에러 코드·메트릭·헤더 등 레지스트리 SSOT |
| `reviews/` | 모듈 코드 리뷰 결과 |
| `runbooks/` | 장애 코드별 대응 런북 (`template.md` 기준) |
| `security/` | 공개 경로 스냅숏 |
## 설계와 계획
## 설계와 기록
설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.
| 디렉터리 | 대상 |
| --- | --- |
| `superpowers/specs/` | 설계서. `YYYY-MM-DD-<주제>-design.md` |
| `superpowers/plans/` | 구현·확장 계획서. `YYYY-MM-DD-<주제>-plan.md` |
| `superpowers/packages/` | 외부에서 납품된 설계 패키지의 README와 정적 검증 결과 |
| `design/` | 설계서. `YYYY-MM-DD-<주제>-design.md` |
| `history/plans/` | 구현·확장 계획서. `YYYY-MM-DD-<주제>-plan.md` |
| `history/packages/` | 외부에서 납품된 설계 패키지의 README와 정적 검증 결과 |
| `history/evidence/` | 작업 단계별 증거·체크포인트 |
| `history/study/` | 학습 문서. 쓴 때의 코드를 따라 읽은 기록이다 |
`superpowers/packages/<어댑터>/` 는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을
남긴 기록 보관소다. 설계서·계획서 본문은 전부 `specs/` 와 `plans/` 에 있으므로 이 디렉터리에서
`history/packages/<어댑터>/` 는 설계서가 처음 전달됐을 때의 안내와 `VALIDATION.md` 검증 이력을
남긴 기록 보관소다. 설계서·계획서 본문은 전부 `design/` 과 `history/plans/` 에 있으므로 이 디렉터리에서
문서를 찾을 필요는 없다. 각 README 상단의 보존 안내가 무엇이 옮겨졌고 무엇이 제거됐는지 밝힌다.
`history/packages/*-superpowers-package/` 셋은 납품된 묶음 그대로이고, 그 안의 `MANIFEST.sha256` 은
납품 당시 바이트의 해시다.
계획서 본문에는 당시 계획한 경로와 명령이 그대로 남아 있다. 그중 일부는 실제 구현에서 다른 위치로
조정됐고, 저장소에 어떻게 대응시켰는지는 각 어댑터의 `repository-adaptation.md` 또는
`module-mapping.md` 가 기록한다. 계획서를 사후에 고치지 않는 이유는 그렇게 하면 계획의 기록이 아니라
결과를 계획처럼 보이게 만든 글이 되기 때문이다.
## 문서 수명과 언어
규칙의 정본은 design-docs `conventions/docs-system.md`다. 이 절은 이 repo에 적용한 내용이고,
이 템플릿을 받은 파생 서비스도 이 절을 따른다.
| 수명 | 문서 | 위치 | 언어 | 고치는 법 |
| --- | --- | --- | --- | --- |
| 살아 있음 | README, `CLAUDE.md`, `AGENTS.md`, 매뉴얼(`manual/`, `work/`), 영역 운영 문서, `registries/`, `runbooks/`, `upgrade/` | 제자리 | 한국어 | 코드와 같은 변경에서 고친다 |
| 결정 | 결정 기록(ADR) | `adr/`, `notification/adr/` | 한국어 | 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 보완 절을 덧붙인다. 크게 바뀌면 새 ADR을 쓰고 옛 ADR을 「대체됨」으로 한다 |
| 기록 | 설계서, 계획서, 납품 패키지, 증거, 학습 문서, 리뷰 | `design/`, `history/`, `reviews/` | 머리 블록은 한국어, 본문은 쓴 때의 원문 | 머리 블록의 칸만 고친다 |
- 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 제품 이름은 원문으로 둔다.
- 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
- 아직 한국어로 옮기지 않은 살아 있는 문서와 ADR은 문서 검사의 예외 목록에 있다(「문서 검사」).
## 기록 문서의 머리 블록
`design/`, `history/`, `adr/`, `notification/adr/`의 `.md` 파일은 맨 위에 이 블록을 둔다.
블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다).
```text
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 구현됨
- 작성일: 2026-08-11
- 요약: 한국어 한 문장
- 현재 정본: `docs/jpa/repository-adaptation.md`
- 대체됨: `docs/design/<대체한 문서>.md`
<!-- 머리 블록 끝 -->
```
- 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: `design/` 설계서, `history/plans/` 계획서,
`history/evidence/`·`history/plans/evidence/` 증거, `history/packages/` 납품 패키지,
`history/study/` 학습 문서. ADR의 둘째 줄은
`> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.`다.
- 상태는 종류마다 고정 어휘다.
| 종류 | 상태 |
| --- | --- |
| 설계서 | 제안 · 채택 · 구현됨 · 보류 · 폐기 · 대체됨 · 확인 안 함 |
| 결정 기록 | 제안 · 채택 · 채택(보완) · 폐기 · 대체됨 |
| 계획서 | 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함 |
| 납품 패키지 · 증거 · 학습 문서 | 보관 |
- 「현재 정본」은 지금 동작을 설명하는 살아 있는 문서의 경로다. 여럿이면 쉼표로 잇고, 없으면 「없음 — 이유」로 쓴다.
- 「대체됨」은 상태가 대체됨일 때 대체한 문서의 경로다. 이 문서가 다른 문서를 대체했으면 「대체」 칸에 그 경로를 쓴다.
- 상태는 그 결정을 바꾼 변경이 같이 바꾼다. 기능을 지우는 커밋이 그 기능의 설계서를 「폐기」나 「대체됨」으로 바꾼다.
- 2026-11-07에 처음 단 상태는 문서의 원래 상태 줄을 바꾼 값이다: Accepted·Approved·확정·승인 → 채택,
Superseded → 대체됨, Proposed → 제안, implemented → 구현됨, 보완 메모가 있는 ADR → 채택(보완).
상태 줄이 없던 설계서와 체크 상자가 모두 표시되지 않은 계획서는 「확인 안 함」이다.
`capability-status.md` 「제거된 코드」로 지운 것이 확인된 설계서 다섯은 「폐기」다.
- 리뷰(`reviews/`)는 아직 머리 블록을 요구하지 않는다.
## 문서와 코드를 같은 변경에서 고친다
- 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법:
`grep -rn '<바꾼 이름>' docs src --include=*.md`.
- 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·태스크는 `capability-status.md` 「제거된 코드」나
`upgrade/`에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 `> 이력` 으로 시작하는 인용 블록 안에 쓴다.
- 숫자·버전을 복사하지 않는다. Spring Boot 버전은 `src/gradle/libs.versions.toml`, leaf 목록과 개수는
registry(`src/config/architecture/modules.json`)를 가리킨다.
- 루트 README는 「프로젝트 구조」(최상위 폴더와 `src/` 폴더가 하는 일)와 「문서 지도」(매뉴얼·계약·운영·결정·기록이
어디 있나) 절을 반드시 둔다. 전체 절 목록과 순서는 design-docs `conventions/docs-system.md` 6절이다.
## 문서 검사
`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 넷을 본다. PR마다 workflow `docs-check`가
돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이
문서를 낡게 만든다.
| 검사 | 보는 것 |
| --- | --- |
| `language` | 살아 있는 문서와 ADR 본문이 한국어인가(코드·명령·경로·인용은 세지 않는다) |
| `head` | 기록과 ADR 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 있는지 |
| `reference` | 살아 있는 문서의 인라인 코드 안 경로(`src/`, `docs/`, `scripts/`, `compose/`, `.github/`로 시작하는 것과 지운 infra 폴더 아래 경로)와 Gradle 경로가 지금 트리·registry에 있는가. 코드 블록, `> 이력` 인용 블록, 제거 표, `upgrade/`는 보지 않는다 |
| `number` | 살아 있는 문서가 Spring Boot 버전이나 leaf 개수를 복사했는가 |
- 하나만 돌리기: `python3 scripts/check-docs.py --only head`.
- 예외 목록 `scripts/check-docs-exceptions.txt`는 2026-11-07의 기준선이고 줄기만 한다. 문서를 번역하거나 고쳐서
더는 걸리지 않으면 그 줄을 지운다(남겨 두면 실패한다). 목록에 새 줄을 더하면 실패한다. 기준선을 늘리는 것은
규칙을 바꾸는 일이라 소유자 결정이 필요하다.
- 검사 자신의 시험: `python3 -m unittest discover -s scripts/tests`.
- 마크다운 상대 링크는 이 검사가 아니라 lychee(`link-check` workflow)와 `scripts/check-work-docs.py --links`가 본다.
## 여기에 없는 것
- 실행되는 검증 스크립트는 문서가 아니다. `scripts/` 와 `.github/scripts/` 에 있다.
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-09-07
- 요약: 공유 테스트 코드는 java-test-fixtures 한 가지 방식으로 둔다는 결정이다.
- 현재 정본: `src/build-logic/README.md`
<!-- 머리 블록 끝 -->
# ADR-BUILD-001: `java-test-fixtures` is the standard for shared test code
- Status: Accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-24
- 요약: GraphQL context는 inbound에 두고 객체 권한 판단은 application-core로 옮긴다는 결정이다.
- 현재 정본: `src/adapter/inbound/graphql/README.md`
<!-- 머리 블록 끝 -->
# ADR-GQL-001 — GraphQL context stays inbound; object authorization moves to application-core; the persisted-operation store stays an inbound SPI
- Status: Accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-30
- 요약: gRPC 플랫폼을 adapter leaf 하나가 아니라 registry에 등록한 family로 낸다는 결정이다.
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-001: The gRPC platform ships as a registered family, not as one adapter leaf
- Status: accepted
@@ -1,3 +1,13 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 대체됨
- 작성일: 2026-08-30
- 요약: protoc와 Buf CLI 없이 스키마를 관리하려던 결정이다. 2026-09-28 Gradle protobuf plugin과 buf로 바뀌었다.
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
- 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-002: Schema governance runs without protoc and without the Buf CLI
- Status: **superseded (2026-09-28)** by owner decision 18 of the 2026-09-25 review follow-up
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-30
- 요약: 전송·업무·스트림 증거를 서로 대신하지 않는 세 축으로 본다는 결정이다.
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-003: Transport, business and stream evidence are three axes, and none implies another
- Status: accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-30
- 요약: 재시도 주인은 하나이고 키가 있는 변경은 영속 원장이 필요하다는 결정이다.
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-004: One retry owner, and keyed mutations need a durable ledger
- Status: accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-30
- 요약: 서버 스트림은 writer 하나, 제한된 큐, 추측하지 않는 resume로 다룬다는 결정이다.
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-005: One writer per stream, a bounded queue, and resume that refuses to guess
- Status: accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-31
- 요약: Stable discovery는 DNS와 정적 목록이고 Kubernetes에서는 누가 부하를 나누는지 profile이 정한다는 결정이다.
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-006: Stable discovery is DNS and static, and a Kubernetes profile names who balances
- Status: accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-30
- 요약: gRPC 고급 기능마다 따로 플래그·등급·승격 기준을 둔다는 결정이다.
- 현재 정본: `docs/compatibility/grpc-advanced-support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-GRPC-ADV-001: Each advanced capability has its own flag, its own grade and its own promotion
- Status: accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-11
- 요약: 영속성 모델은 도메인이 소유한다는 결정이다.
- 현재 정본: `docs/jpa/repository-adaptation.md`
<!-- 머리 블록 끝 -->
# ADR-JPA-001 — The domain owns the persistence model
- Status: Accepted
@@ -1,3 +1,13 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 대체됨
- 작성일: 2026-08-11
- 요약: 재시도는 유스케이스 전체를 다시 돌린다는 결정이다. 그 재시도 엔진은 2026-09-25에 지웠다.
- 현재 정본: `docs/jpa/transaction-guide.md`
- 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 -->
# ADR-JPA-002 — Retry re-runs the whole use case
- Status: Superseded (2026-09-25) — the retry engine this ADR describes
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택(보완)
- 작성일: 2026-08-11
- 요약: commit 결과를 모르는 실패는 재시도하지 않는다는 결정이다. 2026-09-25 보완이 있다.
- 현재 정본: `docs/jpa/transaction-guide.md`
<!-- 머리 블록 끝 -->
# ADR-JPA-003 — Completion unknown is never retried
- Status: Accepted; amended 2026-09-25 — `TransactionCompletionResolver`, `CommitFailureClassifier`
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-11
- 요약: 스키마의 정본은 Flyway라는 결정이다.
- 현재 정본: `docs/jpa/migration-guide.md`
<!-- 머리 블록 끝 -->
# ADR-JPA-004 — Flyway is the schema source of truth
- Status: Accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-11
- 요약: 영속성 계약은 실제 PostgreSQL에서 돌린다는 결정이다.
- 현재 정본: `docs/jpa/support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-JPA-005 — Contracts run against real PostgreSQL
- Status: Accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-24
- 요약: 기술 감사 모델은 audit 하나뿐이라는 결정이다.
- 현재 정본: `docs/jpa/repository-adaptation.md`
<!-- 머리 블록 끝 -->
# ADR-JPA-006 — `audit` is the sole technical audit model
- Status: Accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-13
- 요약: MongoDB 플랫폼의 경계를 정한 결정이다.
- 현재 정본: `docs/mongodb/repository-adaptation.md`
<!-- 머리 블록 끝 -->
# ADR-MONGO-001 — MongoDB platform boundary
- **Status:** Accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-13
- 요약: BSON 표현을 고정한 목록으로 관리한다는 결정이다.
- 현재 정본: `docs/mongodb/bson-mapping-guide.md`
<!-- 머리 블록 끝 -->
# ADR-MONGO-002 — BSON representation is a pinned manifest
- **Status:** Accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-13
- 요약: 트랜잭션 본문 재시도와 commit 재시도를 다른 반복으로 둔다는 결정이다.
- 현재 정본: `docs/mongodb/consistency-transaction-guide.md`
<!-- 머리 블록 끝 -->
# ADR-MONGO-003 — Transaction body retry and commit retry are separate loops
- **Status:** Accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-13
- 요약: 인덱스와 스키마 변경은 관리 평면이 맡는다는 결정이다.
- 현재 정본: `docs/mongodb/schema-index-migration-guide.md`
<!-- 머리 블록 끝 -->
# ADR-MONGO-004 — Index and schema changes belong to the admin plane
- **Status:** Accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택(보완)
- 작성일: 2026-08-13
- 요약: MongoDB 고급 기능의 승격 기준을 정한 결정이다. 2026-09-25 보완이 있다.
- 현재 정본: `docs/mongodb/support-matrix.md`
<!-- 머리 블록 끝 -->
# ADR-MONGO-ADV-001 — Advanced capability promotion
- **Status:** Accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-25
- 요약: 스트리밍은 실시간 전달이고 web 모듈은 이력을 저장하지 않는다는 결정이다.
- 현재 정본: `docs/web/streaming-contract.md`
<!-- 머리 블록 끝 -->
# ADR-WEB-ADV-001: Streaming is live delivery, and the web module stores no history
- Status: Accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-25
- 요약: 가상 스레드는 스케줄링을 바꿀 뿐 동시성 예산을 없애지 않는다는 결정이다.
- 현재 정본: `docs/web/virtual-thread-profile.md`
<!-- 머리 블록 끝 -->
# ADR-WEB-ADV-002: Virtual threads change scheduling, not the concurrency budget
- Status: Accepted
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-25
- 요약: OpenAPI 3.2 문서는 나란히 만들고 실험 등급으로 둔다는 결정이다.
- 현재 정본: `docs/web/openapi-32-compatibility.md`
<!-- 머리 블록 끝 -->
# ADR-WEB-ADV-003: OpenAPI 3.2 is generated in parallel and stays experimental
- Status: Accepted
@@ -1,3 +1,13 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 대체됨
- 작성일: 2026-08-25
- 요약: WebSocket 플랫폼을 leaf 하나의 패키지들로 내고 경계를 기계로 검사한다는 결정이다. 2026-09-25 플랫폼을 줄이면서 바뀌었다.
- 현재 정본: `src/adapter/inbound/websocket/README.md`
- 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 -->
# ADR-WS-001: The WebSocket platform ships as packages in one leaf, with machine-checked boundaries
- Status: Superseded 2026-09-25 — the eighteen-package platform was cut to the parts a Spring
+10
View File
@@ -1,3 +1,13 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 대체됨
- 작성일: 2026-08-25
- 요약: resume·cluster 상태는 캐시로 다룬다는 결정이다. 그 기능은 2026-09-25에 지웠다.
- 현재 정본: `src/adapter/inbound/websocket/README.md`
- 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 -->
# ADR-WS-002: Resume and cluster state are caches, and are treated as caches
- Status: Superseded 2026-09-25 — `advanced.resume`, `advanced.cluster` and `advanced.presence`
@@ -1,3 +1,13 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 대체됨
- 작성일: 2026-08-25
- 요약: STOMP를 목적지 목록이 있는 고급 어댑터로 둔다는 결정이다. 그 고급 STOMP는 2026-09-25에 지웠다.
- 현재 정본: `src/adapter/inbound/websocket/README.md`
- 대체됨: `docs/capability-status.md`
<!-- 머리 블록 끝 -->
# ADR-WS-003: STOMP is an Advanced adapter with a declared destination catalog
- Status: Superseded 2026-09-25 — `advanced.stomp` and `advanced.stomp.rabbit` were removed; the
+3 -3
View File
@@ -27,11 +27,11 @@ lanes and CI; it is not a deployment artifact.
| Capability | Enabled key (property / env, default) | IMPLEMENTED | WIRED | QUALIFIED | Evidence |
| --- | --- | --- | --- | --- | --- |
| Relational persistence (JPA/PostgreSQL) | `ca-skeleton.persistence-jpa.enabled` / `APP_PERSISTENCE_JPA_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-jpa')`) | yes | Not in the default composition. The one line brings everything — its own `AutoConfiguration.imports` (`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `JpaStartupAutoConfiguration`), its environment handling (`JpaActivationEnvironmentPostProcessor`, `spring.factories`: readiness `db` while on; with `false` it also excludes Boot's JDBC, Hibernate, Spring Data JPA and Flyway auto-configuration, so no DataSource is bound), the startup guards (Flyway strategy, datasource/OSIV/DDL/pool/TLS/vendor checks, exit codes unchanged) and its settings (`config/module-defaults/persistence-jpa.yml`). `persistence-jpa:PersistenceJpaCapabilityAssemblyTest` proves the module assembles on its own; the `postgresql*IntegrationTest` readiness lanes, run by `integration-main.yml` → `integration-check` (`:integrationCheck`), qualify it against PostgreSQL. `sample-portfolio` selects it by its build dependency and the module's auto-configuration (no broad scan of the persistence package). `bootRunH2` adds the module to its own classpath only. |
| Relational persistence (JPA/PostgreSQL) | `ca-skeleton.persistence-jpa.enabled` / `APP_PERSISTENCE_JPA_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-jpa')`) | yes | Not in the default composition. The one line brings everything — its own `AutoConfiguration.imports` (`PersistenceJpaAutoConfiguration`, `PersistenceJpaRuntimeConfig`, `JpaStartupAutoConfiguration`), its environment handling (`JpaActivationEnvironmentPostProcessor`, `spring.factories`: readiness `db` while on; with `false` it also excludes Boot's JDBC, Hibernate, Spring Data JPA and Flyway auto-configuration, so no DataSource is bound), the startup guards (Flyway strategy, datasource/OSIV/DDL/pool/TLS/vendor checks, exit codes unchanged) and its settings (`config/module-defaults/persistence-jpa.yml`). `persistence-jpa:PersistenceJpaCapabilityAssemblyTest` proves the module assembles on its own; the `postgresql*IntegrationTest` readiness lanes, run by `integration-main.yml` → `integration-check` (`:integrationCheck`), qualify it against PostgreSQL. `bootRunH2` adds the module to its own classpath only. |
| Document persistence (MongoDB) | `ca-skeleton.persistence-mongo.enabled` / `APP_PERSISTENCE_MONGO_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:persistence-mongo')`) | yes | On when present; `false` also excludes Boot's Mongo auto-configuration (`MongoCapabilityActivationTest`). The connection-source rule (`SPRING_MONGODB_URI` or the selected profile's `uri-secret`) is checked by the module's own `MongoDefaultsEnvironmentPostProcessor`. Six container lanes (`mongoReplicaSetTest`, `mongoFailoverTest`, …), run by `integration-main.yml` → `integration-check` (`:integrationCheck`) |
| Messaging (Kafka) | `app.messaging.enabled` / `APP_MESSAGING_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:messaging-kafka')`, which brings the application bridge, the legacy `KafkaSender` seam and the vendored platform with its Kafka transport) | Kafka only | On when present (`KafkaCapabilityActivationTest`). `messaging-kafka:messagingCertificationTest` behind `verifyMessagingCertificationEvidence`, run by `messaging-certification.yml`; the starter's `integrationTest` is the live Kafka round trip. Kafka is the only registered broker; the RabbitMQ broker keys were removed (no transport). |
| Redis capabilities (cache / rate-limit / lease / idempotency) | `app.redis.enabled` / `APP_REDIS_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':adapter:outbound:cache-redis')`, which brings `redis-runtime`) | yes | `cache-redis:redisContainerContractTest` (Testcontainers Redis, `integrationCheck`); `cache-redis:redisTopologyTest`, run by `redis-sdk-topology.yml`. Not in the default composition. On when present; `false` contributes no Redis bean — no settings, client, connection, thread or health contributor. The module owns its readiness contribution (`RedisReadinessGroupPostProcessor`, `spring.factories`) and its settings (`config/module-defaults/cache-redis.yml`: `app.redis.enabled`, `app.rate-limit.*`, the Redis `ca-skeleton.capabilities.*`). No `app-bootstrap` main source names a Redis type. |
| Request idempotency | `APP_IDEMPOTENCY_PROVIDER` (`disabled` \| `redis` \| `postgresql`; a selector, not an on/off key) | yes | yes | Redis and PostgreSQL | One generation: the application `IdempotencyExecutor`, built once by `composition:idempotency` (`IdempotencyAutoConfiguration`) over the one store the selected provider contributes (`cache-redis` or `persistence-jpa`); startup is refused unless exactly one store exists. `app-bootstrap` and `sample-portfolio` both take that module with one `runtimeOnly` line, so there is no second assembly. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, run by `integration-main.yml` → `integration-check` (`:integrationCheck`). The `postgresql` provider refuses a non-PostgreSQL data source, so `bootRunH2` uses `disabled` or `redis`. Each store comes with its module: `postgresql` needs the persistence-jpa line, `redis` the cache-redis one. |
| Request idempotency | `APP_IDEMPOTENCY_PROVIDER` (`disabled` \| `redis` \| `postgresql`; a selector, not an on/off key) | yes | yes | Redis and PostgreSQL | One generation: the application `IdempotencyExecutor`, built once by `composition:idempotency` (`IdempotencyAutoConfiguration`) over the one store the selected provider contributes (`cache-redis` or `persistence-jpa`); startup is refused unless exactly one store exists. `app-bootstrap`이 그 모듈을 `runtimeOnly` 한 줄로 받고, 다른 조립은 없다. Redis is covered by the row above. PostgreSQL has `persistence-jpa:postgresqlIdempotencyIntegrationTest`, run by `integration-main.yml` → `integration-check` (`:integrationCheck`). The `postgresql` provider refuses a non-PostgreSQL data source, so `bootRunH2` uses `disabled` or `redis`. Each store comes with its module: `postgresql` needs the persistence-jpa line, `redis` the cache-redis one. |
| Transactional outbox relay | `ca-skeleton.outbox.enabled` / `APP_OUTBOX_ENABLED`, `false` (+ `APP_OUTBOX_RELAY_ENABLED`, `false`; persistence-jpa settings) | yes | yes (with the persistence-jpa line; the scheduler also needs the messaging-kafka line) | yes | The store and its settings are persistence-jpa's; the relay (`OutboxConfig`) is application composition in `app-bootstrap` because a driven adapter must not build or call a use case. It turns on only when an `OutboxStorePort` bean exists, and the scheduler only when an `OutboxMessagePublishPort` does (the messaging bridge), each ordered after its contributor by `afterName` — so an environment with no publisher keeps its PENDING rows. The bridge registers no stand-in publisher: a present-and-enabled bridge with a blank broker and no canonical transport is refused at startup. `postgresqlLegacyOutboxConcurrentRelayIntegrationTest` qualifies claim/fencing against PostgreSQL. |
| Notification platform | `ca-skeleton.notification.platform.enabled` / `APP_NOTIFICATION_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:notification-platform')`, plus the persistence-jpa line) | claim-scoped | Not in the default composition. The one line brings the use-case assembly, `adapter:outbound:notification`, the HTTP surface `adapter:inbound:web-notification` and its own settings (`config/module-defaults/notification.yml`), each registered through the module's own `AutoConfiguration.imports`; `adapter:inbound:web` no longer depends on `application-notification`. `verifyNotificationEvidence` refuses a grade in `docs/notification/support-matrix.md` that no proven claim backs; run by `notification-platform.yml`. There is no real-SMTP lane, and the matrix says so rather than implying one. |
| File server platform | `app.fileserver-platform.enabled` / `APP_FILESERVER_PLATFORM_ENABLED`, `true` | yes | yes (one line: `runtimeOnly project(':composition:fileserver-platform')`, plus the persistence-jpa line) | yes | On when present; module-owned `config/module-defaults/fileserver.yml` also carries the servlet multipart ceiling. `app-bootstrap:integrationTest` → `FileserverCompositionIntegrationTest` (required by the strict lane), run by `integration-main.yml` → `integration-check` (`:integrationCheck`) |
@@ -71,7 +71,7 @@ web 경로의 `W/`는 `src/adapter/inbound/web/src/main/java/dev/caskeleton/adap
복구가 필요하면 표의 커밋에서 경로를 꺼낸다(`git show <커밋>:<경로>`).
리뷰 후속 작업(2026-09-25~28, `docs/superpowers/plans/2026-09-25-review-followup.md`)에서 지운 것은 마지막으로 존재한 커밋이 `6d27356e`인 행으로 표 끝에 이어 붙였다.
리뷰 후속 작업(2026-09-25~28, `docs/history/plans/2026-09-25-review-followup.md`)에서 지운 것은 마지막으로 존재한 커밋이 `6d27356e`인 행으로 표 끝에 이어 붙였다.
| 대상 | 경로 | 마지막으로 존재한 커밋 | 이유 |
| --- | --- | --- | --- |
+4 -6
View File
@@ -60,12 +60,10 @@ GitHub Actions 워크플로는 `kubectl apply`, `helm upgrade`, `argocd app sync
| Argo CD Application 정의 | **없음.** GitOps 저장소에 둘 예정 |
| CI에서의 클러스터 접근 | 없음 — 유일했던 `kubectl apply`는 제거됨 |
`release.yml`의 fileserver certification 잡(`fileserver-pvc-certification` 등, 예전
`fileserver-certification.yml`)은 예외처럼 보이지만 아니다. PVC 매니페스트가 여전히 ReadWriteOnce를
선언하는지 **파일만** 확인하고, 클러스터에는 아무것도 적용하지 않는다. 실제 클러스터에서의 인증은
운영자가 `infra/fileserver/kubernetes/pvc-certification-job.yaml`을 직접 실행하고
`docs/fileserver/storage-certification.md`에 기록한다. 잡 이름이 "release"가 아니라 "certification"인
이유가 이것이다 — 이 잡은 릴리스하지 않는다.
PVC 매니페스트와 그 파일을 검사하던 `release.yml` 잡(`fileserver-pvc-certification`)은 2026-11-07에
지웠다(소유자 결정: Kubernetes·프록시 설정은 이 repo 밖). 클러스터 인증은 배포하는 쪽이
`docs/fileserver/storage-certification.md` 절차로 하고, volume 조건은 `docs/fileserver/operations.md`
「운영 환경이 지켜야 할 조건」에 있다.
## 규칙
+3 -6
View File
@@ -4,8 +4,8 @@
이 저장소에는 성격이 다른 두 종류의 검증이 섞여 있다.
1. **스켈레톤을 만드는 사람**에게 필요한 검증 — sample 모듈이 정말 제거 가능한가, optional 모듈
조합이 모두 빌드되는가, 레지스트리가 확장 가능한가.
1. **스켈레톤을 만드는 사람**에게 필요한 검증 — optional 모듈 조합이 모두 빌드되는가, 레지스트리가
확장 가능한가.
2. **스켈레톤을 가져다 서비스를 만드는 사람**에게 필요한 검증 — 내 애플리케이션의 테스트,
아키텍처 방향, 보안, 릴리스.
@@ -16,10 +16,7 @@
| 대상 | 무엇을 지키는가 |
| --- | --- |
| `:app-bootstrap:sampleOffTest`, `ci-quality-gates.yml`의 `sample-off` job | sample 픽스처를 지워도 애플리케이션이 빌드·부팅되는가 |
| `sample-portfolio` leaf 전체 | 참조 구현 |
| `Dockerfile.sample`, `docker-compose.*` 중 sample 관련 | 위와 동일 |
| `docs/superpowers/**` | 이 템플릿을 만든 과정의 설계/계획 기록 |
| `docs/design/**`, `docs/history/**` | 이 템플릿을 만든 과정의 설계서·계획서·납품 패키지·증거·학습 기록 |
| `gradle/qualification/**` | 이 템플릿이 벤더링한 플랫폼(JPA, messaging)의 인증 체계 |
| `*-certification.yml`, `*-qualification.yml`, `jpa-next-*.yml` | 템플릿이 광고하는 지원 매트릭스의 근거 |
@@ -1,3 +1,13 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 대체됨
- 작성일: 2026-07-20
- 요약: 중복된 하네스 규칙을 레지스트리 기반 정책 엔진으로 바꾸려던 설계다.
- 현재 정본: `src/config/architecture/modules.json`
- 대체됨: `docs/design/2026-07-25-harness-free-mode-b-amendment.md`
<!-- 머리 블록 끝 -->
> **SUPERSEDED — HISTORICAL PROVENANCE ONLY (2026-07-25):** The user-approved harness-free
> Mode B amendment supersedes this design. Retain the body as historical provenance; it is not
> executable instruction.
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-25
- 요약: application-core에서 Spring·로깅 의존을 걷어내고 확정된 outbox 실패를 보고하는 방식을 정한 설계다.
- 현재 정본: `src/composition/outbox-relay/README.md`
<!-- 머리 블록 끝 -->
# Application Outbox Failure Reporting Refactoring Design
- **Date:** 2026-07-25
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 확인 안 함
- 작성일: 2026-07-25
- 요약: 하네스 없이 application-core를 프레임워크·로깅 없이 두면서 outbox 실패를 구조화된 ERROR 한 줄로 남기는 설계다.
- 현재 정본: `src/composition/outbox-relay/README.md`
<!-- 머리 블록 끝 -->
# Application Outbox Failure Reporting — Harness-Free Design
## Context
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-25
- 요약: 숨어 있던 CI 제어면을 저장소 안으로 되살려 Gradle·Docker 빌드와 의존성 자동화를 맞추는 설계다.
- 현재 정본: `docs/work/reference/gates.md`
<!-- 머리 블록 끝 -->
# CI Control Plane Recovery Design
- **Date:** 2026-07-25
@@ -114,7 +123,7 @@ native provenance.
**Mode B — controlled reconstruction.** The original source is unavailable or incomplete. The
human records that fact and explicitly authorizes reconstruction from the approved
[`2026-07-20-harness-policy-engine-design.md`](2026-07-20-harness-policy-engine-design.md),
[`2026-07-20-harness-policy-engine.md`](../plans/2026-07-20-harness-policy-engine.md), the tracked
[`2026-07-20-harness-policy-engine.md`](../history/plans/2026-07-20-harness-policy-engine.md), the tracked
Gradle/module sources, and this design. Reconstructed artifacts receive new hashes and a
`controlled-reconstruction` provenance record. Schema, renderer parity, mutation coverage, Gradle
project discovery, and architecture dependency checks must pass before the new artifacts can act as
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-25
- 요약: 하네스를 되살리지 않고 Gradle 부트스트랩과 의존 방향 검사를 복구하며 registry JSON을 정본으로 정한 범위 수정이다.
- 현재 정본: `src/config/architecture/modules.json`
<!-- 머리 블록 끝 -->
# Harness-Free Mode B Amendment
- **Date:** 2026-07-25
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-25
- 요약: 하네스 없이 품질·의존성 보안 CI를 저장소 안에서 다시 세우는 설계다.
- 현재 정본: `docs/work/reference/gates.md`
<!-- 머리 블록 끝 -->
# Harness-Free Quality and Security CI Design
- **Date:** 2026-07-25
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-25
- 요약: leaf Gradle 의존 그래프를 Clean Architecture를 지키는 최소 모양으로 줄이는 정리 설계다.
- 현재 정본: `src/config/architecture/modules.json`
<!-- 머리 블록 끝 -->
# Module and Gradle Hygiene Refactoring Design
- **Date:** 2026-07-25
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-25
- 요약: 같은 모듈·Gradle 정리를 하네스 없이 적용하는 설계다.
- 현재 정본: `src/config/architecture/modules.json`
<!-- 머리 블록 끝 -->
# Harness-Free Module and Gradle Hygiene Design
- **Date:** 2026-07-25
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 폐기
- 작성일: 2026-07-26
- 요약: 파일 서버를 단계별로 운영 가능한 capability로 올리는 상세 설계다. 이 설계의 publication R1/R2 어댑터는 2026-09-25에 지웠다.
- 현재 정본: `docs/fileserver/support-matrix.md`
<!-- 머리 블록 끝 -->
# Fileserver Production Capability Deep Design
- 작성일: 2026-07-26
@@ -1,3 +1,13 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 대체됨
- 작성일: 2026-07-26
- 요약: 통합 지점 모음을 opt-in 운영 capability 플랫폼으로 키우는 전체 설계다. 스위치로 끄던 방식은 2026-09-25 capability 모듈 포장으로 바뀌었다.
- 현재 정본: `docs/capability-status.md`
- 대체됨: `docs/design/2026-09-25-capability-module-packaging-design.md`
<!-- 머리 블록 끝 -->
# Production Capability Platform Design
- Date: 2026-07-26
@@ -952,7 +962,7 @@ and durable interfaces are explicit.
The authoritative implementation-level design for this capability is
[Object Storage Production Capability Deep Design](2026-07-28-objectstorage-production-capability-design.md).
Its ordered RED–GREEN execution batches and promotion gates are in the
[Object Storage Production Capability Implementation Plan](../plans/2026-07-28-objectstorage-production-capability.md).
[Object Storage Production Capability Implementation Plan](../history/plans/2026-07-28-objectstorage-production-capability.md).
This subsection is only the cross-capability baseline; the dedicated design governs when details
differ.
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-26
- 요약: Redis를 운영 가능한 capability로 올리는 단계별 상세 설계다.
- 현재 정본: `docs/redis/support-matrix.md`
<!-- 머리 블록 끝 -->
# Redis Production Capability Deep Design
- Date: 2026-07-26
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-27
- 요약: HTTP client를 운영 가능한 capability로 올리는 단계별 상세 설계다.
- 현재 정본: `docs/httpclient/support-matrix.md`
<!-- 머리 블록 끝 -->
# HTTP Client Production Capability Deep Design
- 작성일: 2026-07-27
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 폐기
- 작성일: 2026-07-28
- 요약: 파일 서버 R2 제어면과 provider 선택을 정한 설계다. 이 R2 어댑터는 2026-09-25에 지웠다.
- 현재 정본: `docs/fileserver/support-matrix.md`
<!-- 머리 블록 끝 -->
# Fileserver R2 Control Plane and Provider Selection Design
- Date: 2026-07-28
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-28
- 요약: JPA·PostgreSQL을 운영 가능한 capability로 올리는 상세 설계다.
- 현재 정본: `docs/jpa/repository-adaptation.md`
<!-- 머리 블록 끝 -->
# JPA/PostgreSQL Production Capability Deep Design
- 작성일: 2026-07-28
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-28
- 요약: 메시징을 운영 가능한 capability로 올리는 상세 설계다.
- 현재 정본: `docs/messaging/support-matrix.md`
<!-- 머리 블록 끝 -->
# Messaging Production Capability Deep Design
- 작성일: 2026-07-28
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-28
- 요약: 알림을 운영 가능한 capability로 올리는 상세 설계다.
- 현재 정본: `docs/notification/support-matrix.md`
<!-- 머리 블록 끝 -->
# Notification Production Capability Deep Design
- 작성일: 2026-07-28
@@ -15,7 +24,7 @@
이 문서는 Notification capability의 승인된 상세 설계다. 2026-07-28에 §36의 다섯 gate를
사용자가 승인했으며, 실제 구현 순서는
[Notification Production Capability Implementation Plan](../plans/2026-07-28-notification-production-capability.md)을
[Notification Production Capability Implementation Plan](../history/plans/2026-07-28-notification-production-capability.md)을
정본으로 사용한다. 구현 및 production readiness는 아직 주장하지 않는다.
2026-07-28 현재 구현된 범위:
@@ -4793,7 +4802,7 @@ COMPLETE 뒤 reverse가 필요하다면 canonical in-flight/intent backlog/provi
inbound messaging/inbox architecture로 설계를 수정해야 한다.
사용자는 2026-07-28에 위 다섯 결정을 승인했다. 구현은
[Notification Production Capability Implementation Plan](../plans/2026-07-28-notification-production-capability.md)의
[Notification Production Capability Implementation Plan](../history/plans/2026-07-28-notification-production-capability.md)의
작은 TDD task, owner leaf, registry-derived Gradle path, focused test, architecture gate,
real-provider evidence와 rollback point를 따른다.
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-28
- 요약: object storage를 운영 가능한 capability로 올리는 상세 설계와 batch 진행 기록이다.
- 현재 정본: `src/adapter/outbound/objectstorage/README.md`
<!-- 머리 블록 끝 -->
# Object Storage Production Capability Deep Design
- 작성일: 2026-07-28
@@ -12,7 +21,7 @@
- 상위 문서:
[Production Capability Platform Design](2026-07-26-production-capability-platform-design.md)
- 구현 계획:
[Object Storage Production Capability Implementation Plan](../plans/2026-07-28-objectstorage-production-capability.md)
[Object Storage Production Capability Implementation Plan](../history/plans/2026-07-28-objectstorage-production-capability.md)
- 참고 설계:
[Redis Production Capability Deep Design](2026-07-26-redis-production-capability-design.md),
[Fileserver Production Capability Deep Design](2026-07-26-fileserver-production-capability-design.md),
@@ -78,11 +87,11 @@
create-only PUT/complete 조건을 무시하므로 managed/direct mutation profile을
`UNSUPPORTED`로 유지하며 readiness를 올리지 않는다.
증거는 [Batch A checkpoint](../../evidence/object-storage/batch-a-checkpoint.md),
[Batch B checkpoint](../../evidence/object-storage/batch-b-checkpoint.md),
[Batch C checkpoint](../../evidence/object-storage/batch-c-progress.md),
[Batch D checkpoint](../../evidence/object-storage/batch-d-checkpoint.md),
[Batch E pause checkpoint](../../evidence/object-storage/batch-e-pause-checkpoint.md)에 기록했다.
증거는 [Batch A checkpoint](../history/evidence/object-storage/batch-a-checkpoint.md),
[Batch B checkpoint](../history/evidence/object-storage/batch-b-checkpoint.md),
[Batch C checkpoint](../history/evidence/object-storage/batch-c-progress.md),
[Batch D checkpoint](../history/evidence/object-storage/batch-d-checkpoint.md),
[Batch E pause checkpoint](../history/evidence/object-storage/batch-e-pause-checkpoint.md)에 기록했다.
격리 브랜치에서는 private vault 경로를 잘못 선택해 capture가 차단됐지만, main 통합 작업은
사용자가 지정한 public vault의
@@ -4015,7 +4024,7 @@ authorization endpoint의 ephemeral response이며 stored object DTO에 영구
## 37. 구현 계획 작성 전 확정 항목
정본 구현 순서와 아래 결정의 현재 freeze/approval gate는
[Object Storage Production Capability Implementation Plan](../plans/2026-07-28-objectstorage-production-capability.md)에
[Object Storage Production Capability Implementation Plan](../history/plans/2026-07-28-objectstorage-production-capability.md)에
기록한다. Tasks 1–24의 구현은 Batch E pause checkpoint까지 진행됐지만 Batch E 전체
combined/root gate는 아직 통과하지 않았다. Tasks 25–30은 미착수다. 이 구현 진행이나
계획 승인이 public API, scanner provider 또는 AWS/IaC 외부 변경 권한을 자동으로 부여하지
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 제안
- 작성일: 2026-07-28
- 요약: 운영 수준 테스트 구조와 테스트 환경(서비스 준비, 데이터 격리, CI·릴리스 환경)을 정하는 제안이다.
- 현재 정본: `docs/testing/TESTING_STRATEGY.md`
<!-- 머리 블록 끝 -->
# Production-grade test architecture and environment design
- Status: proposed design; implementation not started
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-28
- 요약: Redis 캐시에 cache-aside, 원본 보호, soft/hard TTL을 더하는 증분 설계다.
- 현재 정본: `docs/redis/support-matrix.md`
<!-- 머리 블록 끝 -->
# Redis Cache Resilience Increment Design
**Status:** approved for implementation
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 구현됨
- 작성일: 2026-07-28
- 요약: Redis로 고를 수 있는 분산 rate-limit 알고리즘 셋을 제공하는 증분 설계다.
- 현재 정본: `docs/redis/support-matrix.md`
<!-- 머리 블록 끝 -->
# Redis Distributed Rate-Limit Increment Design
**Status:** implemented as standalone R1
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-01
- 요약: 릴리스 위생 경로(sample-off 게이트, wrapper 검증, Docker 캐시, SpotBugs)를 사실대로 맞추는 리팩터링 설계다.
- 현재 정본: `docs/work/reference/gates.md`
<!-- 머리 블록 끝 -->
# Release Hygiene Refactoring Design
**Date:** 2026-08-01
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-02
- 요약: 공개 HTTP 오류 응답에 허용한 문구와 안전한 값만 담게 하는 경계 설계다.
- 현재 정본: `docs/web/http-contract.md`
<!-- 머리 블록 끝 -->
# Client-Safe Error Boundary Design
**Date:** 2026-08-02
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-02
- 요약: GraphQL·gRPC·WebSocket 전송을 고를 때만 켜고 위험한 활성화는 실패시키는 경계 설계다.
- 현재 정본: `docs/web/http-contract.md`
<!-- 머리 블록 끝 -->
# Conditional Inbound Transport Boundary Design
**Date:** 2026-08-02
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 확인 안 함
- 작성일: 2026-08-02
- 요약: 동작을 바꾸지 않고 남은 fail-open 검증 경로를 없애는 리팩터링 설계다.
- 현재 정본: `docs/work/reference/gates.md`
<!-- 머리 블록 끝 -->
# P2 Verification Governance Refactoring Design
## Goal
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-02
- 요약: Redis 세션과 HTTP 경계에서 브라우저 세션 보안이 유지되고 실패 시 닫히는지 증명하는 설계다.
- 현재 정본: `docs/redis/support-matrix.md`
<!-- 머리 블록 끝 -->
# Redis Session HTTP Boundary Design
**Date:** 2026-08-02
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-02
- 요약: 파일을 고치던 검증 경로(stale JAR, 공개 경로)를 읽기 전용으로 바꾸는 설계다.
- 현재 정본: `docs/work/reference/gates.md`
<!-- 머리 블록 끝 -->
# Verification Purity Refactoring Design
**Date:** 2026-08-02
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-02
- 요약: 컴파일러·정적 분석·테스트 출력 경고를 0으로 만드는 빌드 설계다.
- 현재 정본: `docs/work/reference/gates.md`
<!-- 머리 블록 끝 -->
# Warning-Zero Build Refactoring Design
**Date:** 2026-08-02
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-02
- 요약: JWT·JWKS와 CORS 필터 경계를 밀봉된 테스트와 릴리스 차단 검사로 고정하는 설계다.
- 현재 정본: `docs/web/http-contract.md`
<!-- 머리 블록 끝 -->
# Web Security Boundary Design
**Date:** 2026-08-02
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 확인 안 함
- 작성일: 2026-08-07
- 요약: 업로드·다운로드를 넘어 저장·게시·전송을 나눈 공통 파일 서비스 플랫폼 설계다.
- 현재 정본: `docs/fileserver/support-matrix.md`
<!-- 머리 블록 끝 -->
# Fileserver Platform 설계서
**문서 상태:** 설계 확정안
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-07
- 요약: Redis 자료구조와 명령을 위험도에 따라 Typed API와 통제된 Raw Gateway로 나눠 제공하는 설계다.
- 현재 정본: `docs/redis/support-matrix.md`
<!-- 머리 블록 끝 -->
# Redis Wrapper 및 Typed API 설계서
- **상태:** 구현 기준선 확정
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 확인 안 함
- 작성일: 2026-08-08
- 요약: 외부 HTTP 호출의 대상, 연결 자원, 시간 예산, 재시도 증거를 다루는 HTTP client 플랫폼 설계다.
- 현재 정본: `docs/httpclient/support-matrix.md`
<!-- 머리 블록 끝 -->
# HTTP Client Platform 설계서
**문서 상태:** 구현 기준선 확정
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-10
- 요약: 메시지 생성부터 브로커 수락, 소비자 정산까지 증거로 다루는 메시징 플랫폼 설계다.
- 현재 정본: `docs/messaging/support-matrix.md`
<!-- 머리 블록 끝 -->
# Messaging Platform 설계서
- **상태:** 구현 승인용 기준 설계
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 확인 안 함
- 작성일: 2026-08-10
- 요약: 요청·수신자·시도 수명주기와 provider 결과를 다루는 알림 전달 플랫폼 설계다.
- 현재 정본: `docs/notification/support-matrix.md`
<!-- 머리 블록 끝 -->
# Notification Delivery Platform 설계서
> 상태: 구현 기준 설계(Implementation-ready)
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 확인 안 함
- 작성일: 2026-08-11
- 요약: JPA 관계형 영속성 플랫폼의 공개 계약, 모듈 경계, 트랜잭션 의미론을 정한 설계다.
- 현재 정본: `docs/jpa/repository-adaptation.md`
<!-- 머리 블록 끝 -->
# JPA 관계형 영속성 플랫폼 설계서
- 문서 상태: 구현 기준 설계
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 확인 안 함
- 작성일: 2026-08-11
- 요약: 도메인이 MongoDB 문서와 repository를 소유하게 하는 문서 영속성 플랫폼 설계다.
- 현재 정본: `docs/mongodb/repository-adaptation.md`
<!-- 머리 블록 끝 -->
# MongoDB 문서 영속성 플랫폼 설계서
- 문서 상태: 구현 기준 설계
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 확인 안 함
- 작성일: 2026-08-12
- 요약: SDL 계약이 인증·제한·실행·오류 계약을 거쳐 유스케이스에 닿게 하는 GraphQL 실행 플랫폼 설계다.
- 현재 정본: `src/adapter/inbound/graphql/README.md`
<!-- 머리 블록 끝 -->
# GraphQL API 실행 플랫폼 설계서
- **문서 상태:** 구현 기준선 확정
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 확인 안 함
- 작성일: 2026-08-15
- 요약: 다섯 어댑터를 한 bootJar에서 켜고 끌 수 있게 고치는 통합 리뷰와 개선 설계다.
- 현재 정본: `docs/capability-status.md`
<!-- 머리 블록 끝 -->
# 다섯 Adapter 최종 통합 리뷰 및 개선 설계
- 기준 일자: 2026-08-15
@@ -1,3 +1,12 @@
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 확인 안 함
- 작성일: 2026-08-30
- 요약: 타입 안전 gRPC 실행 플랫폼 계획을 이 저장소의 구조와 게이트에 맞춘 설계다.
- 현재 정본: `docs/compatibility/grpc-support-matrix.md`
<!-- 머리 블록 끝 -->
# 타입 안전 gRPC 실행 플랫폼 — 이 저장소 규약으로의 어댑팅 설계
두 계획 문서를 이 저장소(`ca-skeleton`)의 실제 구조·정책·빌드 게이트에 맞춰 실행 가능한 형태로

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