Commit Graph
12 Commits
Author SHA1 Message Date
DongHyeonka 3c73fc333c docs(agents)!: 루트 AGENTS.md를 40줄 정본으로 줄이고 CLAUDE.md가 가져온다
루트에 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행.
2026-11-07 21:59:42 +09:00
DongHyeonka 0e54b5b564 docs(work): 문서 검사를 게이트 표와 단계 묶음에 넣는다
문제: 문서 체계 1단계가 PR·main push마다 도는 `python3 scripts/check-docs.py`
(workflow `docs-check`)를 더했지만 게이트 정본 gates.md에는 없다. 라운드
끝 게이트를 gates.md 3절대로 돌리는 세션은 이 검사를 빠뜨린다. 파일이나
Gradle 프로젝트를 지우는 코드 변경이 문서를 낡게 만든다는 것도 2절 표에
없다.

고친 방법: 구조 정리가 `check-repo-layout.py`를 넣은 모양을 따른다.
- 1절 게이트 목록에 한 행(무엇·단계·workflow, 앞에 도는 자기 시험).
- 3절 단계별 묶음의 pull request·main 줄과 (가) 명령 목록에 자기 시험과
  검사 두 줄. workflow가 main push에서도 돌리므로 main 줄에도 넣는다.
- 2절 「바꾼 것에 맞춰 고르기」의 문서 행에 더하고, 「파일·폴더·Gradle
  프로젝트를 지우거나 옮김」 행을 새로 둔다.

위험·한계: docs-writing.md·review-criteria.md에 새 검사와 규칙 줄을 더하는
일은 매뉴얼 보강 작업에 남긴다.

검증: check-work-docs.py rc=0, check-docs.py rc=0, gates.md 상대 링크 0 깨짐.
2026-11-07 15:05:57 +09:00
DongHyeonka e13a29024f ci(repo)!: 최상위 폴더 허용 목록 검사를 더한다
문제: src/ 아래 계층이 아닌 폴더가 2026-07-24의 둘에서 두 달 사이
여덟으로 늘었고, 루트에는 compose 파일과 infra/가 쌓였다. 어느 커밋도
최상위 모양을 묻지 않았고 리뷰 기준에도 그 칸이 없었다.

고른 방법(소유자 결정 2026-11-07, 설계 10.3절): scripts/check-repo-layout.py
- 저장소 루트와 src/ 바로 아래의 추적 항목이 허용 목록 안에 있는가
- registry source_path가 허용된 src/ 폴더 아래인가
- (경고) compose·스크립트·compose 보조 파일을 아무 추적 파일도 가리키지
  않는가
를 본다. ci-quality-gates.yml quality-gates job에 한 단계로 붙인다.
Gradle 밖 스크립트다(문서·배치를 파싱하는 Gradle 검사를 두지 않는 정책).
버린 대안: registry에서 허용 폴더를 파생하기. 새 vendored 폴더를 registry
에 등록하는 것만으로 통과해, 막으려는 drift를 막지 못한다.

위험·한계: 참조 0 경고는 경로를 변수로 조립하는 workflow를 따라가지
못해 경고로만 둔다. 리뷰 기준·playbook 문장은 매뉴얼 보강 작업이 넣는다.

검증:
- 노트북·desktop: python3 scripts/check-repo-layout.py rc=0, 경고 0
- 일부러 infra/, src/messaging/, 고아 compose/orphan.sh를 둔 임시 저장소:
  rc=1, 실패 3건과 경고 1건
- desktop(트리 c7cacf54): :app-bootstrap:repositoryContractTest
  :app-bootstrap:documentContractTest rc=0, :verifyStrictLaneStages --dry-run rc=0
- check-work-docs.py rc=0
- 업그레이드 안내 B-50~B-52의 근거 칸을 커밋 해시로 채운다

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 10.3
BREAKING CHANGE: 저장소 루트나 src/에 허용 목록 밖의 최상위 폴더를 둔 파생 서비스는 PR 게이트가 실패한다. docs/upgrade/2026-11-maturity-review.md B-53.
2026-11-07 13:09:05 +09:00
DongHyeonka 8d69e599a3 refactor(repo)!: 들여온 플랫폼을 src/platforms 아래로 묶는다
문제: src/ 최상위에 계층 폴더와 들여온 제품 폴더(messaging, grpc,
grpc-advanced)와 optional 빌드 폴더(optional-platforms)가 같은 높이로
놓여, 무엇이 이 애플리케이션의 계층인지 폴더만으로 안 보인다.
src/config/에는 빌드 전체 설정과 기능 하나가 주인인 데이터(jpa,
messaging, mongodb)가 섞여 있다.

