main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
ContractRegistrySchemaGovernanceTest(모든 레지스트리 행에 legal
compatibility_impact + non-blank required_test 강제)는 @Tag(document-contract)
라 main 스테이지에서만 돈다. PR 레인은 repository-contract이고 그 입력에
docs/**가 빠져 있어, 잘못된 env-keys가 prCheck를 통과하고 병합 뒤 mainCheck
에서야 깨졌다(BE-CONFIG-001이 그렇게 새어 나갔다). 또 필드가 아예 빠지면
Set.of(...).contains(null)이 NPE를 던져 어느 행이 문제인지 알 수 없었다.
- RegistrySchemaPullRequestGateTest(@Tag repository-contract): 같은
RegistryGovernanceCatalog.validate를 PR 레인에서 돌려 위반이 병합 전에
막히게 한다.
- app build.gradle repositoryContractInputs에 docs/registries/**를 더해
레지스트리가 바뀌면 PR 레인이 재실행된다.
- RegistryGovernanceCatalog: compatibility_impact가 null이면 "... must be one
of [...], but was null"로 또렷이 실패한다(NPE 대신). 누락-필드 음성 사례를
ContractRegistrySchemaGovernanceTest에 더했다.
- ManagementActuatorSecurityContractTest javadoc에
actuator-contract:management-address-loopback 항목을 더해 열거를 맞춘다.
버린 대안: required_test가 실제 시험을 가리키는지 범용 강제는 안 넣었다 —
env-keys의 distinct required_test 193개 중 테스트 소스에 literal로 있는 건
7개뿐이라(나머지는 문서적 식별자), 범용 강제는 기존 186행을 깨뜨린다.
위험·한계: PR 레인이 docs/registries 변경에도 재실행된다(의도).
검증(desktop, 고친 env-keys): spotlessCheck·verifyEnvKeys·build-logic test·
documentContractTest·repositoryContractTest(새 게이트)·
ManagementActuatorSecurityContractTest·web-fileserver·web-advanced 모두 rc=0.
RED 재현: 고치기 전 새 게이트가 "env-keys.yaml row MANAGEMENT_SERVER_PORT
compatibility_impact must be one of [...], but was null"로 실패.
env-keys.yaml에서 MANAGEMENT_SERVER_ADDRESS를 MANAGEMENT_SERVER_PORT 항목
중간에 끼워 넣어, PORT의 compatibility_impact와 required_test
(actuator-contract:management-port-separated) 두 줄이 ADDRESS로 넘어갔다.
PORT는 두 칸을 잃어 스키마상 불완전해졌고, ADDRESS의 required_test는 제
시험이 아니라 포트 분리 시험을 가리켰다.
PORT에 두 줄을 되돌리고, ADDRESS의 required_test를
actuator-contract:management-address-loopback로 바꾼다. 이 id는
ManagementActuatorSecurityContractTest의 loopback 기본값 시험 마커로 이미
존재한다(실제 시험을 가리킨다). validation: host_or_ip_address는 env-keys의
자유 서술 규약에 맞는 신규 서술자다(닫힌 집합 강제 없음).
위험·한계: 데이터 수정만. 동작 변화 없음.
검증(desktop): :app-bootstrap:verifyEnvKeys rc=0,
documentContractTest(ContractRegistrySchemaGovernanceTest) rc=0.
문제: 실제 세션 평가(구현 과제 3번)에서 `be-persistence`는 세 번 모두 스킬 목록에
떴지만 부른 세션은 한 번뿐이었다. 나머지 둘은 관련 문서를 직접 읽고 스킬을 건너뛰었다.
규칙은 "어느 스킬인지는 experts.md 3절 표"라고만 해서 한 번 더 읽어야 짝을 알았다.
고른 방법: 규칙에 고칠 것 → 스킬 짝을 한 줄로 적고, 처음 Edit·Write하기 전에 Skill
도구로 부르며 문서를 읽었어도 부른다고 적었다. 버린 대안: 모듈마다 leaf AGENTS.md에
한 줄 더하기(파일 수십 개, 배치 검사와 겹침), 강조어(MUST 등, 과다 호출을 부른다).
위험: 규칙이 붙는 세션마다 약 300토큰이 는다. 여러 분야를 부르면 호출이 는다.
검증: python3 -m unittest discover -s scripts/tests 154건 통과, scripts/verify.sh docs rc=0.
PR #12의 액추에이터·fileserver·web-advanced 수정 커밋이 긴 주석과
assertion 메시지에 포맷 드리프트를 남겨, runner pr / gradle의
:app-bootstrap:spotlessJavaCheck가 깨졌다. 모듈 시험만 돌리고 포맷
게이트(spotlessCheck)를 건너뛴 탓이다.
./gradlew spotlessApply로 바뀐 3개 파일만 재포맷했다. 이미 push된
커밋이라 force push 금지 → squash 대신 새 커밋으로 올린다.
위험·한계: 포맷만 바뀐다(긴 줄의 줄바꿈). 동작·의미 변화 없음.
검증: spotlessCheck rc=0. 바뀐 3개 모듈 시험 재실행 —
ManagementActuatorSecurityContractTest·FileserverAdminControllerRequestBodyValidationTest·WebCodecMapperTest
BUILD SUCCESSFUL (1m8s).
W4 red team BE-OBS-A 소유자 결정(2026-11-12): 요청 빈도 제한은 앱 기본 off로 두고
ingress/gateway 책임으로 명시한다. 앱은 크기/양 bound는 이미 강제하고, 빠진 축은
요청 빈도 하나이며 그것은 앞단이 서비스 전체 기준으로 보는 게 맞다.
docs/security/rate-limiting.md에 자세(기본 off·ingress 책임)와 앞단에서 안 거는
배포를 위한 앱 내 redis limiter 켜는 법(모듈·env·client-ip 주의)을 적는다. 운영
매뉴얼(docs/work/operate.md 파생 서비스 절)과 PR 체크리스트(docs/manual/
11-checklist.md inbound)에서 가리켜, 파생 서비스가 릴리스 전에 "요청률을 어디서
거는가"를 정하게 한다.
동작/코드 변경 없음(문서만).
공격 표면 목록·ASVS L2/API Top 10 행렬·정적/수동/동적 결과와 발견 3건
(BE-CONFIG-001 고침·BE-INPUT-002 고침·BE-INPUT-001 by-design 재분류)을
기록한다. 소유자 결정 칸에 BE-OBS-A(요청률 제한 기본 off)를 올린다.
red team 리뷰가 WebXmlMapperFactory를 WebCborMapperFactory의 scalar-coercion
잠금(withCoercionConfig String->Fail, Textual Integer->Fail)을 빠뜨린 것으로 보고
표현별 엄격성 불일치를 의심했다. 실제로는 by-design이다: XML은 textual 포맷이라
숫자·불리언 DTO 필드도 전부 String 토큰(<count>5</count>)으로 들어온다. 거기서
String 입력을 막으면 모든 숫자/불리언 바인딩이 깨지고, WebCodecMapperTest의
xmlRoundTripPreservesWireTypes(int count를 바인딩)가 바로 그걸 고정한다. CBOR과의
엄격성 차이는 검증 우회가 아니다 — FAIL_ON_UNKNOWN_PROPERTIES와 SecureXmlInputFactory
하드닝은 여기에도 적용되고, @Valid 제약은 바인딩 뒤 모든 표현에 돈다.
순진한 "parity fix"가 멀쩡한 XML 바인딩을 깨뜨리지 않도록, 왜 CoercionConfig를
두지 않는지 주석으로 못 박는다(동작 변경 없음).
검증: :adapter:inbound:web-advanced:test --tests '*WebCodecMapperTest*' rc=0(무회귀).
web-fileserver admin 평면에서 orphans:reconcile만 @RequestBody에 @Valid가 없었다.
다른 다섯 핸들러(relocate·force-delete·submit-notification 등)는 모두 @Valid다.
지금은 OrphanReconcileHttpRequest에 Bean Validation 제약이 없어 드러나지 않지만,
나중에 limit에 @Min, reason에 @NotBlank를 더하면 @Valid가 없어 조용히 무시된다 —
이 템플릿이 평소 막는 검증 우회 부류다.
reconcileOrphans 파라미터에 @Valid를 더하고, 이 컨트롤러의 모든 @RequestBody가
@Valid를 갖는지 반사로 확인하는 막는 시험을 더해 admin 평면 전체에 규약을 고정한다.
검증: RED→GREEN — @Valid를 빼면 FileserverAdminControllerRequestBodyValidationTest
가 실패(rc=1, 그 파일 41행 AssertionError: offenders 비지 않음), 넣으면
:adapter:inbound:web-fileserver:test rc=0.
`management.server.address`가 비어 있어 Spring이 관리 커넥터를 모든 인터페이스
(0.0.0.0)에 바인딩했다. 별도 포트는 별도 네트워크가 아니다. 그 포트의
health·prometheus·info는 permitAll이고 actuator 체인에 인증 메커니즘이 없어,
파드/호스트 네트워크의 누구에게나 무인증으로 응답한다.
동적으로 확인했다(bootRunH2): `ss`가 `*:9001`, `curl :9001/actuator/health·info·
prometheus`=200. info는 build group/artifact/version·capabilities를, prometheus는
disk 경로·free/total·JVM·timing을 유출한다(API 표면·인프라 토폴로지). compose의
`127.0.0.1:9001` publish는 Docker 호스트만 막고 같은 compose 네트워크의 형제
컨테이너나 NetworkPolicy 없는 k8s/bare 배포는 막지 못한다. 선행 리뷰(07-13)는
compose publish만 확인했고 앱의 bind 주소는 보지 않았다.
observability.yml에 `management.server.address: ${MANAGEMENT_SERVER_ADDRESS:
127.0.0.1}`를 둬서 posture가 compose·NetworkPolicy에 의존하지 않고 앱 자체에서
loopback으로 닫히게 한다. 원격 스크레이프 배포는 그 env를 명시하거나 loopback
사이드카로 긁는다. 노출 allowlist는 그대로다.
버린 대안:
- 하드코딩 `127.0.0.1` → operator override 불가, env-driven 관례 위반.
- compose/NetworkPolicy에만 의존 → 앱 밖 설정에 보안 posture를 맡김(이 발견의 원인).
검증: 막는 계약 시험 `actuator-contract:management-address-loopback`를 더했다.
desktop에서 RED→GREEN 확인 — address 줄을 빼면 그 시험이 실패(rc=1,
ManagementActuatorSecurityContractTest.java:239 AssertionError), 넣으면
`:app-bootstrap:test` rc=0. build-logic `EnvContractVerifierTest` rc=0(env-keys와
설정 정합).
main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
문제: 하네스에 분야 지식이 없다. 영속성·메시징·보안·관측·성능·API 계약·
빌드·시험·문서·도메인의 이 repo 규칙(적용된 마이그레이션 금지, 잠금 상한,
동시 인덱스 빌드, env 키 레지스트리 등)은 문서에 흩어져 있어, 세션이 그
문서를 찾아 읽어야만 지킨다. 여러 분야에 걸친 일을 누가 보고 어떻게
합치는지도 정한 곳이 없다.
고른 방법(소유자 결정 2026-11-11 「W3 설계대로」):
- 지식 스킬 be-* 10개(.claude/skills/). 각자 paths를 걸어 그 분야 파일을
만질 때만 목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 →
검증 → 이 repo에서 정한 것 순서이고, 정본 문서를 가리킨다. 초안은 이
repo 문서만 본 서브에이전트가 썼고, 경로는 relayout 배치에 맞췄다.
- 서브에이전트 reviewer(렌즈 = brief의 스킬 경로). arch-reviewer는
be-domain을 미리 싣고 lead 공통 양식으로 돌려준다.
- .claude/rules/expert-skills.md: 분야 파일을 고치기 전에 그 스킬의
「함정」·「검증」을 보게 하는 두 줄(평가에서 스킬 호출이 5번 중 2번이었다).
- docs/work/experts.md: 명단·경로 → 렌즈·넘김 지도·충돌·비용. 루트
AGENTS.md 한 줄, CLAUDE.md 두 줄 고침(10줄 상한 유지), README 3절 4단계와
delegate.md 4.3절에 가리키는 말.
- 시험: 에이전트 넷, Agent 도구 금지, 설명 합 1,200자, 지식 스킬의 paths·
설명 300자·금지어·절 순서·150줄, 모든 paths glob이 추적 파일에 걸림,
명단이 모든 전문가를 담음.
버린 대안: 분야마다 서브에이전트. Anthropic 2026-10-22·2026-01-23·2026-04-07
글이 반대하고, 설명이 모든 세션에 든다.
위험: 플러그인 lead·new-expert·harness-eval은 claude-harness PR #3(0.3.0)이
병합돼야 받는다. 그전에는 lead를 가리키는 문장이 설명만 남는다.
검증: python3 -m unittest discover -s scripts/tests → 154건 통과. 새 시험 6개는
조건을 깰 때마다 실패했다. scripts/verify.sh docs → rc=0.
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.
고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
:composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
(getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
src/를 붙인다. notification API surface의 application-notification 소스
루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
docs/upgrade/2026-11-relayout.md를 더한다.
위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.
검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.
BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
문제: Gradle 루트가 src/라서 빌드 도구(build-logic, gradle, config, 빌드
파일)가 계층 코드 폴더 옆에 섞여 있다. composition과 app-bootstrap은 같은
조립 계층인데 폴더가 따로이고, application 모듈 넷은 최상위에 흩어져 있다.
「Gradle은 src/에서 실행」이라는 예외 규칙이 모든 문서와 스크립트에 퍼졌다.
고른 방법: 저장소 루트를 Gradle 루트로 하고 src/에는 계층 코드만 둔다
(design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3, 소유자
승인 2026-11-07). 이 커밋은 git mv만 한다. 이름 바꾸기 감지가 1541개
파일 모두를 R100으로 잡도록 내용을 바꾸지 않았다. 바뀐 곳은 둘뿐이다:
src/.gitignore의 줄을 루트 .gitignore로 옮겼다.
- 빌드 파일, gradle/, build-logic/ → 저장소 루트
- config/checkstyle·spotbugs → config/ (코드 검사 도구 설정만)
- registry config/architecture/modules.json → gradle/modules.json,
시험 이미지 config/testing/container-images.properties
→ gradle/container-images.properties, registry 설명 → gradle/README.md
- Dockerfile, .dockerignore, .env*.example → 저장소 루트
- src/README.md(빌드·env 참조) → docs/build.md
- src/domain-core → src/domain/core,
src/application-* → src/application/*,
src/app-bootstrap → src/bootstrap/app,
src/composition/* → src/bootstrap/*
- 기능 생성 템플릿 scripts/feature-scaffold/{templates,probes}/src/ 아래도
같은 모양으로(domain/core, application/core, bootstrap/app)
위험: 이 커밋만으로는 빌드되지 않는다. 경로를 부르는 곳은 다음 커밋이
고친다. 두 커밋을 나눈 것은 파생 서비스가 merge할 때 이름 바꾸기와 내용
변경을 따로 보게 하려는 것이다.
검증: git diff --cached -M --name-status 에서 R100 1541개, 그 밖은
.gitignore 수정과 src/.gitignore 삭제뿐.
BREAKING CHANGE: 모든 빌드 파일과 계층 폴더의 경로가 바뀐다. 옛 경로 →
새 경로 표와 받는 순서는 docs/upgrade/2026-11-relayout.md에 있다.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절
main / jpa-next (hibernate-8, Hibernate 8 is not resolvable from this build, so nothing has been compiled or run against it, Hibernate 8, *Hibernate8CompatibilityTest) (push) Skipped
main / jpa-next (jakarta-persistence-4, the JPA 4 API is not on any configuration this build resolves, so nothing has been compiled against it, Jakarta Persistence 4, *Jpa4CompatibilityTest) (push) Skipped
main / jpa-next (postgresql-19, no PostgreSQL 19 image is published yet, so no container of that major has ever been started by this lane, PostgreSQL 19, *PostgreSql19CompatibilityTest) (push) Skipped
b0bca2a6이 단 주석 한 줄이 100칸을 넘어 spotlessJavaCheck가 PR #7의
pr.yml(run 61)을 막았다. 같은 뜻으로 줄을 다시 나눈다.
검증: desktop :adapter:inbound:websocket:spotlessJavaCheck와 check 통과.
t2a-backend-ci의 착수 예측(p30·p50·p80)과 실측(작업 중 132분, 호출 374,
출력 37.5만, 벽시계 849분)을 더한다. 하네스 회고(claude-harness
docs/retro/2026-11-08.md 7절)가 정한 retro 줄 셋(h3·x2·x3)을 ledger.py
append로 더한다. 이미 있던 줄은 고치지 않았다.
redis-topology.sh는 job 컨테이너의 기본 게이트웨이(=Docker 데몬 호스트)를
/proc/net/route에서 awk로 읽었다. awk는 "0x.." 문자열을 0으로 읽어 주소가
0.0.0.0이 됐고, 포워더가 자기 자신에게 이어 붙어 "Too many open files"로
main.yml 수동 실행(run 52)의 redis-topology 11행이 모두 실패했다.
python3로 little-endian 16진수를 바르게 바꾸고, 주소가 없거나 0.0.0.0이면
그 자리에서 실패한다.
검증: 노트북에서 같은 계산이 기본 게이트웨이를 낸다. runner 재실행은
다음 main.yml 수동 실행에서.
websocketNginxTest의 Nginx 컨테이너는 host.docker.internal을
host-gateway(Docker 호스트)로 풀어 시험 JVM의 앱에 붙었다. desktop에서는
Docker 호스트가 곧 JVM의 호스트라 됐지만, Gitea runner처럼 job이 자기
컨테이너 안에서 돌면 앱은 거기 없다. release 수동 실행(run 51)의
websocket-stable-release-gate가 upgrade마다 DeploymentException으로
실패했다.
Testcontainers의 호스트 포트 노출(exposeHostPorts, withAccessToHost)로
host.testcontainers.internal을 이 JVM으로 잇는다. 두 환경에서 같은
이름이다. 버린 것: runner 설정을 host 네트워크로 바꾸기(platform-core 몫,
job 격리를 푼다).
위험: Testcontainers가 sshd 보조 컨테이너를 하나 더 띄운다(이미지는
Testcontainers가 고정한 것, container-images.properties 밖).
검증: desktop에서 :adapter:inbound:websocket:websocketNginxTest.
하네스 설계(design-docs harness/01-harness-design.md)는 검증 진입점
scripts/verify.sh와 비전 문서 docs/vision.md가 함께 생긴다고 했다.
verify.sh는 이 브랜치가 만들었는데 비전과 문제 정의 자리가 없었다.
claude-harness template/docs의 두 양식을 옮긴다. vision.md는 세 문장
자리만 두고 소유자가 쓴다(에이전트는 읽기만 한다). problem-statement.md는
고객의 말 그대로·지금 버티는 법·하지 않는 것·잴 수 있는 성공 기준 칸을
둔다. AGENTS.md 첫 문단과 docs/README.md 「폴더 밖 문서」가 두 파일을
가리킨다.
검증: python3 scripts/check-docs.py, check-work-docs.py 통과.
메시징 플랫폼 분리(PR #8)를 받는다. 충돌 둘: 옛 integration-main.yml은
이 브랜치가 지웠으므로 삭제를 둔다(메시징 측정 주석은 main.yml에 옮길
측정 수치가 없어 버린다). 업그레이드 안내는 메시징 절을 3.9(B-57~B-59)로
두고 CI 절을 3.10(B-60~B-66)으로 미룬다.
release.yml이 태그에서 이미지를 올리고 서명하려면 repo secret
PACKAGE_TOKEN·COSIGN_PRIVATE_KEY·COSIGN_PASSWORD가 필요하다. 이름만
있고 만드는 법이 없어 소유자가 첫 릴리스 전에 찾아야 했다.
operate.md 4.3절에 각 값의 출처(개인 access token의 package 범위,
cosign generate-key-pair의 cosign.key와 비밀번호)와 공개 키를 어디에
주는지 적는다.
검증: python3 scripts/check-docs.py, check-work-docs.py 통과.
workflow 15개(+ composite action, jq 설치 스크립트)가 모듈 모양으로
나뉘어 있었고, 그것을 읽는 판독기(ShellScript·WorkflowGradleInvocations·
TaskSelectors, 운영 3,283줄과 그 시험 1,814줄)가 리뷰 라운드마다 새 셸
모양으로 결함을 냈다. 그런데 Gitea에서는 Actions가 꺼져 있어 workflow는
한 번도 돌지 않았다(design-docs repo-structure/03-ci.md 2.1·3.4절).
소유자가 정한 B안(같은 문서 7절, 11절 ①~⑧)대로 바꾼다.
- .gitea/workflows/pr.yml: `gradle` job이 `./gradlew :prCheck`와
`./gradlew :verifyStrictLaneStages --dry-run` 두 줄, `vulnerabilities`
(trivy), 필수 검사 하나 `done`.
- main.yml: push마다 mainCheck·integrationCheck·build-logic 시험·
configuration cache·lychee·trivy·http3(권고). nightly·수동 실행에서
PostgreSQL major·HTTP transport·Redis topology 행렬, NFS, 알림 chaos,
jpa-next, compose smoke, 마지막에 `needs`로 performanceCheck.
- release.yml: releaseCheck와 기존 release lane, 이미지를 이 Gitea
레지스트리에 올리고 cosign 키 쌍으로 서명한다. 수동 실행은 push·서명
앞까지 돈다. upload/download-artifact를 쓰지 않는다. JPA 승격은
`needs: jpa-release-gate`가 대신한다.
- 새 집계 `prCheck` = ci + verifyDependencyLocks + compose 렌더링 +
저장소 배치 + 문서 검사(Exec). workflow와 verify.sh가 같은 한 줄을 쓴다.
- verifyStrictLaneStages: 그래프 검사(모든 strict lane이 선언한 단계의
계획에 있다)는 그대로 두고, workflow 쪽은 고정 문자열 형식 검사로
바꾼다. 단계마다 workflow·이벤트·필터·job·옵션·조건을 build.gradle에
선언하고, 그 job의 step이 `run: ./gradlew <단계> <옵션>`을 가지며 다른
run도 셸 문법 없는 ./gradlew 한 줄이고, 선언 밖의 if:, 조건 없는
needs:, continue-on-error·shell:·defaults:, 따옴표 키·flow 형식, 다른
working-directory, 선언 밖의 이벤트 필터가 없는지 본다. PR 단계 job
하나는 이 검사 자신을 돌려야 한다. 셸 해석 코드와 그 시험을 지운다
(build-logic 운영 코드 −3,167줄, 시험 −2,231줄). 우회 입력 21가지를
TestKit 시험으로 둔다.
- scripts/verify.sh <단계>: 사람·세션의 진입점. 무거운 단계는 지금 작업
트리를 패치로 desktop에 보내 잠금 아래에서 돌린다(operate.md 4.1절의
손 절차). scripts/ci/는 workflow가 부르는 trivy·Redis topology·포트
포워더·configuration cache 스크립트다.
- workflow를 읽는 시험(DeveloperExperienceContractTest, JpaRelease
RenderingTest, FileserverDocumentationCoverageTest)과 입력 선언을
.gitea로 옮기고, keyless 서명 시험을 키 쌍 서명 시험으로 바꾼다.
- 문서: gates.md·operate.md·docs/ci-cd·AGENTS.md(검증 절)·build-logic
AGENTS.md(셸 규칙 문단을 세 줄로)·leaf 문서의 workflow 참조,
docs/upgrade B-57~B-61.
버린 것: workflow 하나에 if:로 단계를 나누기(파일만 보고 단계를 알 수
없다), 레지스트리에서 생성(같은 정보의 셋째 사본), 바뀐 모듈만 돌리기
(결정 30과 충돌). 판독기를 남기고 고치기는 6라운드 13건이 반증했다.
위험: PR이 어댑터 컨테이너 lane과 Redis standalone lane을 더는 막지
않는다(main·nightly에서 빨갛게 된다. 소유자 결정 ②). main push는 ci를
다시 돌리지 않는다. 성능 lane은 매 push가 아니라 nightly에서만 돈다.
`.github/workflows/messaging-certification.yml`은 메시징 분리 작업이
지우므로 남겼다(.gitea가 있으면 Gitea가 읽지 않는다). 서명·push는 secret이
없어 실제 태그로는 돌려 보지 않았다.
BREAKING CHANGE: workflow 파일 위치와 이름, strictLaneStages 문법,
릴리스 레지스트리·서명 방식이 바뀌었다. docs/upgrade/2026-11-maturity-
review.md B-57~B-61을 따른다.
NotificationReleaseGateTest(알림 leaf의 `test`)는 docs/notification의
문서와 docs/adr의 NOTIF-ADR 넷이 있는지 본다. 그 파일들이 test 태스크의
입력이 아니어서, ADR을 옮기거나 지워도 Gradle이 태스크를 up-to-date나
캐시로 끝내고 시험이 다시 돌지 않았다. 지운 notification-platform.yml의
경로 필터가 docs/adr/로 옮긴 ADR을 못 보던 것과 같은 빈틈이다.
두 경로를 test의 입력으로 선언한다. 이 시험은 `ci` → `prCheck` 안에서
경로 필터 없이 매 PR 돈다(--dry-run 계획으로 확인).
검증: desktop PR 단계.
dev lane overlay(src/app-bootstrap/compose-lanes/dev.yaml)가 heap dump
폴더를 bind mount `./tmp/heap-dumps`로 두었다. Docker가 그 폴더를 root
소유로 만들어, compose lane을 돌린 git worktree를 일반 사용자가 지우지
못했다(`git worktree remove`가 Permission denied). 그래서 operate.md
4.1절에 컨테이너로 폴더를 지우는 우회 문장이 있었다.
named volume `heap-dumps`로 바꾼다. dump는 컨테이너가 사라져도 남고,
`docker compose cp`로 꺼낸다. 우회 문장을 지운다.
버린 것: bind mount에 사용자 uid를 맞추기(이미지·환경마다 다르다).
검증: desktop PR 단계(`verifyComposeProfiles`가 렌더링된 모델의 mount
대상 중복을 본다)와 nightly compose smoke.
앞 커밋이 메시징 플랫폼을 지웠지만 살아 있는 문서는 아직 src/platforms
경로와 docs/messaging/을 부른다. 기록 8개의 머리 블록 「현재 정본」도
지운 docs/messaging/support-matrix.md를 가리킨다.
- docs/messaging/(10개)을 지운다. 같은 이름의 파일이 이력째
messaging-library에 있다. 이 repo에서 그 내용을 부르던 문서(manual 09,
messaging-kafka README·AGENTS)는 그 repo 파일로 링크한다.
- 기록(설계서 3, 계획서 3, 납품 패키지 2): 본문은 두고 머리 블록만
고쳤다. 플랫폼을 다룬 것은 「없음 — messaging-library로 옮겼다」, 앱
쪽 발행·소비를 다룬 것은 docs/manual/09-outbox-events.md.
- docs/work/reference/related-repos.md: 관련 저장소 표(메시징 줄 채움),
라이브러리를 고치는 법, 템플릿에서 버전 올리는 법, 같이 고칠 때
composite build(Gradle 루트가 src/라 ../../messaging-library), registry
라이브러리 칸. 설계 14절이 근거다.
- src/config/architecture/README.md: library_groups·allowed_libraries 설명.
- docs/upgrade/2026-11-maturity-review.md 3.9절: B-57(지운 것), B-58(받는
법·패키지·auto-config 이름), B-59(registry 칸).
- 진입 문서와 지역 지침(AGENTS.md, README.md, delegate, decisions,
review-criteria, defect-patterns, gates, capability-status, manual 07,
build-logic·persistence-jpa·inbound messaging·shared-contract 지침,
env-keys 주석)에서 「들여온 제품」·src/platforms 문장을 별도 repo
라이브러리 문장으로 바꿨다.
위험: 다른 repo 파일을 가리키는 링크는 lychee가 외부 URL로 본다(공개
repo라 익명으로 읽힌다).
검증: python3 scripts/check-docs.py OK, check-work-docs.py OK(상대 링크
깨짐 0), check-repo-layout.py OK, python3 -m unittest discover -s
scripts/tests OK.
BREAKING CHANGE: docs/messaging/이 없어졌다. 메시징 문서는
messaging-library repo의 docs/messaging/에 있다.
Refs: design-docs repo-structure/05-library-repos.md 4.3·14절
템플릿 안에 프로젝트 계층이 아닌 메시징 플랫폼(src/platforms/messaging,
19개 모듈)이 있다. 소유자 결정(2026-11-07)은 라이브러리를 별도 repo에서
관리하고 템플릿은 버전으로 받는 것이다. 라이브러리는 이력째
messaging-library로 옮겨 dev.cakit.messaging 1.0.0으로 Gitea Packages에
게시했다(태그 v1.0.0 = 8c6045e, release run 28).
- 받는 법: src/settings.gradle에 exclusiveContent 저장소(group dev.cakit와
그 아래는 Gitea에서만, 나머지는 Maven Central에서만). 카탈로그
messagingLibrary = "1.0.0"과 쓰는 모듈 여섯.
- 쓰는 leaf: adapter:outbound:messaging, adapter:outbound:messaging-kafka,
adapter:inbound:messaging(admin exclude 좌표를 새 group으로), 시험만
composition:outbox-relay와 app-bootstrap architectureTest. import와
auto-configuration 이름 문자열 dev.caskeleton.messaging →
dev.cakit.messaging, 시험 stand-in도 같은 FQCN으로.
- persistence-jpa migration 시험이 라이브러리 소스 폴더를 경로
(../../../platforms/…)로 읽던 것을, 카탈로그 버전의 jar를 전용 구성
messagingMigrations(non-transitive)로 받아 db/migration을 풀어 읽게
했다. classpath에 올리면 그 leaf 시험의 Flyway가 메시징 migration까지
볼 수 있어 버렸다.
- registry: 메시징 19행을 지우고 library_groups ["dev.cakit"]와 쓰는 세
행의 allowed_libraries. 분리 전 프로젝트 edge 검사가 지키던 약속이
앞 커밋의 라이브러리 edge 검사로 그대로 남는다.
- 계약 테스트: MessagingPublicSurfaceContractTest는 라이브러리로 옮겼고,
MessagingAuthorityContractTest는 이 repo의 app.messaging 주인 하나만
본다(라이브러리 쪽 하나는 그 repo가 본다).
- system caller 규칙(ApplicationBoundaryArchitectureTest)의 「프로젝트
타입」에 dev.cakit.을 더했다. 메시지 handler가 구현하는 MessageHandler가
라이브러리 타입이 되면서, 그대로 두면 manual 09의 handler가
SYSTEM_CALLERS_HAVE_ONLY_PROJECT_SUPERTYPES에 걸리고 MessageHandler로
주입받는 endpoint를 USER_TRANSPORTS_DO_NOT_REACH_SYSTEM_CALLERS가
따라가지 못한다(구조 리뷰가 찾음).
- 순서 시험: 이름 정렬로도 라이브러리 root가 먼저 오게 되어 bridge 시험이
afterName을 지키지 못했다. stand-in을 맨 뒤 순서로 두고, inbox 쪽
beforeName을 지키는 시험을 더했다.
- 지움: src/platforms(와 빈 폴더), messaging-certification.yml, 카탈로그의
avro·cloudevents·protobuf 4.33.2, SpotBugs 제외의 메시징 줄,
check-repo-layout.py의 platforms. 편집 훅이 계층 leaf의 dev.cakit import를
알린다.
- lockfile: 바뀐 줄은 dev.cakit.messaging 좌표 추가 45줄뿐이다(외부
의존성 집합은 그대로, 설계 16절 H6).
버린 대안: 라이브러리 jar를 persistence-jpa testRuntimeOnly로 올려
classpath에서 읽기(위 이유). 템플릿에 docs/messaging 사본을 남기기
(라이브러리 문서와 갈라진다. 다음 커밋이 문서를 그 repo로 가리킨다).
위험: 캐시가 빈 빌드(새 기계, 이미지 builder)는 git.learn.hyeonworks.com에
닿아야 한다. 공개 owner라 토큰은 필요 없다(익명 200 확인). 이 커밋만으로는
살아 있는 문서가 지운 경로를 부른다(check-docs는 다음 커밋에서 통과).
검증: desktop에서 이 트리로 RED·GREEN(system caller 고정 시험 2건, 순서
시험 2건은 수정 전·제약 제거 시 실패, 수정 후 통과). 전체 게이트는
PR 본문.
BREAKING CHANGE: src/platforms/messaging과 project(':messaging:…') 경로가
없어졌다. dev.cakit.messaging:<모듈>:1.0.0 좌표로 받고 import를
dev.caskeleton.messaging → dev.cakit.messaging으로 바꾼다
(docs/upgrade/2026-11-maturity-review.md B-57~B-59).
Refs: design-docs repo-structure/05-library-repos.md 4·8·10·13절
방향 검사(verifyModuleDependencyDirection)는 프로젝트 edge만 센다.
라이브러리가 별도 repo로 나가 외부 좌표가 되면, 지금 registry가
지키는 약속(메시징 bridge는 core-api만 본다, Kafka capability는
starter-kafka를 runtimeOnly로만 싣는다, 계층 leaf는 메시징을 모른다)을
아무것도 검사하지 않게 된다.
registry에 칸 둘을 더한다(설계 10.2절 T2, 소유자 승인 Q11).
- 맨 위 선택 칸 library_groups: 다스릴 Maven group 접두사.
- 행마다 선택 칸 allowed_libraries: group:artifact 목록. 꼴이 틀리거나,
library_groups 밖 group이거나, 겹치면 registry를 읽을 때 거절한다.
계층 leaf(domain-core, shared-contract, application-*) 행이 칸을
채우면 registry 위반이다. purity 검사가 비프로젝트 선언을 막는 것과
따로 registry 자체가 막는다.
- 방향 검사는 프로젝트 edge와 같은 방식으로 본다: 운영 선언
(api·implementation·compileOnly·runtimeOnly)의 소유 group 좌표와,
compileClasspath에서 보이는 소유 group 모듈(라이브러리 모듈이 api로
내보낸 것 포함)이 모두 칸에 있어야 한다. --include-build로 끼운
라이브러리 프로젝트는 프로젝트 edge가 아니라 그 좌표로 본다. 그래야
같이 고치는 흐름(composite build)에서도 같은 판정이 나온다. 「자기
빌드」는 ":"로 짐작하지 않고 해석 root의 build path로 읽는다(이 빌드가
다른 빌드에 끼워 돌아도 검사가 꺼지지 않게).
버린 대안: app-bootstrap ArchUnit 패키지 규칙(T1). import만 보고
runtimeOnly로 싣는 starter를 못 본다. 「어떤 모듈을 싣는가」는 빌드
사실이라 빌드 검사가 맞다.
위험: 시험 구성(testImplementation 등)은 프로젝트 edge처럼 보지 않는다.
이 빌드 자체를 다른 빌드에 끼우는 경우는 시험이 없다.
검증: desktop ./gradlew -p build-logic test rc=0. 새 시험: ModuleRegistryTest
4, CleanArchitectureResolvedClasspathFunctionalTest 7. functional 시험은
구현 전 RED였다(runtimeOnly·compile-visible 두 건은 게이트가 통과해
버렸고, --include-build 건은 「forbidden project dependencies
[demo-included]」로 실패).
Refs: design-docs repo-structure/05-library-repos.md 10.2절
workflow 15개 가운데 모듈 모양 파일들이 PR·main·nightly 단계가 이미
계획하는 Gradle 태스크를 한 번 더 돌린다(설계 design-docs
repo-structure/03-ci.md 3.1절 「중복」).
- fileserver-pr.yml 다섯 job: 모두 leaf `test`나 그 부분집합이다.
`ci`가 매 PR 돌린다.
- fileserver-nightly.yml의 --rerun-tasks job 셋: 같은 `test`의
부분집합이다. NFS job만 남긴다.
- jpa-nightly.yml의 failure·query plan·security·pool job: 모두
integration()·performance() lane이라 :integrationCheck·
:performanceCheck가 돈다. PostgreSQL major 행렬만 남긴다.
- notification-platform.yml의 pr job: `ci`와 :integrationCheck의
태스크다. 경로 필터가 docs/adr/로 옮긴 알림 ADR을 보지 못했다.
chaos job만 남긴다.
- object-storage-qualification.yml의 MinIO job 둘: integration lane이다.
보호된 AWS job만 남긴다.
- link-check.yml: 문서 검사라 main 단계로(소유자 결정 2026-09-16).
integration-main.yml의 links job으로 옮긴다.
fileserver 지원 매트릭스는 지운 job id 대신 그 증거를 실제로 만드는
테스트 클래스·모듈 test·남은 job을 적고, FileserverDocumentation
CoverageTest가 행마다 그 이름이 있는지 본다. job이 사라진 시험 문장
(PoolLaneClaimTest의 nightly job 검사, lychee 경로 필터 검사)은
지우거나 새 위치로 맞춘다.
위험: PR에서 경로로 켜지던 컨테이너 lane(notification의 실 PostgreSQL
두 lane, MinIO)은 이제 main push와 nightly에서만 돈다. 어댑터 컨테이너
lane을 main 단계로 옮긴 소유자 결정(2026-11-07 ②)과 같은 쪽이다.
검증: 기준 2959eff0의 desktop worktree에서 workflow의 Gradle 명령 50개를
--dry-run해 태스크 집합을 만들었다. 지운·옮긴 job 27개의 태스크는 모두
:ci·:mainCheck·:integrationCheck·:performanceCheck·:releaseCheck 계획
안에 있다(단계 집계 밖 0). 로그 desktop ~/t2a-backend-ci-logs/wave1-base/.
python3 scripts/check-docs.py, check-work-docs.py 통과.
Refs: design-docs repo-structure/03-ci.md 7.3절 Wave 1
grpc-library가 이름을 com.hyeonworks.grpc에서 dev.cakit.grpc로 바꾼다
(grpc-library PR #2, 소유자 2026-11-08: 개인 도메인 이름을 공용
라이브러리에 쓰지 않는다). 이 브랜치 문서는 옛 이름을 적고 있었다.
- README 재사용 체크리스트 6번: 라이브러리 패키지 dev.cakit.*은 바꾸지
않는다. 2번이 바꾸는 dev.caskeleton과 겹치지 않게 정한 이름이라고 적었다
- related-repos.md(group 두 칸과 받는 법), capability-status, 업그레이드
안내 B-55, 카탈로그 주석
남긴 것: Gitea 서버 주소, 기록(ADR-GRPC-002, 리뷰·history 본문)의 옛
proto 조직 이름 hyeonworks.
검증: check-docs.py OK, check-work-docs.py OK, --links broken 0.
구조 리뷰(arch-reviewer, 이 브랜치)가 찾은 권고 다섯을 고친다.
1. ModuleRegistry가 행의 `build` 칸을 아직 읽었다. 두 번째 빌드가 없어진
뒤로 main이 아닌 값(오타 포함)을 적은 leaf는 settings가 include하지
않고, 방향 검사도, 등록 안 된 build 스크립트 검사도 보지 않는데 ci는
초록으로 남는다(08-05가 막으려던 모양). 칸이 있으면(빈 값 포함) read에서
그 id와 'build'를 이름 대고 실패한다.
2. gates.md·defect-patterns.md의 「두 빌드의 verifyStrictLaneStages」.
3. shared-contract AGENTS.md의 「optional gRPC 빌드는 자기 사본을 둔다」를
별도 repo 라이브러리로.
4. QualityConventionsPlugin 주석의 현재형 「optional-platforms 빌드가 같은
제외 파일을 읽는다」를 이력으로.
5. StrictLaneStagesExtension 주석의 optional-build 경로에 그 빌드가 옮겨
갔다는 말을 붙였다.
버린 대안: `build` 칸과 modulesForBuild를 통째로 지우기. settings 설치기와
ArchitecturePlugin의 시그니처까지 바뀌고, 막는 효과는 같다.
검증(desktop ~/x2-template-wt, --no-build-cache):
- RED: 새 시험 aBuildFieldIsRejected… 고치기 전 실패(9 tests, 1 failed)
- GREEN: ModuleRegistryTest 통과. 옛 blankBuildOwnershipIsRefused는 새
문구로 바꿨다(빈 값도 같은 이유로 거절)
- -p build-logic check javadoc rc=0(172 tests), :ci :verifyDependencyLocks
rc=0(7389 tests, 실패 0), verifyStrictLaneStages --dry-run, check-docs,
check-work-docs(--links 포함), check-repo-layout 모두 rc=0
앞 커밋이 ADR-GRPC 7개와 gRPC 설계서를 살아 있는 문서와 함께 지웠다.
그러자 기록 docs/history/plans/2026-08-30-grpc-platform-implementation.md의
상대 링크가 깨졌다(desktop: check-work-docs --links broken 1, lychee
Error 1). 기록 본문은 고치지 않는다는 규칙이라 링크를 고칠 수 없다.
기록은 그때 템플릿 안 코드를 두고 한 결정·설계이므로 템플릿에도 남는
것이 맞다(설계 Q15 「리뷰 기록은 템플릿에 남김」과 같은 이유).
- ADR-GRPC 7개와 설계서를 22df3525에서 되살리고, 머리 블록 「현재 정본」을
「없음 — grpc-library로 옮겼다」로 바꿨다. 사본은 grpc-library에도 있다.
- 업그레이드 안내 B-55의 지운 목록에서 그 기록들을 뺐다.
- persistence-jpa testkit 주석 둘을 Spotless 줄바꿈대로 다시 쌌다
(desktop ci의 spotlessJavaCheck 실패).
검증(로컬, 문서만): check-docs.py rc=0, check-work-docs.py --links
broken 0. Gradle 게이트는 desktop에서 다시 돈다.
공통 훅·스킬(되돌릴 수 없는 명령 차단 H12, 비밀 값 알림, 예측·실측
장부 기록, estimate·retro·techdebt)은 claude-harness repo의 플러그인이
준다. 이 repo는 그 플러그인을 켜지 않아 새 세션이 그것들을 받지 못했다.
.claude/settings.json에 extraKnownMarketplaces(claude-harness, git URL)와
enabledPlugins를 더했다. 기존 deny와 repo 훅은 그대로다. 사용자 전역에
같은 H12가 등록돼 있으면 플러그인 H12는 스스로 아무것도 하지 않는다
(소유자 기계가 그렇다). 비대화형(claude -p)은 플러그인을 자동 설치하지
않으므로 CLAUDE.md와 docs/upgrade/2026-11-harness.md 9번에 수동 설치 두
명령을 적었다.
위험: 이 세션은 ~/.claude를 바꾸지 않으므로 플러그인 설치 자체는 하지
않았다. 대화형 앱이 처음 열 때 설치를 묻는지는 확인하지 않았다(claude-
harness README도 같은 미확인).
검증: settings.json JSON 파싱, check-work-docs.py rc=0(CLAUDE.md 10/10줄).
템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼
(src/platforms/grpc, grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드
(src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데,
registry 9행, workflow job 넷과 단계 하나, build-logic 플러그인 둘,
카탈로그·SpotBugs 항목, 문서 열두 개를 템플릿이 함께 지고 있었다.
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.5절,
05-library-repos.md Q1~Q17 승인)대로 라이브러리마다 별도 repo로 옮긴다.
gRPC는 템플릿 소비자가 없어 먼저 옮기고, 템플릿은 지우기만 한다(Q13).
코드와 이력은 grpc-library repo에 filter-repo로 옮겼다(옮긴 폴더의 트리
해시가 이 기준 커밋 22df3525와 같다).
지운 것:
- src/platforms/grpc, grpc-advanced, optional-build(343파일)
- registry의 "build": "optional-grpc" 9행
- ci-quality-gates.yml job optional-platforms·grpc-proto-buf와 그 needs,
integration-main.yml optional 성능 단계와 job
grpc-optional-platform-integration, release.yml job
grpc-stable-release-gate와 이미지 job의 needs 한 줄
- build-logic ca.grpc-platform-module·ca.optional-architecture-registry,
MainBuild(두 번째 빌드에서 주 빌드를 찾던 것)와 ArchitecturePlugin의
optional 분기. 도구 설정·이미지 목록·registry는 Gradle 루트에서 찾는다
- 카탈로그 protobufPlugin·protobuf-java-grpc·protoc·plugin protobuf(Q14:
채택 전이라 grpc-library 좌표도 넣지 않는다), SpotBugs 제외의 gRPC 줄
- 옮긴 문서: ADR-GRPC 7개, docs/compatibility/(폴더째), gRPC runbook 둘,
gRPC 설계서. 리뷰·기록 본문은 고치지 않았다(Q15). 기록 하나의 머리
블록 「현재 정본」만 새 자리를 말하게 했다
- DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험,
adopter API 표면 검사의 optional-build 제외 경로
남긴 것: adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다),
src/platforms/messaging(다음 분리 작업), registry의 build 칸 지원
(ModuleRegistry, 일반 기능).
살아 있는 문서: README, docs 지도, capability-status, work/delegate·
gates·decisions(새 행 「라이브러리 repo」)·defect-patterns·
review-criteria(경계 밖 파일을 경로로 읽는 결합을 결함 후보로),
manual 04, jpa migration-guide, build-logic AGENTS·README, testkit 주석.
새 docs/work/reference/related-repos.md가 라이브러리 repo 목록과 같이
고치는 법을 둔다. 파생 서비스 안내는 docs/upgrade 3.8절 B-55·B-56.
위험: 파생 서비스가 이 경로를 고쳤으면 수정 대 삭제 충돌이 난다
(tech-log-backend는 플랫폼을 받은 적이 없다, 설계 12절). 분리 직전
커밋 태그 pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지
않았다.
검증: desktop 게이트 결과는 PR 본문(ci, mainCheck 계열, releaseCheck,
compose smoke, 빠른 시작). 문서 검사 셋 rc=0.
BREAKING CHANGE: src/platforms/grpc*·optional-build, :grpc:*·:grpc-advanced:*
프로젝트, ca.grpc-platform-module, 카탈로그 protoc·protobuf-java-grpc·plugin
protobuf가 없다. 쓰던 서비스는 grpc-library 좌표 com.hyeonworks.grpc로
받는다(docs/upgrade/2026-11-maturity-review.md 3.8절).
Refs: design-docs repo-structure/05-library-repos.md 13.1절 1·2단계
착수 예측(21:46, p30 150분·호출 450·출력 45만) 뒤 끝 보고 직전의 실측을
세션 기록에서 뽑아 같은 task로 한 줄 더한다: 벽시계 94분, 작업 중 68분, 호출
270, 출력 34.6만 토큰, 다시 읽은 입력 1.33억 토큰, 최대 컨텍스트 80.5만. 모두
p30 안이다. 틀린 이유와 다음에 바꿀 근거는 줄의 why 칸에 있다.
작업 중 시간의 정의를 선례(design-docs harness 설계 14절)가 잰 방식과 같게
「빈틈을 5분까지만 더한 시간」으로 README에 적었다.
검증: test_ledger(예측보다 뒤의 실측, 구간 판정), check-docs, check-work-docs rc=0.
매뉴얼 보강 묶음이 각 빈틈을 어디에 넣었는지, 넣지 않았으면 왜인지를 다음
cold-read 시험과 총괄 대조가 찾을 곳이 없다. 1·2회차는 evidence.md 9·11절에
처리 표를 두었다. 같은 방식으로 12절을 더한다.
- 22행: 3회차 빈틈 9건(R3-1~R3-8), 장부의 통합·배치·문서·번역 세션 빈틈,
공유 노트 목록, repo-structure 세 문서의 매뉴얼 규칙. 고침 21행(기본값 2),
고치지 않음 1행(design-docs 몫).
- 리뷰 ID와 세션 이름은 이 근거 문서에만 둔다(매뉴얼 본문 이력 ID 0 규칙).
검증: check-work-docs, check-docs rc=0.
leaf 지역 규칙(src/**/AGENTS.md)은 그 폴더 파일을 열 때마다 통째로
읽힌다. Claude Code 공식 권장은 지침 파일마다 200줄 이하인데,
persistence-jpa 357줄, application-core 337줄, graphql 218줄이었다. 총괄이
2026-11-07에 상한 200을 검사에 넣고 셋을 줄이기로 정했다(소유자 결정
「자료대로 해 본다」의 방향).
- 참조 표, 계약 세부, 설계 근거를 절 단위로 그 leaf README 끝 「지역
규칙에서 옮긴 표와 계약」으로 옮겼다(내용 그대로, 제목 한 단계 내림).
지역 규칙의 같은 자리에는 README 절을 가리키는 줄과 그 폴더를 고칠 때
지킬 규칙 몇 줄을 남겼다.
- application-core: 계약 타입, 패키지 소유 표, 정해진 유스케이스 모양,
멱등성(KEYED) → 337줄에서 190줄.
- persistence-jpa: Spring 조립 소유, 플랫폼 lane, vendor 고르기,
TransactionPort 모드표, 영속 실패 번역(SQLState 표), 영속 감사 → 357줄에서
194줄.
- graphql: 구현된 플랫폼 범위 등급 표 → 218줄에서 185줄.
- 템플릿 패키지 목록의 정본이 src/application-core/README.md로 옮겨 가서
TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다. 표를 머리 줄로
찾고 단언은 그대로다. 옛 경로를 읽으면 표가 없어 실패한다(옮긴 뒤
AGENTS.md에 표 머리 줄 없음, README에 둘 다 있음을 확인했다). 그 표를
가리키는 테스트 주석·실패 메시지와 매뉴얼·리뷰 기준·스킬의 참조도 바꿨다.
- persistence-jpa README가 계약 표의 정본을 AGENTS.md라고 적던 줄 넷을 새
자리로 고쳤다. 그중 「세 템플릿 모두 isolation을 READ_COMMITTED로 고정」은
코드(`SpringTransaction`: pool에 고정, template은 기본값)와 달라 코드에
맞췄고, AGENTS.md에 없던 분산 락 provider 선택표 포인터는 실제 설정 코드
`lock/DistributedLockPersistenceConfig`로 바꿨다.
- check-work-docs.py: src/**/AGENTS.md 200줄 상한(시험 둘). RolePermission
PolicyTest 주석의 옛 절 이름을 새 규칙 파일로 바꿨다.
위험: 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의
표"를 가리킨다. 업무 코드라 고치지 않았다. CLAUDE.md → AGENTS.md → README
포인터로 닿는다. persistence-jpa README는 V1이 70~72줄을 고친다. 이 커밋은
그 범위를 건드리지 않는다.
검증: check-work-docs(가장 긴 지역 규칙 194/200), check-docs, unittest rc=0.
상한 검사를 끈 사본과 상한을 400으로 올린 사본에서 시험이 실패했다. Java
변경은 최종 트리에서 desktop documentContractTest·ci로 돌린다.
BREAKING CHANGE: 세 leaf의 표가 README로 옮겨 갔다. docs/upgrade/
2026-11-harness.md 2절 8행.
폴더 지역 규칙은 이제 src/**/AGENTS.md이고 옆의 CLAUDE.md는 `@AGENTS.md`
한 줄이다. 누가 CLAUDE.md에 규칙을 다시 쓰거나, AGENTS.md만 만들고
CLAUDE.md를 빠뜨리면 Claude Code가 그 폴더 규칙을 못 읽거나 규칙이 두 벌이
된다. 그리고 check-work-docs.py에는 자기 시험이 하나도 없었다.
- check-work-docs.py: src/**/AGENTS.md마다 옆 CLAUDE.md가 있고, 모든
src/**/CLAUDE.md가 정확히 `@AGENTS.md`이며 옆에 AGENTS.md가 있는지 본다
(build 출력 제외).
- scripts/tests/test_check_work_docs.py(13건): 최소 매뉴얼 통과, 지도 41줄·
CLAUDE.md 11줄 실패, CLAUDE.md 첫 줄이 가져오기가 아니면 실패, 진입 경로가
네 파일(AGENTS.md + CLAUDE.md + README + playbook) 합인지, 짝 셋, 하위
규칙과 .claude/rules·skills·agents의 이력 ID, 로컬 .claude 상태는 안 봄,
하위 규칙의 깨진 링크.
- gates.md 「링크 검사」: lychee 범위 밖 지침 문서는 check-docs.py `link`가
보고, 손으로 돌리는 범위를 src/**/AGENTS.md로 바꿨다. docs/README.md의
검사 설명에서 링크 문법 예를 뺐다(링크 검사기가 링크로 읽었다).
위험: 진입 경로 상한 350은 파일별 상한의 합(40+10+80+150=280)보다 커서
지금 구조에서는 닿지 않는다. 옛 상한(120+80+150=350)도 같았다. 상한은 그대로
두고 시험은 상한을 낮춰 계산식을 본다.
검증: unittest(전체), check-work-docs, check-docs, 같은 범위 --links 모두
rc=0(깨진 링크 0). 조건 다섯(짝 검사, 지도 상한, 진입 경로의 CLAUDE.md,
첫 줄 가져오기, .claude 문서 이력)을 하나씩 끈 사본마다 시험이 1~3건 실패했다.
cold-read 3회차(수정 세션 넷의 빈틈 9건), 통합·배치·문서 체계·번역 세션이
「매뉴얼에서 답을 못 찾았다」고 적은 곳, 프론트 총괄 교훈 둘, design-docs
repo-structure 01·02·03의 「매뉴얼에 넣을 규칙」 중 백엔드 몫이 아직 매뉴얼에
없다. 세션마다 같은 판단을 스스로 다시 했다.
넣은 자리(항목별 표는 PR 본문):
- delegate.md: upgrade 안내 「커밋:」 줄은 총괄이 합칠 때 적는다, 두 라운드
연속 결함이면 조사로, 병합 커밋에는 충돌 해결만, 자주 하는 실수 둘(충돌
없음은 merge-tree로, PR 만들기 전 head 브랜치의 PR을 API로).
- improve.md: 절차 문서 결함과 대기 결함의 RED 모양, 테스트 Javadoc도 고친다,
그 코드를 지키는 lane 찾기, 두 라운드 연속 결함이면 조사로.
- docs-writing.md: 문체·용어·언어 범위(코드 주석 제외), check-docs도 돌린다,
이동 커밋에 참조 수정을 같이, 번역 기준(영어 절 제목, 레지스트리 yaml,
머리말 없는 runbook, MANIFEST는 납품 당시 해시).
- operate.md 4.1: zsh 파이프 rc와 자기 실행 멈추기, runner 사실(capacity 1,
12코어·31GB, 잠금 밖), 취약점 DB는 설치가 아니다, 형식은 나누기 전에.
- reference/gates.md: 커밋하는 수정의 lockfile, 처음 켜진 lane의 이전 실패,
lychee·buf·trivy 공식 이미지, smoke 이미지가 이 트리에서 만들어졌음,
원래 있던 실패 가리기(세 번), 순서 의존 재현, 공유 잠금 기다리기, 증거
실행의 --no-build-cache, 거짓 통과 두 줄(OOM 재시작, 조건 안 set -e),
새 7절 「workflow·검사 스크립트를 더할 때」.
- reference/review-criteria.md: 관점 2·4·9·18·20·21·23·26·27의 볼 곳과 결함,
Important 예시, leaf 변경 체크리스트(README 다섯 칸, 문서 검사).
- reference/decisions.md: brief와 결정 원문이 다르면 원문, 취약점 DB 기본값.
- reference/terms.md(새): 영어 그대로 쓰는 말과 「개발 환경」의 뜻.
- README.md 2절(최상위 폴더는 큼), new-feature.md(테스트 환경·release/는
leaf 안), docs/ci-cd/template-vs-consumer.md(docs-check·link-check·
check-repo-layout은 파생 서비스도 유지), settings-and-runtime 규칙.
버린 대안: 항목마다 따로 커밋(소유자 결정: 매뉴얼 보강은 한 묶음).
위험: 정한 기본값 둘은 소유자 확인 대상이다: 취약점 DB 받기 허용,
병합 커밋에 충돌 해결만. operate.md는 143/150줄, improve.md 144/150줄로
상한에 가깝다.
검증: check-work-docs(진입 경로 최대 269/350), check-docs, unittest 모두 rc=0.