docs(ledger): 흔들린 시험을 장부에 남기고 시간·순서 단언 규칙을 리뷰 기준에 건다 #40

Open
donghyeon.kang wants to merge 2 commits from claude/w2-be-flaky-ledger into main
Owner

무엇을, 왜

2026-11-12~13 사이 백엔드 runner에서 시험 넷이 흔들렸고, desktop에서 하나가 더 흔들렸다. 그 기록은 공유 노트와 세션 메시지에 흩어져 있다. 리뷰 기준의 「타이밍에 기대지 않나」 행은 「스레드 없음」 단언만 본다. 그래서 이번에 흔들린 모양(벽시계 상한, 스레드 시작 순서)이 다시 들어와도 막을 근거가 없다. design-docs CI 계획 FLAKY-1(백엔드 몫)을 한다.

  1. docs/ledger/flaky-tests.jsonl: 흔들림 하나가 한 줄이다. 칸과 범주의 정본은 design-docs ci/manual.md 8.5절이다.

    시험 범주 처음 본 run 고친 PR
    compose smoke local-messaging 기동 concurrency-order 100 #13
    GrpcP1BoundaryWireTest#aSlowCallWithoutAClientDeadline… fixed-time 221 #34
    FailureInjectionContractTest#aSlowDripThroughToxiproxy…[JDK] fixed-time 228 #34
    LiveEventLogContractTest#concurrentWritersAllocateDistinctPositions concurrency-order 260 #39(열림, 병합되면 fixed_by를 채운다)
    JettyAttemptDeadlineTest#aSlowDripExchangeIsAbortedAtTheAttemptDeadline fixed-time desktop(main c7a18ec7 prCheck, 1.68초 > 1.5초) 아직(벽시계 시험 담당 세션에 넘김)
    • .gitattributes에 merge=union을 준다(예측 장부와 같다).
    • scripts/tests/test_ledger.py가 칸 일곱 개, 범주 다섯 값, 날짜 형식을 본다.
    • docs/ledger/README.md에 두 파일을 소개한다.
  2. docs/work/reference/review-criteria.md 「타이밍에 기대지 않나」 행에 두 모양을 더하고 매뉴얼 8.4절을 가리킨다.

    • PR·main 단계 시험의 벽시계 상한 단언
    • 스레드 시작 순서를 결과 순서로 보는 단언
  3. docs/work/reference/gates.md 「원래 있던 실패 가리기」에 세 가지를 더한다.

    • 반복마다 시작 부하를 적는다.
    • runner에서 실패했으면, 그 시각에 desktop 공유 잠금 아래 돈 실행도 적는다. runner는 잠금 밖이라 같은 CPU를 나눠 쓴다.
    • 흔들림으로 판정하면 장부에 한 줄을 더한다. 상한을 늘리거나 재시도를 붙이지 않고 8.4절대로 고친다.

고른 방법과 버린 대안

결정 고른 것 버린 것과 이유
칸 정의 design-docs 매뉴얼 8.5절을 가리킨다 README에 칸 표를 다시 쓰기: 갈라진 복사본이 된다
형식 검사 기존 test_ledger.py에 한 클래스 새 검사 스크립트: PR 단계 documentCheck가 이미 scripts/tests를 돈다
PR #12 HTTP/2 흔들림 넣지 않음 그 PR의 runner run(94·102·115·131)은 모두 cancelled라 시험을 특정할 수 없다

위험과 영향

  • 문서와 검사 스크립트 시험만 바뀐다. Gradle 빌드와 workflow는 그대로다.
  • 장부 줄을 고치려면 형식 검사를 통과해야 한다. 범주는 매뉴얼의 다섯 값으로 제한된다.

검증

명령 결과
scripts/verify.sh docs(노트북) rc=0. scripts/tests 166개 통과
test_ledger.py의 새 시험 변이 확인 첫 줄의 범주를 timing으로 바꾸면 실패, 되돌리면 통과
이 문서를 읽는 Java 시험 없음(git grep -e reference/gates.md -e review-criteria -e ledger/ -- 'src/*.java' 0건)
runner pr / done 이 PR의 run으로 본다

