docs(work): 쌓인 매뉴얼 빈틈과 조사 문서의 매뉴얼 규칙을 한 묶음으로 넣는다

cold-read 3회차(수정 세션 넷의 빈틈 9건), 통합·배치·문서 체계·번역 세션이
「매뉴얼에서 답을 못 찾았다」고 적은 곳, 프론트 총괄 교훈 둘, design-docs
repo-structure 01·02·03의 「매뉴얼에 넣을 규칙」 중 백엔드 몫이 아직 매뉴얼에
없다. 세션마다 같은 판단을 스스로 다시 했다.

넣은 자리(항목별 표는 PR 본문):
- delegate.md: upgrade 안내 「커밋:」 줄은 총괄이 합칠 때 적는다, 두 라운드
  연속 결함이면 조사로, 병합 커밋에는 충돌 해결만, 자주 하는 실수 둘(충돌
  없음은 merge-tree로, PR 만들기 전 head 브랜치의 PR을 API로).
- improve.md: 절차 문서 결함과 대기 결함의 RED 모양, 테스트 Javadoc도 고친다,
  그 코드를 지키는 lane 찾기, 두 라운드 연속 결함이면 조사로.
- docs-writing.md: 문체·용어·언어 범위(코드 주석 제외), check-docs도 돌린다,
  이동 커밋에 참조 수정을 같이, 번역 기준(영어 절 제목, 레지스트리 yaml,
  머리말 없는 runbook, MANIFEST는 납품 당시 해시).
- operate.md 4.1: zsh 파이프 rc와 자기 실행 멈추기, runner 사실(capacity 1,
  12코어·31GB, 잠금 밖), 취약점 DB는 설치가 아니다, 형식은 나누기 전에.
- reference/gates.md: 커밋하는 수정의 lockfile, 처음 켜진 lane의 이전 실패,
  lychee·buf·trivy 공식 이미지, smoke 이미지가 이 트리에서 만들어졌음,
  원래 있던 실패 가리기(세 번), 순서 의존 재현, 공유 잠금 기다리기, 증거
  실행의 --no-build-cache, 거짓 통과 두 줄(OOM 재시작, 조건 안 set -e),
  새 7절 「workflow·검사 스크립트를 더할 때」.
- reference/review-criteria.md: 관점 2·4·9·18·20·21·23·26·27의 볼 곳과 결함,
  Important 예시, leaf 변경 체크리스트(README 다섯 칸, 문서 검사).
- reference/decisions.md: brief와 결정 원문이 다르면 원문, 취약점 DB 기본값.
- reference/terms.md(새): 영어 그대로 쓰는 말과 「개발 환경」의 뜻.
- README.md 2절(최상위 폴더는 큼), new-feature.md(테스트 환경·release/는
  leaf 안), docs/ci-cd/template-vs-consumer.md(docs-check·link-check·
  check-repo-layout은 파생 서비스도 유지), settings-and-runtime 규칙.

버린 대안: 항목마다 따로 커밋(소유자 결정: 매뉴얼 보강은 한 묶음).

위험: 정한 기본값 둘은 소유자 확인 대상이다: 취약점 DB 받기 허용,
병합 커밋에 충돌 해결만. operate.md는 143/150줄, improve.md 144/150줄로
상한에 가깝다.