고른 방법(소유자 결정 2026-11-07, 설계 가-1):
- git mv로 src/platforms/{messaging,grpc,grpc-advanced,optional-build}.
  registry source_path 28행만 바꾸고 Gradle 경로(:messaging:*, :grpc:*)는
  그대로다. optional 빌드의 이름(optional-platforms)도 그대로다.
- optional 빌드가 한 단계 깊어져, build-logic이 "optional 빌드의 부모 =
  주 빌드"로 가정한 네 곳(registry settings, ArchitecturePlugin, 테스트
  이미지 catalog, checkstyle·spotbugs 설정)을 MainBuild(위로 올라가며
  registry·설정 파일을 찾음)로 바꾼다.
- settings.gradle·build.gradle의 상대 경로, workflow의 -p 값과 경로,
  buf 작업 폴더를 고친다. buf breaking은 이동 전 baseline에서도 옛
  경로로 비교해 이동 PR에서 건너뛰지 않는다.
- config/jpa, config/messaging, config/mongodb의 데이터를 주인 leaf의
  release/로 옮기고 읽는 빌드 줄·테스트·스크립트·문서를 고친다.
- 루트 CLAUDE.md 5절에 최상위 폴더 지도를 한 줄로 적는다.
버린 대안: Gradle 루트를 저장소 루트로(가-3, CI 재편 때 다시 봄),
application-* 묶기(가-2, 파생 서비스 충돌이 큼).

위험·한계: Gradle 문서의 "이름 = 위치" 권고와 한 단계 어긋난다
(:messaging:x가 platforms/messaging/x). 옮긴 폴더를 고쳐 쓰던 파생
서비스는 이름 바뀜 충돌이 날 수 있다(B-52). docs/capability-status.md
「제거된 코드」 표와 docs/work/evidence.md의 옛 경로는 이력이라 두었다.

검증(desktop, 트리 2b3354a4, ~/t1-layout-logs/):
- ./gradlew :ci :verifyDependencyLocks --warning-mode=fail --continue
  첫 실행 rc=1: MessagingAuthorityContractTest가 src/messaging을 찾아 실패
  → 경로를 고침. 두 번째 rc=1: messaging-policy
  MessagingAdmissionControllerTest.aWaitingCallerIsAdmittedOnceAPermitIsReturned
  (2초 대기 경쟁, 부하 7.3에서 한 번 실패, 코드 변경 없는 leaf) → --rerun
  3회 모두 통과. 세 번째 rc=0
- -p platforms/optional-build ci rc=0, 두 빌드의 verifyStrictLaneStages
  --dry-run rc=0, -p build-logic check rc=0
- :app-bootstrap:documentContractTest
  :adapter:outbound:persistence-mongo:mongoDocumentContractTest rc=0
- ./gradlew projects(주 빌드)와 optional 빌드 projects의 프로젝트 목록이
  이동 전 트리와 같다(Gradle 경로 불변)
- check-work-docs.py, 상대 링크 검사 rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.1
BREAKING CHANGE: src/messaging·src/grpc·src/grpc-advanced·src/optional-platforms가 src/platforms/ 아래로, src/config/{jpa,messaging,mongodb}가 주인 leaf의 release/로 옮겨졌다. optional 빌드는 -p platforms/optional-build로 부른다. docs/upgrade/2026-11-maturity-review.md B-52.
2026-11-07 13:04:54 +09:00
DongHyeonka 50cd7154d0 refactor(compose)!: compose 파일을 개발 환경 하나와 lane fixture로 나눈다
문제:
- 루트 compose 6개와 infra/ 아래 12개가 개발 환경, 테스트 lane fixture,
  보조 파일을 가리지 않고 섞여 있다. 이름 모양도 셋이다.
