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
+5 -1
View File
@@ -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 <base> <브랜치 A> <브랜치 B>`로 본다.
- PR을 만들기 전에 그 head 브랜치의 열린·닫힌 PR과 base 상태를 보지 않아, 이미 병합된 커밋으로 PR을 또 만든다. Gitea API(`/api/v1/repos/<owner>/<repo>/pulls?state=all`)로 먼저 본다.