리뷰어가 볼 곳

  • docs/ledger/flaky-tests.jsonl 네 줄의 판정(verdict)이 각 run 기록과 맞는지.
  • gates.md에 더한 문장: runner 실패일 때 desktop 잠금 아래 실행을 적게 한 부분.

관련

  • design-docs ci/03-time-reduction-plan.md FLAKY-1, ci/manual.md 8.3~8.5절
  • PR #34(벽시계 시험 14건 고침), #39(동시 writer)
## 무엇을, 왜 2026-11-12~13 사이 백엔드 runner에서 시험 넷이 흔들렸고, desktop에서 하나가 더 흔들렸다. 그 기록은 공유 노트와 세션 메시지에 흩어져 있다. 리뷰 기준의 「타이밍에 기대지 않나」 행은 「스레드 없음」 단언만 본다. 그래서 이번에 흔들린 모양(벽시계 상한, 스레드 시작 순서)이 다시 들어와도 막을 근거가 없다. design-docs CI 계획 FLAKY-1(백엔드 몫)을 한다. 1. **`docs/ledger/flaky-tests.jsonl`**: 흔들림 하나가 한 줄이다. 칸과 범주의 정본은 design-docs `ci/manual.md` 8.5절이다. | 시험 | 범주 | 처음 본 run | 고친 PR | |---|---|---|---| | compose smoke local-messaging 기동 | concurrency-order | 100 | #13 | | `GrpcP1BoundaryWireTest#aSlowCallWithoutAClientDeadline…` | fixed-time | 221 | #34 | | `FailureInjectionContractTest#aSlowDripThroughToxiproxy…[JDK]` | fixed-time | 228 | #34 | | `LiveEventLogContractTest#concurrentWritersAllocateDistinctPositions` | concurrency-order | 260 | #39(열림, 병합되면 `fixed_by`를 채운다) | | `JettyAttemptDeadlineTest#aSlowDripExchangeIsAbortedAtTheAttemptDeadline` | fixed-time | desktop(main c7a18ec7 prCheck, 1.68초 > 1.5초) | 아직(벽시계 시험 담당 세션에 넘김) | - `.gitattributes`에 `merge=union`을 준다(예측 장부와 같다). - `scripts/tests/test_ledger.py`가 칸 일곱 개, 범주 다섯 값, 날짜 형식을 본다. - `docs/ledger/README.md`에 두 파일을 소개한다. 2. **`docs/work/reference/review-criteria.md`** 「타이밍에 기대지 않나」 행에 두 모양을 더하고 매뉴얼 8.4절을 가리킨다. - PR·main 단계 시험의 벽시계 상한 단언 - 스레드 시작 순서를 결과 순서로 보는 단언 3. **`docs/work/reference/gates.md`** 「원래 있던 실패 가리기」에 세 가지를 더한다. - 반복마다 시작 부하를 적는다. - runner에서 실패했으면, 그 시각에 desktop 공유 잠금 아래 돈 실행도 적는다. runner는 잠금 밖이라 같은 CPU를 나눠 쓴다. - 흔들림으로 판정하면 장부에 한 줄을 더한다. 상한을 늘리거나 재시도를 붙이지 않고 8.4절대로 고친다. ## 고른 방법과 버린 대안 | 결정 | 고른 것 | 버린 것과 이유 | |---|---|---| | 칸 정의 | design-docs 매뉴얼 8.5절을 가리킨다 | README에 칸 표를 다시 쓰기: 갈라진 복사본이 된다 | | 형식 검사 | 기존 `test_ledger.py`에 한 클래스 | 새 검사 스크립트: PR 단계 `documentCheck`가 이미 `scripts/tests`를 돈다 | | PR #12 HTTP/2 흔들림 | 넣지 않음 | 그 PR의 runner run(94·102·115·131)은 모두 cancelled라 시험을 특정할 수 없다 | ## 위험과 영향 - 문서와 검사 스크립트 시험만 바뀐다. Gradle 빌드와 workflow는 그대로다. - 장부 줄을 고치려면 형식 검사를 통과해야 한다. 범주는 매뉴얼의 다섯 값으로 제한된다. ## 검증 | 명령 | 결과 | |---|---| | `scripts/verify.sh docs`(노트북) | rc=0. `scripts/tests` 166개 통과 | | `test_ledger.py`의 새 시험 변이 확인 | 첫 줄의 범주를 `timing`으로 바꾸면 실패, 되돌리면 통과 | | 이 문서를 읽는 Java 시험 | 없음(`git grep -e reference/gates.md -e review-criteria -e ledger/ -- 'src/*.java'` 0건) | | runner `pr / done` | 이 PR의 run으로 본다 | ## 리뷰어가 볼 곳 - `docs/ledger/flaky-tests.jsonl` 네 줄의 판정(`verdict`)이 각 run 기록과 맞는지. - gates.md에 더한 문장: runner 실패일 때 desktop 잠금 아래 실행을 적게 한 부분. ## 관련 - design-docs `ci/03-time-reduction-plan.md` FLAKY-1, `ci/manual.md` 8.3~8.5절 - PR #34(벽시계 시험 14건 고침), #39(동시 writer)
donghyeon.kang added 1 commit 2026-11-13 10:46:50 +00:00
2026-11-12~13 백엔드 runner에서 흔들린 시험은 넷이다. 그런데 기록이 공유
노트와 세션 메시지에 흩어져 있다. 같은 모양(벽시계 상한, 스레드 시작
순서)이 다시 들어와도 리뷰 기준에는 「스레드 없음」 단언만 적혀 있어서
막을 근거가 없다.

