docs: 낡은 단계표·capability 상태를 고치고 안내 없던 leaf 여섯에 안내를 쓴다 #26

Closed
donghyeon.kang wants to merge 0 commits from claude/r9-c-docs-body into main
Owner

무엇을, 왜

round9 리뷰 그룹 C의 문서 묶음(B18b 단계표·capability 상태·설정 설명, B18c 나머지 낡은 이름·leaf 안내)을 고친다. 살아 있는 문서가 지운 workflow·태스크·job과 옛 동작을 가리켰고, leaf 여섯은 고치는 세션이 볼 지역 규칙이 없었다.

  • 단계표: 단계 구성이 네 곳에 따로 적혔고 둘이 틀렸다 → gates.md 1절과 루트 build.gradle을 정본으로 가리키고 남긴 행은 지금 태스크대로. (gates.md·루트 build.gradle 주석은 CI 세션 몫이라 넘겼다.)
  • capability 상태: 지운 workflow·태스크, 옛 OutboxConfig 위치, 없는 lane 이름을 증거로 들던 행 넷 → 지금 job·태스크·모듈. 제거된 코드 표의 경로는 지운 때의 배치라는 머리말, #24가 지운 ComposeMergeCharacterizationTest 행.
  • 설정 설명: 기본 조립이 Flyway를 돈다는 설명(기본은 web뿐), 복사해 틀린 알림 키 개수(→ registry를 가리킴), roadmap의 지운 태스크(→ > 이력), #13이 합친 integration job을 가리키던 셋, Renovate 실행기 없이 「두 봇」을 전제한 정책, graphql의 「모듈별 yml 없음」(leaf는 config/graphql.yml을 직접 읽는다).
  • leaf 안내: application-notification·-fileserver·-objectstorage, web-notification·web-fileserver, redis-runtime에 AGENTS.md·CLAUDE.md·README.md. 규칙의 정본은 가리키기만 한다.
  • web 문서: 「애플리케이션 칸은 강제하지 않는다」였지만 JSON 본문 1 MiB(413)를 강제하고, multipart는 Spring 기본 한도다. 아무도 막지 않는 칸을 「늘 애플리케이션」이라 했다. OpenAPI 문서가 아무도 만들지 않는 3.1.2 산출물·3.1 snapshot 불변식을 이 repo 것처럼 적었다.

병합 순서

#23·#24·#25 뒤에 병합한다. 이 PR의 문장 셋이 그 PR들이 만드는 사실을 적는다.

  • #25: 새 leaf 문서가 적는 동작(batch bulk envelope, 알림 VALIDATION_FAILED, SERVER_BUSY, 전송이 파일 이름을 짓지 않음)과 docs/fileserver/http-contract.md 「오류 코드」 절.
  • #23: web-notification 안내의 「callback permitAll은 공개 경로 스냅숏에 있다」.
  • #24: capability-status 「제거된 코드」의 ComposeMergeCharacterizationTest 행(#24가 그 시험을 지운다).
  • docs/build.md는 #23도 고친다. git merge-tree로 #23 head와 대 보았고 hunk가 겹치지 않는다(#23은 공개 경로 snapshot 절, 이 PR은 단계표·기본 조립·알림 키 절).

정한 기본값

  • provider callback이 본문 없이 status만 답하는 것(204·400·413·503)을 Envelope 규칙의 예외로 적었다. 소유자 결정은 「Envelope가 아닌 실패는 Draft-12 offset 문서 하나」였지만, callback은 provider가 status만 읽는 webhook이고 인증 전 경로라 거절 이유를 싣지 않는 것이 맞다. 코드는 그대로 두고 HTTP 계약 §1·callback 문서·leaf 안내에 적었다. 소유자가 뒤집으면 callback에 실패 Envelope를 싣는 코드 변경이 된다.

고른 방법과 버린 대안

  • 단계표를 네 곳에서 모두 고쳐 맞추는 안은 버렸다. 다시 갈린다. 정본 한 곳을 가리키고 꼭 필요한 행만 남긴다.
  • 알림 키를 맞는 개수로 고치는 안은 버렸다. 숫자 복사는 쓰는 순간 낡는다(docs/README.md).

위험과 영향

문서만 바뀐다. 동작·공개 표면은 그대로다. 문서를 읽는 시험은 CapabilityStatusDocumentTest(app-bootstrap documentContractTest)다.

