From b5c17d114a527e72db4ffacd3259a43178dca10d Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 12 Nov 2026 21:40:32 +0900 Subject: [PATCH] =?UTF-8?q?docs(work):=20=EA=B2=B0=EC=A0=95=20=EC=83=89?= =?UTF-8?q?=EC=9D=B8=EC=9D=98=20=EB=82=A1=EC=9D=80=20=ED=96=89=20=EB=84=B7?= =?UTF-8?q?=EC=97=90=20=EB=B0=94=EB=80=90=20=EA=B3=B3=EC=9D=84=20=ED=91=9C?= =?UTF-8?q?=EC=8B=9C=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 결정 색인의 네 행이 지금 코드와 다른데 바뀌었다는 표시가 없다. 색인 1절 6번은 리뷰어가 정한 결정을 결함으로 올리지 않게 하므로, 낡은 행대로 읽은 리뷰어는 맞는 코드를 결함으로 올린다. - 「문서 검사」: workflow `docs-check`는 2026-11-08 workflow를 셋으로 접으며 없어졌다. 지금은 pr.yml done → :prCheck → documentCheck다. - 「build-logic 의존성 잠금」: "잠그지 않음(보류)"인데 build-logic/build.gradle은 2026-09-25 커밋부터 STRICT로 잠근다. - 「릴리스 이미지 서명」: "cosign keyless"인데 2026-11-07 소유자가 키 쌍으로 바꿨다(Gitea Actions가 OIDC 토큰을 주지 않음, operate.md 4.3절). - 「workflow 명령의 빌드 판정」: "cd도 따라간다"인데 2026-11-08 셸을 해석하지 않는 고정 형식 검사로 바꿨다(소유자가 고른 B안, StrictLaneStagesPlugin). docs/README.md 「문서 검사」도 같은 `docs-check`를 가리켜 함께 고친다. 고른 방법: 1절 5번대로 원문을 지우지 않고 취소선과 "→ 바꿈"으로 새 위치를 가리키고, 서명 키와 job 모양은 새 행을 더한다. 위험·한계: build-logic 잠금을 언제 누가 바꾸기로 했는지 기록이 없다. 행에 "바꾼 결정의 기록은 없다"고 적었다. 소유자 확인이 필요하다. 검증: check-work-docs.py rc=0, check-docs.py rc=0. --- docs/README.md | 4 ++-- docs/work/reference/decisions.md | 10 ++++++---- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/README.md b/docs/README.md index 730ce894..e600e909 100644 --- a/docs/README.md +++ b/docs/README.md @@ -184,8 +184,8 @@ leaf마다 둘 필요는 없고 family 하나에 하나여도 된다. 담는 것 ## 문서 검사 -`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여덟을 본다. PR마다 workflow `docs-check`가 -돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이 +`python3 scripts/check-docs.py`가 위 규칙 중 기계로 볼 수 있는 여덟을 본다. PR마다 `pr.yml`의 `done` job이 `./gradlew :prCheck` +안의 `documentCheck`로 돌리고, 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 Gradle 프로젝트를 지우는 변경이 문서를 낡게 만든다. | 검사 | 보는 것 | diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index db1f8aa0..67cb64e1 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -61,7 +61,7 @@ | 학습 문서(지난 것) | 삭제된 코드를 설명하는 학습 문서(지금 `docs/history/study/*.ko.md`, `docs/history/packages/*-superpowers-package/`)는 현재 코드에 맞게 갱신 → 2026-11-07 갱신하지 않고 기록으로 보관(머리 블록만 단다)으로 바뀜 | 소유자 | 2026-09-25 | 결정 6, design-docs `repo-structure/README.md` 3.2절 | | 문서 체계 | 문서를 수명으로 나눈다. 살아 있는 문서는 제자리에 두고 한국어로 옮긴다. 기록은 `docs/history/`, 설계서는 `docs/design/`, 결정 기록은 `docs/adr/`에 둔다. 폴더 이름은 짝 프론트와 같이 쓴다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절, 적용은 `docs/README.md` | | 한국어의 범위 | 살아 있는 문서는 본문까지 한국어로 쓴다. 기록 문서는 맨 위에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달고 본문은 원문 그대로 둔다. 상태는 한국어 고정 어휘다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 | -| 문서 검사 | 언어·머리 블록·참조·숫자 검사를 PR에서 실패로 둔다(`scripts/check-docs.py`, workflow `docs-check`) | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절, `docs/README.md` 「문서 검사」 | +| 문서 검사 | 언어·머리 블록·참조·숫자 검사를 PR에서 실패로 둔다(`scripts/check-docs.py`, workflow `docs-check`) → 2026-11-08 workflow를 셋으로 접으며 `pr.yml` `done`의 `:prCheck` 안 `documentCheck`로 옮겼다(아래 2.7 「workflow 단계 job 모양」) | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절, `docs/README.md` 「문서 검사」 | | 학습 문서 | `docs/history/study/`에 기록으로 보관한다. 코드에 맞춰 갱신하지 않고 머리 블록만 단다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 | | 문서 규칙 정본 | design-docs `conventions/docs-system.md`(두 템플릿 공통). 이 repo의 적용은 `docs/README.md`에 적는다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 | | 레지스트리 yaml 설명 칸 | 번역한다. 그 칸을 읽는 테스트를 먼저 찾는다 | 소유자 | 2026-11-07 | design-docs `repo-structure/README.md` 3.2절 | @@ -190,13 +190,15 @@ | 의존성 checksum | 추가 안 함(보류) | 소유자 | 결정 19 | | 취약점이 있는 의존성 버전 | 고친 버전으로 올리는 것이 먼저다. 고친 버전 중 가장 작은 것을 고르고, 짝으로 움직이는 라이브러리(httpclient5와 httpcore5, gRPC와 protobuf)는 upstream이 선언한 짝을 따른다. Boot BOM이 관리하면 Boot 패치를 먼저 보고, 없으면 BOM 속성 override(build-logic `JavaConventionsPlugin`, 이유와 지울 조건 옆). 어떤 leaf도 선언하지 않는데 upstream이 낡은 버전을 가져오면 카탈로그 `pinned-*`로 모든 구성에 고정한다. 무시 목록(`.trivyignore.yaml`)은 고친 버전이 없을 때만, 묻고 쓴다 | 기본값(2026-11-07) | `gradle/libs.versions.toml` 「Pinned」, 업그레이드 안내 `docs/upgrade/2026-11-maturity-review.md` B-54 | | Querydsl 취약 좌표 | `com.querydsl:querydsl-jpa`(CVE-2024-49203, 고친 버전 없음)를 템플릿이 싣지 않는다. persistence-jpa는 쓰는 타입(`Predicate`)이 있는 querydsl-core로만 컴파일하고, querydsl-jpa는 capability를 켜는 서비스가 더한다. leaf README는 그 좌표에 고친 버전이 없다고 적고 OpenFeign 포크(`io.github.openfeign.querydsl`)를 검토하라고 한다 | 위임(2026-11-07, 총괄이 권한 안 A를 확인) | 커밋 「persistence-jpa가 querydsl-jpa 대신 querydsl-core로 컴파일한다」, `src/adapter/outbound/persistence-jpa/README.md` 「라이브러리 API」 | -| build-logic 의존성 잠금 | 잠그지 않음 + 문서화(보류) | 소유자 | 결정 27 | -| 릴리스 이미지 서명 | cosign keyless, tag 릴리스에서 서명·검증 | 소유자 | 결정 31 | +| build-logic 의존성 잠금 | ~~잠그지 않음 + 문서화(보류)~~ → 지금은 잠근다(`build-logic/build.gradle` `lockMode = LockMode.STRICT`, 2026-09-25 커밋부터). 바꾼 결정의 기록은 없다 | 소유자 | 결정 27 | +| 릴리스 이미지 서명 | ~~cosign keyless~~, tag 릴리스에서 서명·검증 → 2026-11-07 키 쌍으로 바꿈(아래 「릴리스 이미지 서명 키」) | 소유자 | 결정 31 | +| 릴리스 이미지 서명 키 | cosign 키 쌍으로 서명한다. Gitea Actions는 keyless 서명에 필요한 OIDC 토큰을 주지 않는다. 개인 키와 비밀번호는 repo secret이다 | 소유자(2026-11-07) | `docs/work/operate.md` 4.3절, `.gitea/workflows/release.yml` | | gRPC `.proto` | protobuf Gradle 플러그인 + Buf. 2026-11-08부터 `grpc-library` repo의 `ci` 단계 | 소유자 | 결정 18 | | SpotBugs 신뢰도 | MEDIUM으로 내림. 패턴 단위 제외는 이유를 단다 | 위임 | `1101` 15절(08-07) | | 테스트 코드 정적 분석 | `testQualityCheck`는 `mainCheck` | 위임 | `1103` 14절 | | lane 정책과 캐시 | lane 정책 값(`rejectSkipped` 등)은 모두 캐시 입력 | 위임 | `1103` 4절(RR-06-02) | -| workflow 명령의 빌드 판정 | 같은 셸의 `cd <상대 경로>`도 따라간다 | 소유자 | `1103` 15절 ② | +| workflow 명령의 빌드 판정 | ~~같은 셸의 `cd <상대 경로>`도 따라간다~~ → 2026-11-08 셸을 해석하지 않게 바꿈(아래 「workflow 단계 job 모양」) | 소유자 | `1103` 15절 ② | +| workflow 단계 job 모양 | workflow는 `pr.yml`·`main.yml`·`release.yml` 셋이다. 단계 job의 `run:`은 셸 문법 없는 `./gradlew` 한 줄이나 `bash scripts/<이름>.sh` 한 줄이고, `verifyStrictLaneStages`는 셸을 해석하지 않고 이 고정 형식만 본다 | 소유자(2026-11-08) | design-docs `repo-structure/03-ci.md` 7·11절, `build-logic/AGENTS.md`, `StrictLaneStagesPlugin` Javadoc | | 성능 lane 단언 | 끄는 스위치 없음. convention이 `performance.assertions.enabled=true`를 넣고, 빌드·lane이 다른 값을 주거나 skip이 있으면 테스트 전에 실패. 손으로 돌리든 workflow든 같은 상한 | 소유자(2026-11-06 병합 승인) | design-docs `delegation-loop/02-design.md` 13절 D9, 커밋 `e6b6e18e`, `build-logic/AGENTS.md` 「lane 캐시와 성능 lane」 | | 문서 파싱 검사 | 문서를 파싱해 대조하는 Gradle 검사를 두지 않는다(`verifyDocumentedLeafCount` 등 삭제). 문서와 코드 대조는 leaf의 document-contract lane | 정책 | `build-logic/AGENTS.md` 「저장소 파일을 읽는 테스트」 | | MinIO 이미지 | `pgsty/minio` digest | 위임 | `1101` 15절(05-09) |