From c8db79a78fb5c7ba1357f9f7f322a9ed5c4fa936 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 22:20:38 +0900 Subject: [PATCH] =?UTF-8?q?docs(work):=20=EC=8C=93=EC=9D=B8=20=EB=A7=A4?= =?UTF-8?q?=EB=89=B4=EC=96=BC=20=EB=B9=88=ED=8B=88=EA=B3=BC=20=EC=A1=B0?= =?UTF-8?q?=EC=82=AC=20=EB=AC=B8=EC=84=9C=EC=9D=98=20=EB=A7=A4=EB=89=B4?= =?UTF-8?q?=EC=96=BC=20=EA=B7=9C=EC=B9=99=EC=9D=84=20=ED=95=9C=20=EB=AC=B6?= =?UTF-8?q?=EC=9D=8C=EC=9C=BC=EB=A1=9C=20=EB=84=A3=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- .claude/rules/settings-and-runtime.md | 2 +- docs/ci-cd/template-vs-consumer.md | 3 +++ docs/work/README.md | 3 ++- docs/work/delegate.md | 6 ++++- docs/work/docs-writing.md | 16 +++++++++---- docs/work/improve.md | 7 +++--- docs/work/new-feature.md | 1 + docs/work/operate.md | 6 +++-- docs/work/reference/decisions.md | 4 ++-- docs/work/reference/gates.md | 32 ++++++++++++++++++++++---- docs/work/reference/review-criteria.md | 25 ++++++++++---------- docs/work/reference/terms.md | 25 ++++++++++++++++++++ 12 files changed, 99 insertions(+), 31 deletions(-) create mode 100644 docs/work/reference/terms.md diff --git a/.claude/rules/settings-and-runtime.md b/.claude/rules/settings-and-runtime.md index 861e9cae..8610ae5d 100644 --- a/.claude/rules/settings-and-runtime.md +++ b/.claude/rules/settings-and-runtime.md @@ -30,5 +30,5 @@ paths: - `src/Dockerfile`을 바꾸면 build context와 runtime env 요구사항을 함께 확인한다. - container 안에서 필요한 profile, port, env 키를 문서나 예시 설정에 반영한다. -- local 전용 경로와 운영 경로를 섞지 않는다. 개발 환경 compose는 루트 `compose.yaml` 하나다. 테스트 환경(compose, 스크립트)은 그 lane을 가진 leaf 안에 둔다. 배포 매니페스트·프록시 설정·IaC는 이 repo에 두지 않는다(`docs/ci-cd/boundary.md`). +- local 전용 경로와 운영 경로를 섞지 않는다. 개발 환경 compose는 루트 `compose.yaml` 하나다(「개발 환경」과 lane overlay의 차이는 `docs/work/reference/terms.md`). 테스트 환경(compose, 스크립트)은 그 lane을 가진 leaf 안에 둔다. 배포 매니페스트·프록시 설정·IaC는 이 repo에 두지 않는다(`docs/ci-cd/boundary.md`). - Docker는 노트북에서 돌리지 않는다. desktop에서 돌린다(`docs/work/operate.md` 4.1절). diff --git a/docs/ci-cd/template-vs-consumer.md b/docs/ci-cd/template-vs-consumer.md index 715189bc..cd0bf320 100644 --- a/docs/ci-cd/template-vs-consumer.md +++ b/docs/ci-cd/template-vs-consumer.md @@ -32,6 +32,9 @@ | `dependency-vulnerability.yml` | dependency-review + Trivy | | `ci-quality-gates.yml` | PR 게이트 | | `release.yml` | 이미지 · SBOM 생산 | +| `docs-check.yml` | 문서 규칙(`scripts/check-docs.py`: 언어·머리 블록·참조·숫자·지도·링크·문체)과 Gradle 밖 스크립트·편집 훅의 시험(`scripts/tests/`). 파생 서비스의 문서도 같은 규칙을 따른다(`docs/README.md`) | +| `link-check.yml` | 문서의 외부 URL과 상대 링크(lychee) | +| `scripts/check-repo-layout.py`(`ci-quality-gates.yml` 안) | 저장소 최상위 배치. 서비스가 최상위 항목을 더하면 허용 목록과 `AGENTS.md` 지도를 함께 고친다 | | action의 full SHA 핀 | 공급망 | ## 파생 프로젝트가 할 일 diff --git a/docs/work/README.md b/docs/work/README.md index f90a056e..f770bacd 100644 --- a/docs/work/README.md +++ b/docs/work/README.md @@ -24,7 +24,7 @@ - brief(작업 지시문)에 크기가 있으면 그대로 한다. 올릴 수는 있고 내릴 수는 없다. 올리면 이유를 보고에 쓴다. - brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다. - 이 repo에서 "경계"는 registry의 leaf 하나다. 파일 수가 아니라 바뀌는 경계와 영향으로 정한다. -- 아래는 파일이 하나여도 큼이다: 공개 계약(HTTP wire 계약 `docs/web/http-contract.md`, 오류 코드 레지스트리, API surface 스냅숏, env 키), 파생 서비스가 따라 고쳐야 하는 변경, 새 leaf, 보안 정책. +- 아래는 파일이 하나여도 큼이다: 공개 계약(HTTP wire 계약 `docs/web/http-contract.md`, 오류 코드 레지스트리, API surface 스냅숏, env 키), 파생 서비스가 따라 고쳐야 하는 변경, 새 leaf, 저장소 루트나 `src/` 최상위에 폴더를 새로 만들거나 옮기는 일, 보안 정책. - 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다([research-design.md](research-design.md)). 소유자가 그 변경을 이미 정했으면(결정 색인 행, 소유자 원문) 그 결정이 소유자 검토다. 출처와 시각을 보고에 적고 만든다. 결정이 다루지 않은 범위만 멈추고 묻는다. ## 3. 모든 작업의 공통 단계 @@ -69,6 +69,7 @@ | [reference/review-criteria.md](reference/review-criteria.md) | 결함 정의, 심각도, 증거·통제 수준, 점검 항목, 리뷰 문서 양식 | | [reference/defect-patterns.md](reference/defect-patterns.md) | 반복해서 나온 결함의 모양과 막는 기준 | | [reference/decisions.md](reference/decisions.md) | 이미 정한 결정의 색인, 결정을 다시 여는 조건과 기록하는 법 | +| [reference/terms.md](reference/terms.md) | 영어 그대로 쓰는 말과 정한 표기의 뜻 | | [evidence.md](evidence.md) | 이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID | ## 8. 이 폴더를 고칠 때 diff --git a/docs/work/delegate.md b/docs/work/delegate.md index fadabd29..40716eff 100644 --- a/docs/work/delegate.md +++ b/docs/work/delegate.md @@ -63,7 +63,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 | 파일 | 왜 | | --- | --- | -| `docs/upgrade/` 안내 문서 | 묶음마다 행을 더해 번호가 겹친다 | +| `docs/upgrade/` 안내 문서 | 묶음마다 행을 더해 번호가 겹치고, 머리 「커밋:」 줄을 여럿이 고치면 충돌한다. 묶음은 「커밋:」 줄을 고치지 않고 보고에 커밋을 적는다. 총괄이 합칠 때 한 번에 적는다 | | `docs/reviews/<폴더>/README.md` | 처리 표·결정의 답·게이트 기록·남은 것은 총괄이 쓴다. 리뷰어는 자기 라운드 색인 절 하나만 쓴다([improve.md](improve.md) 4.1절 7단계) | | `src/config/architecture/modules.json`, `src/settings.gradle` | registry 하나가 모든 leaf를 정한다 | | `src/gradle/libs.versions.toml`, lockfile | 의존성을 바꾸면 lockfile 전체가 바뀐다 | @@ -80,6 +80,8 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 - 묶음 크기 상한을 지킨다([improve.md](improve.md) 4.4절: 영역 하나, 발견 8건 이하, 확인 리뷰당 추가 1,500줄 이하). - 전 leaf의 import를 바꾸는 묶음은 나머지를 합친 뒤 혼자 마지막에 한다. - 같은 결함을 두 영역이 보면 한 묶음에만 배정한다. +- 같은 파일·장치에서 결함이 두 라운드 연속 나오면 다음 묶음은 수정이 아니라 「이 장치가 필요한가, 형식을 좁혀 없앨 수 있나」를 보는 조사([research-design.md](research-design.md))로 맡긴다. +- 합칠 때 충돌 해결 밖에서 새로 고칠 것이 생기면 병합 커밋에 넣지 않고 병합 뒤 따로 커밋한다. 병합 커밋에는 충돌 해결만 둔다. - 합칠 때는 하위 브랜치를 모아 [reference/gates.md](reference/gates.md) 3절 묶음을 돌린다. 합치기와 그 게이트도 하위 세션에 맡길 수 있다. ### 4.3 소유자 환경 @@ -125,3 +127,5 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 - 묶음을 너무 크게 만들어 마감 안에 검증 보고가 오지 않는다. 묶음 크기 상한을 지킨다. - 하위 세션이 적은 태스크 이름을 확인하지 않고 소유자에게 옮긴다. - 같은 범위를 두 리뷰에 따로 맡기고(비교 시험 등) ID를 매길 쪽을 정하지 않아, 같은 ID가 다른 결함을 가리킨다. brief에 ID를 매길 리뷰 하나를 정한다(규칙은 [reference/review-criteria.md](reference/review-criteria.md) 10절 「ID」). +- brief에 「다른 PR과 충돌 없음」을 대상 파일 몇 개만 비교해 적는다. 쓰려면 바뀌는 모든 파일을 `git merge-tree --write-tree <브랜치 A> <브랜치 B>`로 본다. +- PR을 만들기 전에 그 head 브랜치의 열린·닫힌 PR과 base 상태를 보지 않아, 이미 병합된 커밋으로 PR을 또 만든다. Gitea API(`/api/v1/repos///pulls?state=all`)로 먼저 본다. diff --git a/docs/work/docs-writing.md b/docs/work/docs-writing.md index df4c0fe5..844d18d2 100644 --- a/docs/work/docs-writing.md +++ b/docs/work/docs-writing.md @@ -30,18 +30,24 @@ 1. 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다". 2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `AGENTS.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다. 3. 위치를 정한다. 문서 위치 규칙은 `docs/README.md`다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다. -4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다. +4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다. 문체는 「~한다」다. 높임 문장은 `check-docs.py` `style`이 막는다. 용어는 [reference/terms.md](reference/terms.md)의 표기를 쓰고, 새 용어를 정하면 거기에 더한다. 언어 규칙(`docs/README.md` 「문서 수명과 언어」)은 문서(`.md`)에 걸린다. 코드 주석·Javadoc은 그 파일이 쓰는 언어를 따른다. 5. 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은 `src/build.gradle`이나 leaf `build.gradle`에서, 경로는 `ls`로 확인한다. 6. 지난 일을 근거로 쓸 때는 날짜, 무엇이 일어났나, 숫자를 한 줄로 쓴다. 리뷰 ID·묶음 이름·번호만 쓴 결정은 매뉴얼 본문에 쓰지 않는다. 걷어낸 ID 중 근거로 남길 것은 어느 문서에서 왔든 [evidence.md](evidence.md)에 원래 문서·문장과 함께 모은다. 걷어낸 문서 묶음(예: `docs/manual/`, 진입 문서)마다 절 하나를 두고, 같은 묶음을 다시 걷어내면 그 절에 표를 더한다. ID가 무엇을 가리키는지는 evidence.md 머리말 「표기」로 찾는다. 번호의 원래 문서가 이 repo에 없으면 그 번호가 가리키는 규칙 이름과 코드 위치를 근거로 적고, 원래 문서가 repo에 없다고 쓴다. 7. 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)와 `file:line`은 링크가 아니라 코드 표기로 쓴다. 링크 검사(lychee)가 따라가지 못하기 때문이다. 8. 숫자를 복제하지 않는다. leaf 개수, 테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다. 9. 그 문서를 읽는 테스트가 있는지 찾는다: `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). 없으면(주석만 걸리는 것도 없음이다) lane은 돌리지 않고, grep 명령과 결과를 보고에 적는다. brief가 돌릴 lane을 정했으면 그 lane을 돌린다(지도 3절: brief가 먼저다). -10. `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다. +10. `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다. 어느 문서든 바꿨으면 `python3 scripts/check-docs.py`도 돌린다(언어, 머리 블록, 참조, 복사한 숫자, 문서 지도, 상대 링크, 문체). 11. 리뷰 폴더 README를 만들거나 고쳤으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다. 12. 다른 문서는 같은 스크립트의 모드로 본다: 상대 링크는 `--links <파일 또는 폴더>`(PR에서는 lychee가 다시 본다), 이력 ID는 `--history <파일 또는 폴더>`. - 이력 검사 패턴을 더하면 오탐을 시험한다. 잡아야 할 이력 문장과 잡지 말아야 할 보통 문장을 시험 파일로 만들어 `--history`로 돌린다. `docs/reviews/**` 밖 전체(`git ls-files '*.md' ':!docs/reviews'`)에도 돌려 새로 걸린 줄을 모두 읽는다. 검사 대상 파일의 오탐은 패턴을 좁혀 없애고, 대상 밖의 오탐은 보고에 적는다. - 기본 검사를 넓히는 커밋은 그 검사가 새로 잡는 문서를 고친 커밋 뒤에 둔다(또는 같은 커밋). 그래야 어느 커밋에서도 기본 모드가 rc=0이다. -13. 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다. 정본은 design-docs `conventions/delegation-loop.md` 10절이다. 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다. +13. 파일·폴더를 옮기는 커밋에는 옮긴 경로를 가리키는 참조 수정(문서 링크, 테스트가 읽는 경로)을 같이 넣는다. 그래야 커밋마다 검사가 통과한다. 내용 수정은 다음 커밋으로 나눈다. 같은 이름의 새 파일이 옛 자리에 생기면 git이 이동으로 잡지 못하니 커밋 본문에 옛 이력을 보는 법을 적는다. +14. 옮겨 쓰는(번역하는) 문서의 기준: + - 코드·다른 문서가 영어 절 제목으로 인용하는 절은 제목을 「한국어 (English)」로 둔다. 그 제목을 글자로 비교하는 테스트가 있으면 같은 변경에서 고친다. + - 레지스트리 yaml(`docs/registries/`)은 값 칸·머리 설명·행별 설명 주석을 한국어로 옮긴다. 출처 줄, 인용, 테스트가 글자로 비교하는 줄은 원문으로 둔다. + - 머리말(`docs/runbooks/template.md`의 front matter)이 없는 runbook에 머리말을 새로 만들지 않는다. `error_codes`·`severity`를 채우는 것은 새 결정이라 그 runbook을 맡은 작업에서 한다. + - 납품 묶음의 해시 목록(`MANIFEST.sha256`)은 납품 당시 바이트의 해시다(`docs/README.md`). 머리 블록을 달거나 번역해 지금 바이트와 맞지 않게 돼도 목록을 고치지 않고, 지금 파일을 맞춰 보는 검사로 쓰지 않는다. +15. 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다. 정본은 design-docs `conventions/delegation-loop.md` 10절이다. 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다. **playbook을 새로 만들 때의 뼈대** (모든 playbook이 같은 제목을 쓴다. 검사 스크립트가 본다): @@ -52,7 +58,7 @@ - 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다. - 문서의 명령·태스크 이름·경로가 기준 커밋에 실제로 있다. - 정본을 복사한 문장이 없다. 가리키는 줄만 있다. -- `docs/work/`·루트 `AGENTS.md`·`CLAUDE.md`·`src/**/AGENTS.md`·`.claude/` 아래 문서를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다. +- `docs/work/`·루트 `AGENTS.md`·`CLAUDE.md`·`src/**/AGENTS.md`·`.claude/` 아래 문서를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다. 어느 문서든 `scripts/check-docs.py`가 rc=0이다. - 그 문서를 읽는 document-contract lane이 있으면 rc=0이다(desktop 로그). - 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다. @@ -74,7 +80,7 @@ [README](README.md) 6절에 더해 적는다. - 바꾼 문서와 줄 수, 분량 상한 대비. -- 검사 결과: `check-work-docs.py`, `check-review-index.py`, 링크 검사, document-contract lane의 rc와 로그 경로. +- 검사 결과: `check-work-docs.py`, `check-docs.py`, `check-review-index.py`, 링크 검사, document-contract lane의 rc와 로그 경로. - cold-read 시험이나 자가 점검: 써 본 brief, 막힌 곳, 고친 것. - 정본과 다른 곳을 찾았으면 그 위치. diff --git a/docs/work/improve.md b/docs/work/improve.md index ab77a9de..c1710cc7 100644 --- a/docs/work/improve.md +++ b/docs/work/improve.md @@ -58,13 +58,13 @@ 1. 원인 경로를 확인한다. 증상이 아니라 원인을 적는다. 2. RED: 결함을 재현하는 테스트를 먼저 쓰고, 수정 전 코드에서 실패하는 것을 실행으로 본다. 실패 메시지가 그 결함을 말해야 한다. 컴파일 오류나 준비 실패는 RED가 아니다. 3. 수정과 테스트를 이미 같이 썼으면, 기준 커밋에 테스트만 얹은 임시 worktree에서 RED를 본다. 실 DB·Redis가 필요한 결함은 실 vendor lane에서 본다. RED용 임시 파일은 테스트든 main 리소스(임시 마이그레이션 등)든 그 worktree에만 둔다. - - RED가 없는 수정도 있다. 문서를 동작에 맞추면, 문서의 주장을 그대로 단언하는 임시 테스트가 기준 커밋에서 실패하는 것을 RED로 쓴다. 이름·설명 문제처럼 테스트로 옮길 수 없으면 틀린 문장과 실제 동작의 출처를 적는다. 동작은 두고 계약만 넓히면 새 케이스가 기준 커밋에서도 통과함을 보이고 「지키는 테스트」로 적는다. 보고 RED 칸에는 "RED 없음 — 이유"를 쓴다. + - RED가 없는 수정도 있다. 문서를 동작에 맞추면, 문서의 주장을 그대로 단언하는 임시 테스트가 기준 커밋에서 실패하는 것을 RED로 쓴다. 절차 문서(runbook)의 결함이면 기준 문서의 단계를 그대로 따르는 임시 테스트를 기준 커밋에 얹어 실패를 보이고, 최종 테스트는 새 단계를 따르게 한다. 한 단계가 다른 단계를 기다려 막히는 결함은 시간 제한으로 끊는 도우미로 "기다렸다"를 실행으로 보인다. 이름·설명 문제처럼 테스트로 옮길 수 없으면 틀린 문장과 실제 동작의 출처를 적는다. 동작은 두고 계약만 넓히면 새 케이스가 기준 커밋에서도 통과함을 보이고 「지키는 테스트」로 적는다. 보고 RED 칸에는 "RED 없음 — 이유"를 쓴다. 4. 가장 작은 수정으로 GREEN을 본다. 5. 같은 원인의 다른 자리를 찾는다. 경계마다 다시 구현된 규칙은 한 곳만 고치면 다른 곳에서 다시 갈라진다. 찾은 자리가 brief 영역 안이고 공개 동작이 바뀌지 않으면 함께 고치고 보고에 적는다. 공개 동작이 바뀌거나 brief 영역 밖이면 고치지 않고 「범위 밖에서 본 것」에 권하는 안과 함께 적는다. 묶음 상한(4.4절)도 지킨다. -6. 그 동작을 설명하는 문서를 같은 변경에서 고친다: `docs/web/http-contract.md`, `docs/registries/`, runbook, `docs/manual/`, leaf README·`AGENTS.md`, Javadoc. 고친 뒤 옛 표현을 grep으로 찾는다. +6. 그 동작을 설명하는 문서를 같은 변경에서 고친다: `docs/web/http-contract.md`, `docs/registries/`, runbook, `docs/manual/`, leaf README·`AGENTS.md`, Javadoc. 고친 뒤 옛 표현을 grep으로 찾는다. 넘겨받은 발견이 테스트 Javadoc·주석이어도 고친다(동작이 바뀌지 않으면 "RED 없음 — 이유"). 7. 파생 서비스가 따라 고쳐야 하면 `docs/upgrade/`의 안내에 행을 적고, 커밋 제목에 `!`와 `BREAKING CHANGE:` 꼬리말을 단다. 문서에 이미 적힌 규칙을 검사가 더 엄하게 지키게 되어 그 규칙을 어기던 코드가 새로 실패하는 것도 여기에 든다(규칙은 이미 정해져 있어 크기는 올리지 않는다). - 안내의 범위(머리 「범위」)가 아직 main에 합쳐지지 않았으면 파생 서비스는 그 행을 받기 전이다. 같은 표면의 행이 있으면 그 행을 고쳐 최종 동작을 적고, 머리 「커밋:」 목록에 이번 커밋을 더한다. main에 합쳐진 안내는 고치지 않고 새 행을 더한다. -8. 영향 leaf의 `check`와 그 코드를 지키는 lane을 돌린다([reference/gates.md](reference/gates.md) 2절, 실행 위치는 [operate.md](operate.md)). +8. 영향 leaf의 `check`와 그 코드를 지키는 lane을 돌린다([reference/gates.md](reference/gates.md) 2절, 실행 위치는 [operate.md](operate.md)). registry는 lane을 모른다. 그 lane은 바꾼 클래스·기능 이름으로 leaf `build.gradle`의 `strictTestLanes` 블록과 lane source set(`src//`)의 테스트를 grep해 찾는다. brief의 lane 목록에 없는 lane이 걸리면 그것도 돌리고 보고에 적는다. ### 4.3 리팩터링, 성능, 구조, 테스트 구조 @@ -118,6 +118,7 @@ - 고치는 법이 공개 동작(응답 코드, 기동 실패 조건, env 키, 파생 서비스 동작)을 바꾸면 고치기 전에 멈추고 묻는다. 형식은 [README](README.md) 5절이다. 레지스트리·`docs/web/http-contract.md`·Javadoc이 이미 약속한 응답으로 코드를 맞추는 것은 결함 수정이라 묻지 않는다(4.2절 7단계의 안내 행은 적는다). 약속한 곳끼리 다르면 셋째 줄대로 한다. - RED를 만들 수 없으면(실 vendor가 없다, 머신에 따라 통과한다) 그 사실과 이유를 보고하고 그 발견만 멈춘다. +- 같은 파일·장치에서 결함이 두 라운드 연속 나오면 그 다음은 수정이 아니라 [research-design.md](research-design.md)로 "이 장치가 필요한가, 형식을 좁혀 없앨 수 있나"를 먼저 본다. - 계약을 적은 곳끼리(설계서, 포트 Javadoc, 모듈 README, 테스트) 다르게 말하고 [reference/decisions.md](reference/decisions.md)에 결정이 없으면, 어느 쪽도 고르지 않는다. 양쪽 근거를 표로 붙이고 권하는 안과 함께 묻는다. 그 발견만 멈춘다. ## 8. 보고 형식 diff --git a/docs/work/new-feature.md b/docs/work/new-feature.md index 04e39663..5ff0fde4 100644 --- a/docs/work/new-feature.md +++ b/docs/work/new-feature.md @@ -56,6 +56,7 @@ - 저장 adapter를 `persistence-jpa` leaf 안에 만들지 않는다. 서비스 전용 persistence leaf에 둔다. - 한 단계가 다른 leaf나 계층을 고쳐야 하면 범위를 조용히 넓히지 않는다. 거기서 멈추고 설계를 다시 본다(7절). - bootstrap에 capability 이름·스위치 목록·scan 정규식을 넣지 않는다. 모듈이 자기 `AutoConfiguration.imports`로 켜진다. +- 새 capability가 테스트 환경(compose, 스크립트)을 더하면 그 leaf 안에 둔다. 저장소 루트에 두지 않는다. leaf가 가진 기능 데이터(readiness card, release registry)는 그 leaf의 `release/`에 둔다. - 노트북에서 Gradle을 돌리지 않는다. ## 7. 막혔을 때 diff --git a/docs/work/operate.md b/docs/work/operate.md index 36702f19..2bc00406 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -32,6 +32,8 @@ - desktop의 Gradle·Docker 실행은 모두 공유 잠금 `flock /tmp/claude-gates/heavy.lock`으로 감싼다. 짝 프론트 repo도 같은 desktop에서 같은 잠금을 쓴다. - desktop의 기존 checkout `~/workspace/clean-architecture-backend-template`은 여러 세션이 함께 쓴다. 그 `stash@{0}`는 소유자의 보관분이다. 건드리지 않는다. `git stash pop`·`drop`·`clear`와 이름 없는 `git stash`를 쓰지 않는다. - design-docs repo는 노트북 `~/workspace/desktop-server-git/design-docs`에 있다. +- desktop 기본 셸은 zsh다. 파이프의 rc는 `bash -o pipefail -c '<명령> | tee <로그>'; echo "rc=$?"`로 받는다(zsh에는 `PIPESTATUS`가 없다). 자기 실행을 멈출 때는 시작할 때 남긴 PID로 `kill `를 쓴다. `pkill -f <경로>`는 그 경로가 든 ssh 명령줄 자신과도 맞아 세션을 끊는다. +- CI runner(2026-11-07): Gitea Actions가 켜졌고, desktop에 `desktop-runner` 하나(`gitea/runner` dind, `capacity: 1`, label `ubuntu-latest`)가 돈다. desktop은 12코어·31GB다. CI job은 공유 잠금을 쓰지 않으므로, 손으로 돌린 게이트가 느리면 `docker ps`로 runner job이 함께 도는지 본다. 절차: @@ -58,7 +60,7 @@ git worktree remove ~/workspace/<작업 이름> - 로그는 desktop `~/<작업 이름>-logs/`에 남기고, 보고에 그 desktop 경로와 rc를 쓴다. 같은 worktree의 다음 실행이 결과 XML을 덮어쓰니, 명령이 끝날 때마다 그 태스크의 `build/test-results/<태스크>/`를 로그 폴더로 복사한다(세는 법은 [reference/gates.md](reference/gates.md) 4절). - RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다. -- workflow job이 도구를 내려받아 설치하는 단계(`curl … | sh`, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다. +- workflow job이 도구를 내려받아 설치하는 단계(`curl … | sh`, setup action)는 desktop에서 따라 하지 않는다. 소유자 기계를 바꾸는 일이다. 이미 설치된 도구로만 돌리고, 없으면 못 돌림으로 적는다. 도구가 실행 때 받는 데이터(trivy 취약점 DB)는 설치가 아니다. 받아도 되고, 받은 DB의 갱신 시각을 기록에 적는다. - compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. bind mount 폴더(dev lane overlay `src/app-bootstrap/compose-lanes/dev.yaml`의 `tmp/heap-dumps`)는 Docker가 root로 만들어 `git worktree remove`가 Permission denied로 실패한다. compose가 이미 받은 이미지(`compose.yaml`의 `redis:7.4`)로 폴더를 지운 뒤 다시 지운다: `docker run --rm --pull=never -v "$PWD/tmp:/t" redis:7.4 rm -rf /t/heap-dumps`. - Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다. @@ -75,7 +77,7 @@ git diff --cached --binary <기준 커밋> | ssh desktop 'cd ~/workspace/<작업 - 그다음 위 3) 4)대로 돌리고 지운다. 결과를 본문에 적어 커밋한 뒤 `git rev-parse HEAD^{tree}`가 같은 해시인지 본다. 같으면 desktop이 돌린 트리가 그 커밋이다. - RED는 같은 방법으로 테스트 파일만 stage해 보낸다. 한 파일의 일부만 stage하는 법은 design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」이다. -- 형식 맞추기(`spotlessApply`)도 Gradle이라 desktop에서 돈다. 패치를 얹은 worktree에서 돌리고, 바뀐 파일을 노트북에 가져와 두 트리 해시가 같은지 본다. 그 뒤의 게이트는 이 트리에서 돌린다. +- 형식은 편집 훅이 파일마다 맞추므로 보통 바뀌는 것이 없다. 그래도 커밋을 나누기 전에 확인한다(나눈 뒤에 고치면 앞 커밋을 다시 만들어야 한다). 형식 맞추기(`spotlessApply`)도 Gradle이라 desktop에서 돈다. 패치를 얹은 worktree에서 돌리고, 바뀐 파일을 노트북에 가져와 두 트리 해시가 같은지 본다. 그 뒤의 게이트는 이 트리에서 돌린다. ```bash ssh desktop 'cd ~/workspace/<작업 이름>/src && flock /tmp/claude-gates/heavy.lock ./gradlew spotlessApply --console=plain' diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index 34e651ea..0c307a94 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -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절 | diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md index 211a17a4..6fa6446f 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -66,6 +66,7 @@ - 탐침마다 무엇을 단언했는지 적는다. 결함 동작을 단언했으면 rc=0이 확인이고, 약속(Javadoc·결정)을 단언했으면 실패가 확인이다. 둘이 섞이면 rc만으로 결과를 읽을 수 없다. - strict lane에 `--tests`를 붙여 탐침만 돌려도 된다. 단 `requires`(클래스 이름)로 고르는 lane은 고른 클래스가 모두 돌지 않으면 실패한다(`StrictTestLanePlugin`의 required 검사). 그 lane은 필터 없이 돌린다. 필터 실행은 탐침의 증거일 뿐 lane 통과의 증거가 아니다. +- 커밋하는 수정이 그 source set에 없던 의존성을 쓰면 lockfile도 같은 커밋에 넣는다. desktop worktree에서 `./gradlew :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절). diff --git a/docs/work/reference/review-criteria.md b/docs/work/reference/review-criteria.md index f331c4be..5d0dd5f0 100644 --- a/docs/work/reference/review-criteria.md +++ b/docs/work/reference/review-criteria.md @@ -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" 행이다. diff --git a/docs/work/reference/terms.md b/docs/work/reference/terms.md new file mode 100644 index 00000000..85a7a699 --- /dev/null +++ b/docs/work/reference/terms.md @@ -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`) |