검증: check-work-docs(진입 경로 최대 269/350), check-docs, unittest 모두 rc=0.
This commit is contained in:
DongHyeonka
2026-11-07 22:21:04 +09:00
parent 59dff0041c
commit c8db79a78f
12 changed files with 99 additions and 31 deletions
+2 -2
View File
@@ -10,7 +10,7 @@
## 1. 결정을 다시 묻지 않는 규칙
1. 작업을 시작하기 전에 이 색인과 원문을 읽는다. 표에 있는 주제면 그 결정대로 한다. brief에도 결정의 **내용**을 옮겨 적는다.
1. 작업을 시작하기 전에 이 색인과 원문을 읽는다. 표에 있는 주제면 그 결정대로 한다. brief에도 결정의 **내용**을 옮겨 적는다. brief가 옮긴 내용과 원문이 다르면 원문을 따르고, 차이를 보고에 적는다(brief가 요약하며 빠뜨린 것일 수 있다).
2. 다시 열 수 있는 경우는 셋뿐이다.
- 결정의 전제가 코드나 측정으로 틀렸다고 확인됐다.
- 두 결정이 서로 충돌한다.
@@ -38,7 +38,7 @@
| 이력 ID 0 규칙의 범위 | `docs/work/`·`docs/manual/` 본문에 더해 진입 문서 `AGENTS.md`와 `src/**/CLAUDE.md`(2026-11-07부터 `src/**/AGENTS.md`, 루트 `CLAUDE.md`, `.claude/` 아래 문서). 모듈 README·설계 문서·`docs/reviews/**`는 넓히지 않는다. `check-work-docs.py` 기본 모드가 진입 문서까지 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 결정), `1103` 19.4절 ③, `docs/work/evidence.md` 10절 |
| 커밋 단위 | 커밋 하나에 논리 변경 하나(`conventions/commit-and-pr.md` 3.1절). 수정 묶음은 브랜치 하나이고 결함(또는 같은 원인)마다 커밋을 나눈다. 나눈 커밋마다 그 커밋이 바꾼 leaf `check`를 돌리고, 무거운 묶음은 마지막 트리에서 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/evidence.md` 11절 |
| 넘어온 「범위 밖」 항목 | 수정 세션의 「범위 밖에서 본 것」은 총괄이 README 남은 항목으로 옮기고(멈춤 기준 4가 센다), 다음 확인 리뷰가 brief를 받아 판정한다. 「정한 기본값」은 처리 표와 이 색인 기본값 행으로 옮긴다 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/evidence.md` 11절 |
| desktop 도구 설치 | workflow job이 도구를 내려받아 설치하는 단계는 desktop에서 따라 하지 않는다. 설치된 도구로만 돌리고 없으면 못 돌림 | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/operate.md` 4.1절 |
| desktop 도구 설치 | workflow job이 도구를 내려받아 설치하는 단계는 desktop에서 따라 하지 않는다. 설치된 도구로만 돌리고 없으면 못 돌림. 도구가 실행 때 받는 데이터(trivy 취약점 DB)는 설치가 아니라 받아도 된다(기본값 2026-11-07, 갱신 시각을 기록에 적는다) | 소유자(2026-11-07, 기본값 확인) | 2026-11-07 | `docs/work/operate.md` 4.1절 |
| 하위 세션 보고 | 총괄에게도 쉬운 한국어로 쓴다. Slack 브리핑은 전역 `~/.claude/CLAUDE.md` 규칙이 하위 세션에도 그대로 적용된다. brief 7절에 "Slack 말고"가 있으면 보내지 않는다 | 기본값(전역 규칙의 적용 범위를 적음) | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절 「보고」 |
| 커밋 예외(지난 것) | `refactor/review-followup`에 Wave마다 커밋(2026-09-25), 리뷰 수정을 `refactor/maturity-review-2026-11`에 커밋·push(2026-11-03) | 소유자 | 2026-09-25, 2026-11-03 | 결정 1, `1101` 17절 |
| 리뷰 발견 처리 | Minor도 기록만 하지 않고 고친다. 보고할 때 남은 문제가 0이어야 한다. 수정이 새 결함을 만들면 리뷰·수정을 0까지 반복한다 | 소유자 | 2026-11-05 | `1103` 16절 |
+28 -4
View File
@@ -66,6 +66,7 @@
- 탐침마다 무엇을 단언했는지 적는다. 결함 동작을 단언했으면 rc=0이 확인이고, 약속(Javadoc·결정)을 단언했으면 실패가 확인이다. 둘이 섞이면 rc만으로 결과를 읽을 수 없다.
- strict lane에 `--tests`를 붙여 탐침만 돌려도 된다. 단 `requires`(클래스 이름)로 고르는 lane은 고른 클래스가 모두 돌지 않으면 실패한다(`StrictTestLanePlugin`의 required 검사). 그 lane은 필터 없이 돌린다. 필터 실행은 탐침의 증거일 뿐 lane 통과의 증거가 아니다.
- 커밋하는 수정이 그 source set에 없던 의존성을 쓰면 lockfile도 같은 커밋에 넣는다. desktop worktree에서 `./gradlew <gradle-path>:resolveAndLockAll --write-locks`로 다시 만들어 가져오고 `verifyDependencyLocks`로 본다. 손으로 고친 lockfile은 Gradle이 실제로 고른 버전과 다를 수 있다.
- 탐침이 그 source set에 없는 의존성을 써야 하면 버릴 worktree에서만 `build.gradle` 한 줄을 더하고 `--write-locks`로 돌린다. 바꾼 줄(빌드 파일, lockfile)을 실행 기록에 적는다. 그렇게 하지 않기로 했으면 코드 읽기 증거(E1)로 판정한다.
**링크 검사**: workflow `link-check.yml`(lychee)이 PR에서 `README.md`, `src/README.md`, `src/**/README.md`, `src/**/CLAUDE.md`, `docs/**/*.md`, `.github/**/*.md`를 검사한다. 루트 `CLAUDE.md`는 그 범위 밖이라 `scripts/check-work-docs.py`가 본다. lychee가 없는 곳에서는 저장소 루트에서 같은 범위의 상대 링크만 확인한다(외부 URL은 보지 못한다):
@@ -90,7 +91,7 @@ python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(
- 태그 두 줄(`releaseCheck`)은 합친 트리에서 provenance와 공개 경로 스냅숏이 깨지지 않았는지만 본다. `release.yml`의 다른 job(web·websocket·gRPC·httpclient·jpa·fileserver release gate, 이미지)은 릴리스 전에만 돈다([operate.md](../operate.md) 4.3절). 결과 표에 "태그 단계 — 라운드 끝 아님"으로 적는다.
**실제로 돌았음을 보이기.** 새 detached worktree에서 시작하고 모든 Gradle 명령에 `--no-build-cache`를 붙인다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다.
**실제로 돌았음을 보이기.** 새 detached worktree에서 시작하고 모든 Gradle 명령에 `--no-build-cache`를 붙인다. workflow 명령에 그 옵션이 없어도(예: `tasks --group verification`) 증거 실행에는 붙인다. 바뀌는 것은 캐시 사용뿐이라 판정은 같다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다(4절). `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다.
- `mainCheck` 안의 `verifyFeatureScaffold`는 생성한 복사본에서 Gradle을 따로 띄워(`scripts/verify-feature-scaffold.sh`) 바깥의 `--no-build-cache`를 받지 않는다. 바깥 빌드는 FROM-CACHE를 만들 수 없으니 그 로그에 나온 FROM-CACHE는 중첩 빌드의 것이다. 「실제 실행」 칸에 "바깥 FROM-CACHE 0, 중첩 빌드 FROM-CACHE N(태스크 이름)"으로 적는다.
@@ -133,15 +134,16 @@ bash scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lan
- `pr-adapters.yml`의 `changes` job에 있는 `emit` 줄. lane(web·websocket·httpclient·jpa)마다 정규식이고, `grep -E`로 맞춘다.
3. 걸린 workflow·job의 `run` 줄을 그대로 돌린다. matrix가 있으면 값마다 한 번이다(예: jpa는 PostgreSQL 버전마다, httpclient는 transport마다). compose가 필요한 job은 그 job의 `docker compose … up`·`down` 단계도 같이 한다.
4. 걸리지 않은 workflow는 이름과 "경로 안 걸림"을, nightly·수동 전용 job은 "PR·main 단계 아님"을 결과 표에 적는다.
5. 경로로 처음 켜진 lane이 이번 변경과 무관한 이전부터의 실패를 드러내면(예: 진입 문서만 바꿨는데 그 영역 lane이 켜짐), 기준 커밋에서 같은 실패인지 보고 「이전부터」로 적는다. 그 lane 영역의 남은 문제로 넘기고 이번 변경 몫으로 세지 않는다.
(다) 로컬에 도구가 없는 것:
| job | 로컬에서 | 대체가 못 보는 것 |
| --- | --- | --- |
| `link-check.yml`(lychee) | 2절 끝의 같은 범위 상대 링크 검사 | 외부 URL |
| `ci-quality-gates.yml` `grpc-proto-buf`(`buf lint`·`buf breaking`) | buf가 있으면 job의 `run` 줄 그대로. 없으면 못 돌림으로 적는다. diff에 `.proto`·`buf*.yaml`이 없으면 "해당 없음 — proto 변경 없음" | 전부 |
| `link-check.yml`(lychee) | 2절 끝의 같은 범위 상대 링크 검사. desktop에 lychee 공식 이미지가 이미 있으면 그 이미지로 같은 범위를 돌린다 | 외부 URL |
| `ci-quality-gates.yml` `grpc-proto-buf`(`buf lint`·`buf breaking`) | buf나 desktop에 이미 있는 buf 공식 이미지가 있으면 job의 `run` 줄 그대로. 없으면 못 돌림으로 적는다. diff에 `.proto`·`buf*.yaml`이 없으면 "해당 없음 — proto 변경 없음" | 전부 |
| `dependency-vulnerability.yml` `dependency-review`·`dependency-submission` | GitHub에서만 돈다. diff에 lockfile·`src/gradle/libs.versions.toml` 변경이 없으면 "해당 없음", 있으면 PR 결과를 보고 남은 문제로 적는다 | 전부 |
| `dependency-vulnerability.yml` `trivy-fs` | 이미 설치된 trivy가 있으면 job의 검사 줄 그대로. job이 trivy를 내려받아 설치하는 줄은 따라 하지 않는다([operate.md](../operate.md) 4.1절). 없으면 못 돌림 | 전부(못 돌렸을 때) |
| `dependency-vulnerability.yml` `trivy-fs` | 이미 설치된 trivy나 desktop에 이미 있는 trivy 공식 이미지가 있으면 job의 검사 줄 그대로. workflow가 쓰는 버전이 없으면 있는 버전으로 기준 트리와 이번 트리를 같은 DB로 돌려 새로 생긴 걸림만 이번 변경 몫으로 본다. job이 trivy를 내려받아 설치하는 줄은 따라 하지 않는다([operate.md](../operate.md) 4.1절). 없으면 못 돌림 | 전부(못 돌렸을 때) |
## 4. 결과 기록
@@ -166,6 +168,12 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
- 같은 트리 해시에서 돈 자기 실행 로그가 있다(맡은 발견이 이미 커밋된 수정에 들어 있을 때 등). 로그에 적힌 트리 해시와 지금 트리 해시를 함께 적는다.
- 트리가 다르거나 다른 세션 보고의 「통과」는 증거가 아니다(E0). 다시 돌린다.
**smoke 이미지가 이 트리에서 만들어졌음을 보이기.** smoke·compose lane은 Docker 레이어 캐시를 쓴다. 이미지 생성 시각은 runtime 레이어가 캐시에서 오면 증거가 못 된다. 앱 jar를 복사하는 단계가 smoke 로그의 build 출력에서 `CACHED`가 아닌지 본다. 앱 jar가 이 트리에서 새로 만들어졌으면 그 단계는 캐시가 될 수 없다. 결과 표 「실제 실행」 칸에 그 줄과 이미지 id를 적는다.
**원래 있던 실패 가리기.** 시간·자원에 기대는 실패(OOM, 시간 초과, 순서 의존)는 기준 커밋과 이번 트리에서 같은 명령을 각각 세 번 돌린다. 기준에서 한 번이라도 같은 원인(같은 테스트, 로그의 같은 OOM·시간 초과)으로 실패하면 이전부터의 실패로 적는다. 기준에서 세 번 다 통과하고 이번 트리에서만 실패하면 이번 변경 몫이다. 순서 의존을 재현하려면 그 테스트 클래스를 `--tests <클래스> --rerun`으로 열 번 돌리고, 부하가 필요하면 잠금을 쥔 채 `nproc`개의 `yes > /dev/null &`를 띄웠다가 끝나면 끈다. 실패한 반복 수를 적는다.
**공유 잠금 기다리기.** 순서는 `flock`이 정한다(먼저 잡은 쪽). 따로 순번을 정하지 않는다. 기다리는 명령은 background로 두고 다른 일을 하며, 대기는 완료나 첫 실패에서 끝나는 것 하나로 둔다. 30분 넘게 못 잡으면 `ps -o pid,etime,args -C flock`으로 쥔 쪽을 보고 맡긴 쪽에 알린다([operate.md](../operate.md) 7절).
함께 적는다:
- 대상 커밋 sha. 작업 트리가 커밋되지 않았으면 그렇다고 적는다.
@@ -206,5 +214,21 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
| 시간 단언을 끈 채 performance lane 실행 | convention이 단언을 켜고, 끄는 값이나 skip이 있으면 테스트 전에 실패(5절) |
| 캐시에서 가져온 결과를 지금 통과한 것으로 셈 | 기준 상태 확인과 시간·환경에 민감한 테스트는 그 태스크를 `--rerun`으로 다시 돌린다. `--rerun`은 바로 앞 태스크 하나에만 걸리므로 태스크마다 붙인다. 집계 태스크는 새 worktree와 `--no-build-cache`로 돌리고 FROM-CACHE 0을 보인다(3절) |
| 외부 이미지가 사라져 다른 lane 결과까지 가림 | 테스트 이미지를 `src/config/testing/container-images.properties` 한 곳에 digest로 고정, main 단계는 `--continue` |
| smoke rc=0인데 앱이 OOM으로 재시작함 | `scripts/run-compose-runtime-smoke.sh`가 lane 컨테이너 재시작·OOMKilled를 실패로 보고 `restarts.txt`·`app-memory-peak-bytes.txt`를 남긴다. 그 밖의 compose 실행은 `docker inspect -f '{{.RestartCount}} {{.State.OOMKilled}}' <컨테이너>`로 본다 |
| 셸 함수·`if` 조건 안에서 `set -e`가 꺼져 중간 실패가 지나감 | 실패를 받아야 하는 명령은 `if`·`&&`·`||` 조건 밖에 두거나 rc를 직접 본다(`<명령>; rc=$?; [ "$rc" -eq 0 ] \|\| exit "$rc"`) |
게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다.
## 7. workflow·검사 스크립트를 더할 때
리뷰는 빠진 검사만 찾기 쉽다. 장치를 더하기 전에 아래를 보고, 더하는 PR 본문에 답을 적는다. workflow 파일을 고치는 일은 CI 담당 작업이 한다.
1. 어느 단계인가(PR·main·nightly·release), 그리고 그 단계의 기존 workflow에 job으로 넣을 수 없는 이유를 한 줄로 쓴다. 모듈 이름의 workflow 파일은 만들지 않는다.
2. 새 job이 다른 단계가 이미 돌리는 태스크를 다시 돌리지 않는지 `--dry-run` 태스크 목록으로 보인다.
3. lane 고르기·순서·집계는 Gradle에 둔다. 단계 job의 `run:`은 한 줄이다.
4. 경로 필터를 새로 쓰려면 그 lane이 다른 단계에서 무조건 돈다는 것을 보인다.
5. 문서·이름·개수·CI 배선을 검사하는 것은 main 단계다(2026-09-16 소유자 결정). PR에 두어야 하면 이유를 적는다.
6. 이벤트별 job 수 변화와 잰 실행 시간을 적는다. runner 용량은 [operate.md](../operate.md) 4.1절의 값으로 판단한다.
7. 실행 환경(Gitea)에서 돌지 않는 action·권한(`id-token`, ghcr, GitHub 의존성 그래프, `upload-artifact@v4` 이상)을 쓰지 않는다. 써야 하면 `github.server_url` 조건을 단다.
8. Gradle 밖 검사 스크립트는 `scripts/`에 두고, 머리 주석에 누가 부르는지(workflow·Gradle·사람·훅)를 적는다. 부르는 곳이 없는 검사 스크립트는 만들지 않는다. 같은 일을 하는 빌드 태스크가 있으면 거기에 넣는다. 스크립트의 시험은 `scripts/tests/`에 unittest로 둔다. `docs-check.yml`이 PR마다 `python3 -m unittest discover -s scripts/tests`로 돌린다.
9. 같은 장치에서 결함이 두 라운드 연속 나오면 고치기 전에 그 장치가 필요한지 다시 본다([improve.md](../improve.md) 7절).
+13 -12
View File
@@ -56,7 +56,7 @@
| 등급 | 정의 |
| --- | --- |
| Critical | 전체 리뷰의 Critical과 같다 |
| Important | 현실적 조건에서 틀린 동작·보안·데이터·공개 계약, 또는 운영자에게 틀린 조치를 시키는 문서 |
| Important | 현실적 조건에서 틀린 동작·보안·데이터·공개 계약, 또는 운영자·개발자에게 틀린 조치를 시키는 문서(예: README·`AGENTS.md`가 지운 타입을 지금 것으로 설명, 지운 설정 키를 켜라고 함) |
| Minor | 그 밖의 결함. 예: 거짓 실패 쪽 검사, 좁은 조건의 불일치, 문구 |
확인 리뷰 발견에는 "이번 수정이 만들었나 / 이전부터 있었나"를 적는다. 이번 수정이 만든 것은 회귀로 따로 센다.
@@ -101,14 +101,14 @@
| # | 관점 | 볼 곳 | 이런 증거면 결함 |
| --- | --- | --- | --- |
| 1 | 코드 성숙도 | 바뀐 클래스와 호출자, 예외 경로 | 이름·Javadoc과 다른 동작, 항상 참·거짓인 조건 |
| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md` | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import |
| 2 | 구조적 성숙도 | registry `allowed_dependencies`, ArchUnit, leaf `AGENTS.md`, 저장소 루트와 `src/`의 최상위 목록(폴더마다 계층·조립 leaf, Gradle 루트 표준 `build-logic`·`gradle`·`config`, 지도에 적힌 예외 `platforms/`, 저장소 운영 `docs`·`scripts`·`.github` 중 하나인지) | HARD-STOP 위반, registry 밖 leaf 디렉터리, 템플릿 패키지가 기능 패키지를 import, 역할을 한 문장으로 말할 수 없는 최상위 폴더, 같은 역할의 폴더가 같은 높이에 여럿, 지도(`AGENTS.md`)와 `scripts/check-repo-layout.py` 허용 목록에 없는 최상위 항목 |
| 3 | 변경 용이성 | 기능 하나를 더하거나 뺄 때 고칠 파일, `scripts/new-feature.sh` 왕복 | 같은 규칙을 여러 곳에서 바꿔야 함 |
| 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음 |
| 4 | 인지 부하 | 따라 할 예시 수, 같은 질문에 답하는 문서 수, 루트 README만 읽고 구조·매뉴얼·첫 실행을 5분 안에 찾는가(cold-read 결과), 이벤트별 workflow job 수 | 예시·규칙이 여러 갈래이고 고르는 기준이 없음, 같은 Gradle 태스크를 두 단계 이상이 돎(의도한 행렬 제외) |
| 5 | 위험 가시성 | 기본값, 설정 검증, 기동 rule, 프로필 허용 목록 | 위험이 기본값 뒤에 숨음, 레지스트리 `required`인데 코드는 빈 값 허용 |
| 6 | 실패 성숙도 | 예외 분류, `retryable`, 결과 불명 | 결과 불명을 확실함으로, 재시도 가능을 확정 실패로 기록 |
| 7 | 운영 성숙도 | `docs/runbooks/`, `docs/registries/metrics.yaml`, 종료 순서 | runbook이 틀린 조치를 시킴, 레지스트리 지표를 아무 코드도 내보내지 않음 |
| 8 | 디버깅 가능성 | `ServerFailureLog`, correlation id, 오류 코드 | 서버 실패를 남기지 않음, 원인이 다른 실패를 같은 코드로 |
| 9 | 유지보수 성숙도 | 복사본, 죽은 코드, 낡은 주석 | 갈라진 복사본, 현재 동작과 다른 주석·문서 |
| 9 | 유지보수 성숙도 | 복사본, 죽은 코드, 낡은 주석, 살아 있는 문서의 표본 주장(문서 종류마다 1~2개 파일, 파일마다 주장 2~5개를 코드와 대조하고 틀린 비율을 README에 적는다), 기록 문서의 상태 칸 | 갈라진 복사본, 현재 동작과 다른 주석·문서, 코드·테스트·workflow·스크립트 어디서도 읽지 않는 비소스 파일(compose, 셸 스크립트, 설정, README. 파일마다 `git grep -l -F <경로> -- ':!docs/history' ':!docs/reviews'`가 0건. 경로를 변수로 조립하는 workflow `matrix`는 따로 본다) |
| 10 | 테스트 성숙도 | 7절 | 이름의 성질을 단언하지 않음, 변이 생존, 계약 밖 fake |
| 11 | 데이터 성숙도 | 마이그레이션 스트림, 유일 제약, `@Version`, 잠금 시간 제한 | 중복 규칙에 DB 제약 없음, 적용된 마이그레이션 수정, `lock_timeout` 없는 강한 잠금 |
| 12 | 동시성 성숙도 | claim·lease, `SKIP LOCKED`, 트랜잭션 경계 | 트랜잭션 없는 `SKIP LOCKED`, lease 없는 claim |
@@ -117,16 +117,16 @@
| 15 | 보안 성숙도 | 인증·인가 체인, `docs/security/public-paths-snapshot.txt`, `docs/registries/secrets-classification.yaml`, 로그 | 기본으로 꺼진 검증, 권한 검사 없는 경로, 로그로 새는 입력값 |
| 16 | 의존성 성숙도 | `src/gradle/libs.versions.toml`, lockfile, `src/config/testing/container-images.properties` | 사라진 외부 이미지, 운영 jar의 테스트용 드라이버 |
| 17 | API·계약 성숙도 | `docs/web/http-contract.md`, `docs/registries/error-codes.yaml`, `docs/architecture/*-api-surface.txt`, 짝 프론트 계약 | 코드·문서·짝 계약이 서로 다름 |
| 18 | 배포 성숙도 | `src/Dockerfile`, compose, `release.yml` | 빌드되지 않는 Dockerfile, relay를 모르는 종료 순서 |
| 18 | 배포 성숙도 | 저장소 루트 `compose.yaml`, `src/Dockerfile`, 테스트 lane 계약(`compose-profile-contracts.json`), `release.yml` | 빌드되지 않는 Dockerfile, relay를 모르는 종료 순서, README의 개발 환경 기동 명령이 실제로 뜨지 않음, 개발 환경을 띄우는 길이 둘 이상, 개발 환경 compose와 테스트 fixture가 한 파일에 섞임, Kubernetes 매니페스트·프록시 설정·IaC가 이 repo에 있음(배포 경계 `docs/ci-cd/boundary.md`) |
| 19 | 설정 성숙도 | `StrictSettingsBinder`, `docs/registries/env-keys.yaml`, `config/module-defaults/<모듈>.yml`, `verifyEnvKeys` | 바인딩되지만 동작하지 않는 키, 한 설정을 두 곳에서 읽음 |
| 20 | 개발자 경험 | `scripts/new-feature.sh`, `docs/manual/`, 게이트 시간 | 매뉴얼·생성 명령대로 하면 게이트를 통과하지 못함 |
| 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계 | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사 |
| 20 | 개발자 경험 | `scripts/new-feature.sh`, `docs/manual/`, 게이트 시간, 빈 clone에서 README 명령만으로 개발 환경을 띄우고 내리기(compose 파일 하나), 문서 지도가 모든 문서 폴더를 덮는가(`check-docs.py` `map`), 템플릿 CI 변경이 파생 서비스 동기화에서 건드리는 파일 수 | 매뉴얼·생성 명령대로 하면 게이트를 통과하지 못함, 개발 환경에 compose 파일이 둘 이상 필요함 |
| 21 | Guardrail 성숙도 | ArchUnit, `verifyStrictLaneStages`, 기동 rule, 정적 분석 단계, 편집 훅(`scripts/hooks/`), CI 실행 기록(URL) | 거짓으로 통과하는 게이트, 어떤 단계도 돌리지 않는 검사, CI 최근 실행 기록이 없음(확인 못 하면 「미검증」이 아니라 결함 후보), 검사 장치가 지키는 대상보다 큼, 같은 장치에서 두 라운드 연속 결함, 개수·문서·배선 검사가 PR 단계에 있음, 실행 환경(Gitea)에서 돌지 않는 action·권한 |
| 22 | 추상화 성숙도 | 포트·SPI가 보호하는 것 | adapter가 정책을 소유, 역할 없는 단계 |
| 23 | 일관성 | 같은 역할의 이름·모양·규칙 | 같은 개념이 여러 벌 |
| 23 | 일관성 | 같은 역할의 이름·모양·규칙, 문서의 언어·문체·상태 어휘(`check-docs.py` `language`·`style`·`head`) | 같은 개념이 여러 벌, 한 문서 안에서 문체가 섞임 |
| 24 | 네이밍·의미 | `src/application-core/AGENTS.md` 「Naming convention」, `NamingConventionTest` | 이름과 내용이 다름 |
| 25 | 조직 확장성 | 파생 서비스가 upstream을 받을 때 겹치는 곳 | 기능 패키지가 템플릿 패키지와 섞임 |
| 26 | Ownership | leaf마다 가까운 `AGENTS.md`·README | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 |
| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎 |
| 26 | Ownership | leaf마다 가까운 `AGENTS.md`·README(자기 것이나 family 것) | 안내 문서 없음, 패키지가 평평해 소유가 안 보임 |
| 27 | 삭제 가능성 | capability `runtimeOnly` 한 줄 제거, 샘플·예시 모듈 | 한 줄 지워도 흔적이 남음, bootstrap이 capability 이름을 앎, 매뉴얼·생성 명령이 같은 역할을 하는데 남은 샘플(그 샘플이 어떤 게이트의 유일한 검증 대상이면 그 역할과 옮길 곳이 적혀 있는지) |
| 28 | 회복 가능성 | runbook SQL, DEAD·park, ledger 회수 | 영구히 막히는 key, 복구가 행마다 수작업 |
**따라갈 시나리오** (가이드 31절). 전체 리뷰는 시나리오마다 요청 하나를 끝까지 따라가며 입력 신뢰 수준, 권한 판단 위치, 규칙 소유자, 트랜잭션 시작과 끝, 외부 부작용, 오류 변환을 적는다. 해당 기능이 없으면 적용 제외 사유를 한 줄 적는다.
@@ -201,7 +201,7 @@ RED가 증거가 되려면: 실패 메시지가 그 결함을 말한다. 머신
- 새 업무 기능은 계층 leaf 안의 패키지가 기본이다(`docs/manual/03-placement.md`).
- 템플릿 패키지 목록은 `src/application-core/AGENTS.md` 「Package ownership」 표 하나가 정본이다. 템플릿에 패키지를 더하면 같은 변경에서 표에 넣는다.
- capability는 자기 `AutoConfiguration.imports`로 켜진다. `app-bootstrap`은 capability 이름·스위치 목록·scan 정규식을 갖지 않는다.
- vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `CLAUDE.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다.
- vendored family(`messaging:*`, 같은 방식의 `grpc:*`)는 `domain-core`·`application-core`·`shared-contract`에 의존하지 않는다. 그래서 남는 복사본은 이유를 family `AGENTS.md`에 적고, 값이 같아야 하면 대조 테스트를 둔다.
- source set은 runtime·classpath·외부 인프라·JVM 옵션·실행 비용 중 하나가 다를 때만 나눈다. 공유 테스트 코드는 `src/testFixtures/java`다(`docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md`).
- 마이그레이션은 저장소마다 자기 디렉터리와 history table을 가진다. 번호는 스트림 안의 순번이다. 어딘가에 적용된 파일은 고치지 않는다(`src/adapter/outbound/persistence-jpa/src/test/resources/db/applied-migrations.sha256`이 해시를 고정한다).
- 문서 위치 규칙은 `docs/README.md`가 정본이다.
@@ -212,11 +212,12 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼
- [ ] leaf `build.gradle`: `ca.java-library`·`ca.spring-library`·`ca.platform-module` 중 하나
- [ ] lockfile(`verifyDependencyLocks`가 통과하게 다시 만든다)
- [ ] capability면 `src/app-bootstrap/build.gradle`의 `runtimeOnly` 한 줄과 자기 `AutoConfiguration.imports`
- [ ] leaf `AGENTS.md`, capability면 README 세 가지(제공하는 것, 추가할 한 줄, 필요한 env 키)
- [ ] leaf `AGENTS.md`(그 폴더 `CLAUDE.md`는 `@AGENTS.md` 한 줄), 자기 README나 family README의 다섯 칸(`docs/README.md` 「모듈 README」). capability면 README에 제공하는 것, 추가할 한 줄, 필요한 env 키
- [ ] 템플릿 패키지를 더하거나 지우면 「Package ownership」 표
- [ ] ArchUnit 규칙과 그 위반·허용 fixture
- [ ] 지운 leaf를 가리키던 문서·workflow·주석(grep으로 찾는다)
- [ ] 파생 서비스에 영향이 있으면 `docs/upgrade/`의 안내 행
- [ ] 문서를 바꿨으면 `python3 scripts/check-docs.py`와 `python3 scripts/check-work-docs.py`
검증은 [gates.md](gates.md) 2절의 "leaf 경계·의존·registry" 행이다.
+25
View File
@@ -0,0 +1,25 @@
# 용어
이 repo가 영어 그대로 쓰는 말과, 한국어로 정한 말의 뜻이다. 문서는 처음 나올 때 이 표기를 쓴다. 용어 순서(자연스러운 한국어 → 한국어(영어) → 영어 그대로)의 정본은 design-docs `conventions/docs-system.md` 3절이다.
| 표기 | 뜻 |
| --- | --- |
| leaf | registry(`src/config/architecture/modules.json`)에 등록된 Gradle 프로젝트 하나. 경계의 단위다 |
| family | 이름 앞부분이 같은 leaf 묶음(`adapter:inbound:*`, `messaging:*`). 공통 규칙은 그 폴더의 `AGENTS.md`다 |
| registry | leaf 목록·경로·허용 의존의 정본 파일 `src/config/architecture/modules.json` |
| capability | `runtimeOnly` 한 줄로 켜고 끄는 부가 기능 모듈(`docs/manual/10-capabilities.md`) |
| 조립(composition) | 기능을 엮기만 하는 leaf(`src/composition/*`)나 `app-bootstrap`의 배선 |
| lane | 같은 조건(실 DB, 컨테이너, 시간)으로 묶어 돌리는 테스트 실행 단위. strict lane은 build-logic `strictTestLanes`가 정의한 것 |
| 단계 | workflow가 게이트를 도는 때: PR, main, nightly, 태그 |
| 개발 환경 | 루트 `compose.yaml` 하나로 띄우는 로컬 스택(앱 컨테이너의 Spring 프로필은 `local`). `src/app-bootstrap/compose-lanes/`의 overlay는 테스트 lane fixture다. 그중 `dev.yaml`·`prod-smoke.yaml`은 앱을 Spring 프로필 `dev`·`prod`로 띄워 그 프로필의 기동을 보는 lane이고, 개발 환경이 아니다 |
| 게이트 | 통과해야 병합·릴리스하는 검사(`docs/work/reference/gates.md`) |
| outbox | 트랜잭션 안에 남긴 이벤트를 relay가 나중에 발행하는 방식 |
| HARD-STOP | 어기면 동작해도 완료가 아닌 일곱 조건(루트 `AGENTS.md`) |
| brief | 다른 세션에 일을 맡기는 지시문(`docs/work/delegate.md`) |
| 총괄 | 일을 나누고 brief를 쓰고 결과를 대조하는 세션 |
| 하위 세션 | 총괄이 띄운 별도 세션. 파일을 바꾸는 위임을 맡는다. 소유자가 열어 보고 멈출 수 있다 |
| 서브에이전트 | 한 세션 안에서 Agent 도구로 띄우는 도우미(`.claude/agents/`). 결과만 돌려준다 |
| 훅, 넛지 | 훅은 Claude Code가 정해진 때 대신 돌리는 명령(`scripts/hooks/`). 넛지는 막지 않고 알리기만 하는 훅이다 |
| 탐침 | 의심 결함을 보려고 버릴 worktree에서 잠깐 돌리는 테스트(`docs/work/reference/gates.md` 2절) |
| RED, GREEN | 수정 전 실패를 실행으로 본 것, 수정 뒤 통과를 본 것 |
| 살아 있는 문서, 기록 | 코드와 같이 고치는 문서, 쓴 때의 글로 두고 머리 블록만 고치는 문서(`docs/README.md`) |