docs(ci): 단계·job 설명과 링크 검사 범위를 지금 workflow에 맞춘다 #18

Merged
donghyeon.kang merged 2 commits from claude/w2-be-ci-perf-3 into main 2026-11-12 16:59:59 +00:00
Owner

무엇을, 왜

round9 확인 리뷰에서, CI 파일과 게이트 문서의 설명 가운데 실제 workflow·빌드와 다른 곳이 나왔다. 이 PR은 그 지적 일곱 건을 고친다. 그중 하나는 검사 범위가 틀린 결함이고, 여섯은 설명이 틀린 것이다.

  1. lychee 링크 검사 범위(main.yml links): 범위에 src/**/CLAUDE.md가 있다.
    • 폴더 규칙이 같은 폴더의 AGENTS.md로 옮겨 간 뒤, CLAUDE.md에는 @AGENTS.md 한 줄만 남았다. 그래서 이 파일에는 링크가 하나도 없다.
    • 정작 외부 URL이 있는 src/**/AGENTS.md는 범위 밖이다. 그 링크가 죽어도 어떤 단계도 알아채지 못한다.
    • 범위를 src/**/AGENTS.md로 바꾼다. 범위를 고정하는 DeveloperExperienceContractTest와 gates.md 2절 문장도 함께 바꾼다.
  2. verify.sh 머리 표: PR 단계 job 이름이 gradle로 적혀 있다. 실제 이름은 done이다.
  3. build.gradle 주석 두 곳:
    • JMH가 「세 leaf」에 있다고 적혀 있다. 실제로는 플러그인을 적용한 leaf에 있다.
    • verifyFeatureScaffold가 「leaf 다섯」을 본다고 적혀 있다. 실제로는 그 안의 architectureCheck가 모든 leaf의 architecture lane을 부른다.
  4. release.yml release job 주석: 「ci를 다시 돌리지 않는다」고 적혀 있다. 그런데 뒤의 job들은 ci가 이미 돈 시험 일부를 다시 돈다. 다시 도는 이유를 적었다. job 구성은 그대로다.
  5. gates.md redis-topology 줄: desktop에서 그대로 돌리라고 하지만, 스크립트 안의 ./gradlew는 daemon을 남긴다. desktop에서는 GRADLE_OPTS=-Dorg.gradle.daemon=false를 붙이라고 적었다.
  6. redis-sdk compose README: cache-redis 칸의 필수 클래스가 두 개뿐이다. build.gradle의 standalone·cluster 목록에 맞춰 다섯 개로 늘렸다.
  7. template-vs-consumer.md 두 곳:
    • object-storage-aws가 nightly job으로 적혀 있다. 실제로는 손으로 실행하면서 입력 run_protected_aws를 켤 때만 돈다.
    • 최상위 항목을 더할 때 「AGENTS.md 지도도 고친다」고 적혀 있다. 실제로는 check-repo-layout.py 허용 목록을 고치고, src/ 최상위 폴더일 때만 지도의 src/ 줄을 고친다.

고른 방법과 버린 대안