- README 빠른 시작 scripts/bootstrap-local.sh는 docker-compose.yml과
  .local.yml만 합친 뒤, 둘 어디에도 없는 db 서비스를 띄우려다 멈춘다.
- compose smoke all-adapters lane은 앱이 mem_limit 512m를 넘어 커널에
  죽고(OOM), restart: unless-stopped로 다시 떠서 죽는 때가 smoke 요청과
  겹칠 때만 실패한다. smoke는 재시작을 보지 않아 나머지 실행은 거짓 통과다.

고른 방법(소유자 결정 2026-11-07):
- 루트에 개발용 compose.yaml 하나. app(local 런타임)과 뒷단 서비스를
  capability profile(jpa, redis, kafka, mongo, objectstorage, auth, mail)로
  고른다. 마운트하는 보조 파일은 compose/(keycloak, minio init, Redis ACL,
  mailpit 인증서 폴더).
- lane fixture는 lane을 가진 leaf로: dev·prod-smoke·tls overlay, fileserver
  overlay, smoke·스키마 적용 서비스(lane-services.yaml)와 스크립트, lane
  계약 JSON → src/app-bootstrap/compose-lanes/. Redis topology →
  redis-sdk/compose/, NFS → fileserver/compose/nfs/. infra/는 없어진다.
- 계약의 composeProfile(문자열)을 composeProfiles(목록)로 바꾼다. lane이
  backing profile과 lane profile을 함께 켠다. 18 lane의 서비스 집합은
  전과 같다(verify-compose-profile-contracts.sh가 정확히 대조).
- smoke: lane이 끝나기 전에 그 project의 모든 컨테이너가 재시작 0,
  OOMKilled false인지 보고 아니면 실패한다. 앱의 memory.peak를 증거로
  남긴다. all-adapters만 appMemoryLimit 1g(계약 칸, smoke가 overlay에 씀).
- bootstrap-local.sh는 compose.yaml로 db와 app을 띄운다(인자 없음).
- 개발 compose와 lane 바탕이 같은 파일이라, app healthcheck는 모든
  런타임에서 답하는 관리 포트 readiness로 둔다.
버린 대안: lane을 Testcontainers로 옮기기(설계 다-2, 별도 판단), lane마다
기본 메모리를 올리기(배포 기본값 512m 계약을 흐림).

위험·한계:
- 개발 compose의 app이 src/.env를 읽으므로, 개발자 src/.env가 dev·prod
  lane에도 들어간다. lane 값은 생성 overlay의 environment가 이기고, CI에는
  src/.env가 없다.
- MinIO 이미지 기본값이 compose.yaml과 lane-services.yaml 두 곳에 있다
  (YAML anchor는 파일을 넘지 못한다). ComposeMinioImageMatchesEvidenceTest가
  둘 다 evidence digest와 대조한다.
- env 키 검사(verifyEnvKeys)는 compose.yaml과 lane overlay를 읽고
  lane-services.yaml(smoke client 변수)은 뺀다.

검증(desktop, 트리 6d1e9f9d → 주석·문서만 고친 d0703901, ~/t1-layout-logs/):
- verify-compose-profile-contracts.sh rc=0 (18 lane 정확히 일치)
- :app-bootstrap:check :app-bootstrap:documentContractTest
  :app-bootstrap:verifyEnvKeys와 objectstorage·cache-redis·redis-sdk·
  redis-runtime·fileserver·composition:fileserver-platform check rc=0
- :app-bootstrap:integrationTest(ComposeMergeCharacterizationTest 포함),
  :adapter:outbound:cache-redis:redisContainerContractTest rc=0
- -p build-logic check rc=0, :verifyStrictLaneStages --dry-run rc=0
- scripts/run-compose-runtime-smoke.sh --matrix(18 lane) rc=0, 794초.
  모든 lane 컨테이너 재시작 0·OOMKilled false. 앱 memory.peak 최고
  all-adapters 532MiB(512m 한도를 넘는 값이라 1g의 근거), 나머지 244~422MiB
- scripts/bootstrap-local.sh rc=0(db·app 기동, /api/healthcheck 200 UP).
  기준 ac03192d의 base+local 조합은 config --services가 app뿐이고
  up --wait db가 "no such service: db"로 rc=1
- 정리할 때 `docker compose down`은 profile 서비스(db)를 남겨
  README·compose.yaml 안내를 `--profile '*' down`으로 고치고 다시 확인
