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.
문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만
지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다.
그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데,
2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다.
- check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다·
입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드,
따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다.
- runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가
울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다.
- 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지
않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명,
docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안).
- docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고,
링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs
docs-system.md 6.2절 다섯 칸)을 더했다.
버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다).
위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo
밖이라 고치지 않았다(총괄에게 알린다).
검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함),
check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시
worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건,
1건 실패했다.
작업 시간을 예측해도 실제와 비교해 기록하는 곳이 없어서, 틀린 예측에서
하네스를 고칠 단서를 얻지 못한다. 소유자가 2026-11-07에 자료의 방식대로
repo마다 docs/ledger/estimates.jsonl을 두기로 정했다(design-docs
harness/01-harness-design.md 10절, 13절 Q11).
- docs/ledger/README.md: 줄 셋(estimate·actual·retro)과 칸, p30·p50·p80의
뜻, 시간 기준은 작업 중 시간이라는 것, 더하기만 한다는 것.
- 첫 줄은 이 작업의 착수 예측이다(21:46, 공유 노트 착수 보고와 같은 값).
실측 줄은 끝 보고 직전에 더한다.
- 여러 브랜치가 파일 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes에
merge=union을 줬다(설계가 걱정한 병합 충돌).
- docs/work/README.md 6절(보고)과 delegate.md 4.1절에 착수 보고와 장부를
더했고, docs/README.md 지도에 ledger/ 행을 더했다.
- scripts/tests/test_ledger.py: 줄마다 공통 칸, 예측의 p30 ≤ p50 ≤ p80과
근거, 실측이 앞선 예측을 가지며 들어간 구간이 맞는지 본다.
버린 대안: design-docs 위임 장부를 schema 2로 넓히기(설계 권함, 소유자가
repo 장부로 정함). 위임 장부는 대조용으로 그대로 두고 task로 이 줄을 가리킨다.
위험: Gitea 서버 쪽 병합이 .gitattributes의 merge=union을 쓰는지는 확인하지
못했다. 충돌이 나면 두 쪽 줄을 다 남기면 된다.
검증: unittest, check-docs(지도 검사 포함), check-work-docs,
check-repo-layout rc=0. git check-attr로 merge: union을 확인했다.
새 기능을 만드는 순서와 desktop에서 게이트를 돌리는 순서는 그 일을
할 때만 필요하다. 지금은 루트 문서와 playbook을 세션이 스스로 찾아 읽어야
하고, cold-read 시험에서 desktop 절차 질문이 되풀이됐다. 소유자가
2026-11-07에 특정 시점 절차는 스킬로, 새 스킬은 모델이 부를 수 있게 하고
설명에 발동 조건을 문단으로 적기로 정했다(design-docs
harness/01-harness-design.md 5.5절, 13절 Q9·Q18).
- .claude/skills/new-feature: docs/work/new-feature.md와 docs/manual/의
실행 순서표(크기 → 받을 것 → 배치 → new-feature.sh --no-format → 안쪽부터
→ 테스트 먼저 → 훅 알림 → desktop 검증 → 체크리스트).
- .claude/skills/desktop-gates: operate.md 4.1·4.2와 gates.md의 실행
순서표(게이트 고르기 → 트리 정하기·패치 → worktree → flock·로그·rc →
테스트 수 → 잠금 대기 → 정리 → 보고 칸).
- 두 스킬 모두 정본 문서를 가리키고 다르면 정본이 맞다고 적는다. 설명은
327자·268자로 목록 상한(1,536자) 안이다.
- 설치된 스킬이 없던 skills-lock.json과 그 레이아웃 허용 항목을 지웠다.
- test_claude_setup.py에 스킬 시험(목록, 모델 호출, 발동 조건, 정본
가리키기, skills-lock.json 없음)을 더했다.
버린 대안: 사용자 호출 전용 스킬(설계 권함, 소유자가 모델 호출로 정함),
verify 스킬(내장 /verify와 이름이 겹친다. 검증 진입점 스크립트는 CI 재편
몫이라 여기서는 만들지 않는다).
위험: 스킬 목록이 컨텍스트 예산(창의 1%)에 닿아 있어, 두 설명이 다른
스킬 설명을 밀어낼 수 있다. 전역 스킬 정리는 소유자 전역 설정 세션 몫이다.
검증: unittest, check-docs(검사가 아직 없는 verify.sh 경로를 잡아
고쳤다), check-work-docs, check-repo-layout 모두 rc=0.
BREAKING CHANGE: 루트 skills-lock.json이 없어진다. docs/upgrade/
2026-11-harness.md 2절 6행.
Agent 도구를 프로젝트 설정으로 막아 두어서, 넓은 검색·구조 리뷰·앱을
띄워 보는 확인처럼 결과만 받으면 되는 일도 메인 세션 컨텍스트에 쌓이거나
하위 세션을 따로 띄워야 했다. 소유자가 2026-11-07에 금지를 풀고, 결과만
받는 일은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야
하는 위임은 하위 세션으로 나누기로 정했다(design-docs
harness/01-harness-design.md 8절, 13절 Q5).
- .claude/settings.json에서 "Agent" deny를 지웠다(.env deny는 남긴다).
- .claude/agents/: arch-reviewer(HARD-STOP 1~5·registry를 읽기만 하고
판정), verify-api(desktop에서 공유 잠금 아래 bootstrap-local.sh로 앱을
띄워 health와 지정 endpoint를 호출), code-simplifier(동작을 바꾸지
않는 단순화 제안). 셋 다 Edit·Write 도구가 없다.
- 나누는 기준을 AGENTS.md 「일하는 방식」과 docs/work/delegate.md
4.3절에 썼다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는
직접 하거나 하위 세션에 맡긴다.
- scripts/tests/test_claude_setup.py: deny가 없고, 정의마다 이름·발동
조건·도구 목록이 있고, 쓰기 도구가 없고, verify-api가 desktop 절차를
따르는지 본다.
버린 대안: 금지 유지(설계 권함, 소유자가 자료 쪽으로 정함), Explore만
허용하는 훅(맨 deny를 빼면 allow로 예외를 못 판다).
위험: 서브에이전트가 Bash로 파일을 바꾸는 것은 도구 목록으로 막지
못한다(arch-reviewer, verify-api). 정의 본문이 읽기 명령만 쓰라고 하고,
노트북 Gradle·Docker는 소유자 전역 훅이 서브에이전트 안에서도 막는다.
데스크톱 앱에서 서브에이전트 기록이 소유자에게 어떻게 보이는지는 확인하지
못했다.
검증: python3 -m unittest discover -s scripts/tests rc=0. arch-reviewer에
Edit를 더한 사본, Agent deny를 되살린 사본에서 각각 시험 1건이 실패했다.
check-work-docs·check-docs rc=0.
BREAKING CHANGE: 파생 서비스에서도 Agent 도구가 열린다. 막으려면 서비스
설정에 deny를 남긴다. docs/upgrade/2026-11-harness.md 2절 5행.
지금은 지켜야 할 규칙이 모두 문서에만 있다. 포맷·레이어 위반·문서 검사
실패는 desktop 게이트에서야 보이고, 이미 적용된 migration을 고쳐도
desktop의 AppliedMigrationImmutabilityTest가 돌 때까지 아무도 모른다.
소유자가 2026-11-07에 편집 훅이 그 파일 하나만 Gradle 없이 포맷·린트하고,
전체 검사는 턴 끝 넛지로, 되돌릴 수 없는 것만 막기로 정했다
(design-docs harness/01-harness-design.md 5절, 13절 Q6·Q7).
scripts/hooks/hooks.py 하나에 이벤트 넷(표준 라이브러리만):
- pre-edit H13: 편집 대상이 applied-migrations.sha256에 있는 migration이면
종료 코드 2로 막고 새 버전 파일을 더하라고 안내한다.
- post-edit 포맷: src/**/*.java 한 파일을 google-java-format으로 맞춘다.
버전은 카탈로그 googleJavaFormat, jar는 Gradle 캐시에 이미 있는 것만
쓰고(받거나 설치하지 않음), 옵션은 Spotless 단계와 같게
--skip-reflowing-long-strings --replace. 이 옵션으로 Spotless 대상
파일 전부를 dry-run 하면 차이가 0이었다(차이는 Spotless를 쓰지 않는
build-logic뿐이라 훅도 제외한다). 파일이 바뀌면 다시 읽으라고 알린다.
- post-edit N1: registry로 leaf를 찾고 import를 순수성 목록
(DomainPurityArchitectureTest, verifyApplicationCoreDependencyPurity와
같은 패키지)과 allowed_dependencies 전이 closure에 대 본다.
- post-edit N2: 문서 편집 뒤 check-work-docs·check-docs의 실패 줄.
- post-bash·stop N5: Java를 고친 뒤 ssh desktop gradlew 실행이 없으면
턴 끝을 한 번 막고 desktop 검증이나 못 돌린 이유를 쓰라고 한다.
- 권한: 실제 .env·.env.local·.env.lane 읽기·쓰기 deny(예시 파일은 둠).
버린 대안: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로
정함), 편집마다 desktop 원격 실행(왕복 비용), checkstyle 한 파일
(Gradle 없이 classpath를 맞출 수 없다. 린트는 N1이 맡는다).
위험: 이 세션에서 settings.json을 바꿔도 훅은 돌지 않았다. 훅은 세션이
시작할 때 읽힌다. 그래서 settings.json이 부르는 명령에 같은 입력을 넣어
확인했다. N1은 게이트의 일부만 본다. 정본은 architectureCheck다.
검증: python3 -m unittest discover -s scripts/tests rc=0(훅 시험 29,
그중 실제 포매터 시험은 이 노트북 캐시의 1.35.0 jar로 돌았다). 변이
시험: 조건 10개를 하나씩 끈 사본마다 시험이 1~2건 실패했다. 실제
운영 소스 3,230개에 N1을 돌려 걸림 0. 편집 한 번 훅 시간 Java 0.3초,
문서 1.2초. check-docs·check-work-docs·check-repo-layout rc=0.
BREAKING CHANGE: 파생 서비스에도 같은 훅과 .env deny가 걸린다.
docs/upgrade/2026-11-harness.md 2절 4행.
루트에 CLAUDE.md와 AGENTS.md가 둘 다 있으면 Claude Code 기본 설정은
AGENTS.md를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만
닿았고, HARD-STOP은 CLAUDE.md 요약으로만 실렸다. 두 문서가 같은
규칙을 아홉 군데 따로 적었다. 소유자가 2026-11-07에 루트 정본은
AGENTS.md 20~40줄, CLAUDE.md는 `@AGENTS.md`로 정했다(design-docs
harness/01-harness-design.md 13절 Q1·Q2·Q3).
- AGENTS.md(37줄): 무엇인가, HARD-STOP 7, 지도, 맡은 일, 검증,
일하는 방식. CLAUDE.md(6줄): `@AGENTS.md`와 Claude 전용 줄.
- 옛 절의 새 자리: Gradle 정책 권위 → src/build-logic/AGENTS.md(새),
테스트 작성 규칙 → .claude/rules/java-tests.md(paths: 테스트 소스),
계층별 테스트 기준·family 책임 → 각 core AGENTS.md와 새
src/adapter/inbound·outbound/AGENTS.md, composition 조립 규칙 →
src/composition/AGENTS.md(새), capability 규칙·완료 기준 →
docs/manual/10-capabilities.md(이제 정본), 설정·Docker 규칙 →
.claude/rules/settings-and-runtime.md, 문서 편집 규칙 →
.claude/rules/docs.md, 템플릿 재사용 체크리스트 → README
「새 서비스로 시작하기」. Superpowers 목록·강제 수준·금지된 지름길·
작업 보고 규칙은 HARD-STOP과 전역 규칙의 중복이라 지웠다.
- 살아 있는 문서의 옛 절 참조를 새 자리로 바꿨다. 결정 색인은 옛
행에 취소선을 긋고 「지침 배치」 행을 더했다.
- check-work-docs.py: 지도를 AGENTS.md로, 상한 40(CLAUDE.md 10),
진입 경로에 CLAUDE.md를 더하고, CLAUDE.md 첫 줄이 가져오기인지,
.claude/rules·skills·agents 문서의 이력 ID와 링크를 본다.
- DeveloperExperienceContractTest는 루트 안내 명령을 AGENTS.md에서
읽는다. 단언은 그대로다.
버린 대안: 루트 120줄(설계 권함, 소유자가 자료 쪽으로 정함),
CLAUDE.md만 두기(다른 에이전트가 못 읽음), 심볼릭 링크.
위험: 폴더를 가로지르는 규칙(.claude/rules/)은 Claude Code만 자동으로
읽는다. 다른 에이전트용으로 AGENTS.md 지도에 위치 한 줄을 뒀다.
검증: check-work-docs.py(AGENTS.md 37/40, CLAUDE.md 6/10),
check-docs.py, unittest, check-repo-layout.py 모두 rc=0. Java 테스트
변경은 마지막 트리에서 desktop documentContractTest로 확인한다.
BREAKING CHANGE: 루트 AGENTS.md의 절 이름이 바뀌고 내용이 위 자리로
옮겨 갔다. docs/upgrade/2026-11-harness.md 2절 2·3행.
leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code
밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가
2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다
(design-docs harness/01-harness-design.md 13절 Q1·Q2).
- 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리
CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서
src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져
AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는
지금처럼 그 폴더를 만질 때 규칙을 읽는다.
- 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다),
CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다).
- 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다.
기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴
때의 경로를 그대로 둔다.
- link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이
AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는
check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다.
workflow는 CI 재편 몫이라 고치지 않았다.
- check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다.
위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은
이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은
`git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는
가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다.
검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py,
python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사
시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다.
BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로
바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
문제: cb67b879는 `docs/upgrade/2026-11-maturity-review.md` 머리의 「커밋:」 목록에
「의존성 취약점 수정(3.7절 B-54)」을 더했다. 그 안내는 PR #2(03a313ed)로 이미
main에 합쳐졌다. 결정 색인 「아직 합치지 않은 업그레이드 안내」는 합쳐진 안내를
고치지 말고 새 행을 더하라고 한다. 머리의 「범위:」도 main → 리뷰 브랜치라 V1을
포함하지 않는다.
고친 방법: 머리 「커밋:」 목록을 main과 같게 되돌리고, 3.7절 첫머리에 이 절의
범위(`5ab1b418..claude/v1-vuln-fix-e089b9`)와 머리를 고치지 않은 이유를 적는다.
B-54 행은 그대로다. 이제 이 파일의 main과의 차이는 3.7절 하나다.
검증: check-docs.py rc=0, check-work-docs.py rc=0.
main(b3f63be6, 문서 2단계 통합 PR #3)을 V1 브랜치에 합친다. 충돌은 없었다.
- docs/web/repository-adaptation.md: V1이 숫자를 고쳤다가 되돌려(23f04afb) 기준과
같았으므로 main의 번역(숫자 없이 카탈로그를 가리킴)이 그대로 들어왔다.
- src/adapter/outbound/persistence-jpa/README.md: V1의 Querydsl 문장(71~75줄)과
main의 번역이 자동으로 함께 남았다.
- docs/work/reference/decisions.md, docs/upgrade/2026-11-maturity-review.md: V1이
더한 행과 main의 행이 모두 남았다.
- main 쪽에서 들어온 workflow 변경은 없다.
검증(노트북, 합친 트리): check-docs.py rc=0(넓어진 숫자 검사 포함 걸림 0),
자기 시험 OK, check-work-docs.py rc=0, check-repo-layout.py rc=0. 게이트는
desktop에서 이 커밋으로 돌린다.
문제: cb67b879가 `docs/web/repository-adaptation.md:65`의 baseline 숫자를
4.0.8에서 4.0.9로 고쳤다. 이 파일은 문서 번역 작업(D2d)이 지금 옮기고 있고,
총괄은 숫자를 하나도 고치지 않기로 정했다(2026-11-07). 번역 작업이 숫자를
복사하는 대신 정본(`src/gradle/libs.versions.toml`)을 가리키게 바꾸므로 4.0.9도
그때 맞춰진다.
고친 방법: 그 한 줄을 4.0.8로 되돌린다. 이 파일은 기준 커밋 5ab1b418과 같아진다.
- cb67b879는 이미 push해서 고쳐 쓰지 않고 되돌림 커밋을 붙인다.
위험·한계: 번역이 끝날 때까지 이 줄과 check-docs 예외로 얼린 8곳이 실제 Boot
4.0.9와 다른 숫자를 말한다.
검증: 앞 커밋과 같다(트리 fbb325c1에서 문서 검사 전부 rc=0).
`git diff 5ab1b418 -- docs/web/repository-adaptation.md`가 비어 있다.
문제: persistence-jpa README 「라이브러리 API」가 Querydsl을 쓰는 서비스에
`com.querydsl:querydsl-jpa:5.1.0:jakarta`를 직접 추가하라고 한다. 그 좌표에는
HIGH CVE-2024-49203(orderBy를 통한 HQL injection)이 있고 고친 버전이 없다.
8e3bef0f가 이 leaf를 querydsl-core로 옮겼는데, 살아 있는 문서는 아직 그
좌표를 권한다.
고친 방법: 총괄이 권한 안 A를 확인하고 이 문장도 고치라고 했다(2026-11-07).
문장을 넷으로 나눴다: 템플릿은 querydsl-core의 `Predicate`만 쓴다, JPA 질의가
필요한 서비스는 querydsl-jpa를 직접 더한다, 그 좌표 5.1.0에는 CVE-2024-49203이
있고 고친 버전이 없다, 쓰려면 OpenFeign 포크(`io.github.openfeign.querydsl`)를
검토한다. Envers 안내는 그대로다. 결정 색인 「Querydsl 취약 좌표」 행의 「누가」를
「총괄 확인 전」에서 위임(총괄 확인)으로 바꾸고 README를 출처에 더했다.
- 원래는 8e3bef0f와 같은 커밋이어야 했다. 그 커밋은 이미 push해서 고쳐 쓰지
않고 바로 뒤에 붙인다.
위험·한계: README 줄은 문서 번역 작업(D2b) 범위 안이다. 총괄이 D2b에 이 줄을
건드리지 말라고 알린다.
검증(desktop, 이 커밋과 다음 커밋을 얹은 트리 fbb325c1):
`python3 -m unittest discover -s scripts/tests` OK, `check-docs.py` rc=0,
`check-work-docs.py` rc=0, 같은 범위 상대 링크 555개 깨짐 0, `check-repo-layout.py`
rc=0. lychee(0.22.0 이미지)는 rc=2이고 실패 4건이 앞 트리와 같다(기록 문서의
404, 이 변경 전부터). 이 README를 읽는 테스트는 없다(`grep -rn --include='*.java'`).
참조 검사(reference)와 머리 블록의 「현재 정본」·「대체됨」 검사는 경로가
있는지를 파일 시스템(Path.exists)으로 본다. git mv는 옮긴 뒤 빈 옛 폴더를
디스크에 남긴다. 그래서 지운 폴더를 가리키는 살아 있는 문서가 노트북에서는
통과하고, 빈 폴더가 없는 새 checkout(PR workflow)에서만 실패한다. 알림 ADR을
옮길 때(39d4f248) 실제로 그랬다: docs/README.md에 쓴 옛 폴더 경로가 빈
docs/notification/adr/ 때문에 통과했고, 폴더를 지운 뒤에야 걸렸다.
「있다」를 git이 아는 파일(추적 + 무시되지 않은 새 파일, 문서 목록과 같은
git ls-files)과 그 위 폴더로 바꿨다(known_paths). leaf 기준 상대 경로를
위 폴더로 올라가며 찾는 규칙은 그대로다. 무시되는 경로(src/.env 등)는
전처럼 git check-ignore가 건너뛴다.
버린 대안: 빈 폴더만 따로 빼기. 아무도 추가하지 않은 파일(디스크에만 있는
build 밖 산출물)도 같은 거짓 통과를 만든다. git이 보는 것과 같게 하면
노트북과 PR workflow가 같은 답을 낸다.
자기 시험 셋을 더했다(79 OK): 빈 폴더를 가리키는 참조가 실패, 파일이 든
폴더는 통과, 빈 폴더를 가리키는 「현재 정본」이 실패. 변이 시험: 디스크의
모든 경로를 다시 세게 하면 rc=1, 빈 폴더 시험 둘이 실패한다.
검증(노트북): check-docs.py OK(여섯 검사 걸림 0, 0.8초), 자기 시험 79 OK.
빈 docs/notification/adr/를 다시 만들어도 known_paths는 그 폴더를 모른다.
runtime-jvm-oom runbook이 「컨테이너가 코드 137로 끝난다
(-XX:+ExitOnOutOfMemoryError가 동작함)」고 적는다. 그 옵션으로 JVM이 스스로
끝나면 종료 코드는 3이고 stderr에 「Terminating due to
java.lang.OutOfMemoryError: …」가 남는다. 137은 SIGKILL이다. 힙이 아니라
프로세스 전체 메모리가 컨테이너 한계를 넘어 커널이 죽인 경우이고, 원인과
볼 것이 다르다(번역 묶음 D2c가 확인 필요로 넘긴 것).
증상 절을 둘로 나눴다: 코드 3 + 그 stderr 줄은 이 runbook, 코드 137 +
OOMKilled는 다른 일(힙과 네이티브 메모리의 합, MaxRAMPercentage가 남긴 몫,
힙 덤프 없음).
검증: desktop에서 이 저장소 이미지(caskeleton:0.0.1_local_0000000-default,
9ae52229)를 공유 잠금 아래 java -Xmx4m·-Xmx6m
-XX:+ExitOnOutOfMemoryError -jar application.jar로 띄웠다. 둘 다 rc=3,
stderr 「Terminating due to java.lang.OutOfMemoryError: Java heap space」.
노트북 check-docs.py OK.
한계: ContainerRuntimeOomContractTest Javadoc의 「exit 137」은 테스트 코드라
이 변경에서 고치지 않았다.
AGENTS.md와 src/**/CLAUDE.md는 본문에 지난 리뷰 ID를 두지 않는다
(docs/work/README.md 8절). 번역한 CLAUDE.md 넷에 짝 하나짜리 번호가
남았다: persistence-jpa·app-bootstrap의 「07-08」, grpc의 「11-M9」,
messaging의 「06-01 수정」. check-work-docs.py는 단독 NN-NN을 일부러 잡지
않으므로(범위·절 번호와 구별할 수 없다) 통과했다(번역 묶음 D2b가 넘긴 것).
ID 대신 그 발견의 내용과 날짜를 적었다. 원래 ID와 근거 리뷰 파일은
docs/work/evidence.md 10절 끝에 행 넷으로 남겼다(앞 행들과 같은 칸).
검증(노트북): check-work-docs.py OK, --history(바꾼 파일) 이력 ID 0,
check-docs.py OK. 이 넷을 읽는 테스트는 없다(git grep 'CLAUDE.md' -- '*Test.java').
runbook 상태 어휘가 초안·운영으로 바뀌었는데(docs/runbooks/template.md,
RunbookCoverageContractTest) docs/mongodb/runbooks/의 두 runbook은 옛 값
status: active를 쓴다. 그 시험은 docs/runbooks만 보므로 걸리지 않았다
(번역 묶음 D2c가 범위 밖으로 넘긴 것).
failover.md, unknown-commit.md의 status: active → 운영(옛 active의 뜻).
본문은 바꾸지 않았다.
검증(노트북): check-docs.py OK. 살아 있는 문서의 머리말 status 중 초안·운영
밖의 값 0(git grep '^status:').
번역 묶음(D2b)이 확인하지 못하고 넘긴 대문자 식별자 넷을 코드와 대조했다.
MAX_CONCURRENT_STREAMS(RFC 9113 HTTP/2 설정 이름)와 DEFAULT_MAX_PAGE_SIZE
(Spring Data 상수)는 바깥 이름이라 맞다. 둘은 틀렸다.
- 예외 대응 표의 MaxUploadSizeExceededException 행이 「multipart 전용
413(UPLOAD_SIZE_EXCEEDED)은 이 영역의 책임 — 병합 후 정제」라고 적는다.
그런 오류 코드는 레지스트리에도 코드에도 없다.
GlobalExceptionHandler.handleMaxUploadSizeExceededException은 multipart와
JSON 본문 모두 PAYLOAD_TOO_LARGE(413)로 답한다. 그대로 적었다.
- 「클라이언트 IP」 절이 지운 모드의 이름(FORWARDED_HEADERS_TRUSTED)을 지금
있는 것처럼 인라인 코드로 적는다. 이름을 빼고, 지운 사실은 제거 표
(docs/capability-status.md 「제거된 코드」)를 가리킨다.
검증(노트북): check-docs.py OK. 이 README를 읽는 테스트는 없다
(git grep 'inbound/web/README').
src/README.md가 「~합니다」체다(끝맺음 215곳, 「~한다」는 번역 묶음이 고친
두 문장뿐). docs/README.md 「문서 수명과 언어」는 살아 있는 문서의 문체를
「~한다」로 정하고 한 문서 안에서 섞지 않게 한다. 번역 묶음(D2a)이 이
문서의 영어 제목·문장만 맡아 문체는 범위 밖으로 넘겼다.
- 끝맺음만 바꿨다. 낱말 111개를 하나씩 대응표로 바꾸고(합니다 → 한다,
입니다 → 이다·다, 형용사는 하다·다: 견고하다, 필요하다, 다르다, 크다,
쉽다, 같다, 「있지 않습니다」 → 「있지 않다」, 「~세요」 → 「~한다」),
바뀐 195줄을 한 줄씩 읽었다. 줄 수(577)와 다른 글자는 그대로다.
- 「Docker Compose 최소 버전 `2.24.4`」가 정본
(compose-profile-contracts.json의 minimumComposeVersion)을 옆에 적고도
값을 복사했다. 값을 지우고 정본 키를 가리킨다.
버린 대안: 문체를 그대로 두고 규칙 쪽에 예외를 두기. 한 파일만 다른
문체를 허용할 근거가 없다.
이 문서를 글자 그대로 읽는 테스트는 없다(git grep 'src/README' — 링크
검사 범위 목록 테스트 하나만 경로를 적는다).
검증(노트북): check-docs.py OK, 「~니다」 끝맺음 남은 수 0(「아니다」 제외).
숫자 검사(number)는 「Spring Boot 4.0.8」처럼 이름 바로 뒤에 붙은 버전만
본다. 이름과 떨어진 복사는 지나간다. 기준 커밋 03a313ed의 살아 있는
문서에 그런 복사가 넷 있었다.
- docs/web/repository-adaptation.md:65 「baseline is **4.0.8**」
(의존성 세션이 손으로 찾아 고친 줄. 그 브랜치는 **4.0.9**로 바꾼다)
- docs/compatibility/grpc-support-matrix.md:29 「| Spring Boot | 4.0.8 …」
- docs/mongodb/support-matrix.md:12 「| Spring Boot | 4.0.0 |」
- docs/jpa/repository-adaptation.md:100 「Boot 4.0.0 resolves …」
번역 묶음이 넷 모두 정본을 가리키게 고쳤지만, 검사가 막지 않으면
다시 생긴다.
규칙 셋을 더했다(Spring Boot 버전에만).
1. 이름 규칙이 「Spring」 없는 「Boot x.y.z」도 잡는다.
2. 표 행에 칸 전체가 「Spring Boot」(굵은 글씨·코드·링크를 벗긴 뒤,
뒤에 BOM·버전이 붙어도 됨)인 칸이 있으면 그 행의 세 자리 버전.
3. 정본(src/gradle/libs.versions.toml의 springBoot)과 같은 버전 문자열은
어디에 쓰든(굵은 글씨, 표 칸, 인라인 코드). 앞이 낱말·점·§이거나
뒤가 낱말·「.숫자」이면 다른 수의 일부로 보고 넘긴다(RFC §4.0.8,
14.0.8, 4.0.80, 4.0.8.1).
이름 옆 복사는 한 번만 센다(2·3이 그 안의 버전을 다시 세지 않는다).
결정 기록·제거 표·upgrade/를 빼는 범위는 그대로다(checked_for_drift).
버린 대안: 굵은 글씨 안의 모든 세 자리 버전을 잡기. 살아 있는 문서를
훑으면 Spring Boot 아닌 것이 둘 걸린다. docs/jpa/support-matrix.md의
Hibernate **7.1.8.Final**은 JpaDocumentationContractTest가 release
registry의 값과 같은지 단언하는 렌더링이라 지울 수 없다. 그것을 잡으면
굵은 글씨만 빼서 검사를 피하게 된다. 규칙 3은 정본 값을 직접 보므로,
지금 버전의 복사는 모양과 상관없이 생길 수 없고, 버전을 올리는 변경
때 옛 값의 복사가 남아 있을 수 없다.
한계: 정본 값과 다르고 이름과도 떨어진 버전(「4.0.0 / 5.0.0」 같은
문장)은 잡지 않는다. Spring Boot 밖의 버전 복사는 이 검사의 범위가
아니다(docs/README.md 「문서 검사」 number 행).
시험: 03a313ed 트리와 의존성 브랜치(cb67b879) 트리에 옛·새 검사를
돌렸다. 새 검사가 위 네 줄(의존성 브랜치는 **4.0.9**)을 더 잡고,
옛 검사가 잡던 28건은 모두 그대로 잡는다. 합친 트리는 걸림 0이라
예외를 더하거나 고칠 문서가 없다.
자기 시험 8개를 더했다(76 OK). 조건을 하나씩 끈 변이 시험 7개가 모두
rc=1이다: 옛 이름 정규식, 표 칸 규칙 끔, 정본 값 규칙 끔, 중복 세기
제거 끔, 정본 값 앞 § 허용, 정본 값 뒤 경계 끔, 칸 이름 앞부분만 맞춤.
검증(노트북): check-docs.py OK, 자기 시험 76 OK, check-work-docs.py OK.