- `docs/ledger/flaky-tests.jsonl`: 흔들림 하나가 한 줄이다. 칸과 범주의
  정본은 design-docs `ci/manual.md` 8.5절이다. 첫 네 줄:
  - compose 기동 경쟁(run 100, #13으로 고침)
  - gRPC 서버 deadline(run 221, #34)
  - HTTP client slow drip JDK(run 228, #34)
  - JPA 동시 writer replay 순서(run 260, #39 열림)
  `.gitattributes`에 `merge=union`을 준다. `scripts/tests/test_ledger.py`가
  칸·범주·날짜 형식을 본다.
- review-criteria.md 「타이밍에 기대지 않나」: 벽시계 상한 단언과 스레드
  시작 순서 단언을 더하고, 매뉴얼 8.4절을 가리킨다.
- gates.md 「원래 있던 실패 가리기」: 반복마다 시작 부하를 적게 한다.
  runner 실패면 그 시각에 잠금 아래 돈 desktop 실행도 적는다(runner는
  잠금 밖이다). 흔들림이면 장부에 한 줄을 더하고, 상한을 늘리거나 재시도를
  붙이지 않고 8.4절대로 고친다.

PR #12가 실패했다는 HTTP/2 흔들림은 넣지 않았다. 그 PR의 runner run은
모두 cancelled라 어느 시험인지 특정할 수 없다.

검증: scripts/verify.sh docs(노트북) rc=0. test_ledger의 새 시험이 잘못된
범주를 잡는지 한 줄을 바꿔 실패를 확인하고 되돌렸다.

Refs: design-docs ci/03-time-reduction-plan.md FLAKY-1
donghyeon.kang added 1 commit 2026-11-13 11:42:24 +00:00
desktop에서 main c7a18ec7의 prCheck를 돌렸을 때(시작 부하 11~15)
JettyAttemptDeadlineTest#aSlowDripExchangeIsAbortedAtTheAttemptDeadline이
1.68초로, 상한 1.5초를 넘어 실패했다. #34가 고친 벽시계 시험 범위 밖에 남은
것이다. 고치는 일은 벽시계 시험을 맡은 쪽에 넘겼다.

검증: python3 -m unittest scripts/tests/test_ledger.py 통과.
All checks were successful
pr / done (pull_request) Successful in 13m24s
Required
Details
This pull request is blocked because it's outdated.
You are not authorized to merge this pull request.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin claude/w2-be-flaky-ledger:claude/w2-be-flaky-ledger
git checkout claude/w2-be-flaky-ledger
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#40