결정 고른 것 버린 것과 이유
lychee 범위 src/**/CLAUDE.md를 src/**/AGENTS.md로 바꾼다 두 패턴을 다 두기: 링크 없는 파일을 매번 읽을 뿐이다
release 재실행 주석으로 이유를 적는다(지원 문서가 job id로 부르는 릴리스 증거이고, 이미지 job이 모든 job을 needs로 받아 같은 run·같은 커밋에서 통과한 뒤 publish한다) 재실행 job 빼기: 지원 문서와 이미지 job의 needs가 그 job id에 기대므로 계약이 바뀐다
redis-topology daemon 문서에 GRADLE_OPTS를 적는다 스크립트에 --no-daemon 넣기: CI는 한 job 안의 step 11개가 daemon을 다시 쓴다(#15)

위험과 영향

  • lychee가 새로 보는 외부 링크는 하나다. messaging-kafka AGENTS.md의 Gitea 링크이고, 익명 GET이 200을 돌려준다. 병합 뒤 main push의 links job에서 확인한다.
  • 나머지 여섯은 주석과 문서만 바꾼다. workflow·스크립트의 동작은 그대로다.

검증

명령 커밋 rc 비고
desktop scripts/verify.sh pr --no-cache 3272faeb(트리 aea9e3bc, 시작 부하 12.6) 0 :prCheck 6분 34초, 527 태스크 전부 실행, FROM-CACHE 0. 시험 6,724개, 실패 0, DeveloperExperienceContractTest 포함. 로그 desktop ~/claude-w2-be-ci-perf-3-logs/pr.log
scripts/verify.sh docs(노트북) 3272faeb 0
runner pr / done(run 153) 3272faeb 초록 11.6분. :prCheck 10분 29초(527 태스크 중 캐시 8), Trivy DB 캐시 hit

base인 새 main(ca1fbfde)의 트리는 이 브랜치의 기준 커밋 13ed3a1d와 같다(9f1f746f). 그래서 위 실행이 이 PR의 diff를 그대로 검증한다.

리뷰어가 볼 곳

  • .gitea/workflows/main.yml links의 args와 DeveloperExperienceContractTest의 목록이 같은지.
  • .gitea/workflows/release.yml release job 아래 주석이 뒤 job들과 맞는지.

관련

  • round9 확인 리뷰(공유 노트 r9-be/wave1-r4.md 「넘길 것 → 백엔드 CI 세션」 2~8번. 1번은 #15에서 고쳤다)
  • PR #15, 공유 노트 w2-be-ci-perf.md
## 무엇을, 왜 round9 확인 리뷰에서, CI 파일과 게이트 문서의 설명 가운데 실제 workflow·빌드와 다른 곳이 나왔다. 이 PR은 그 지적 일곱 건을 고친다. 그중 하나는 검사 범위가 틀린 결함이고, 여섯은 설명이 틀린 것이다. 1. **lychee 링크 검사 범위**(`main.yml` `links`): 범위에 `src/**/CLAUDE.md`가 있다. - 폴더 규칙이 같은 폴더의 `AGENTS.md`로 옮겨 간 뒤, `CLAUDE.md`에는 `@AGENTS.md` 한 줄만 남았다. 그래서 이 파일에는 링크가 하나도 없다. - 정작 외부 URL이 있는 `src/**/AGENTS.md`는 범위 밖이다. 그 링크가 죽어도 어떤 단계도 알아채지 못한다. - 범위를 `src/**/AGENTS.md`로 바꾼다. 범위를 고정하는 `DeveloperExperienceContractTest`와 `gates.md` 2절 문장도 함께 바꾼다. 2. **`verify.sh` 머리 표**: PR 단계 job 이름이 `gradle`로 적혀 있다. 실제 이름은 `done`이다. 3. **`build.gradle` 주석 두 곳**: - JMH가 「세 leaf」에 있다고 적혀 있다. 실제로는 플러그인을 적용한 leaf에 있다. - `verifyFeatureScaffold`가 「leaf 다섯」을 본다고 적혀 있다. 실제로는 그 안의 `architectureCheck`가 모든 leaf의 architecture lane을 부른다. 4. **`release.yml` `release` job 주석**: 「ci를 다시 돌리지 않는다」고 적혀 있다. 그런데 뒤의 job들은 ci가 이미 돈 시험 일부를 다시 돈다. 다시 도는 이유를 적었다. job 구성은 그대로다. 5. **`gates.md` redis-topology 줄**: desktop에서 그대로 돌리라고 하지만, 스크립트 안의 `./gradlew`는 daemon을 남긴다. desktop에서는 `GRADLE_OPTS=-Dorg.gradle.daemon=false`를 붙이라고 적었다. 6. **redis-sdk compose README**: cache-redis 칸의 필수 클래스가 두 개뿐이다. `build.gradle`의 standalone·cluster 목록에 맞춰 다섯 개로 늘렸다. 7. **`template-vs-consumer.md`** 두 곳: - `object-storage-aws`가 nightly job으로 적혀 있다. 실제로는 손으로 실행하면서 입력 `run_protected_aws`를 켤 때만 돈다. - 최상위 항목을 더할 때 「AGENTS.md 지도도 고친다」고 적혀 있다. 실제로는 `check-repo-layout.py` 허용 목록을 고치고, `src/` 최상위 폴더일 때만 지도의 `src/` 줄을 고친다. ## 고른 방법과 버린 대안 | 결정 | 고른 것 | 버린 것과 이유 | |---|---|---| | lychee 범위 | `src/**/CLAUDE.md`를 `src/**/AGENTS.md`로 바꾼다 | 두 패턴을 다 두기: 링크 없는 파일을 매번 읽을 뿐이다 | | release 재실행 | 주석으로 이유를 적는다(지원 문서가 job id로 부르는 릴리스 증거이고, 이미지 job이 모든 job을 `needs`로 받아 같은 run·같은 커밋에서 통과한 뒤 publish한다) | 재실행 job 빼기: 지원 문서와 이미지 job의 `needs`가 그 job id에 기대므로 계약이 바뀐다 | | redis-topology daemon | 문서에 `GRADLE_OPTS`를 적는다 | 스크립트에 `--no-daemon` 넣기: CI는 한 job 안의 step 11개가 daemon을 다시 쓴다(#15) | ## 위험과 영향 - **lychee가 새로 보는 외부 링크는 하나다.** messaging-kafka `AGENTS.md`의 Gitea 링크이고, 익명 GET이 200을 돌려준다. 병합 뒤 main push의 `links` job에서 확인한다. - 나머지 여섯은 주석과 문서만 바꾼다. workflow·스크립트의 동작은 그대로다. ## 검증 | 명령 | 커밋 | rc | 비고 | |---|---|---|---| | desktop `scripts/verify.sh pr --no-cache` | 3272faeb(트리 aea9e3bc, 시작 부하 12.6) | 0 | `:prCheck` 6분 34초, 527 태스크 전부 실행, FROM-CACHE 0. 시험 6,724개, 실패 0, `DeveloperExperienceContractTest` 포함. 로그 desktop `~/claude-w2-be-ci-perf-3-logs/pr.log` | | `scripts/verify.sh docs`(노트북) | 3272faeb | 0 | | | runner `pr / done`(run 153) | 3272faeb | 초록 | 11.6분. `:prCheck` 10분 29초(527 태스크 중 캐시 8), Trivy DB 캐시 hit | base인 새 main(ca1fbfde)의 트리는 이 브랜치의 기준 커밋 13ed3a1d와 같다(9f1f746f). 그래서 위 실행이 이 PR의 diff를 그대로 검증한다. ## 리뷰어가 볼 곳 - `.gitea/workflows/main.yml` `links`의 `args`와 `DeveloperExperienceContractTest`의 목록이 같은지. - `.gitea/workflows/release.yml` `release` job 아래 주석이 뒤 job들과 맞는지. ## 관련 - round9 확인 리뷰(공유 노트 `r9-be/wave1-r4.md` 「넘길 것 → 백엔드 CI 세션」 2~8번. 1번은 #15에서 고쳤다) - PR #15, 공유 노트 `w2-be-ci-perf.md`
donghyeon.kang added 2 commits 2026-11-12 15:01:56 +00:00
main.yml `links`의 lychee 범위에 `src/**/CLAUDE.md`가 있다. 폴더
지역 규칙이 같은 폴더 AGENTS.md로 옮겨 간 뒤 CLAUDE.md는
`@AGENTS.md` 한 줄이라 링크가 하나도 없다. 외부 URL이 있는
`src/**/AGENTS.md`는 범위 밖이라 그 링크가 죽어도 아무 단계도
모른다(상대 링크는 PR의 check-docs.py가 본다).

범위의 그 한 칸을 `src/**/AGENTS.md`로 바꾼다. 범위를 고정하는
DeveloperExperienceContractTest와 gates.md 2절 링크 검사 문장도 함께
바꾼다. 버린 안: 두 패턴을 다 두기 — 링크 없는 파일을 매번 읽을 뿐이다.

위험: 새로 보는 외부 링크는 messaging-kafka AGENTS.md의 Gitea 링크
하나다(코드 span 밖 URL 기준). 익명 GET이 200이라 runner에서도
통과할 것으로 본다. main push의 links job에서 확인한다.

검증: scripts/verify.sh docs(노트북) rc=0. Gradle 쪽
(DeveloperExperienceContractTest)은 PR 실행과 desktop verify.sh pr로 본다.
round9 확인 리뷰가 CI 파일의 설명이 실제와 다른 곳을 짚었다.

- verify.sh 머리 표: PR 단계 job 이름이 `gradle`이다. 실제는 `done`.
- build.gradle: JMH가 「세 leaf」에 있다고 하지만 지금은 플러그인을
  쓰는 leaf가 정한다. verifyFeatureScaffold는 「leaf 다섯 중첩
  빌드」라고 하지만 그 안의 architectureCheck가 모든 leaf의
  architecture lane을 부른다.
- release.yml: `release` job 주석은 「ci를 다시 돌리지 않는다」인데
  뒤의 job들은 ci가 이미 돈 시험 일부를 다시 돈다. 그 이유(문서가
  job id로 부르는 릴리스 증거이고, 이미지 job이 모두를 needs로 받아
  같은 run·같은 커밋에서 통과한 뒤 publish한다)를 적었다. job은 그대로다.
- gates.md 2절: redis-topology 줄을 desktop에서 그대로 돌리라고 하지만
  스크립트 안 ./gradlew는 daemon을 남긴다. desktop에서는
  GRADLE_OPTS=-Dorg.gradle.daemon=false를 붙이라고 적었다. 스크립트에
  --no-daemon을 넣지 않은 이유: CI는 한 job의 step 11개가 daemon을
  다시 쓴다.
- redis-sdk compose README: cache-redis 칸에 필수 클래스가 둘뿐이다.
  build.gradle의 standalone·cluster 목록 다섯으로 맞췄다.
- template-vs-consumer.md: object-storage-aws를 nightly job으로 적었다.
  실제는 손으로 실행하고 입력 run_protected_aws를 켤 때만 돈다. 최상위
  항목을 더하면 「AGENTS.md 지도를 함께 고친다」고 했지만 지도는 루트
  목록을 두지 않고 check-repo-layout.py를 가리킨다. src/ 최상위 폴더일
  때만 지도의 src/ 줄을 고친다고 적었다.

동작 변경 없음: workflow는 주석만, 스크립트는 머리 주석만 바꿨다.

검증: scripts/verify.sh docs(노트북) rc=0.

Refs: round9 확인 리뷰(r9-be wave1-r4 「넘길 것」)
donghyeon.kang merged commit fe0f8141ec into main 2026-11-12 16:59:59 +00:00
donghyeon.kang deleted branch claude/w2-be-ci-perf-3 2026-11-12 16:59:59 +00:00
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#18