- 주석·문서 수정 뒤 :app-bootstrap:repositoryContractTest
  :app-bootstrap:documentContractTest, verify-compose rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.3
BREAKING CHANGE: 루트 docker-compose*.yml과 infra/가 없어지고 compose.yaml(profile)·compose/·leaf 안 lane fixture로 옮겨졌다. lane 계약은 src/app-bootstrap/compose-lanes/compose-profile-contracts.json, composeProfile → composeProfiles. docs/upgrade/2026-11-maturity-review.md B-51.
2026-11-07 12:52:36 +09:00
DongHyeonka ab5982e955 refactor(repo)!: 샘플 모듈과 그 참조를 지운다
문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.

고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
  (sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
  app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
  ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
  application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
  ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
  (유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
  샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.

위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
  전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
  총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
  지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
  샘플 경로는 이력이라 두었다.

검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
2026-11-07 12:21:03 +09:00
DongHyeonka 3eb3b06755 docs(work): cold-read 시험 2회차 빈틈 52건을 매뉴얼에 반영한다
문제: 2026-11-07 round7 수정 다섯, 통합, round8 확인 리뷰 둘, 문서 과제
하나를 이력 없는 세션 9개로 돌렸다. 매뉴얼에서 답을 못 찾은 곳이 52건
나왔고(1회차 35건), 코드 수정 과제에서 같은 질문이 되풀이됐다: desktop
포매터 결과 가져오기(4세션), 커밋 단위 모순(4), 테스트 수 세는 곳(3), RED 없는
수정의 증거(3), 넘어온 「범위 밖」 항목(3), PR 단계 명령 묶음(2).

고른 방법: 되풀이된 질문은 절차 한 곳에서 끝냈다.
- operate.md 4.1절: spotlessApply 결과를 노트북에 가져와 트리 해시를 맞추는
  명령, 결과 XML 보관, 중간 커밋 검증, 도구 설치 단계는 따라 하지 않음
- gates.md: 단계별 묶음 표(PR·main·라운드 끝), 테스트 수 세는 명령, 앞 실행을
  증거로 쓰는 조건, 중첩 빌드 FROM-CACHE, 탐침(rc 읽기, --tests 필터, 의존성)
- improve.md: RED 없는 수정의 증거, 같은 원인과 범위 밖의 경계, 업그레이드
  안내 행, 약속한 응답으로 맞추기, 「정한 기본값」 확인, 넘어온 항목
- README 4절 커밋 단위(commit-and-pr 정본에 맞춤), 2절 소유자가 정한 큰 변경
- review-criteria 10절 확인 리뷰 README 절 순서, delegate 4.1절 기본값 옮기기
결정 색인에 기본값 일곱을 남겼다(소유자가 뒤집을 수 있다). 처리 표는
evidence.md 11절이다(34행, 고치지 않음 0, 소유자 결정 필요 0). 수정 과제의
답(round8 발견을 어떻게 고칠지)은 쓰지 않았다. 다음 시험이 그 과제다.

위험·한계: 분량 상한에 가까워졌다(improve 143/150, operate 141/150, README
77/80). cold-read 시험은 이 커밋 뒤 3회차가 한다. 기본값 일곱(커밋 단위,
넘어온 항목, 약속한 응답, 검사를 더 엄하게, 업그레이드 안내 행, 태그 단계,
도구 설치)은 소유자 확인 대상이다.

검증(트리 f43dbc29, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/C-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
  lychee 범위 --links rc=0, check-review-index.py 2026-11-03-rereview rc=0
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- MongoNamespaceContractTest --rerun rc=0(3건)
- 테스트 수 세는 명령은 desktop의 지난 결과 XML로 시험했다
2026-11-07 07:02:09 +09:00
DongHyeonka 6b253c6c75 docs(work): 이력 ID 0 규칙을 AGENTS.md와 src/**/CLAUDE.md로 넓힌다
문제: 이력 ID 0 규칙은 docs/work와 docs/manual 본문에만 걸려 있었다.
새 세션이 처음 읽는 규칙 문서인 AGENTS.md와 leaf CLAUDE.md에는 "리뷰
05-18", "D12", "MSG-023", "owner decision 33"처럼 지난 리뷰를 모르면 읽을
수 없는 번호가 87줄 남아 있었다. 2026-11-07 소유자가 이 둘로 넓히기로
했다(리뷰 README 19.4절 ③의 (b)). 모듈 README·설계 문서·docs/reviews는
넓히지 않는다.

고른 방법: 87줄의 번호를 내용과 날짜로 바꾸거나 지웠다. 근거(번호가 가리키는
발견·결정과 원래 문서)는 docs/work/evidence.md 10절 표로 옮겼다. 원래 설계
기록이 이 repo에 없는 번호(feature-*-contract의 D1~D12)는 가리키는 규칙과
코드 위치를 근거로 적었다. check-work-docs.py 기본 모드가 두 문서 묶음까지
보게 했고, 그동안 못 잡던 꼴을 더했다: 모듈 리뷰 발견(MSG-023, BOOT-006),
리뷰 후속 발견(S6-#10a, X2-P1-5, S5-lead-4), 고른 대안이 붙은 발견 번호
(03-11 (b)), 영어 "decision 9"·"review README §15", 줄바꿈으로 갈린 ID.
날짜로 쓴 결정("owner decision 2026-11-06")을 번호로 잡던 오탐은 뺐다.
문서를 고친 것과 검사를 넓힌 것을 한 커밋에 둔 것은, 따로 두면 검사만 있는
커밋에서 기본 모드가 실패하기 때문이다. 버린 안: 검사만 넓히고 문서는 다음
커밋 — 중간 커밋이 rc=1이 된다.

위험·한계: 검사는 아는 꼴만 잡는다. 걷어낸 뒤 "리뷰·라운드·결정·review·
decision·round·§"로 남은 괄호를 grep으로 다시 읽었다. 새 패턴을 docs/reviews
밖 전체에 돌리면 검사 대상 밖에서 125줄이 새로 걸린다(모듈 README, ADR 등의
실제 ID). 대상 안 오탐은 0이다. 일부러 만든 "line 10-12 (b)" 한 꼴은 오탐이지만
repo에 없다. 이 검사는 CI가 돌리지 않는다. 파생 서비스 tech-log-backend의 같은
문서에 33줄이 있다(대부분 템플릿에서 받은 사본, 고치지 않음).

검증(트리 41e44de0, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/A-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
  lychee 범위 --links rc=0(578파일, 깨짐 0)
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- ./gradlew :adapter:outbound:persistence-mongo:test --tests
  'dev.caskeleton.adapter.outbound.mongo.MongoNamespaceContractTest' --rerun
  rc=0(3건)
2026-11-07 07:02:09 +09:00
DongHyeonka 447a77a35d docs(work): 운영 playbook 시험에서 나온 게이트 실행 빈틈 여섯을 닫는다
문제: 2026-11-07 합친 브랜치 전체 게이트를 매뉴얼만 보고 돌리게 했더니
(1회차 수정 전 매뉴얼) 여섯 곳에서 답이 없었다.
- gates.md 3절 묶음에 main job(configuration-cache, compose smoke,
  http3, notification pr)과 경로 필터 PR lane이 없어 "workflow와 같은
  명령"이 아니었다
- 합친 트리가 어떤 경로 필터 lane을 켜는지 정하는 절차가 없었다
- 집계 태스크 전체가 실제로 돌았음을 보이는 법이 없었다(--rerun은
  앞 태스크 하나만)
- lychee 대체 명령(--links docs)이 lychee 범위보다 좁았고, buf와
  dependency review는 대체 안내가 없었다
- compose bind mount가 tmp/heap-dumps를 root로 만들어 git worktree
  remove가 실패했다
- 결과 기록 형식이 게이트 하나 = Gradle 명령 하나를 가정했다

고른 방법:
- gates.md 3절을 (가) 늘 도는 것, (나) 바뀐 파일로 켜지는 것,
  (다) 로컬 도구가 없는 것으로 나눈다. (가)에 workflow의 run 줄을
  더하고, (나)는 git diff --name-only를 on.pull_request.paths(glob)와
  pr-adapters.yml emit 줄(정규식)에 맞추는 절차로, (다)는 job마다
  로컬 대체와 대체가 못 보는 것을 적은 표로 둔다
- 실제 실행 증명: 새 worktree와 --no-build-cache, 로그의 FROM-CACHE 0
- 링크 검사 대체는 lychee와 같은 glob을 git ls-files로 넘긴다
- operate.md 4.1에 compose down과 root 폴더 지우기 한 줄
- gates.md 4절은 한 줄 = 명령 하나, 여러 명령 job은 순번, 「실제
  실행」 칸
- 처리 표(evidence.md 9절)에 T6 여섯 행
버린 대안: workflow의 모든 job 명령을 gates.md에 옮겨 적기. workflow가
정본이라 옮긴 사본이 낡는다. 경로 필터 lane은 절차만 둔다.

위험·한계:
- (가)의 명령은 workflow의 사본이다. workflow를 바꾸면 이 블록도 고쳐야
  한다
- 경로 필터 맞추기는 손으로 한다. glob을 기계로 맞추는 도구는 없다
- 같은 범위 링크 검사는 지금 rc=1이다. src/README.md와 fileserver·
  objectstorage README의 상대 링크 3건이 기준 커밋부터 깨져 있다(이번
  범위 밖)

검증:
- python3 scripts/check-work-docs.py rc=0. improve.md 141/150,
  delegate.md 121/150, operate.md 131/150, 진입 경로 최대 290/350,
  본문 이력 0줄
- 바꾼 문서를 읽는 테스트: grep 결과 0(delivery-evidence.md 이름만
  걸림)
- desktop: 바꾼 것을 패치로 73d39212 위에 얹어 이 커밋과 같은 트리
  7e28874c를 만들고, flock 아래 :app-bootstrap:documentContractTest
  --rerun --no-build-cache rc=0, 66건 실패 0 건너뜀 0, FROM-CACHE 0,
  직전 1분 부하 5.64. 같은 트리에서 check-work-docs.py rc=0,
  --history docs/manual 16줄 rc=1(기대대로)
  (desktop ~/manual-gap-fix-2-logs/final-*.log)
- 링크 검사(lychee와 같은 범위) rc=1, 깨진 3건은 위 위험·한계의 것
  (desktop ~/manual-gap-fix-2-logs/links-lychee-scope.log)
2026-11-07 00:35:12 +09:00
DongHyeonka 73d39212f5 docs(work): cold-read 시험 1회차의 빈틈과 모순을 매뉴얼에 반영한다
문제: 2026-11-06 이력 없는 세션 6개에 이 매뉴얼만 주고 실제 일을
시켰다. 6개 모두 일은 끝냈지만 매뉴얼에서 답을 못 찾은 곳이 세션마다
1~9건 나왔고, 세 곳은 문서끼리 다르게 말했다.
- 리뷰 README를 누가 쓰나: delegate.md는 총괄, improve.md는 리뷰어
- push: README 4절·decisions.md는 "커밋을 허용하면 push도", 정본
  delegation-loop.md 11절은 brief가 push를 따로 허용해야 한다
- evidence.md 머리말은 "RR-는 1차 재리뷰"라는데 round2도 RR-를 썼다

고른 방법:
- 리뷰어는 README에 자기 라운드 색인 절 하나만 쓰고, 처리 표·결정의
  답·게이트 기록은 총괄이 쓴다(improve.md 4.1, delegate.md 4.2,
  decisions.md 2.1)
- 커밋과 push는 brief 7절이 따로 허용한다. 커밋만 허용되면 push하지
  않는다. push 없이도 패치와 트리 해시로 desktop에서 검증한다
  (operate.md 4.1 「push 전에 검증하기」). 이 방법은 커밋 본문에
  desktop 결과를 넣으려는 세션의 빈틈도 닫는다
- evidence.md 머리말을 접두어별 문서로 고친다
- 나머지 빈틈은 그 일을 하는 playbook의 절차 단계나 자주 하는 실수,
  reference에 한 줄씩 넣는다. 36행 처리 표는 evidence.md 9절이다
  (고침 35, 고치지 않음 1: 새 매뉴얼에 이미 답이 있던 것)
버린 대안: push를 "커밋 허용이면 push도"로 읽기. 정본 11절과 실제
brief(백엔드는 push, design-docs는 push 안 함)가 push를 따로 다룬다.
버린 대안: 빈틈을 모두 자주 하는 실수에 넣기. 10줄 상한을 넘고, 절차의
한 단계인 것은 그 단계에 있어야 읽힌다.

위험·한계:
- 리뷰 README 분담, push를 따로 읽는 것, 하위 세션 Slack은 기본값이다.
  소유자가 뒤집을 수 있게 decisions.md에 기본값으로 적었다
- AGENTS.md의 커밋 예외 문장은 이번 범위 밖이라 그대로다. 세부는 이
  README 4절을 가리키므로 README가 정한다
- 고친 매뉴얼은 2회차 cold-read 시험 전이다

검증:
- python3 scripts/check-work-docs.py rc=0. 지도 73/120, README 76/80,
  improve.md 134/150, 진입 경로 최대 283/350, 본문 이력 0줄
- python3 scripts/check-work-docs.py --links docs CLAUDE.md 결과 링크
  432개, 깨진 것 0
- desktop: 바꾼 것을 패치로 기준 커밋 2c8a359d 위에 얹어 노트북과 같은
  트리 3d0e5900을 만들고 flock 아래
  :app-bootstrap:documentContractTest --rerun rc=0, 66건 실패 0
  건너뜀 0, 13초, 직전 1분 부하 3.13
  (desktop ~/manual-gap-fix-1-logs/documentContractTest.log)
2026-11-06 23:18:47 +09:00
DongHyeonka 06f520e667 docs(work): 성능 lane 단언 강제와 캐시 결과의 한계를 매뉴얼에 맞춘다
문제: 성능 lane 단언을 빌드가 강제하게 된 뒤에도 docs/work/는 옛 동작을
안내했다. gates.md 5절은 "desktop에서 -Pperformance.assertions.enabled=true를
준다. 안 주면 httpclient의 시간 단언 없이 통과한다"고 했고, 3절 라운드 끝
명령과 improve.md·operate.md의 「자주 하는 실수」도 그 속성을 맞추라고 했다.
지금은 convention이 단언을 켜고 true 아닌 값이나 skip이 있으면 테스트 전에
실패하므로, 그 문장은 틀렸고 그 속성은 필요 없다. 또 2026-11-06 B3 desktop
ci rc=0은 캐시 결과(태스크 701개 중 403개)였는데, 그 사이 httpclient
CircuitBreakerStatusAccountingTest 2건은 기준 커밋에서도 10번 중 10번 실패하고
있었다. 캐시 결과를 현재 통과의 증거로 쓰면 이런 기존 결함을 놓친다.

고른 방법:
- gates.md 5절을 새 동작으로 다시 쓰고(정본 AGENTS.md 「Gradle 정책 권위」,
  docs/testing/TESTING_STRATEGY.md), 1절 표와 6절 거짓 통과 표를 맞췄다.
  3절 명령에서는 그 속성을 뺐다. workflow도 이제 주지 않는다.
- improve.md의 같은 실수 줄은 지웠다. 빌드가 막으므로 더는 실수가 아니다.
- operate.md 「자주 하는 실수」의 그 줄 자리에 캐시 교훈을 넣었다: 기준 상태와
  시간·환경에 민감한 테스트는 그 태스크를 --rerun으로 다시 돌린다. gates.md
  6절에도 한 줄, 근거는 evidence.md 2절, 결정은 decisions.md 2.7, 장치는
  defect-patterns.md A7에 더했다.

위험·한계: --rerun은 지정한 태스크 하나만 다시 돈다. 집계 태스크 전체를 캐시
없이 돌리려면 --rerun-tasks가 필요하고 시간이 훨씬 길다. 이 매뉴얼은 그 둘을
가르는 기준까지는 정하지 않았다.

검증
- python3 scripts/check-work-docs.py: rc=0, 본문 이력 ID 0줄, improve.md
  131/150, operate.md 115/150
- python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md
  AGENTS.md: 깨진 링크 0
2026-11-06 21:30:26 +09:00
DongHyeonka 63c63413d1 docs(work): 지도와 작업 종류별 playbook으로 작업 매뉴얼을 만든다
문제: 이 repo의 진입 문서는 아키텍처 규칙을 길게 다시 쓴 CLAUDE.md(183줄)와
리뷰·수정만 다루는 옛 개선 매뉴얼(진입 717줄, 미병합)이었다. 이력 없는 세션이
"이 일이면 무엇을 읽나"를 알 수 없었고, 새 기능·조사·문서·운영·총괄의 절차는
없었다. 규칙도 서로 달랐다: 하위 에이전트(AGENTS.md는 권함, 소유자는 금지),
커밋(human-only와 브랜치 커밋 허용), 리뷰 멈춤 기준(거둔 기준이 남음).

고른 방법(2026-11-06 소유자 결정 D1, D2, D4, D12; 설계 design-docs
delegation-loop/02-design.md 4~6·10절):
- CLAUDE.md를 72줄 지도로 바꿨다: 이 repo, HARD-STOP 7개 한 줄씩(정본
  AGENTS.md), 일 → playbook 표, 검증 명령과 실행 위치, 코드만 보고는 헷갈리는
  곳, 소유자 환경 포인터. AGENTS.md를 요약하던 절은 지웠다. AGENTS.md에 없던
  내용은 옮겼다: messaging 예외는 지도 5절, 판단 보고 규칙은
  reference/review-criteria.md 11절, 위험 비례 원칙은 docs/work/README.md 2절.
- docs/work/: README(라우터·크기·공통 단계·커밋·막혔을 때·보고), playbook 6개
  (new-feature, improve, research-design, docs-writing, operate, delegate, 모두
  같은 9칸 뼈대), reference/ 4개(gates, review-criteria, defect-patterns,
  decisions), evidence.md. 옛 매뉴얼 03~06장은 reference/를 늘리지 않고
  review-criteria(점검 기준), defect-patterns(막는 기준), gates(성능 lane)에
  나눠 넣었다. 다섯 번째 reference 파일은 설계의 파일 구성과 달라 버렸고,
  improve.md 본문에 넣는 안은 150줄 상한을 넘어 버렸다.
- improve.md에 수정 보고의 「새로 가정하는 것」 칸(확인 리뷰가 여기서 시작)과
  수정 묶음 상한(영역 하나·발견 8건, 확인 리뷰당 추가 1,500줄)을 넣었다. 지난
  수정 커밋의 추가 줄과 다음 확인 리뷰 발견 수(+906→9, +1,877→7, +5,420→25,
  +13,479→29)가 근거다(evidence.md 3절). 멈춤 기준은 "발견 0"으로 하나만 둔다.
- 커밋: AGENTS.md human-only는 두고 "brief가 허용할 때만 자기 브랜치에" 예외를
  README 4절과 AGENTS.md에 같은 말로 적었다.
- 본문 이력 ID 0. 지난 리뷰 ID와 사건은 evidence.md와 두 색인
  (reference/decisions.md, reference/defect-patterns.md)에만 둔다.
- 연결: README.md(HARD-STOP을 "8개"로 잘못 적은 것도 7개로), docs/README.md,
  docs/manual/README.md(입구 연결), docs/manual/02-new-feature.md(지운
  CLAUDE.md 「Layer workflow」를 가리키던 줄).

위험·한계: 이 매뉴얼은 이력 없는 새 세션으로 시험(cold-read)하기 전이라
초안이다. 정식 시험은 총괄이 따로 한다. 작성 중 자가 점검(지도부터 읽어
docs-writing.md로 brief 하나를 써 봄)에서 막힌 네 곳은 고쳤다. docs/manual/
본문에는 아직 이력 ID 9줄이 남아 있다(범위 밖, 후속 작업). gates.md 5절의
성능 단언 속성 문장은 성능 게이트를 고치는 다른 작업과 겹친다.

검증
- python3 scripts/check-work-docs.py: rc=0. 지도 72/120, README 75/80,
  playbook 79~132/150, 진입 경로 최대 279/350, 본문 이력 ID 0줄
- python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md
  AGENTS.md: 504파일, 상대 링크 447개, 깨진 것 0
- CLAUDE.md를 읽는 테스트 DeveloperExperienceContractTest
  .guidanceNamesTheArchitectureSourceSetTask가 기대하는
  "./gradlew :app-bootstrap:architectureTest"를 지도에 남겼다. Gradle 게이트는
  이 커밋을 push한 뒤 desktop에서 돌린다
2026-11-06 19:58:44 +09:00