From 06f520e6673919ac2fdb2df05729b8f92e82cf5a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 21:30:26 +0900 Subject: [PATCH] =?UTF-8?q?docs(work):=20=EC=84=B1=EB=8A=A5=20lane=20?= =?UTF-8?q?=EB=8B=A8=EC=96=B8=20=EA=B0=95=EC=A0=9C=EC=99=80=20=EC=BA=90?= =?UTF-8?q?=EC=8B=9C=20=EA=B2=B0=EA=B3=BC=EC=9D=98=20=ED=95=9C=EA=B3=84?= =?UTF-8?q?=EB=A5=BC=20=EB=A7=A4=EB=89=B4=EC=96=BC=EC=97=90=20=EB=A7=9E?= =?UTF-8?q?=EC=B6=98=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 성능 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 --- docs/work/evidence.md | 3 ++- docs/work/improve.md | 1 - docs/work/operate.md | 2 +- docs/work/reference/decisions.md | 1 + docs/work/reference/defect-patterns.md | 2 +- docs/work/reference/gates.md | 17 ++++++++++------- 6 files changed, 15 insertions(+), 11 deletions(-) diff --git a/docs/work/evidence.md b/docs/work/evidence.md index 2c2fe750..0beb7a9d 100644 --- a/docs/work/evidence.md +++ b/docs/work/evidence.md @@ -43,7 +43,8 @@ | 색인은 기계로 대조한다 (`improve.md` 4.1) | 원래 리뷰 색인이 119건이었다. 06 영역 문서의 `NN-10`~`NN-14` 5건이 색인과 모든 수정 묶음에서 빠졌다. 실제는 124건 | `1101` README 12절 정정, `1103` README 1절, `1103/RR-05-10` | | 「새로 가정하는 것」 칸, 수정 묶음 크기 상한 (`improve.md` 4.4, 8절) | round6 발견 25건 중 17건(68%)을 직전 수정 커밋이 만들었다. 짝 프론트 1106 리뷰도 25건 중 16건(64%) | `01-research.md` 4.3절, design-docs `delegation-loop/02-design.md` 4.3절 | | 보고한 태스크가 로그에 있는지 확인 (`improve.md` 9절, `gates.md` 4절) | 묶음 보고가 없는 태스크 `:adapter:outbound:persistence-jpa:documentContractTest`를 적었다 | `1103` README 17.2절 | -| 성능 lane은 workflow와 같은 단언 속성으로 (`gates.md` 5절) | r10 desktop 게이트의 `performanceCheck`가 `-Pperformance.assertions.enabled=true` 없이 돌아, httpclient 시간 단언 없이 통과했다 | desktop `~/r10-logs/gates.sh`, 공유 노트 「백엔드 개선 매뉴얼 인계」 | +| 성능 lane은 상한을 매번 단언하고, 끄는 값은 테스트 전에 실패한다 (`gates.md` 5절) | r10 desktop 게이트의 `performanceCheck`가 `-Pperformance.assertions.enabled=true` 없이 돌아, httpclient 시간 단언 없이 통과했다. 그 전에는 JPA pool lane이 같은 속성 뒤에 숨어 상한을 비교하지 않았다(`PoolLaneClaimTest`). 2026-11-06 빌드가 강제하게 바꿨다 | desktop `~/r10-logs/gates.sh`, `docs/testing/TESTING_STRATEGY.md` PERFORMANCE 문단, 커밋 `e6b6e18e` | +| 캐시에서 가져온 결과는 지금 통과한다는 증거가 아니다. 기준 상태와 시간·환경에 민감한 테스트는 `--rerun`으로 (`operate.md` 9절, `gates.md` 6절) | 2026-11-06 B3 desktop `ci` rc=0은 캐시 결과였다(태스크 701개 중 403개를 캐시에서). 그 사이 httpclient `CircuitBreakerStatusAccountingTest` 2건은 기준 커밋 `3d73b6f1`에서도 10번 중 10번 실패하고 있었다 | desktop `~/b3-logs/ci.log`, 2026-11-06 총괄 전달 | | 묶음을 너무 크게 만들지 않는다 (`delegate.md` 4.2) | 알림·파일 서버를 한 묶음(r2-05a)으로 묶었다가 마감 안에 검증 보고가 오지 않아 합치지 못했다. 다음 라운드(r3-a)에 다시 올려 합쳤다 | `1101` README 14.3절, 16절 | | 두 묶음이 같은 파일을 건드리지 않게 (`delegate.md` 4.2) | 2라운드 묶음 r2-06이 10개 파일 충돌로 처음부터 다시 작업했다 | `1101` README 14.1절 | | 전 leaf import를 바꾸는 묶음은 마지막에 혼자 (`improve.md` 6절, `delegate.md` 4.2) | r3-G | `1101` README 15.1절 | diff --git a/docs/work/improve.md b/docs/work/improve.md index 39f3a8e2..fa655b75 100644 --- a/docs/work/improve.md +++ b/docs/work/improve.md @@ -128,5 +128,4 @@ - 색인을 손으로 옮기다 발견이 빠진다. 색인 검사 스크립트를 돌린다. - 보고에 없는 태스크 이름을 적는다. 로그에서 태스크 이름을 grep해 확인한다. -- 성능 lane을 workflow와 다른 속성으로 돌린다. [reference/gates.md](reference/gates.md) 「성능 lane」을 따른다. - 묶음별 검증으로 합친 트리 검증을 대신한다. 라운드 끝 게이트를 따로 돌린다. diff --git a/docs/work/operate.md b/docs/work/operate.md index 3128b753..de17203d 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -112,4 +112,4 @@ git worktree remove ~/workspace/<작업 이름> - desktop 기존 checkout에서 브랜치를 바꿔 다른 세션의 작업을 방해한다. 자기 worktree를 만든다. - 짧게 끝난 실행을 통과로 적는다. 캐시 재사용인지, 태스크가 실제로 돌았는지 로그로 확인한다. -- performance lane을 workflow와 다른 속성으로 돌린다. [reference/gates.md](reference/gates.md) 5절을 따른다. +- 빌드 캐시에서 가져온 테스트 결과를 지금 이 환경에서 통과한 증거로 쓴다. 기준 상태를 확인하거나 시간·환경에 민감한 테스트를 볼 때는 그 태스크를 `--rerun`으로 다시 돌린다. diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index f0506d09..227e493b 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -152,6 +152,7 @@ | 테스트 코드 정적 분석 | `testQualityCheck`는 main 빌드 `mainCheck`, optional 빌드 `ci` | 위임 | `1103` 14절 | | lane 정책과 캐시 | lane 정책 값(`rejectSkipped` 등)은 모두 캐시 입력 | 위임 | `1103` 4절(RR-06-02) | | workflow 명령의 빌드 판정 | 같은 셸의 `cd <상대 경로>`도 따라간다 | 소유자 | `1103` 15절 ② | +| 성능 lane 단언 | 끄는 스위치 없음. convention이 `performance.assertions.enabled=true`를 넣고, 빌드·lane이 다른 값을 주거나 skip이 있으면 테스트 전에 실패. 손으로 돌리든 workflow든 같은 상한 | 소유자(2026-11-06 병합 승인) | design-docs `delegation-loop/02-design.md` 13절 D9, 커밋 `e6b6e18e`, `AGENTS.md` 「Gradle 정책 권위」 | | 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `AGENTS.md` 「Gradle 정책 권위」 | | MinIO 이미지 | `pgsty/minio` digest | 위임 | `1101` 15절(05-09) | | Jackson 2 | 기본 jar에 남김(logstash encoder·springdoc 요구) | 위임 | `1101` 15절(09-11) | diff --git a/docs/work/reference/defect-patterns.md b/docs/work/reference/defect-patterns.md index 590ff58c..e559218b 100644 --- a/docs/work/reference/defect-patterns.md +++ b/docs/work/reference/defect-patterns.md @@ -51,7 +51,7 @@ - **모양**: 어떤 단계도 돌리지 않는 lane·검사, 캐시가 옛 결과로 통과, 실패를 막지 못하는 workflow 명령을 실행으로 셈, 시간 단언을 끈 채 돈 performance lane. - **막는 기준**: [gates.md](gates.md) 6절. 게이트 장치를 바꾸면 일부러 망가뜨린 입력으로 실패하는 것을 본다. -- **장치**: `verifyStrictLaneStages --dry-run`(두 빌드), lane 정책 값의 캐시 입력 선언, `testQualityCheck`. +- **장치**: `verifyStrictLaneStages --dry-run`(두 빌드), lane 정책 값의 캐시 입력 선언, `testQualityCheck`, 성능 lane 단언 강제(strict lane convention이 `performance.assertions.enabled=true`를 넣고 다른 값·skip은 실패). 캐시에서 가져온 결과는 현재 통과의 증거가 아니다(필요하면 `--rerun`). ### A8. 로그로 새는 입력값·원인 diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md index 4ed57d7b..39bbf98c 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -26,7 +26,7 @@ | `bash scripts/verify-compose-profile-contracts.sh` | compose lane이 선언대로 렌더링되는가(저장소 루트에서) | PR | `ci-quality-gates.yml` | | `mainCheck` | `configContractCheck` + `qualificationCheck`(`testQualityCheck` 포함) + 샘플 실서버 계약 + 샘플 전체 기동(`:sample-portfolio:systemTest`) + 공개 경로 스냅숏 + 전송·메시징 qualification lane + 생성 명령 왕복(`verifyFeatureScaffold`) + 모든 leaf의 `mainCheck`(document-contract lane 등) | main | `integration-main.yml`: `./gradlew :mainCheck --continue --warning-mode=fail` | | `integrationCheck` | 선언된 strict integration lane 전체(실 컨테이너). 입력이 없는 lane은 빼고 이름을 댄다 | main·nightly | `integration-main.yml`, optional 빌드도 | -| `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). main·nightly에서 돈다 | main·nightly | `integration-main.yml`, optional 빌드도. 5절 | +| `performanceCheck` | 선언된 performance lane 전체(부하·종료·풀·자원 한계, 실 서버와 컨테이너). 상한을 매번 단언한다. 손으로 돌리든 workflow든 같은 상한이다 | main·nightly | `integration-main.yml`, optional 빌드도. 5절 | | `releaseCheck -PgitRevision=` | 릴리스 provenance + 공개 경로 스냅숏. sha 없이 돌리면 설계대로 실패한다 | 태그 | `release.yml` | | `:app-bootstrap:verifyEnvKeys` | env 키 레지스트리와 profile YAML·`.env.example` | `mainCheck` 안(`configContractCheck`) | build-logic `ca.config-contract` | | `verifyPublicPathSnapshot` | 기본 공개 경로가 `docs/security/public-paths-snapshot.txt`와 같은가 | `mainCheck`·`releaseCheck` 안 | `src/build.gradle` | @@ -72,8 +72,8 @@ cd src ./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run --console=plain ./gradlew :mainCheck --continue --warning-mode=fail --console=plain ./gradlew :integrationCheck --continue --console=plain -./gradlew -p optional-platforms ci integrationCheck performanceCheck -Pperformance.assertions.enabled=true --console=plain -./gradlew :performanceCheck --continue -Pperformance.assertions.enabled=true --console=plain +./gradlew -p optional-platforms ci integrationCheck performanceCheck --console=plain +./gradlew :performanceCheck --continue --console=plain ./gradlew :releaseCheck -PgitRevision="$(git rev-parse HEAD)" --console=plain cd .. && bash scripts/verify-compose-profile-contracts.sh ``` @@ -98,9 +98,11 @@ cd .. && bash scripts/verify-compose-profile-contracts.sh ## 5. 성능 lane -- 일부 performance lane은 시간 단언을 `performance.assertions.enabled` 속성으로 켠다. workflow는 이 값을 `true`로 준다(`integration-main.yml`의 `GRADLE_OPTS`). -- leaf마다 기본값이 다르다: httpclient lane은 `false`(`src/adapter/outbound/httpclient/build.gradle`), persistence-mongo lane은 `true`(`src/adapter/outbound/persistence-mongo/build.gradle`). -- 그래서 desktop에서 `performanceCheck`를 돌릴 때는 workflow와 같게 `-Pperformance.assertions.enabled=true`를 준다. 안 주면 httpclient의 시간 단언 없이 통과한다. +- performance lane은 상한을 매번 단언한다. 측정만 하고 통과하는 모드는 없다. 정본은 `AGENTS.md` 「Gradle 정책 권위」와 `docs/testing/TESTING_STRATEGY.md`의 PERFORMANCE 문단이다. +- strict lane convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣는다. leaf나 lane은 이 값을 선언하지 않는다. +- 빌드(`-P`, `GRADLE_OPTS`)나 lane이 `true` 아닌 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다. `-Pperformance.assertions.enabled=true`는 받지만 줄 필요가 없다. +- 그래서 desktop에서 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다. +- 판정 없이 숫자만 보려면 JMH가 있는 leaf의 `./gradlew ::jmh`를 쓴다. 게이트가 아니다. - 시간 단언은 다른 빌드가 돌지 않는 머신에서만 뜻이 있다. 그래서 performance lane은 PR·main 단계가 아니라 `performanceCheck`에 있다. 회귀를 막는 장치: @@ -123,7 +125,8 @@ cd .. && bash scripts/verify-compose-profile-contracts.sh | lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | lane 정책 값을 Test 입력으로 | | 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) | | 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 | -| 시간 단언을 끈 채 performance lane 실행 | 5절 속성 | +| 시간 단언을 끈 채 performance lane 실행 | convention이 단언을 켜고, 끄는 값이나 skip이 있으면 테스트 전에 실패(5절) | +| 캐시에서 가져온 결과를 지금 통과한 것으로 셈 | 기준 상태 확인과 시간·환경에 민감한 테스트는 그 태스크를 `--rerun`으로 다시 돌린다 | | 외부 이미지가 사라져 다른 lane 결과까지 가림 | 테스트 이미지를 `src/config/testing/container-images.properties` 한 곳에 digest로 고정, main 단계는 `--continue` | 게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다.