검증

  • desktop scripts/verify.sh pr --no-cache: 7fdbbcaa(트리 2d8d8210) 6724건 실패 0, rc=0, FROM-CACHE 0. 그 뒤 4ca61cd9는 문서만 바꿨다.
  • desktop :app-bootstrap:documentContractTest(문서를 읽는 시험): 최종 head 4ca61cd9(트리 b166a1a6) 68건 실패 0.
  • 노트북 scripts/verify.sh docs: 최종 head rc=0.
  • 노트북: check-docs.py·check-work-docs.py·check-repo-layout.py rc=0.
  • 새 눈 리뷰: reviewer(be-docs) Medium 4·Low 8, arch-reviewer(HARD-STOP으로 이어질 문장 0) Medium 1·Low 4 → 모두 7fdbbcaa·4ca61cd9에서 고침. 넘김: objectstorage 포트 계약 시험이 포트를 가진 leaf에 없음(manual 10 기준 5) — 시험 코드를 새로 쓰는 일이라 총괄에 새 발견으로 넘겼다.

발견 ID 표

ID 판정 커밋
RR9-04-09 고침(이 repo의 살아 있는 문서 셋. gates.md:42·루트 build.gradle 주석은 CI 세션에 넘김) bae2965f, 7fdbbcaa
RR9-04-10 고침 bae2965f
RR9-04-20 고침 bae2965f
RR9-04-21 고침 bae2965f, 7fdbbcaa
RR9-04-22 고침 bae2965f
RR9-04-25 고침 bae2965f
RR9-04-28 고침 bae2965f
RR9-03-30 고침(capability-status 행. 시험 삭제는 #24) bae2965f, 7fdbbcaa
RR9-04-35 고침 bb28dae5, 7fdbbcaa
RR9-04-36 고침 bb28dae5
RR9-04-42 고침 bb28dae5, 7fdbbcaa, 4ca61cd9

관련

  • 리뷰 기록: PR #17 docs/reviews/2026-11-12-round9-review/.
  • 같은 그룹의 #25(계약·오류 코드), PR 2(시험·빌드·스크립트).
## 무엇을, 왜 round9 리뷰 그룹 C의 문서 묶음(B18b 단계표·capability 상태·설정 설명, B18c 나머지 낡은 이름·leaf 안내)을 고친다. 살아 있는 문서가 지운 workflow·태스크·job과 옛 동작을 가리켰고, leaf 여섯은 고치는 세션이 볼 지역 규칙이 없었다. - **단계표**: 단계 구성이 네 곳에 따로 적혔고 둘이 틀렸다 → `gates.md` 1절과 루트 `build.gradle`을 정본으로 가리키고 남긴 행은 지금 태스크대로. (`gates.md`·루트 `build.gradle` 주석은 CI 세션 몫이라 넘겼다.) - **capability 상태**: 지운 workflow·태스크, 옛 `OutboxConfig` 위치, 없는 lane 이름을 증거로 들던 행 넷 → 지금 job·태스크·모듈. 제거된 코드 표의 경로는 지운 때의 배치라는 머리말, #24가 지운 `ComposeMergeCharacterizationTest` 행. - **설정 설명**: 기본 조립이 Flyway를 돈다는 설명(기본은 web뿐), 복사해 틀린 알림 키 개수(→ registry를 가리킴), roadmap의 지운 태스크(→ `> 이력`), #13이 합친 integration job을 가리키던 셋, Renovate 실행기 없이 「두 봇」을 전제한 정책, graphql의 「모듈별 yml 없음」(leaf는 `config/graphql.yml`을 직접 읽는다). - **leaf 안내**: application-notification·-fileserver·-objectstorage, web-notification·web-fileserver, redis-runtime에 `AGENTS.md`·`CLAUDE.md`·`README.md`. 규칙의 정본은 가리키기만 한다. - **web 문서**: 「애플리케이션 칸은 강제하지 않는다」였지만 JSON 본문 1 MiB(413)를 강제하고, multipart는 Spring 기본 한도다. 아무도 막지 않는 칸을 「늘 애플리케이션」이라 했다. OpenAPI 문서가 아무도 만들지 않는 3.1.2 산출물·3.1 snapshot 불변식을 이 repo 것처럼 적었다. ## 병합 순서 **#23·#24·#25 뒤에 병합한다.** 이 PR의 문장 셋이 그 PR들이 만드는 사실을 적는다. - #25: 새 leaf 문서가 적는 동작(batch bulk envelope, 알림 `VALIDATION_FAILED`, `SERVER_BUSY`, 전송이 파일 이름을 짓지 않음)과 `docs/fileserver/http-contract.md` 「오류 코드」 절. - #23: web-notification 안내의 「callback `permitAll`은 공개 경로 스냅숏에 있다」. - #24: capability-status 「제거된 코드」의 `ComposeMergeCharacterizationTest` 행(#24가 그 시험을 지운다). - `docs/build.md`는 #23도 고친다. `git merge-tree`로 #23 head와 대 보았고 hunk가 겹치지 않는다(#23은 공개 경로 snapshot 절, 이 PR은 단계표·기본 조립·알림 키 절). ## 정한 기본값 - provider callback이 본문 없이 status만 답하는 것(204·400·413·503)을 Envelope 규칙의 예외로 적었다. 소유자 결정은 「Envelope가 아닌 실패는 Draft-12 offset 문서 하나」였지만, callback은 provider가 status만 읽는 webhook이고 인증 전 경로라 거절 이유를 싣지 않는 것이 맞다. 코드는 그대로 두고 HTTP 계약 §1·callback 문서·leaf 안내에 적었다. 소유자가 뒤집으면 callback에 실패 Envelope를 싣는 코드 변경이 된다. ## 고른 방법과 버린 대안 - 단계표를 네 곳에서 모두 고쳐 맞추는 안은 버렸다. 다시 갈린다. 정본 한 곳을 가리키고 꼭 필요한 행만 남긴다. - 알림 키를 맞는 개수로 고치는 안은 버렸다. 숫자 복사는 쓰는 순간 낡는다(`docs/README.md`). ## 위험과 영향 문서만 바뀐다. 동작·공개 표면은 그대로다. 문서를 읽는 시험은 `CapabilityStatusDocumentTest`(app-bootstrap `documentContractTest`)다. ## 검증 - desktop `scripts/verify.sh pr --no-cache`: `7fdbbcaa`(트리 `2d8d8210`) 6724건 실패 0, rc=0, `FROM-CACHE` 0. 그 뒤 `4ca61cd9`는 문서만 바꿨다. - desktop `:app-bootstrap:documentContractTest`(문서를 읽는 시험): 최종 head `4ca61cd9`(트리 `b166a1a6`) 68건 실패 0. - 노트북 `scripts/verify.sh docs`: 최종 head rc=0. - 노트북: `check-docs.py`·`check-work-docs.py`·`check-repo-layout.py` rc=0. - 새 눈 리뷰: reviewer(be-docs) Medium 4·Low 8, arch-reviewer(HARD-STOP으로 이어질 문장 0) Medium 1·Low 4 → 모두 `7fdbbcaa`·`4ca61cd9`에서 고침. 넘김: objectstorage 포트 계약 시험이 포트를 가진 leaf에 없음(manual 10 기준 5) — 시험 코드를 새로 쓰는 일이라 총괄에 새 발견으로 넘겼다. ## 발견 ID 표 | ID | 판정 | 커밋 | | --- | --- | --- | | RR9-04-09 | 고침(이 repo의 살아 있는 문서 셋. `gates.md:42`·루트 `build.gradle` 주석은 CI 세션에 넘김) | bae2965f, 7fdbbcaa | | RR9-04-10 | 고침 | bae2965f | | RR9-04-20 | 고침 | bae2965f | | RR9-04-21 | 고침 | bae2965f, 7fdbbcaa | | RR9-04-22 | 고침 | bae2965f | | RR9-04-25 | 고침 | bae2965f | | RR9-04-28 | 고침 | bae2965f | | RR9-03-30 | 고침(capability-status 행. 시험 삭제는 #24) | bae2965f, 7fdbbcaa | | RR9-04-35 | 고침 | bb28dae5, 7fdbbcaa | | RR9-04-36 | 고침 | bb28dae5 | | RR9-04-42 | 고침 | bb28dae5, 7fdbbcaa, 4ca61cd9 | ## 관련 - 리뷰 기록: PR #17 `docs/reviews/2026-11-12-round9-review/`. - 같은 그룹의 #25(계약·오류 코드), PR 2(시험·빌드·스크립트).
donghyeon.kang added 5 commits 2026-11-12 21:29:17 +00:00
문제: 살아 있는 문서가 지운 workflow·태스크·job과 옛 동작을 가리켰다.
- 단계 구성이 네 곳에 따로 적혔고 둘이 틀렸다. TESTING_STRATEGY의 repository
  목록은 releaseCheck를 「ci + ...」라 했고, docs/build.md의 mainCheck·
  qualificationCheck 행은 testQualityCheck·verifyFeatureScaffold·graphqlStableTest를
  빠뜨렸다.
- capability-status가 지운 redis-sdk-topology.yml·notification-platform.yml·
  verifyNotificationEvidence, app-bootstrap의 OutboxConfig(지금
  :composition:outbox-relay), 없는 lane 이름을 증거로 들었다. 제거된 코드 표의
  재배치 전 경로는 설명 없이 지금 트리에 없었다.
- docs/build.md·bootstrap-local.sh가 기본 조립이 Flyway를 돈다고 했다(기본은
  web뿐). 알림 키 개수를 복사해 틀렸다.
- roadmap messaging-r2가 지운 VerifyMessagingEvidenceTask·
  MessagingQualificationPlugin을 예시로 들었다.
- cache-redis README·build.gradle, httpclient build.gradle이 #13이 합친
  integration job을 가리켰다.
- renovate.json·취약점 정책이 「두 봇」과 GitHub vulnerability alert를 전제했다.
  이 Gitea repo에 Renovate 실행기는 없다.
- graphql AGENTS·README가 「모듈별 yml 금지·없음」이라 했지만 leaf는
  config/graphql.yml을 직접 읽는다. 지운 execution profile을 적었다.

고친 것: 단계 구성은 gates.md 1절과 루트 build.gradle을 정본으로 가리키고, 남긴
표 행은 지금 태스크대로 고쳤다. capability-status 행 넷을 지금 job·태스크·모듈로
고치고, 제거된 코드 표의 경로가 지운 때의 배치라는 머리말과 지운
ComposeMergeCharacterizationTest 행을 더했다. 기본 조립·Flyway 설명, 알림 키(개수
대신 registry), roadmap(`> 이력`), 세 integration 설명(`main` job이
:integrationCheck :mainCheck를 함께 돈다), renovate·정책(실행기 없음, enforced는
trivy), graphql 설정 파일 설명을 고쳤다.

검증: check-docs.py·check-work-docs.py rc=0, 이 문서들을 읽는 시험은
CapabilityStatusDocumentTest(app-bootstrap document-contract)다.

Refs: RR9-04-09, RR9-04-10, RR9-04-20, RR9-04-21, RR9-04-22, RR9-04-25, RR9-04-28, RR9-03-30
문제:
- application-notification·-fileserver·-objectstorage는 가장 가까운 AGENTS가
  루트뿐이고 README가 없었다. web-notification·web-fileserver·redis-runtime도 자기
  AGENTS·README가 없었다. 그 leaf를 고치는 세션은 지역 규칙(전송이 이름을 짓지
  않음, 포화 코드의 갈림, callback 경로가 절대 경로인 이유 등)을 볼 곳이 없었다.
- docs/README.md 지도의 security/ 행이 rate-limiting.md를 덮지 않았다.
- shared-contract AGENTS 책임 목록이 PageMeta·ResponseMeta·Category·공용 carrier
  예외 셋·ServerFailureLog·ActiveTrace를 빠뜨렸다.
- docs/web/repository-adaptation.md가 「애플리케이션 칸은 강제하지 않는다」고
  했지만 web은 JSON 본문 1 MiB(app.web.mvc.max-json-body-size, 413)를 강제한다.
- openapi-32-compatibility.md가 아무도 만들지 않는 3.1.2 릴리스 산출물과 3.1
  snapshot 불변식을 이 repo의 것처럼 적었다(샘플 삭제 뒤).

고친 것: leaf 여섯에 AGENTS.md(등록 정보, 책임, 규칙, 시험)·CLAUDE.md(@AGENTS.md)·
README.md(책임과 소유하지 않는 것, 공개 표면, 조립, 시험 명령, 더 읽을 곳)를 쓰고,
규칙의 정본은 가리키기만 했다. 지도 행, shared-contract 책임 목록, 본문 한도 표와
머리말, OpenAPI 문서를 고쳤다.

순서: 새 leaf 문서가 계약 PR(batch bulk envelope, 알림 VALIDATION_FAILED,
SERVER_BUSY, 전송이 이름을 짓지 않음)의 동작을 적는다. 그 PR 뒤에 병합한다.

검증: check-docs.py·check-work-docs.py rc=0.

Refs: RR9-04-35, RR9-04-36, RR9-04-42
문제(새 눈 리뷰):
- web-notification 안내가 callback 서명 검증을 유스케이스가 한다고 적었다.
  실제로는 composition의 ProviderCallbackIngressBridge가 outbound provider
  adapter(SES는 SnsSignatureVerifier)로 검증하고 검증된 event만 넘긴다.
- application-notification 안내가 없는 패키지 platform.port.out을 나가는 포트
  위치로 적었고, testFixtures를 「포트마다 fake 하나」라고 실제보다 크게 적었다.
- web-fileserver 책임 목록에 lifecycle(삭제·복사·이동)과 http(Range·조건부
  다운로드 계획) 패키지가 없었다.
- redis-runtime README가 app.redis.* 기본값 위치를 잘못 적었다. objectstorage
  README가 포트 개수를 복사했다.
- web 한도 표가 multipart 한도를 「전역 한도 없음」이라 했고, 아무도 막지 않는
  칸을 「늘 애플리케이션」이라 했다.
- TESTING_STRATEGY가 묶음 태스크를 셋이라 세며 performanceCheck를 빠뜨렸다.
- roadmap messaging-r2 이력 블록의 날짜·이유가 틀렸다(6d27356e, 2026-09-25).
- 지운 ComposeMergeCharacterizationTest 행의 커밋이 지운 쪽 기준이 아니었다.

고친 것: 위 문장을 지금 코드대로 고쳤다. 공개 경로 스냅숏 문장과 fileserver
「오류 코드」 절 안내는 공개 표면 PR·계약 PR이 만드는 것이라 병합 순서로 맞춘다.

검증: check-docs.py·check-work-docs.py rc=0.

Refs: RR9-04-09, RR9-04-21, RR9-04-35, RR9-04-42, RR9-03-30
문제(구조 리뷰):
- application-notification 안내가 나가는 포트를 `*Port`로만 적어 provider·security
  패키지와 이름이 다른 포트 일곱(NotificationProviderAdapter, TemplateRegistry 등)을
  빠뜨렸다. provider를 더하는 세션이 같은 계약을 두 번 만들 수 있다.
- notification·fileserver testFixtures를 모든 포트에 있는 것처럼 적었다.
- application-objectstorage 안내가 adapter의 provider SPI 계약을 이 leaf 포트의
  계약처럼 적었다. 이 leaf에는 포트 계약 시험이 없다.
- redis-runtime 안내가 redis-sdk를 포트 구현 leaf로 적었고, redis-sdk로 싣는 길에서는
  APP_REDIS_ENABLED를 직접 줘야 한다는 것을 적지 않았다.
- provider callback은 본문 없이 status만 답하는데, Envelope가 아닌 응답이 fileserver
  프로토콜 예외뿐인 것처럼 적혀 있었다. objectstorage README는 registry에 있는
  APP_OBJECTSTORAGE_ENABLED를 「전용 키 없음」이라 했다.

고친 것: 위 문장을 코드대로 고치고, callback 응답(204·400·413·503, 본문 없음)을 HTTP
계약 §1·callback 문서·leaf 안내에 예외로 적었다. callback 동작은 그대로 둔다(인증 전
경로라 거절 이유를 싣지 않고, provider는 status로 재전송을 정한다).

검증: check-docs.py·check-work-docs.py rc=0. 이 문서들을 읽는 시험은 존재 확인뿐이다
(NotificationReleaseGateTest).

Refs: RR9-04-42
Author
Owner

#28로 병합됐다(main 3d31896a). 이 PR의 head 4ca61cd9가 #28 브랜치에 merge 커밋으로 들어 있고, #28의 runner pr / done이 그 합친 트리로 초록이었다. runner 대기를 줄이려고 이번만 쓴 방식이다(소유자 승인, 2026-11-13).

#28로 병합됐다(main `3d31896a`). 이 PR의 head `4ca61cd9`가 #28 브랜치에 merge 커밋으로 들어 있고, #28의 runner `pr / done`이 그 합친 트리로 초록이었다. runner 대기를 줄이려고 이번만 쓴 방식이다(소유자 승인, 2026-11-13).
donghyeon.kang closed this pull request 2026-11-12 23:28:34 +00:00

Pull request closed

Please reopen this pull request to perform a merge.
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#26