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
This commit is contained in:
DongHyeonka
2026-11-06 21:30:26 +09:00
parent 59307afe3e
commit 06f520e667
6 changed files with 15 additions and 11 deletions
+2 -1
View File
@@ -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.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` 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절 | | 보고한 태스크가 로그에 있는지 확인 (`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) | 알림·파일 서버를 한 묶음(r2-05a)으로 묶었다가 마감 안에 검증 보고가 오지 않아 합치지 못했다. 다음 라운드(r3-a)에 다시 올려 합쳤다 | `1101` README 14.3절, 16절 |
| 두 묶음이 같은 파일을 건드리지 않게 (`delegate.md` 4.2) | 2라운드 묶음 r2-06이 10개 파일 충돌로 처음부터 다시 작업했다 | `1101` README 14.1절 | | 두 묶음이 같은 파일을 건드리지 않게 (`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절 | | 전 leaf import를 바꾸는 묶음은 마지막에 혼자 (`improve.md` 6절, `delegate.md` 4.2) | r3-G | `1101` README 15.1절 |
-1
View File
@@ -128,5 +128,4 @@
- 색인을 손으로 옮기다 발견이 빠진다. 색인 검사 스크립트를 돌린다. - 색인을 손으로 옮기다 발견이 빠진다. 색인 검사 스크립트를 돌린다.
- 보고에 없는 태스크 이름을 적는다. 로그에서 태스크 이름을 grep해 확인한다. - 보고에 없는 태스크 이름을 적는다. 로그에서 태스크 이름을 grep해 확인한다.
- 성능 lane을 workflow와 다른 속성으로 돌린다. [reference/gates.md](reference/gates.md) 「성능 lane」을 따른다.
- 묶음별 검증으로 합친 트리 검증을 대신한다. 라운드 끝 게이트를 따로 돌린다. - 묶음별 검증으로 합친 트리 검증을 대신한다. 라운드 끝 게이트를 따로 돌린다.
+1 -1
View File
@@ -112,4 +112,4 @@ git worktree remove ~/workspace/<작업 이름>
- desktop 기존 checkout에서 브랜치를 바꿔 다른 세션의 작업을 방해한다. 자기 worktree를 만든다. - desktop 기존 checkout에서 브랜치를 바꿔 다른 세션의 작업을 방해한다. 자기 worktree를 만든다.
- 짧게 끝난 실행을 통과로 적는다. 캐시 재사용인지, 태스크가 실제로 돌았는지 로그로 확인한다. - 짧게 끝난 실행을 통과로 적는다. 캐시 재사용인지, 태스크가 실제로 돌았는지 로그로 확인한다.
- performance lane을 workflow와 다른 속성으로 돌린다. [reference/gates.md](reference/gates.md) 5절을 따른다. - 빌드 캐시에서 가져온 테스트 결과를 지금 이 환경에서 통과한 증거로 쓴다. 기준 상태를 확인하거나 시간·환경에 민감한 테스트를 볼 때는 그 태스크를 `--rerun`으로 다시 돌린다.
+1
View File
@@ -152,6 +152,7 @@
| 테스트 코드 정적 분석 | `testQualityCheck`는 main 빌드 `mainCheck`, optional 빌드 `ci` | 위임 | `1103` 14절 | | 테스트 코드 정적 분석 | `testQualityCheck`는 main 빌드 `mainCheck`, optional 빌드 `ci` | 위임 | `1103` 14절 |
| lane 정책과 캐시 | lane 정책 값(`rejectSkipped` 등)은 모두 캐시 입력 | 위임 | `1103` 4절(RR-06-02) | | lane 정책과 캐시 | lane 정책 값(`rejectSkipped` 등)은 모두 캐시 입력 | 위임 | `1103` 4절(RR-06-02) |
| workflow 명령의 빌드 판정 | 같은 셸의 `cd <상대 경로>`도 따라간다 | 소유자 | `1103` 15절 ② | | 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 정책 권위」 | | 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `AGENTS.md` 「Gradle 정책 권위」 |
| MinIO 이미지 | `pgsty/minio` digest | 위임 | `1101` 15절(05-09) | | MinIO 이미지 | `pgsty/minio` digest | 위임 | `1101` 15절(05-09) |
| Jackson 2 | 기본 jar에 남김(logstash encoder·springdoc 요구) | 위임 | `1101` 15절(09-11) | | Jackson 2 | 기본 jar에 남김(logstash encoder·springdoc 요구) | 위임 | `1101` 15절(09-11) |
+1 -1
View File
@@ -51,7 +51,7 @@
- **모양**: 어떤 단계도 돌리지 않는 lane·검사, 캐시가 옛 결과로 통과, 실패를 막지 못하는 workflow 명령을 실행으로 셈, 시간 단언을 끈 채 돈 performance lane. - **모양**: 어떤 단계도 돌리지 않는 lane·검사, 캐시가 옛 결과로 통과, 실패를 막지 못하는 workflow 명령을 실행으로 셈, 시간 단언을 끈 채 돈 performance lane.
- **막는 기준**: [gates.md](gates.md) 6절. 게이트 장치를 바꾸면 일부러 망가뜨린 입력으로 실패하는 것을 본다. - **막는 기준**: [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. 로그로 새는 입력값·원인 ### A8. 로그로 새는 입력값·원인
+10 -7
View File
@@ -26,7 +26,7 @@
| `bash scripts/verify-compose-profile-contracts.sh` | compose lane이 선언대로 렌더링되는가(저장소 루트에서) | PR | `ci-quality-gates.yml` | | `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` | | `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 빌드도 | | `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=<sha>` | 릴리스 provenance + 공개 경로 스냅숏. sha 없이 돌리면 설계대로 실패한다 | 태그 | `release.yml` | | `releaseCheck -PgitRevision=<sha>` | 릴리스 provenance + 공개 경로 스냅숏. sha 없이 돌리면 설계대로 실패한다 | 태그 | `release.yml` |
| `:app-bootstrap:verifyEnvKeys` | env 키 레지스트리와 profile YAML·`.env.example` | `mainCheck` 안(`configContractCheck`) | build-logic `ca.config-contract` | | `: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` | | `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 -p optional-platforms :verifyStrictLaneStages --dry-run --console=plain
./gradlew :mainCheck --continue --warning-mode=fail --console=plain ./gradlew :mainCheck --continue --warning-mode=fail --console=plain
./gradlew :integrationCheck --continue --console=plain ./gradlew :integrationCheck --continue --console=plain
./gradlew -p optional-platforms ci integrationCheck performanceCheck -Pperformance.assertions.enabled=true --console=plain ./gradlew -p optional-platforms ci integrationCheck performanceCheck --console=plain
./gradlew :performanceCheck --continue -Pperformance.assertions.enabled=true --console=plain ./gradlew :performanceCheck --continue --console=plain
./gradlew :releaseCheck -PgitRevision="$(git rev-parse HEAD)" --console=plain ./gradlew :releaseCheck -PgitRevision="$(git rev-parse HEAD)" --console=plain
cd .. && bash scripts/verify-compose-profile-contracts.sh cd .. && bash scripts/verify-compose-profile-contracts.sh
``` ```
@@ -98,9 +98,11 @@ cd .. && bash scripts/verify-compose-profile-contracts.sh
## 5. 성능 lane ## 5. 성능 lane
- 일부 performance lane은 시간 단언을 `performance.assertions.enabled` 속성으로 켠다. workflow는 이 값을 `true`로 준다(`integration-main.yml`의 `GRADLE_OPTS`). - performance lane은 상한을 매번 단언한다. 측정만 하고 통과하는 모드는 없다. 정본은 `AGENTS.md` 「Gradle 정책 권위」와 `docs/testing/TESTING_STRATEGY.md`의 PERFORMANCE 문단이다.
- leaf마다 기본값이 다르다: httpclient lane은 `false`(`src/adapter/outbound/httpclient/build.gradle`), persistence-mongo lane은 `true`(`src/adapter/outbound/persistence-mongo/build.gradle`). - strict lane convention이 테스트 JVM에 `performance.assertions.enabled=true`를 넣는다. leaf나 lane은 이 값을 선언하지 않는다.
- 그래서 desktop에서 `performanceCheck`를 돌릴 때는 workflow와 같게 `-Pperformance.assertions.enabled=true`를 준다. 안 주면 httpclient의 시간 단언 없이 통과한다. - 빌드(`-P`, `GRADLE_OPTS`)나 lane이 `true` 아닌 값을 주면 테스트 전에 실패한다. skip된 테스트가 하나라도 있어도 실패한다. `-Pperformance.assertions.enabled=true`는 받지만 줄 필요가 없다.
- 그래서 desktop에서 손으로 돌리는 `./gradlew performanceCheck`와 workflow가 같은 상한을 단언한다.
- 판정 없이 숫자만 보려면 JMH가 있는 leaf의 `./gradlew :<leaf>:jmh`를 쓴다. 게이트가 아니다.
- 시간 단언은 다른 빌드가 돌지 않는 머신에서만 뜻이 있다. 그래서 performance lane은 PR·main 단계가 아니라 `performanceCheck`에 있다. - 시간 단언은 다른 빌드가 돌지 않는 머신에서만 뜻이 있다. 그래서 performance lane은 PR·main 단계가 아니라 `performanceCheck`에 있다.
회귀를 막는 장치: 회귀를 막는 장치:
@@ -123,7 +125,8 @@ cd .. && bash scripts/verify-compose-profile-contracts.sh
| lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | lane 정책 값을 Test 입력으로 | | lane 정책을 바꿨는데 캐시가 옛 결과로 통과 | lane 정책 값을 Test 입력으로 |
| 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) | | 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) |
| 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 | | 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 |
| 시간 단언을 끈 채 performance lane 실행 | 5절 속성 | | 시간 단언을 끈 채 performance lane 실행 | convention이 단언을 켜고, 끄는 값이나 skip이 있으면 테스트 전에 실패(5절) |
| 캐시에서 가져온 결과를 지금 통과한 것으로 셈 | 기준 상태 확인과 시간·환경에 민감한 테스트는 그 태스크를 `--rerun`으로 다시 돌린다 |
| 외부 이미지가 사라져 다른 lane 결과까지 가림 | 테스트 이미지를 `src/config/testing/container-images.properties` 한 곳에 digest로 고정, main 단계는 `--continue` | | 외부 이미지가 사라져 다른 lane 결과까지 가림 | 테스트 이미지를 `src/config/testing/container-images.properties` 한 곳에 digest로 고정, main 단계는 `--continue` |
게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다. 게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다.