Merge branch 'main' into claude/r9-stale-names
pr / done (pull_request) Canceled after 0s

This commit is contained in:
2026-11-12 18:59:03 +00:00
14 changed files with 91 additions and 29 deletions
+2 -2
View File
@@ -184,8 +184,8 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것
## 문서 검사
`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여덟을 본다. PR마다 workflow `docs-check`가
돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이
`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여덟을 본다. PR마다 `pr.yml`의 `done` job이 `./gradlew :prCheck`
안의 `documentCheck`로 돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이
문서를 낡게 만든다.
| 검사 | 보는 것 |
+10 -10
View File
@@ -50,21 +50,21 @@
## 3. 경로 → 전문가
리드가 바뀐 경로로 렌즈를 고르는 표다. 지식 스킬의 `paths`와 맞춘다. `reviewer` 하나에는 렌즈 1~3개를 준다. 관점이 서로 다르고 볼 파일이 많으면 `reviewer`를 렌즈별로 나눠 띄운다.
리드가 바뀐 경로로 렌즈를 고르는 표다. 1열은 1차 렌즈 스킬의 `paths`를 그대로 옮긴 것이다(`scripts/tests/test_claude_setup.py`가 대조한다. 스킬의 `paths`를 바꾸면 이 표도 바꾼다). `reviewer` 하나에는 렌즈 1~3개를 준다. 관점이 서로 다르고 볼 파일이 많으면 `reviewer`를 렌즈별로 나눠 띄운다.
| 경로(glob) | 1차 렌즈 | 이럴 때 더한다 |
|---|---|---|
| `src/domain/core/**`, `src/application/*/**`, `src/shared-contract/**` | be-domain(판정은 `arch-reviewer`) | 오류 코드가 바뀜 → be-api-contract, 포트 계약이 바뀜 → be-testing |
| `src/adapter/outbound/persistence-*/**`, `**/db/migration/**` | be-persistence | 새 조회·인덱스 → be-performance, outbox·멱등성 행 → be-messaging, 응답·이벤트 필드로 드러남 → be-api-contract |
| `src/adapter/*/messaging*/**`, `src/bootstrap/{outbox-relay,idempotency,durable-operation}/**`, `**/outbox/**`, `**/idempotency/**`, `**/contracts/messaging/**` | be-messaging | 테이블·잠금 → be-persistence, schema version → be-api-contract, handler 권한 표시 → be-security |
| `src/adapter/outbound/persistence-*/**`, `**/db/migration/**`, `docs/jpa/**`, `docs/mongodb/**` | be-persistence | 새 조회·인덱스 → be-performance, outbox·멱등성 행 → be-messaging, 응답·이벤트 필드로 드러남 → be-api-contract |
| `src/adapter/*/messaging*/**`, `src/bootstrap/{outbox-relay,idempotency,durable-operation}/**`, `**/outbox/**`, `**/idempotency/**`, `**/contracts/messaging/**`, `src/application/core/src/main/java/dev/caskeleton/application/messaging/**` | be-messaging | 테이블·잠금 → be-persistence, schema version → be-api-contract, handler 권한 표시 → be-security |
| `src/adapter/inbound/**` | be-api-contract + be-security | 새 조회·목록 → be-performance, 로그·헤더 → be-observability |
| `src/bootstrap/app/**`, `**/security/**`, `**/authz/**`, `docs/registries/secrets-classification.yaml`, `docs/security/**` | be-security | env 키·공개 경로 → be-api-contract, `runtimeOnly` 줄·lockfile → be-build-ci |
| `docs/registries/{metrics,mdc-keys}.yaml`, `docs/observability/**`, `**/observability/**`, `**/observation/**`, `**/tracing/**`, `src/bootstrap/service-runtime/**` | be-observability | 로그·지표에 실리는 값 → be-security |
| `docs/registries/{error-codes,env-keys,headers}.yaml`, `docs/architecture/*-api-surface.txt`, `docs/web/**`, `**/*.graphqls` | be-api-contract | 공개 경로·헤더 → be-security, 계약 시험 → be-testing |
| `src/adapter/outbound/**`(위 둘 밖: httpclient, cache-redis, notification, fileserver 등), `**/*Performance*`, `**/jmh/**` | be-performance | 외부 호출 대상·자격 증명 → be-security, 결과 불명 → be-messaging |
| `build-logic/**`, `**/build.gradle`, `**/gradle.lockfile`, `gradle/**`, `config/**`, `.gitea/**`, `.github/**`, `scripts/**` | be-build-ci | 새 의존성·버전 → be-security, lane 안 테스트 → be-testing |
| `**/src/test/**`, `**/src/testFixtures/**`, `**/src/*Test/**` | be-testing | 계약이 약속하는 동작 → 그 분야 렌즈 |
| `docs/**/*.md`, `**/AGENTS.md`, `**/README.md`, `.claude/**/*.md` | be-docs | 문서가 설명하는 동작 → 그 분야 렌즈 |
| `src/bootstrap/app/**`, `**/security/**`, `**/authz/**`, `**/authorization/**`, `docs/registries/secrets-classification.yaml`, `docs/security/**`, `.env.example`, `.trivyignore.yaml`, `.github/dependency-vulnerability-policy.md` | be-security | env 키·공개 경로 → be-api-contract, `runtimeOnly` 줄·lockfile → be-build-ci |
| `docs/registries/{metrics,mdc-keys}.yaml`, `docs/observability/**`, `docs/runbooks/**`, `**/observability/**`, `**/observation/**`, `**/tracing/**`, `**/*Metrics*`, `**/logback-spring.xml`, `src/bootstrap/service-runtime/**` | be-observability | 로그·지표에 실리는 값 → be-security |
| `docs/registries/{error-codes,env-keys,headers}.yaml`, `docs/architecture/*-api-surface.txt`, `docs/web/**`, `docs/security/public-paths-snapshot.txt`, `docs/upgrade/**`, `.env.example`, `**/*.graphqls`, `**/contracts/messaging/**`, `**/released-payload-schemas.sha256` | be-api-contract | 공개 경로·헤더 → be-security, 계약 시험 → be-testing |
| `src/adapter/outbound/**`(위 둘 밖: httpclient, cache-redis, notification, fileserver 등), `**/*Performance*`, `**/*PerformanceTest/**`, `**/jmh/**`, `docs/httpclient/performance-baseline.md`, `docs/web/virtual-thread-profile.md` | be-performance | 외부 호출 대상·자격 증명 → be-security, 결과 불명 → be-messaging |
| `build-logic/**`, `**/build.gradle`, `settings.gradle`, `gradle/**`, `gradle.properties`, `**/gradle.lockfile`, `**/settings-gradle.lockfile`, `config/**`, `Dockerfile`, `.gitea/**`, `.github/**`, `scripts/**`, `renovate.json` | be-build-ci | 새 의존성·버전 → be-security, lane 안 테스트 → be-testing |
| `**/src/test/**`, `**/src/testFixtures/**`, `**/src/*Test/**`, `**/src/*Testkit/**`, `docs/testing/**`, `gradle/container-images.properties` | be-testing | 계약이 약속하는 동작 → 그 분야 렌즈 |
| `docs/**/*.md`, `**/AGENTS.md`, `**/README.md`, `**/CLAUDE.md`, `.claude/**/*.md` | be-docs | 문서가 설명하는 동작 → 그 분야 렌즈 |
## 4. 넘김 지도
+2 -2
View File
@@ -54,7 +54,7 @@ mkdir -p ~/<작업 이름>-logs
uptime # 다른 빌드가 돌고 있는지 부하를 본다
# 3) 공유 잠금 아래에서 한 번에 하나씩 돌리고 rc와 로그를 남긴다
cd ~/workspace/<작업 이름>/src
cd ~/workspace/<작업 이름>
flock /tmp/claude-gates/heavy.lock ./gradlew <게이트> --no-daemon --console=plain > ~/<작업 이름>-logs/<게이트>.log 2>&1; echo "rc=$?"
# 4) 끝나면 worktree를 지운다
@@ -84,7 +84,7 @@ git diff --cached --binary <기준 커밋> | ssh desktop 'cd ~/workspace/<작업
- 형식은 편집 훅이 파일마다 맞추므로 보통 바뀌는 것이 없다. 그래도 커밋을 나누기 전에 확인한다(나눈 뒤에 고치면 앞 커밋을 다시 만들어야 한다). 형식 맞추기(`spotlessApply`)도 Gradle이라 desktop에서 돈다. 패치를 얹은 worktree에서 돌리고, 바뀐 파일을 노트북에 가져와 두 트리 해시가 같은지 본다. 그 뒤의 게이트는 이 트리에서 돌린다.
```bash
ssh desktop 'cd ~/workspace/<작업 이름>/src && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --no-daemon --console=plain'
ssh desktop 'cd ~/workspace/<작업 이름> && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --no-daemon --console=plain'
ssh desktop 'cd ~/workspace/<작업 이름> && git diff --binary' | git apply --index && git write-tree # 노트북
ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' # 같은 해시여야 한다
```
+6 -4
View File
@@ -61,7 +61,7 @@
| 학습 문서(지난 것) | 삭제된 코드를 설명하는 학습 문서(지금 `docs/history/study/*.ko.md`, `docs/history/packages/*-superpowers-package/`)는 현재 코드에 맞게 갱신 → 2026-11-07 갱신하지 않고 기록으로 보관(머리 블록만 단다)으로 바뀜 | 소유자 | 2026-09-25 | 결정 6, design-docs `repo-structure/README.md` 3.2절 |
| 문서 체계 | 문서를 수명으로 나눈다. 살아 있는 문서는 제자리에 두고 한국어로 옮긴다. 기록은 `docs/history/`, 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`에 둔다. 폴더 이름은 짝 프론트와 같이 쓴다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절, 적용은 `docs/README.md` |
| 한국어의 범위 | 살아 있는 문서는 본문까지 한국어로 쓴다. 기록 문서는 맨 위에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달고 본문은 원문 그대로 둔다. 상태는 한국어 고정 어휘다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 |
| 문서 검사 | 언어·머리 블록·참조·숫자 검사를 PR에서 실패로 둔다(`scripts/check-docs.py`, workflow `docs-check`) | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절, `docs/README.md` 「문서 검사」 |
| 문서 검사 | 언어·머리 블록·참조·숫자 검사를 PR에서 실패로 둔다(`scripts/check-docs.py`, workflow `docs-check`) → 2026-11-08 workflow를 셋으로 접으며 `pr.yml` `done`의 `:prCheck` 안 `documentCheck`로 옮겼다(아래 2.7 「workflow 단계 job 모양」) | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절, `docs/README.md` 「문서 검사」 |
| 학습 문서 | `docs/history/study/`에 기록으로 보관한다. 코드에 맞춰 갱신하지 않고 머리 블록만 단다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 |
| 문서 규칙 정본 | design-docs `conventions/docs-system.md`(두 템플릿 공통). 이 repo의 적용은 `docs/README.md`에 적는다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 |
| 레지스트리 yaml 설명 칸 | 번역한다. 그 칸을 읽는 테스트를 먼저 찾는다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 |
@@ -190,13 +190,15 @@
| 의존성 checksum | 추가 안 함(보류) | 소유자 | 결정 19 |
| 취약점이 있는 의존성 버전 | 고친 버전으로 올리는 것이 먼저다. 고친 버전 중 가장 작은 것을 고르고, 짝으로 움직이는 라이브러리(httpclient5와 httpcore5, gRPC와 protobuf)는 upstream이 선언한 짝을 따른다. Boot BOM이 관리하면 Boot 패치를 먼저 보고, 없으면 BOM 속성 override(build-logic `JavaConventionsPlugin`, 이유와 지울 조건 옆). 어떤 leaf도 선언하지 않는데 upstream이 낡은 버전을 가져오면 카탈로그 `pinned-*`로 모든 구성에 고정한다. 무시 목록(`.trivyignore.yaml`)은 고친 버전이 없을 때만, 묻고 쓴다 | 기본값(2026-11-07) | `gradle/libs.versions.toml` 「Pinned」, 업그레이드 안내 `docs/upgrade/2026-11-maturity-review.md` B-54 |
| Querydsl 취약 좌표 | `com.querydsl:querydsl-jpa`(CVE-2024-49203, 고친 버전 없음)를 템플릿이 싣지 않는다. persistence-jpa는 쓰는 타입(`Predicate`)이 있는 querydsl-core로만 컴파일하고, querydsl-jpa는 capability를 켜는 서비스가 더한다. leaf README는 그 좌표에 고친 버전이 없다고 적고 OpenFeign 포크(`io.github.openfeign.querydsl`)를 검토하라고 한다 | 위임(2026-11-07, 총괄이 권한 안 A를 확인) | 커밋 「persistence-jpa가 querydsl-jpa 대신 querydsl-core로 컴파일한다」, `src/adapter/outbound/persistence-jpa/README.md` 「라이브러리 API」 |
| build-logic 의존성 잠금 | 잠그지 않음 + 문서화(보류) | 소유자 | 결정 27 |
| 릴리스 이미지 서명 | cosign keyless, tag 릴리스에서 서명·검증 | 소유자 | 결정 31 |
| build-logic 의존성 잠금 | ~~잠그지 않음 + 문서화(보류)~~ → 지금은 잠근다(`build-logic/build.gradle` `lockMode = LockMode.STRICT`, 2026-09-25 커밋부터). 바꾼 결정의 기록은 없다 | 소유자 | 결정 27 |
| 릴리스 이미지 서명 | ~~cosign keyless~~, tag 릴리스에서 서명·검증 → 2026-11-07 키 쌍으로 바꿈(아래 「릴리스 이미지 서명 키」) | 소유자 | 결정 31 |
| 릴리스 이미지 서명 키 | cosign 키 쌍으로 서명한다. Gitea Actions는 keyless 서명에 필요한 OIDC 토큰을 주지 않는다. 개인 키와 비밀번호는 repo secret이다 | 소유자(2026-11-07) | `docs/work/operate.md` 4.3절, `.gitea/workflows/release.yml` |
| gRPC `.proto` | protobuf Gradle 플러그인 + Buf. 2026-11-08부터 `grpc-library` repo의 `ci` 단계 | 소유자 | 결정 18 |
| SpotBugs 신뢰도 | MEDIUM으로 내림. 패턴 단위 제외는 이유를 단다 | 위임 | `1101` 15절(08-07) |
| 테스트 코드 정적 분석 | `testQualityCheck`는 `mainCheck` | 위임 | `1103` 14절 |
| lane 정책과 캐시 | lane 정책 값(`rejectSkipped` 등)은 모두 캐시 입력 | 위임 | `1103` 4절(RR-06-02) |
| workflow 명령의 빌드 판정 | 같은 셸의 `cd <상대 경로>`도 따라간다 | 소유자 | `1103` 15절 ② |
| workflow 명령의 빌드 판정 | ~~같은 셸의 `cd <상대 경로>`도 따라간다~~ → 2026-11-08 셸을 해석하지 않게 바꿈(아래 「workflow 단계 job 모양」) | 소유자 | `1103` 15절 ② |
| workflow 단계 job 모양 | workflow는 `pr.yml`·`main.yml`·`release.yml` 셋이다. 단계 job의 `run:`은 셸 문법 없는 `./gradlew` 한 줄이나 `bash scripts/<이름>.sh` 한 줄이고, `verifyStrictLaneStages`는 셸을 해석하지 않고 이 고정 형식만 본다 | 소유자(2026-11-08) | design-docs `repo-structure/03-ci.md` 7·11절, `build-logic/AGENTS.md`, `StrictLaneStagesPlugin` Javadoc |
| 성능 lane 단언 | 끄는 스위치 없음. convention이 `performance.assertions.enabled=true`를 넣고, 빌드·lane이 다른 값을 주거나 skip이 있으면 테스트 전에 실패. 손으로 돌리든 workflow든 같은 상한 | 소유자(2026-11-06 병합 승인) | design-docs `delegation-loop/02-design.md` 13절 D9, 커밋 `e6b6e18e`, `build-logic/AGENTS.md` 「lane 캐시와 성능 lane」 |
| 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `build-logic/AGENTS.md` 「저장소 파일을 읽는 테스트」 |
| MinIO 이미지 | `pgsty/minio` digest | 위임 | `1101` 15절(05-09) |
+2 -2
View File
@@ -16,10 +16,10 @@
## 2. 라이브러리를 고칠 때
- 템플릿 안에서 라이브러리 코드를 고치지 않는다. 라이브러리 repo에서 고치고 릴리스한다.
- 템플릿 변경 때문에 라이브러리를 고쳐야 하면 두 repo에 브랜치를 하나씩 만들고, 두 repo를 같은 부모 폴더에 둔다(desktop은 `~/workspace/`). 템플릿에서 명령 줄로만 라이브러리를 끼워 같이 시험한다(composite build: Gradle이 같은 `group:artifact`의 외부 의존성을 끼운 빌드의 프로젝트로 바꿔 끼운다). Gradle 루트가 `src/`라 경로는 두 단계 위다.
- 템플릿 변경 때문에 라이브러리를 고쳐야 하면 두 repo에 브랜치를 하나씩 만들고, 두 repo를 같은 부모 폴더에 둔다(desktop은 `~/workspace/`). 템플릿에서 명령 줄로만 라이브러리를 끼워 같이 시험한다(composite build: Gradle이 같은 `group:artifact`의 외부 의존성을 끼운 빌드의 프로젝트로 바꿔 끼운다). Gradle 루트가 저장소 루트라 경로는 한 단계 위다.
```bash
./gradlew --include-build ../../messaging-library <태스크>
./gradlew --include-build ../messaging-library <태스크>
```
그 상태로 lockfile을 쓰거나 커밋하지 않는다. 끼운 모듈은 lockfile 밖으로 빠질 수 있다. 끼운 빌드는 자기 카탈로그로 컴파일되므로 라이브러리 repo CI 결과와 다를 수 있다. 최종 판정은 배포한 좌표로 돈 템플릿 게이트다.