문제: 성능 lane의 기계 의존 상한(httpclient 스트리밍 힙 증가, Mongo 시간 gate)이 performance.assertions.enabled 뒤에 있었고 기본값이 자리마다 달랐다(httpclient build false, Mongo build true, Mongo 테스트 코드 false). workflow만 GRADLE_OPTS로 켰다. 그래서 desktop에서 손으로 돌린 ./gradlew :performanceCheck가 httpclient 힙 상한을 재지 않고 통과했다 (2026-11-05 r10 게이트). JPA pool lane도 전에 같은 속성 뒤에서 아무 상한도 비교하지 않았다(PoolLaneClaimTest). 방법: 규칙을 build-logic strict-lane convention 한 곳에 둔다. - PERFORMANCE lane 테스트 JVM에 performance.assertions.enabled=true를 넣는다. 빌드(-P, GRADLE_OPTS)나 lane(systemProperty, jvmArgs, task 설정)이 true 아닌 값을 주면 테스트 전에 실패하고, 지우거나 true로 바꾸라고 알려 준다. true는 받아 준다(파생 서비스 workflow가 넘긴다). - PERFORMANCE lane은 skip된 테스트가 있으면 실패한다. - httpclient·Mongo 테스트는 조건 없이 단언하고 잰 값을 한 줄 남긴다. 두 leaf의 속성 선언과 integration-main·release workflow의 GRADLE_OPTS 줄을 지웠다. 사람과 workflow가 같은 명령을 쓴다. verifyStrictLaneStages가 읽는 run: 줄은 그대로다. 버린 대안: 두 leaf 기본값만 true로(정의가 leaf마다 남아 다음 lane이 다시 복사한다), 속성 삭제만(옛 속성을 기본값 false로 읽는 파생 서비스 테스트가 조용히 건너뛴다), 측정 전용 태스크(쓸 곳이 없다: 숫자만 볼 때는 JMH, 실패한 단언과 매 실행 출력이 값을 남긴다). 같은 원인으로 함께 고친 문서: httpclient support-matrix·release-checklist의 없는 lane 이름 spring62CompatibilityTest와 빠진 main push 주기. 위험·한계: 손으로 돌린 performanceCheck가 이제 상한을 실제로 재므로 느린 기계에서는 실패할 수 있다. JVM 인자 공급자(jvmArgumentProviders)가 넣는 -D는 보지 않는다. Docker가 없을 때 skip되는 통합·시스템 lane은 지금 모두 실패한다(전부 skip이면 executed no test, 아니면 skip 안 되는 컨테이너 테스트가 실패) — 거짓 통과가 아니어서 고치지 않았다. 검증(desktop ~/b4-logs, flock 아래, 노트북과 같은 트리 — git diff sha256 일치): - RED(고치기 전 트리 + 새 테스트): build-logic 새 테스트 4건이 UnexpectedBuildSuccess로 실패 — aPerformanceLaneFailsOnAnExceededBound WhenTheBuildSetsNoAssertionsProperty, …FailsBeforeTestingWhenTheBuild TurnsItsAssertionsOff, …FailsWhenItsOwnDeclarationTurnsTheAssertionsOff, …FailsWhenOneOfItsTestsIsSkipped. jvmArgs 경로(…FailsWhenItsJvmArguments TurnTheAssertionsOff)도 같은 실패. 실제 lane: 속성 없이 httpClientPerformanceTest rc=0인데 "skipped machine-dependent bound" 출력. - GREEN: -p build-logic check javadoc rc=0. :performanceCheck rc=0(lane 5개 테스트 26, skip 0; httpclient 힙 증가 5,243,880 B / 상한 16,777,216 B, Mongo p50·p95·p99 1ms, examined/returned 1.0, pool 대기 0). -p optional-platforms performanceCheck rc=0(grpc 1). 두 명령에 -Pperformance.assertions.enabled=false → rc=1, 6개 lane 모두 테스트 전 실패. =true → rc=0. verifyStrictLaneStages --dry-run 두 빌드 rc=0, architectureCheck rc=0, ci·mainCheck·integrationCheck·releaseCheck· performanceCheck --dry-run --configuration-cache rc=0, :mainCheck --continue --warning-mode=fail rc=0, -p optional-platforms ci rc=0, persistence-mongo:check rc=0, verify-httpclient-docs.py rc=0. - 이 변경 밖 실패: :ci :verifyDependencyLocks --continue와 httpclient:check가 CircuitBreakerStatusAccountingTest JDK 2건으로 rc=1. 기준 커밋 3d73b6f1에서도 10/10 실패(이 트리도 10/10). ci의 다른 task는 모두 통과했다. Refs: docs/upgrade/2026-11-maturity-review.md B-43, docs/testing/TESTING_STRATEGY.md 6절 BREAKING CHANGE: PERFORMANCE lane은 performance.assertions.enabled가 true가 아니거나 skip된 테스트가 있으면 실패한다. 자기 성능 lane의 그 속성 선언(false)과 skip을 없앤다.
docs
저장소의 모든 문서는 이 디렉터리 아래에 있다. 어떤 문서를 어디에 두는지가 유일한 규칙이고, 파일 목록은 디렉터리를 직접 읽는다. 개수를 여기에 적으면 다음 문서가 추가되는 순간 틀린 글이 된다.
어댑터별 운영 문서
각 어댑터의 지원 범위, 설정, 보안, 운영, 마이그레이션 문서다. 코드와 함께 갱신되어야 하는 문서이고,
docs/httpclient/ 는 scripts/verify-httpclient-docs.py 가 코드에서 뽑은 이름과 대조한다.
| 디렉터리 | 대상 |
|---|---|
fileserver/ |
파일 서버 어댑터 |
httpclient/ |
HTTP 클라이언트 플랫폼 |
jpa/ |
JPA·PostgreSQL 영속성 |
messaging/ |
메시징 어댑터 |
mongodb/ |
MongoDB 문서 영속성 (advanced/, runbooks/ 포함) |
notification/ |
알림 전달 플랫폼 (adr/ 포함) |
redis/ |
Redis 캐시·세션 |
횡단 문서
| 디렉터리 | 대상 |
|---|---|
adr/ |
아키텍처 결정 기록 |
architecture/ |
공개 API 표면 스냅숏 |
manual/ |
개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(scripts/new-feature.sh) |
evidence/ |
작업 단계별 증거·체크포인트 |
registries/ |
env 키·에러 코드·메트릭·헤더 등 레지스트리 SSOT |
reviews/ |
모듈 코드 리뷰 결과 |
runbooks/ |
장애 코드별 대응 런북 (template.md 기준) |
security/ |
공개 경로 스냅숏 |
설계와 계획
| 디렉터리 | 대상 |
|---|---|
superpowers/specs/ |
설계서. YYYY-MM-DD-<주제>-design.md |
superpowers/plans/ |
구현·확장 계획서. YYYY-MM-DD-<주제>-plan.md |
superpowers/packages/ |
외부에서 납품된 설계 패키지의 README와 정적 검증 결과 |
superpowers/packages/<어댑터>/ 는 설계서가 처음 전달됐을 때의 안내와 VALIDATION.md 검증 이력을
남긴 기록 보관소다. 설계서·계획서 본문은 전부 specs/ 와 plans/ 에 있으므로 이 디렉터리에서
문서를 찾을 필요는 없다. 각 README 상단의 보존 안내가 무엇이 옮겨졌고 무엇이 제거됐는지 밝힌다.
계획서 본문에는 당시 계획한 경로와 명령이 그대로 남아 있다. 그중 일부는 실제 구현에서 다른 위치로
조정됐고, 저장소에 어떻게 대응시켰는지는 각 어댑터의 repository-adaptation.md 또는
module-mapping.md 가 기록한다. 계획서를 사후에 고치지 않는 이유는 그렇게 하면 계획의 기록이 아니라
결과를 계획처럼 보이게 만든 글이 되기 때문이다.
여기에 없는 것
- 실행되는 검증 스크립트는 문서가 아니다.
scripts/와.github/scripts/에 있다. - 모듈 레지스트리·Gradle 정책은
src/config/architecture/modules.json과src/build.gradle이 소유한다. - 각 모듈의 지역 규칙은 해당 모듈의
src/**/CLAUDE.md가 소유한다.