diff --git a/CLAUDE.md b/CLAUDE.md index 3f75426f..406fc9db 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -62,7 +62,7 @@ brief(작업 지시문)가 있으면 brief의 범위·크기·완료 기준이 - **`src/sample-portfolio`는 지울 수 있는 샘플이다.** 한 leaf에 모든 계층을 둔 모양이라 배치를 따라 하지 않는다. 새 기능의 예시는 `scripts/new-feature.sh`의 출력이다. - **성능 lane에는 단언을 끄는 스위치가 없다.** convention이 상한을 매번 단언하고, `performance.assertions.enabled`에 `true` 아닌 값이 들어오거나 skip이 있으면 테스트 전에 실패한다. 손으로 돌리든 workflow든 같다(`AGENTS.md` 「Gradle 정책 권위」). - **저장소 파일을 읽는 테스트는 태그가 있다.** 문서와 대조하는 테스트는 `document-contract`(main 단계 `mainCheck`), 빌드 스크립트·workflow를 읽는 테스트는 `repository-contract`(PR)다. 문서를 고치면 그 문서를 읽는 테스트를 찾는다. -- **커밋 정책은 `human-only`다.** brief가 허용할 때만 자기 브랜치에 커밋·push한다. 자세한 것은 [docs/work/README.md](docs/work/README.md) 4절이다. +- **커밋 정책은 `human-only`다.** brief가 허용한 것만 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 자세한 것은 [docs/work/README.md](docs/work/README.md) 4절이다. - **문서 위치 규칙은 [docs/README.md](docs/README.md)다.** 설계서는 `docs/superpowers/specs/`, 결정 기록은 `docs/adr/`, 리뷰는 `docs/reviews/`, 파생 서비스용 변경 안내는 `docs/upgrade/`다. ## 6. 소유자 환경 diff --git a/docs/work/README.md b/docs/work/README.md index 3926c8a7..c044abd4 100644 --- a/docs/work/README.md +++ b/docs/work/README.md @@ -41,8 +41,8 @@ ## 4. 커밋 - 기본 정책은 `human-only`다(`AGENTS.md`). 에이전트는 stage·commit·amend·push하지 않는다. -- 예외는 하나다. brief가 커밋을 허용하면, 그 작업의 자기 브랜치에만 커밋하고 push한다. -- 그때도 main 병합, 다른 브랜치 push, force push, PR 병합은 하지 않는다. 그것은 소유자가 한다. +- 예외는 하나다. brief 7절이 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다(desktop 검증은 [operate.md](operate.md) 4.1절 「push 전에 검증하기」). +- 그때도 main 병합, main·다른 브랜치 push, force push, PR 병합은 하지 않는다. 그것은 소유자가 한다. - 메시지 형식은 design-docs `conventions/commit-and-pr.md`를 따른다. AI 꼬리말과 자리표시자(`TBD`, `TODO`, 채우지 않은 칸)를 넣지 않는다. ## 5. 막혔을 때 @@ -54,7 +54,8 @@ ## 6. 보고 - 맨 앞에 결과(완료 / 부분 / 못 함)와 브랜치·커밋을 쓴다. -- 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다. +- 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(위치와 내용, 고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다. +- 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다. - 숫자(테스트 수, 실패 수, 태스크 이름)는 로그에서 옮긴다. 기억으로 쓰지 않는다. - 사고 순서 흔적 칸을 둔다(`conventions/work-thinking-order.md` 3절). 다른 세션이 맡긴 일이면 design-docs `conventions/delegation-loop.md` 5절 양식을 쓴다. diff --git a/docs/work/delegate.md b/docs/work/delegate.md index 5e8a49f9..c123b41b 100644 --- a/docs/work/delegate.md +++ b/docs/work/delegate.md @@ -12,7 +12,7 @@ - 소유자의 목표와 이미 정한 결정. 큰 일이면 소유자가 계획을 검토한 시각. - 결과가 올라갈 브랜치와 그 최신 커밋(기준 커밋). -- 커밋·push 허용 범위. 하위 세션 브랜치 push는 desktop 검증에 필요하다. main 병합·push는 소유자가 한다. +- 커밋 허용과 자기 브랜치 push 허용. brief 7절에 따로 적는다. push 없이도 desktop 검증은 된다([operate.md](operate.md) 4.1절 「push 전에 검증하기」). main 병합·main push는 소유자가 한다. - 마감과 보고 받을 방법. ## 3. 크기와 사고 순서 @@ -31,9 +31,12 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 이 repo에서 더할 것: - brief의 「작업 종류」는 이 repo의 `docs/work/<종류>.md`다. 「이미 아는 것」에는 [reference/decisions.md](reference/decisions.md)의 결정을 **내용으로** 옮긴다. 검증 명령은 [reference/gates.md](reference/gates.md)와 빌드 파일에서 실제 태스크 이름을 확인해 쓴다. -- 검증 칸에는 실행 위치와 증거 위치를 쓴다: desktop worktree, `flock /tmp/claude-gates/heavy.lock`, 로그 `~/<작업 이름>-logs/`([operate.md](operate.md) 4.1절). desktop 검증이 필요하면 7절에 자기 브랜치 push를 허용한다. -- 수정 묶음 brief에는 보고의 「새로 가정하는 것」 칸을 요구한다. 확인 리뷰 brief에는 그 칸부터 보라고 적는다. +- 검증 칸에는 실행 위치와 증거 위치를 쓴다: desktop worktree, `flock /tmp/claude-gates/heavy.lock`, 로그 `~/<작업 이름>-logs/`([operate.md](operate.md) 4.1절). 7절에는 커밋 허용과 자기 브랜치 push 허용을 따로 쓴다. +- 수정 묶음 brief에는 보고의 「새로 가정하는 것」 칸을 요구한다. 확인 리뷰 brief에는 그 칸부터 보라고 적고, 지난 라운드에서 열린 채 넘어온 「Declined to judge」를 다시 판정시킬지도 적는다. - 리뷰 brief에는 쓸 심각도 체계([reference/review-criteria.md](reference/review-criteria.md) 3절)와 "발견마다 이번 수정이 만들었나 / 이전부터"를 요구한다. +- 독립 리뷰어 둘([improve.md](improve.md) 4.1절의 세 경우)이면 범위·기준 커밋·심각도 체계가 같은 brief 둘을 쓰고, 두 세션을 함께 띄운다. 다른 칸은 셋이다: 정본 리뷰어인지(ID를 매기고 리뷰 폴더에 커밋한다), 출력 위치(다른 쪽은 보고에 두고 `B-NN-MM`), 5절에 "자기 리뷰를 끝내기 전에 상대 리뷰의 브랜치·문서·보고·노트를 읽지 않는다". +- 두 리뷰가 끝나면 총괄이 합친다. 같은 결함(같은 원인·같은 위치)끼리 짝짓고, 다른 쪽에만 있는 결함은 정본 리뷰어에게 보내 탐침으로 다시 확인한 뒤 다음 번호로 넣게 한다. 그 라운드 색인 절은 총괄이 쓰고 대응표(`B-NN-MM` → 정본 ID)를 둔다. +- 겹침 비율(두 리뷰가 모두 찾은 결함 수 / 합친 결함 수)을 그 라운드 색인 절과 design-docs `delegation-loop/metrics.md`의 M11 칸에 적는다. 2~3라운드 기록이 쌓이면 소유자가 이 방식을 다시 본다. - 대조할 때: 보고의 태스크 이름·테스트 수를 desktop 로그에서 grep으로 찾는다. High·Important 이상은 총괄이 코드에서 직접 다시 확인한다. - 리뷰 결과를 받으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`로 색인이 빠짐없는지 본다. 수정 묶음은 색인에서 배정한다. - 교훈을 보낼 곳: 그 playbook의 「자주 하는 실수」, 코드 결함 모양은 [reference/defect-patterns.md](reference/defect-patterns.md), 거짓 통과는 [reference/gates.md](reference/gates.md) 6절, 근거는 [evidence.md](evidence.md). @@ -58,7 +61,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 | 파일 | 왜 | | --- | --- | | `docs/upgrade/` 안내 문서 | 묶음마다 행을 더해 번호가 겹친다 | -| `docs/reviews/<폴더>/README.md` | 처리 표·결정·게이트 기록은 총괄이 쓴다 | +| `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 전체가 바뀐다 | | `src/build.gradle`, `src/app-bootstrap/build.gradle` | 라이프사이클과 기본 조립 | @@ -82,6 +85,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 - Agent 도구(세션 안의 하위 에이전트)는 이 repo의 `.claude/settings.json`이 막는다. 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 그 세션이 직접 하거나, 이 playbook대로 별도 세션에 맡긴다. 막혔다고 Agent로 우회하지 않는다. - 실행 위치(desktop, 공유 잠금, desktop worktree)는 [operate.md](operate.md) 4.1절이다. +- 하위 세션은 공유 노트 폴더의 다른 노트를 먼저 읽는다. 독립 리뷰어 둘은 노트 파일 이름을 서로 다르게 정해 주고, brief에 상대 노트를 읽지 말라고 쓴다. ## 5. 완료 기준 @@ -97,7 +101,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 - 하위 세션의 일을 대신 하지 않는다. 대조에 필요한 읽기와 확인만 직접 한다. - 보고를 그대로 믿지 않는다. 보고는 E0 증거다. - 같은 파일을 두 세션에 맡기지 않는다. -- 하위 세션에 main 병합·push, force push, 다른 브랜치 push를 허용하지 않는다. +- 하위 세션에 main 병합·main push, force push, 다른 브랜치 push를 허용하지 않는다. - brief에 결정 번호만 쓰지 않는다. 내용을 쓴다. ## 7. 막혔을 때 @@ -114,3 +118,4 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 - 영역 문서의 ID를 색인에 손으로 옮기다 빠뜨린다. 색인 검사 스크립트를 돌린다. - 묶음을 너무 크게 만들어 마감 안에 검증 보고가 오지 않는다. 묶음 크기 상한을 지킨다. - 하위 세션이 적은 태스크 이름을 확인하지 않고 소유자에게 옮긴다. +- 같은 범위를 두 리뷰에 따로 맡기고(비교 시험 등) ID를 매길 쪽을 정하지 않아, 같은 ID가 다른 결함을 가리킨다. brief에 ID를 매길 리뷰 하나를 정한다(규칙은 [reference/review-criteria.md](reference/review-criteria.md) 10절 「ID」). diff --git a/docs/work/docs-writing.md b/docs/work/docs-writing.md index cd12d358..5cb8a524 100644 --- a/docs/work/docs-writing.md +++ b/docs/work/docs-writing.md @@ -32,10 +32,10 @@ 3. 위치를 정한다. 문서 위치 규칙은 `docs/README.md`다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다. 4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다. 5. 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은 `src/build.gradle`이나 leaf `build.gradle`에서, 경로는 `ls`로 확인한다. -6. 지난 일을 근거로 쓸 때는 날짜, 무엇이 일어났나, 숫자를 한 줄로 쓴다. 리뷰 ID·묶음 이름·번호만 쓴 결정은 매뉴얼 본문에 쓰지 않는다. 걷어낸 ID 중 근거로 남길 것은 어느 문서에서 왔든 [evidence.md](evidence.md)에 원래 문서·문장과 함께 모은다. +6. 지난 일을 근거로 쓸 때는 날짜, 무엇이 일어났나, 숫자를 한 줄로 쓴다. 리뷰 ID·묶음 이름·번호만 쓴 결정은 매뉴얼 본문에 쓰지 않는다. 걷어낸 ID 중 근거로 남길 것은 어느 문서에서 왔든 [evidence.md](evidence.md)에 원래 문서·문장과 함께 모은다. 번호의 원래 문서가 이 repo에 없으면 그 번호가 가리키는 규칙 이름과 코드 위치를 근거로 적고, 원래 문서가 repo에 없다고 쓴다. 7. 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)와 `file:line`은 링크가 아니라 코드 표기로 쓴다. 링크 검사(lychee)가 따라가지 못하기 때문이다. 8. 숫자를 복제하지 않는다. leaf 개수, 테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다. -9. 그 문서를 읽는 테스트가 있는지 찾는다: `grep -rn '<파일 이름>' src --include=*.java`. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). +9. 그 문서를 읽는 테스트가 있는지 찾는다: `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). 없으면(주석만 걸리는 것도 없음이다) lane은 돌리지 않고, grep 명령과 결과를 보고에 적는다. 10. `docs/work/`나 루트 `CLAUDE.md`를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0, playbook 뼈대, 상대 링크를 본다. 11. 리뷰 폴더 README를 만들거나 고쳤으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다. 12. 다른 문서는 같은 스크립트의 모드로 본다: 상대 링크는 `--links <파일 또는 폴더>`(PR에서는 lychee가 다시 본다), 이력 ID는 `--history <파일 또는 폴더>`. @@ -81,3 +81,4 @@ - 지난 리뷰 ID로 이유를 대신한다. 내용과 날짜를 쓴다. - 저장소 밖 문서를 상대 링크로 써서 링크 검사가 실패한다. 코드 표기로 쓴다. - 없는 태스크 이름이나 옛 경로를 쓴다. 쓰기 전에 빌드 파일과 `ls`로 확인한다. +- `--history` 결과 0을 이력이 없다는 증거로 쓴다. 검사는 아는 꼴만 잡는다. 걷어낸 뒤 `grep -n -e 리뷰 -e 라운드 -e 결정 <파일>`로 남은 괄호를 한 번 더 읽고, 못 잡은 꼴은 검사 패턴에 더한다. diff --git a/docs/work/evidence.md b/docs/work/evidence.md index 5135dcf4..fd7c4353 100644 --- a/docs/work/evidence.md +++ b/docs/work/evidence.md @@ -2,7 +2,7 @@ `docs/work/` 본문은 지난 리뷰를 모르는 사람도 읽을 수 있게 썼다. 그래서 규칙이 나온 사건과 지난 리뷰 ID는 본문에 넣지 않고 여기에 모았다. 본문을 따르는 데 이 문서는 필요 없다. 규칙의 이유를 확인하거나 규칙을 바꾸려 할 때 읽는다. -표기: `1101/05-01`은 `docs/reviews/2026-11-01-maturity-review/`의 발견 05-01이다. `1103/RR6-01-05`는 `docs/reviews/2026-11-03-rereview/`의 발견이다(`RR-`는 1차 재리뷰, `RR2-`~`RR6-`는 round2~round6). `1101` README, `1103` README는 각 폴더의 `README.md`다. 「결정 N」은 `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」의 N번이다. +표기: `1101/05-01`은 `docs/reviews/2026-11-01-maturity-review/`의 발견 05-01이다. `1103/RR6-01-05`는 `docs/reviews/2026-11-03-rereview/`의 발견이다. 접두어와 문서: `RR-`는 1차 재리뷰(폴더 바로 아래 `01`~`07` 영역 문서)와 round2의 `01`~`03` 영역 문서(1차 번호를 이어 썼다), `RR2-`는 round2의 `04` 영역 문서, `RR3-`~`RR7-`는 round3~round7이다. `1101` README, `1103` README는 각 폴더의 `README.md`다. 「결정 N」은 `docs/reviews/2026-09-25-review-followup-status.md` 「소유자 결정」의 N번이다. ## 1. 이 매뉴얼이 나온 곳 @@ -165,4 +165,60 @@ | `docs/manual/09-outbox-events.md:78` | "재리뷰 2차 RR-02-10" | runbook 가리킴만 남겼다 | `1103/RR-02-10`(tenant scope가 바뀌는 배포의 rolling 구간에서 새 번호가 옛 버전이 쓴 번호보다 작다, `round2/02-persistence-messaging.md`) | | `docs/manual/09-outbox-events.md:89` | "재리뷰 RR-05-03" | runbook 가리킴만 남겼다 | `1103/RR-05-03`(끝나지 않는 재시도 행을 운영자가 구분·처분할 수단이 없었다, `05-messaging.md`) | -- `RR-01-11`·`RR-02-10`·`RR-03-11`은 2차 재리뷰(`round2/`) 문서의 발견이다. 그 문서들은 1차 번호에 이어 `RR-` 접두어를 그대로 썼다. 머리말 표기("`RR-`는 1차 재리뷰")의 예외다. +- `RR-01-11`·`RR-02-10`·`RR-03-11`은 2차 재리뷰(`round2/`) 문서의 발견이다. 그 문서들은 1차 번호에 이어 `RR-` 접두어를 그대로 썼다(머리말 「표기」). + +## 9. cold-read 시험 1회차 빈틈 처리 (2026-11-06~07) + +2026-11-06 이력 없는 세션 6개에 이 매뉴얼만 주고 실제 일을 시켰다(기준선 1개는 옛 매뉴얼). 6개 모두 일은 끝냈지만 매뉴얼에서 답을 못 찾은 곳이 1~9건씩 나와 모두 불합격이었다. 아래는 시험 기록(design-docs `delegation-loop/trials/2026-11-06-*.md`)의 「질문」·「위반」 표와 각 세션 공유 노트(`~/.config/Claude/side-session-notes/local_fcd89c34-c754-4c5b-a38f-fa322834286f/`)의 「매뉴얼에서 답을 못 찾은 곳」을 한 줄씩 처리한 결과다. 기준 커밋 `2c8a359d`. 2026-11-07 운영 playbook 시험(T6, `trials/2026-11-07-integration-gates.md`, 1회차 수정 전 매뉴얼로 돌림)의 빈틈 6건을 T6 행으로 더했다. + +- 세션: T1 `c-t1-r10-review`(확인 리뷰), B `c-t1-baseline`(같은 리뷰를 옛 매뉴얼로, 기준선), T2 `c-t2-circuit-breaker`(결함 수정), T3 `c-t3-error-codes`(조사·설계 → 구현), T4 `c-t4-manual-ids`(문서), T5 `c-t5-idempotency-opid`(결함 수정), T6 `c-t6-integration-gates`(합친 브랜치 전체 게이트). +- 출처 칸: `기록 N`은 시험 기록 「질문」 표의 N번, `노트 N`은 공유 노트의 N번이다. T3 노트는 1단계 `1-N`, 2단계 `2-N`이다. +- 처리 칸: 고침(고친 곳) / 고치지 않음(이유) / 소유자 결정 필요. 기준선(B)은 새 매뉴얼에도 해당하는 것만 고쳤다. + +| # | 출처 | 빈틈 | 처리 | +| --- | --- | --- | --- | +| T1-1 | 기록 1, 노트 1 | 상한을 넘어 나눈 확인 리뷰를 한 세션이 차례로 해도 되나 | 고침 — `improve.md` 4.4절: 나누는 것은 맡긴 쪽, brief 하나로 받으면 차례로, 단위마다 문서 하나 | +| T1-2 | 노트 2 | 영역 pathspec이 파일 단위로 안 갈림, 수정 커밋 안의 리뷰 기록을 상한에서 빼나 | 고침 — `improve.md` 4.4절: 리뷰 기록 `docs/reviews/**` 제외, 테스트 파일은 지키는 코드의 영역 | +| T1-3 | 기록 2, 노트 3 | 수정 보고에 「새로 가정하는 것」 칸이 없을 때 | 고침 — `improve.md` 4.1절 2단계: 커밋 본문 「위험·한계」와 처리 표 「결정」에서 뽑고 뽑은 곳을 적는다 | +| T1-4 | 기록 3, 노트 4 | 지난 라운드 색인 누락으로 색인 검사가 처음부터 rc=1 | 고침 — `improve.md` 4.1절 8단계: 이번 색인 절에 「색인 보완」 한 줄 | +| T1-5 | 기록 4, 노트 5 | 리뷰 README를 누가 쓰나: `delegate.md`(총괄)와 `improve.md`(리뷰어)가 다름 — **모순** | 고침 — `improve.md` 4.1절 7단계, `delegate.md` 4.2절 표, `reference/decisions.md` 2.1 「리뷰 README 분담」: 리뷰어는 자기 라운드 색인 절 하나, 나머지는 총괄 | +| T1-6 | 기록 5, 노트 6 | 지난 라운드 영역을 나눌 때 영역 번호 | 고침 — `reference/review-criteria.md` 10절 「ID」: 그 라운드 영역 표의 순번, 나누면 뒤에 새 번호, 「범위」에 대응 | +| T1-7 | 기록 6, 노트 7 | 클래스 이름으로 고르는 strict lane에서 탐침 돌리기 | 고침 — `improve.md` 9절(자주 하는 실수): 기존 클래스에 메서드로, `-Werror` 주의 | +| T1-8 | 기록 7, 노트 8 | `--rerun`이 바로 앞 태스크에만 걸림 | 고침 — `operate.md` 9절, `reference/gates.md` 6절: 태스크마다 붙인다 | +| T1-9 | 노트 9 | 지난 라운드 Declined 30건이 닫힌 기록 없음, 확인 리뷰어가 다시 판정하나 | 고침 — `improve.md` 4.1절 9단계(brief가 맡겼을 때만), `delegate.md` 4.1절(확인 리뷰 brief에 적는다) | +| T1-10 | 기록 8, 노트 10 | 같은 범위를 두 리뷰가 같은 라운드 ID로 씀 | 고침 — `reference/review-criteria.md` 10절 「ID」(정본 리뷰 하나, 다른 쪽은 새 ID와 대응표), `delegate.md` 9절 | +| T1-11 | 기록 9, 노트 11 | 다른 브랜치 병합을 기다리는 Declined는 닫힌 것인가 | 고침 — `improve.md` 4.5절 2: 합친 트리에서 확인할 때까지 열림 | +| B-1 | 기록 1, 노트 1 | 한 리뷰어가 모든 영역을 볼 때 문서 모양 | 고침 — `reference/review-criteria.md` 10절 「위치」: `roundN/NN-<영역>.md`, 영역마다 하나 | +| B-2 | 기록 2, 노트 2 | 리뷰어가 리뷰 README에 쓰나 | 고침 — T1-5와 같은 곳 | +| B-3 | 기록 3, 노트 3 | strict lane 탐침, 탐침에도 `-Werror` | 고침 — T1-7과 같은 곳 | +| B-4 | 기록 4, 노트 4 | 확인 리뷰에 넣을 「이전부터」 결함의 경계 | 고침 — `improve.md` 4.1절 3단계: 읽은 주변 코드에서 본 것은 적고, 그 밖을 찾아 나서지 않는다 | +| B-5 | 기록 5, 노트 5 | 앞 라운드 Declined가 닫히지 않은 채 시작 | 고침 — T1-9와 같은 곳 | +| B-6 | 기록 6, 노트 6 | 리뷰 스킬은 하위 에이전트를 쓰라 하고 매뉴얼은 금지 — 모순 | 고치지 않음 — 새 매뉴얼에 답이 있다: `improve.md` 3절 끝 줄, `delegate.md` 4.3절. 새 매뉴얼로 같은 리뷰를 한 T1은 묻지 않았다 | +| B-7 | 기록 7, 노트 7 | 리뷰 기록 문서도 document-contract lane 대상인가 | 고침 — `reference/gates.md` 2절, `docs-writing.md` 4절 9단계: 읽는 테스트를 파일·폴더로 찾고, 없으면 돌리지 않고 grep 결과를 적는다 | +| T2-1 | 기록 1 | push한 커밋은 못 고치고 desktop은 push된 것만 받는다. 커밋 본문에 desktop 결과를 넣으려면 | 고침 — `operate.md` 2절·4.1절 「push 전에 검증하기」(패치와 트리 해시)·9절, design-docs `conventions/delegation-loop.md` 11절 「실행 위치」 | +| T3-1 | 기록 1, 노트 1-1 | 「파일 하나여도 큼」 표면에 대한 설계 메모만 쓰는 일의 크기 | 고침 — design-docs `conventions/work-thinking-order.md` 2.1절, `research-design.md` 3절, 스킬 `research-first` | +| T3-2 | 기록 5, 노트 1-2 | push 허용: `docs/work/README.md` 4절·`decisions.md`는 "커밋·push", 정본 11절은 "push는 소유자" — **모순** | 고침 — 커밋과 push를 brief 7절이 따로 허용한다: `docs/work/README.md` 4절, `reference/decisions.md` 2.1, `delegate.md` 2·4.1·6절, 루트 `CLAUDE.md` 5절, design-docs `conventions/delegation-loop.md` 2·3·4.1·11절, 스킬 `delegate` | +| T3-3 | 기록 2, 노트 1-3 | 탐침을 생략해도 되는 기준 | 고침 — `research-design.md` 4절 3단계 | +| T3-4 | 기록 3, 노트 1-4 | 파생 서비스 영향을 어떻게 확인하나 | 고침 — `research-design.md` 4절 5단계, design-docs `conventions/delegation-loop.md` 11절 「세션」(파생 서비스 위치) | +| T3-5 | 기록 4, 노트 1-5 | 조사·설계에서 범위 밖 결함을 어디에 적나 | 고침 — `docs/work/README.md` 6절: 모든 보고에 「범위 밖에서 본 것」 | +| T3-6 | 기록 4, 노트 1-6 | 하위 세션이 Slack 브리핑을 하나 | 고침 — design-docs `conventions/delegation-loop.md` 4.1절 7절 칸·11절 「보고」, `reference/decisions.md` 2.1 「하위 세션 보고」: 전역 규칙 그대로, brief가 "Slack 말고"면 안 보냄 | +| T3-7 | 기록 4, 노트 2-1 | push 전에 RED를 보려면 desktop에 무엇을 보내나 | 고침 — `operate.md` 4.1절 「push 전에 검증하기」 RED 줄 | +| T3-8 | 기록 4, 노트 2-2 | 커밋 본문 「검증」 칸과 push 순서 | 고침 — T2-1과 같은 곳 | +| T3-9 | 기록 4, 노트 2-3 | `git add -p` 없이 한 파일을 두 커밋으로 나눠 stage | 고침 — design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」(패치 hunk를 지우고 `git apply --cached`) | +| T4-1 | 기록 1, 노트 「스크립트가 못 잡는 이력 ID」 | `--history`가 "리뷰 NN-NN"·"N라운드 NN-NN"을 못 잡아 0이 나와도 16줄 남음 | 고침 — `scripts/check-work-docs.py` 패턴 셋, `docs-writing.md` 9절. 새로 드러난 `docs/manual/` 16줄은 고치지 않음 — 이번 범위 밖, 2회차 시험 과제 | +| T4-2 | 기록 2 | 바꾼 문서를 읽는 테스트가 없을 때 무엇을 돌리나 | 고침 — B-7과 같은 곳 | +| T4-3 | 기록 3 | 이 문서 머리말의 ID 표기가 실제(2차 재리뷰도 `RR-`)와 다름 — **모순** | 고침 — 이 문서 머리말 「표기」(접두어별 문서), 8절 끝 줄 | +| T4-4 | 기록 4 | 원래 문서가 repo에 없는 결정 번호 | 고침 — `docs-writing.md` 4절 6단계 | +| T4-5 | 기록 5 | 하위 세션이 Slack 브리핑을 하나 | 고침 — T3-6과 같은 곳 | +| T5-1 | 기록 1 | 설계서 둘과 포트 Javadoc이 서로 다를 때 무엇을 따르나 | 고침 — `improve.md` 7절: 결정이 없으면 고르지 않고 양쪽 근거로 묻는다 | +| T5-2 | 기록 2 | 소유자 지시로 생긴 큰 변경도 따로 멈춰야 하나 | 고침 — design-docs `conventions/work-thinking-order.md` 2.3절, 스킬 `research-first` | +| T5-V | 기록 「위반」 1 | 총괄 보고를 영어로 씀 | 고침 — `docs/work/README.md` 6절, design-docs `conventions/delegation-loop.md` 5·11절. 훅으로는 막지 않는다(보고 문장은 도구 호출이 아니라 훅이 볼 수 없다) | +| T6-1 | 기록 1, 노트 1 | `reference/gates.md` 3절 묶음에 경로 필터 PR lane과 main job(configuration-cache, compose smoke, http3, notification)이 없어 "workflow와 같은 명령"이 성립하지 않음 | 고침 — `reference/gates.md` 3절 (가) 늘 도는 것(main job·optional 빌드·태그 단계 명령 더함) | +| T6-2 | 기록 2, 노트 2 | 합친 트리가 어떤 경로 필터 lane을 켜는지 정하는 절차, "바뀐 영역의 lane"의 정의 | 고침 — `reference/gates.md` 3절 (나): `git diff --name-only`를 `on.pull_request.paths`(glob)와 `pr-adapters.yml` `emit` 줄(정규식)에 맞춘다 | +| T6-3 | 기록 3, 노트 3 | 집계 태스크 전체가 실제로 돌았음을 보이는 법(`--rerun`은 앞 태스크 하나만) | 고침 — `reference/gates.md` 3절 「실제로 돌았음을 보이기」(새 worktree, `--no-build-cache`, FROM-CACHE 0)·6절, `operate.md` 9절 | +| T6-4 | 기록 4, 노트 4 | lychee 대체 명령이 lychee 범위보다 좁음, buf·dependency review 대체 안내 없음 | 고침 — `reference/gates.md` 2절 링크 검사(lychee와 같은 glob을 `git ls-files`로), 3절 (다) 로컬 도구가 없는 job 표 | +| T6-5 | 기록 5, 노트 5 | compose bind mount가 `tmp/heap-dumps`를 root 소유로 만들어 `git worktree remove`가 실패 | 고침 — `operate.md` 4.1절(compose `down` 뒤 컨테이너로 폴더를 지운다) | +| T6-6 | 기록 6, 노트 6 | `reference/gates.md` 4절 기록 형식이 "게이트 하나 = Gradle 명령 하나"를 가정 | 고침 — `reference/gates.md` 4절(한 줄 = 명령 하나, 여러 명령 job은 순번, 「실제 실행」 칸) | + +- 기준선과 새 매뉴얼의 리뷰 발견은 8건 중 1건만 겹쳤다. 이를 근거로 확인 리뷰를 독립 리뷰어 둘로 할지 소유자에게 물었고, 2026-11-07 소유자가 세 경우에만 둘로 하는 안을 골랐다(소유자 원문 "(c)로 받기"). 넣은 곳: `improve.md` 4.1절 「독립 리뷰어 둘」·4.5절 1, `delegate.md` 4.1·4.3절, `reference/review-criteria.md` 10절 「ID」, `reference/decisions.md` 2.1, design-docs `conventions/delegation-loop.md` 3절 5·9절 M11, `delegation-loop/metrics.md`. +- 「자주 하는 실수」에 넣은 줄: `improve.md`(strict lane 탐침), `operate.md`(`--rerun` 범위를 기존 줄에 더함, push 뒤 검증), `docs-writing.md`(`--history` 0을 믿음), `delegate.md`(두 리뷰의 ID). diff --git a/docs/work/improve.md b/docs/work/improve.md index fa655b75..65c2d680 100644 --- a/docs/work/improve.md +++ b/docs/work/improve.md @@ -37,14 +37,21 @@ ### 4.1 리뷰 1. 범위를 고정한다. 확인 리뷰는 pathspec과 `git diff --stat .. -- ` 결과를 문서에 적는다. -2. 확인 리뷰는 수정 보고의 「새로 가정하는 것」 칸부터 본다. 가정마다 다른 코드·설정·운영에서 참인지 확인한다. -3. 그다음 수정 diff와, diff가 바꾼 동작의 주변 코드를 읽는다. 확인 리뷰는 저장소 전체가 아니라 그 수정만 본다. +2. 확인 리뷰는 수정 보고의 「새로 가정하는 것」 칸부터 본다. 가정마다 다른 코드·설정·운영에서 참인지 확인한다. 그 칸이 없으면(보고가 repo에 없거나 옛 양식) 수정 커밋 본문의 「위험·한계」와 리뷰 README 처리 표의 「결정」 칸에서 가정을 뽑고, 뽑은 곳을 문서 「범위」 절에 적는다. +3. 그다음 수정 diff와, diff가 바꾼 동작의 주변 코드를 읽는다. 확인 리뷰는 저장소 전체가 아니라 그 수정만 본다. 읽은 주변 코드에서 본 결함은 이전부터 있었어도 발견으로 적고 「이전부터」로 표시한다. 그 밖을 찾아 나서지 않는다. 4. 전체 리뷰는 게이트를 먼저 한 번 돌려 결과를 적고([reference/gates.md](reference/gates.md)), 영역을 나눈다([delegate.md](delegate.md) 「나누는 법」). 5. 의심 결함은 별도 worktree의 임시 테스트(탐침)로 확인한다. 탐침 코드는 고칠 때 옮겨 쓸 수 있게 남기고(소유자 환경에서는 공유 노트 폴더, design-docs `conventions/delegation-loop.md` 11절), worktree는 지운다. 6. 발견을 [reference/review-criteria.md](reference/review-criteria.md) 양식으로 적는다. 발견마다 증거 수준과 "이번 수정이 만들었나 / 이전부터 있었나"를 적는다. -7. 리뷰 폴더 README에 색인을 만든다. 발견 ID를 모두 이름으로 적는다. 범위(`A~B`)와 이어 쓰기(`A·07`)는 된다. 건수만 쓰지 않는다. -8. `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다. 색인 절이 따로 있으면 `--index-heading "<절 제목>"`을 붙인다. rc=0이어야 한다. -9. 판단하지 않은 항목은 「Declined to judge」에 위치와 이유를 적는다. 맡긴 쪽이 다음 묶음에 배정하거나 결정으로 닫는다. +7. 리뷰 폴더 README에 이번 라운드의 색인 절 하나를 더한다: 발견 ID, 심각도, 한 줄 내용, 결정이 필요한 질문. 발견 ID를 모두 이름으로 적는다. 범위(`A~B`)와 이어 쓰기(`A·07`)는 된다. 건수만 쓰지 않는다. README의 다른 절(처리 표, 결정의 답, 라운드 끝 게이트)은 맡긴 쪽이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면 색인 절도 맡긴 쪽이 쓰고, 리뷰어는 보고에 같은 표를 둔다. +8. `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다. 색인 절이 따로 있으면 `--index-heading "<절 제목>"`을 붙인다. rc=0이어야 한다. 지난 라운드 색인에서 빠진 ID 때문에 처음부터 rc=1이면, 빠진 ID를 이번 색인 절에 「색인 보완」 한 줄로 이름만 적는다. 지난 영역 문서는 고치지 않는다. +9. 판단하지 않은 항목은 「Declined to judge」에 위치와 이유를 적는다. 맡긴 쪽이 다음 묶음에 배정하거나 결정으로 닫는다. 지난 라운드에서 열린 채 넘어온 Declined는 brief가 맡겼을 때만 다시 판정한다. 맡기지 않았으면 건수와 위치만 적는다. + +**독립 리뷰어 둘.** 아래 셋 중 하나면 같은 범위를 서로 결과를 보지 않는 리뷰어 둘이 따로 리뷰하고 맡긴 쪽이 합친다([delegate.md](delegate.md) 4.1절). + +- 멈추는 확인 리뷰: 리뷰어 하나가 0을 냈으면 멈추기 전에 두 번째 리뷰어가 같은 범위를 본다(4.5절 1). +- 수정 diff가 추가 1,000줄 이상인 확인 리뷰(상한 1,500줄에 가까움. 세는 법은 4.4절). +- Critical·Important(전체 리뷰는 High)를 고친 수정의 확인 리뷰. +- 리뷰어는 자기 문서를 끝내기 전에 다른 리뷰어의 브랜치·문서·보고·노트를 읽지 않는다. 리뷰 폴더에 문서를 커밋하는 것은 brief가 정한 정본 리뷰어뿐이다. 다른 리뷰어는 같은 양식을 보고에 두고, ID 자리에 임시 번호 `B-NN-MM`을 쓴다. ### 4.2 결함 수정 @@ -68,7 +75,8 @@ ### 4.4 수정 묶음의 크기 - 묶음 하나는 리뷰 영역 하나 안이고 발견 8건 이하다. 묶음마다 커밋 하나다. -- 확인 리뷰 하나가 보는 수정 diff는 추가 1,500줄 이하다(`git diff --shortstat ..`, 테스트 포함, lockfile·스냅숏 같은 생성 파일 제외). 넘으면 확인 리뷰를 나눈다. 묶음 커밋이 따로 있으면 커밋별로, 한 커밋에 여러 영역이 섞였으면 영역 pathspec별로(`git diff --shortstat .. -- `) 나눠 각각 상한 안이 되게 한다. +- 확인 리뷰 하나가 보는 수정 diff는 추가 1,500줄 이하다(`git diff --shortstat ..`, 테스트 포함, lockfile·스냅숏 같은 생성 파일과 리뷰 기록 `docs/reviews/**` 제외). 넘으면 확인 리뷰를 나눈다. 묶음 커밋이 따로 있으면 커밋별로, 한 커밋에 여러 영역이 섞였으면 영역 pathspec별로(`git diff --shortstat .. -- `) 나눠 각각 상한 안이 되게 한다. 테스트 파일은 그 테스트가 지키는 코드의 영역에 넣는다. +- 나누는 것은 맡긴 쪽이 brief로 한다. 상한을 넘는 범위를 brief 하나로 받았으면, 한 세션이 나눈 단위를 차례로 보고 단위마다 문서 하나를 쓴다. 그렇게 했다고 보고에 적는다. - 왜: 지난 수정 라운드에서 추가 줄이 2,000줄 아래면 다음 확인 리뷰 발견이 9건 이하였고, 5,000줄을 넘으면 19건 이상이었다([evidence.md](evidence.md) 「수정 묶음 크기」). 상한 값은 판단이다. 라운드당 새 결함 수로 다시 맞춘다. - 묶음을 합친 트리는 따로 검증한다([reference/gates.md](reference/gates.md) 「라운드 끝」). 두 묶음의 수정은 한 트리에서 처음 만날 때 새 결함을 만든다. @@ -76,8 +84,8 @@ 리뷰 → 수정 → 확인 리뷰는 아래 넷이 모두 참일 때만 멈춘다. -1. 마지막 확인 리뷰의 발견이 심각도와 상관없이 0이다. Minor도 기록만 하지 않고 고친다. -2. 열린 「Declined to judge」가 0이다. +1. 마지막 확인 리뷰의 발견이 심각도와 상관없이 0이다. 서로 보지 않은 리뷰어 둘이 모두 0이어야 한다(4.1절 「독립 리뷰어 둘」). Minor도 기록만 하지 않고 고친다. +2. 열린 「Declined to judge」가 0이다. 다른 브랜치가 처리했지만 아직 합치지 않은 항목은 합친 트리에서 확인할 때까지 열린 것으로 센다. 3. 합친 트리에서 라운드 끝 게이트가 모두 통과했다. 4. 리뷰 README의 남은 항목이 0이다. 결정으로 닫은 항목은 결정 위치를 적었다. @@ -108,6 +116,7 @@ - 고치는 법이 공개 동작(응답 코드, 기동 실패 조건, env 키, 파생 서비스 동작)을 바꾸면 고치기 전에 멈추고 묻는다. 형식은 [README](README.md) 5절이다. - RED를 만들 수 없으면(실 vendor가 없다, 머신에 따라 통과한다) 그 사실과 이유를 보고하고 그 발견만 멈춘다. +- 계약을 적은 곳끼리(설계서, 포트 Javadoc, 모듈 README, 테스트) 다르게 말하고 [reference/decisions.md](reference/decisions.md)에 결정이 없으면, 어느 쪽도 고르지 않는다. 양쪽 근거를 표로 붙이고 권하는 안과 함께 묻는다. 그 발견만 멈춘다. ## 8. 보고 형식 @@ -129,3 +138,4 @@ - 색인을 손으로 옮기다 발견이 빠진다. 색인 검사 스크립트를 돌린다. - 보고에 없는 태스크 이름을 적는다. 로그에서 태스크 이름을 grep해 확인한다. - 묶음별 검증으로 합친 트리 검증을 대신한다. 라운드 끝 게이트를 따로 돌린다. +- strict lane에 돌릴 탐침을 새 클래스로 만들어 lane이 고르지 않는다. lane은 `build.gradle`의 `requires`(클래스 이름)나 `tag`로 테스트를 고른다. 탐침은 그 lane이 고르는 기존 클래스에 메서드로 넣는다. 탐침도 `-Werror`로 컴파일되니 경고를 남기지 않는다. diff --git a/docs/work/operate.md b/docs/work/operate.md index de17203d..75040f6a 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -12,8 +12,8 @@ ## 2. 받아야 할 것 -- 대상 브랜치와 커밋 sha. desktop은 push된 브랜치만 받을 수 있다. -- 자기 브랜치 push 허용 여부. desktop 검증이 필요한 일이면 brief가 허용해야 한다. main push는 허용되지 않는다. +- 대상 브랜치와 커밋 sha. desktop은 push된 브랜치나, 노트북이 보낸 패치(4.1절 「push 전에 검증하기」)를 받는다. +- 자기 브랜치 push 허용 여부. brief 7절이 push를 허용하지 않았으면 패치로 검증한다. main push는 허용되지 않는다. - 돌릴 게이트 목록(없으면 [reference/gates.md](reference/gates.md) 2절로 정한다)과 로그를 둘 이름. ## 3. 크기와 사고 순서 @@ -58,11 +58,26 @@ git worktree remove ~/workspace/<작업 이름> - 로그는 desktop `~/<작업 이름>-logs/`에 남기고, 보고에 그 desktop 경로와 rc를 쓴다. - RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다. +- compose를 띄웠으면 지우기 전에 `docker compose … down`을 한다. bind mount 폴더(`docker-compose.dev.yml`의 `tmp/heap-dumps`)는 Docker가 root로 만들어 `git worktree remove`가 Permission denied로 실패한다. compose가 이미 받은 이미지(`docker-compose.infra.yml`의 `redis:7.4`)로 폴더를 지운 뒤 다시 지운다: `docker run --rm --pull=never -v "$PWD/tmp:/t" redis:7.4 rm -rf /t/heap-dumps`. - Python 검사 스크립트는 노트북에서 돌려도 된다. 보고 증거로 쓸 때는 desktop worktree에서 한 번 더 돌린다. +**push 전에 검증하기.** push한 커밋은 고쳐 쓰지 않는다. 그래서 커밋 본문에 desktop 결과를 쓰거나 push가 허용되지 않았으면, 커밋 전에 바꾼 것을 패치로 보내 같은 트리에서 돌린다. + +```bash +# 노트북: 커밋할 파일만 stage하고(git status로 확인) 트리 해시를 적어 둔다 +git add <바꾼 파일>... && git status --short && git write-tree +# desktop: 기준 커밋(push된 커밋)에서 worktree를 만든다 +ssh desktop 'cd ~/workspace/clean-architecture-backend-template && git fetch origin && git worktree add --detach ~/workspace/<작업 이름> <기준 커밋>' +# 노트북: 패치를 보내 얹는다. 마지막 줄이 위 트리 해시와 같아야 한다 +git diff --cached --binary <기준 커밋> | ssh desktop 'cd ~/workspace/<작업 이름> && git apply --index && git write-tree' +``` + +- 그다음 위 3) 4)대로 돌리고 지운다. 결과를 본문에 적어 커밋한 뒤 `git rev-parse HEAD^{tree}`가 같은 해시인지 본다. 같으면 desktop이 돌린 트리가 그 커밋이다. +- RED는 같은 방법으로 테스트 파일만 stage해 보낸다. 한 파일의 일부만 stage하는 법은 design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」이다. + ### 4.2 게이트 실행과 기록 -1. [reference/gates.md](reference/gates.md) 2절로 돌릴 게이트를 고른다. 라운드 끝이면 3절 묶음 전체다. +1. [reference/gates.md](reference/gates.md) 2절로 돌릴 게이트를 고른다. 라운드 끝이면 3절의 (가) 늘 도는 것, (나) 바뀐 파일로 켜지는 것, (다) 로컬 도구가 없는 것 전체다. 2. 잠금을 얻은 뒤 1분 부하를 적고 돌린다. 한 번에 하나씩이다. 3. 첫 실행이 실패하면 원인을 찾아 고치고 다시 돌린다. 첫 실행과 다시 돌린 결과를 둘 다 적는다. 4. 결과를 [reference/gates.md](reference/gates.md) 4절 형식으로 적는다: 게이트, rc, 시간, 직전 부하, 로그 경로, 대상 커밋. @@ -112,4 +127,5 @@ git worktree remove ~/workspace/<작업 이름> - desktop 기존 checkout에서 브랜치를 바꿔 다른 세션의 작업을 방해한다. 자기 worktree를 만든다. - 짧게 끝난 실행을 통과로 적는다. 캐시 재사용인지, 태스크가 실제로 돌았는지 로그로 확인한다. -- 빌드 캐시에서 가져온 테스트 결과를 지금 이 환경에서 통과한 증거로 쓴다. 기준 상태를 확인하거나 시간·환경에 민감한 테스트를 볼 때는 그 태스크를 `--rerun`으로 다시 돌린다. +- 빌드 캐시에서 가져온 테스트 결과를 지금 이 환경에서 통과한 증거로 쓴다. 기준 상태를 확인하거나 시간·환경에 민감한 테스트를 볼 때는 그 태스크를 `--rerun`으로 다시 돌린다. `--rerun`은 바로 앞 태스크 하나에만 걸린다. 태스크마다 붙인다(`:a:test --rerun :b:test --rerun`). `ci` 같은 집계 태스크는 새 worktree에서 `--no-build-cache`로 돌린다([reference/gates.md](reference/gates.md) 3절). +- 커밋하고 push한 뒤 desktop에서 돌려, 결과를 커밋 본문에 못 넣는다. push 전에 패치로 검증한다(4.1절). diff --git a/docs/work/reference/decisions.md b/docs/work/reference/decisions.md index 2abff16a..cba22c15 100644 --- a/docs/work/reference/decisions.md +++ b/docs/work/reference/decisions.md @@ -31,7 +31,9 @@ | 주제 | 결정 | 누가 | 날짜 | 출처 | | --- | --- | --- | --- | --- | | 커밋 정책 기본 | `human-only`. 에이전트는 stage·commit·amend·push하지 않는다 | 정책 | — | `AGENTS.md` 「Gradle 정책 권위」 끝 | -| 커밋 예외 | brief가 허용하면 그 작업의 자기 브랜치에만 커밋·push한다. main 병합·다른 브랜치 push·force push는 하지 않는다 | 소유자 | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절, `docs/work/README.md` 4절 | +| 커밋 예외 | brief 7절이 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다. main 병합·main 또는 다른 브랜치 push·force push는 하지 않는다 | 소유자(2026-11-06), 커밋과 push를 나눠 읽는 것은 기본값(2026-11-06) | 2026-11-06 | design-docs `conventions/delegation-loop.md` 11절 「커밋과 병합」, `docs/work/README.md` 4절, `docs/work/evidence.md` 9절 | +| 리뷰 README 분담 | 리뷰어는 리뷰 폴더 README에 자기 라운드의 색인 절 하나만 쓴다. 처리 표·결정의 답·라운드 끝 게이트·남은 것은 총괄이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면 색인 절도 총괄이 쓴다 | 기본값 | 2026-11-06 | `docs/work/evidence.md` 9절 | +| 하위 세션 보고 | 총괄에게도 쉬운 한국어로 쓴다. 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절 | | 옛 멈춤 기준 | "새 Important 0이면 멈춤", "Minor는 기록만" — 거둠 | 위임 → 소유자가 거둠 | 2026-11-05 | `1103` 9.1·11.1·16절 | @@ -50,6 +52,7 @@ | `@DisplayName` 언어 | 한국어(기본값 영어를 거부) | 소유자 | 2026-09-25 | 결정 5, `AGENTS.md` 테스트 작성 규칙 2 | | 학습 문서 | 삭제된 코드를 설명하는 학습 문서(`docs/study/*.ko.md`, `docs/*-superpowers-package/`)는 현재 코드에 맞게 갱신 | 소유자 | 2026-09-25 | 결정 6 | | client 오류 문구 | 한국어. `Category`별 문구 표 하나를 shared-contract에 | 소유자 | 2026-09-25 | 결정 11 | +| 확인 리뷰 독립 리뷰어 둘 | 세 경우에 서로 결과를 보지 않는 리뷰어 둘이 같은 범위를 리뷰하고 총괄이 합친다: 반복을 멈추기 직전 확인 리뷰(리뷰어 하나가 0을 내면 두 번째가 본다), 수정 diff가 상한에 가까운 리뷰("가까움"은 추가 1,000줄 이상 — 기본값), Critical·Important를 고친 수정의 리뷰. 그 밖은 하나. 2~3라운드 두 리뷰의 겹침 비율을 기록하고 그 결과로 언제나 하나·언제나 둘로 옮길지 다시 본다 | 소유자 | 2026-11-07 | 2026-11-07 총괄 세션 전달(소유자 원문 "(c)로 받기"), `docs/work/improve.md` 4.1·4.5절, `docs/work/delegate.md` 4.1절 | ### 2.2 구조·조립 diff --git a/docs/work/reference/gates.md b/docs/work/reference/gates.md index 39bbf98c..8272269d 100644 --- a/docs/work/reference/gates.md +++ b/docs/work/reference/gates.md @@ -56,36 +56,77 @@ | 테스트 코드 | 그 leaf `testQualityCheck` | | compose·Dockerfile | compose 검사 스크립트, 실제 `docker build`와 기동 | -어떤 테스트가 그 문서를 읽는지는 `grep -rn '<파일 이름>' src --include=*.java`로 찾는다. +어떤 테스트가 그 문서를 읽는지는 `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`로 찾는다. 걸리는 테스트가 없으면(주석만 걸려도 없음이다) document-contract lane은 돌리지 않고 grep 명령과 결과를 보고에 적는다. 리뷰 기록(`docs/reviews/**`)도 같다. -**링크 검사**: 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가 없는 곳에서는 `python3 scripts/check-work-docs.py --links docs`로 상대 링크만 확인한다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다). +**링크 검사**: 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은 보지 못한다): + +```bash +python3 scripts/check-work-docs.py --links $(git ls-files ':(glob)README.md' ':(glob)src/**/README.md' ':(glob)src/**/CLAUDE.md' ':(glob)docs/**/*.md' ':(glob).github/**/*.md') +``` + +`--links docs`만 돌리면 `src/**/README.md`·`src/**/CLAUDE.md`·`.github/**/*.md`를 빠뜨린다. 저장소 밖 경로와 `file:line`은 링크로 쓰지 않는다(lychee가 따라가지 못한다). ## 3. 라운드 끝 — 합친 트리의 전체 묶음 -여러 묶음을 합친 트리는 workflow와 같은 명령으로 검증한다. 한 번에 하나씩, 공유 잠금 아래에서 돌린다. +여러 묶음을 합친 트리는 workflow가 PR과 main push에서 돌리는 것을 모두 돌린다. 정본은 `.github/workflows/`다. (가)는 늘 도는 것, (나)는 바뀐 파일로 켜지는 것, (다)는 로컬에 도구가 없는 것이다. 한 번에 하나씩, 공유 잠금 아래에서 돌린다. + +**실제로 돌았음을 보이기.** 새 detached worktree에서 시작하고 모든 Gradle 명령에 `--no-build-cache`를 붙인다. 로그마다 `grep -c 'FROM-CACHE' <로그>`가 0이어야 한다. UP-TO-DATE는 같은 worktree에서 앞 명령이 만든 출력일 때만 받아들인다. `--rerun`은 바로 앞 태스크 하나에만 걸려 `ci` 같은 집계 태스크의 증거가 되지 않는다. + +(가) 늘 도는 것: ```bash cd src -./gradlew :ci :verifyDependencyLocks --warning-mode=fail --console=plain -./gradlew :sample-portfolio:check :sample-portfolio:qualityCheck --console=plain +# PR: ci-quality-gates.yml +./gradlew :ci :verifyDependencyLocks --warning-mode=fail --no-build-cache --console=plain ./gradlew :verifyStrictLaneStages --dry-run --console=plain +./gradlew :sample-portfolio:check :sample-portfolio:qualityCheck --no-build-cache --console=plain +./gradlew -p optional-platforms ci --no-build-cache --console=plain ./gradlew -p optional-platforms :verifyStrictLaneStages --dry-run --console=plain -./gradlew :mainCheck --continue --warning-mode=fail --console=plain -./gradlew :integrationCheck --continue --console=plain -./gradlew -p optional-platforms ci integrationCheck performanceCheck --console=plain -./gradlew :performanceCheck --continue --console=plain -./gradlew :releaseCheck -PgitRevision="$(git rev-parse HEAD)" --console=plain -cd .. && bash scripts/verify-compose-profile-contracts.sh +# main push: integration-main.yml +./gradlew :mainCheck --continue --warning-mode=fail --no-build-cache --console=plain +./gradlew :integrationCheck --continue --no-build-cache --console=plain +./gradlew :performanceCheck --continue --no-build-cache --console=plain +./gradlew -p optional-platforms performanceCheck --continue --no-build-cache --console=plain +./gradlew -p optional-platforms integrationCheck --no-build-cache --console=plain +./gradlew :adapter:outbound:httpclient:test -Phttp3.tests.enabled=true --no-build-cache --console=plain # 실험 job, 실패해도 workflow는 통과 +# 태그: release.yml (CI는 GITHUB_SHA로 커밋을 받는다. 손으로 돌릴 때는 -PgitRevision) +./gradlew :releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain +./gradlew -p optional-platforms releaseCheck -PgitRevision="$(git rev-parse HEAD)" --no-build-cache --console=plain +cd .. +bash scripts/verify-compose-profile-contracts.sh +bash scripts/run-compose-runtime-smoke.sh --matrix src/config/runtime/compose-profile-contracts.json ``` +- 여러 명령으로 된 main job 둘은 그 job의 `run` 줄을 차례로 그대로 돌린다: `integration-main.yml`의 `configuration-cache`(로그에 "Reusing configuration cache."가 있어야 한다), `notification-platform.yml`의 `pr`(main push마다 경로와 상관없이 돈다). - 첫 실행이 실패하면 고치고 다시 돌린다. 둘 다 기록한다. - 합친 뒤에만 드러나는 결함이 있다. 묶음별 검증으로 이 단계를 대신하지 않는다. +(나) 바뀐 파일로 켜지는 것 — brief의 "바뀐 영역의 lane"은 이것이다: + +1. 바뀐 파일 목록을 만든다: `git diff --name-only <기준 커밋> <합친 커밋>`. +2. 그 목록을 두 종류의 패턴과 맞춘다. + - `on.pull_request.paths`가 있는 workflow(`grep -l 'paths:' .github/workflows/*.yml`). 패턴은 glob이다(`**`는 폴더 여러 단계). + - `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 단계 아님"을 결과 표에 적는다. + +(다) 로컬에 도구가 없는 것: + +| 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 변경 없음" | 전부 | +| `dependency-vulnerability.yml` `dependency-review`·`dependency-submission` | GitHub에서만 돈다. diff에 lockfile·`src/gradle/libs.versions.toml` 변경이 없으면 "해당 없음", 있으면 PR 결과를 보고 남은 문제로 적는다 | 전부 | +| `dependency-vulnerability.yml` `trivy-fs` | trivy가 있으면 job의 `run` 줄 그대로, 없으면 못 돌림 | — | + ## 4. 결과 기록 -| 게이트 | 결과 | 시간 | 실행 직전 1분 부하 | 로그 | -| --- | --- | --- | --- | --- | -| `:ci :verifyDependencyLocks --warning-mode=fail` | rc=0 | 5분 42초 | 2.65 | desktop `~/<작업 이름>-logs/ci.log` | +| 단계 | 게이트(명령) | 결과 | 시간 | 실행 직전 1분 부하 | 실제 실행 | 로그 | +| --- | --- | --- | --- | --- | --- | --- | +| PR | `:ci :verifyDependencyLocks --warning-mode=fail --no-build-cache` | rc=0 | 6분 32초 | 0.39 | 태스크 756 executed, FROM-CACHE 0, 테스트 7298 실패 0 | desktop `~/<작업 이름>-logs/ci.log` | + +- 한 줄은 명령 하나다. 여러 명령으로 된 job(`configuration-cache`, notification `pr`)은 명령마다 한 줄을 쓰고 「게이트」 칸에 ` 1/7`처럼 순번을 붙인다. Gradle의 태스크 집계 줄은 명령마다 하나씩 나오므로 로그도 명령마다 나눈다. +- 「실제 실행」 칸은 로그의 `> Task` 줄에서 센다: executed(꼬리 없음), UP-TO-DATE, FROM-CACHE. 테스트 수는 그 명령이 새로 쓴 JUnit XML에서 센다. 함께 적는다: @@ -126,7 +167,7 @@ cd .. && bash scripts/verify-compose-profile-contracts.sh | 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) | | 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 | | 시간 단언을 끈 채 performance lane 실행 | convention이 단언을 켜고, 끄는 값이나 skip이 있으면 테스트 전에 실패(5절) | -| 캐시에서 가져온 결과를 지금 통과한 것으로 셈 | 기준 상태 확인과 시간·환경에 민감한 테스트는 그 태스크를 `--rerun`으로 다시 돌린다 | +| 캐시에서 가져온 결과를 지금 통과한 것으로 셈 | 기준 상태 확인과 시간·환경에 민감한 테스트는 그 태스크를 `--rerun`으로 다시 돌린다. `--rerun`은 바로 앞 태스크 하나에만 걸리므로 태스크마다 붙인다. 집계 태스크는 새 worktree와 `--no-build-cache`로 돌리고 FROM-CACHE 0을 보인다(3절) | | 외부 이미지가 사라져 다른 lane 결과까지 가림 | 테스트 이미지를 `src/config/testing/container-images.properties` 한 곳에 digest로 고정, main 단계는 `--continue` | 게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다. diff --git a/docs/work/reference/review-criteria.md b/docs/work/reference/review-criteria.md index de30a617..5d861c5a 100644 --- a/docs/work/reference/review-criteria.md +++ b/docs/work/reference/review-criteria.md @@ -222,7 +222,7 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼 ## 10. 리뷰 문서 양식 -**위치**: 전체 리뷰는 `docs/reviews/-<종류>/README.md` + 영역 문서 `NN-<영역>.md`. 확인 리뷰는 그 폴더 아래 `roundN/`. 리뷰 문서는 리뷰 시점 기록이다. 수정 뒤에도 영역 문서를 고치지 않고 처리 결과는 README에 적는다. +**위치**: 전체 리뷰는 `docs/reviews/-<종류>/README.md` + 영역 문서 `NN-<영역>.md`. 확인 리뷰는 그 폴더 아래 `roundN/NN-<영역>.md`, 영역마다 하나다. 한 리뷰어가 모든 영역을 봐도 영역마다 나눈다. 리뷰 문서는 리뷰 시점 기록이다. 수정 뒤에도 영역 문서를 고치지 않고 처리 결과는 README에 적는다. **전체 리뷰 README의 절** (가이드 36.5절 양식에 처리 현황·결정 기록을 더한 것): @@ -264,6 +264,8 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼 - 라운드 안에서는 `NN-MM`(영역-순번)이다. 확인 리뷰는 라운드 접두어를 붙여 `RR-NN-MM`으로 쓴다(첫 재리뷰만 `` 없이). - 라운드 밖(다른 문서, 커밋, 주석)에서는 리뷰 폴더 날짜의 월일을 붙인다: `MMDD/`(가이드 36.3절). - 영역 번호 자리에 `NN` 같은 자리표시자를 남기지 않는다. 리뷰가 끝난 뒤 영역 접두어를 바꾸지 않는다. +- 영역 번호는 그 라운드 영역 표의 순번이다. 지난 라운드 번호와 맞추지 않아도 된다. 지난 라운드 영역 하나를 둘로 나누면 뒤에 새 번호를 잇고(04를 나누면 04·05), 「범위」 절에 지난 영역과의 대응을 적는다. +- 한 라운드의 ID는 리뷰 하나가 매긴다. 같은 범위를 두 리뷰가 따로 봤으면(독립 리뷰어 둘, [improve.md](../improve.md) 4.1절) brief가 정한 쪽이 정본이다. 다른 쪽은 임시 번호 `B-NN-MM`을 쓰고, 그 발견은 합칠 때 정본의 다음 번호로 새 ID를 받는다. 두 ID의 대응표를 README의 그 라운드 색인 절에 둔다. 다른 쪽 문서를 그대로 합치지 않는다(같은 ID가 다른 결함을 가리킨다). - ID는 리뷰 문서·brief·커밋에서 쓴다. 매뉴얼(`docs/work/`) 본문에는 쓰지 않는다. ## 11. 판단을 적는 법 diff --git a/docs/work/research-design.md b/docs/work/research-design.md index de9d32a8..1b7ba181 100644 --- a/docs/work/research-design.md +++ b/docs/work/research-design.md @@ -19,7 +19,7 @@ ## 3. 크기와 사고 순서 -- 설계 메모 하나는 보통 중간이다: 선행 사례 2~3곳(내부 선례 포함), 대안 2~3개. +- 설계 메모 하나는 보통 중간이다: 선행 사례 2~3곳(내부 선례 포함), 대안 2~3개. 다루는 대상이 [README](README.md) 2절의 "파일 하나여도 큼" 표면(오류 코드 레지스트리 등)이어도 메모만 쓰고 바꾸지 않으면 중간이다. 큼은 그 메모를 적용하는 일이다(design-docs `conventions/work-thinking-order.md` 2.1절). - 새 체계·아키텍처·공개 계약은 큼이다: 선행 사례 10~15곳, 대안 3~5개. 1~5단계 결과와 대안 비교를 소유자가 먼저 본다. - 이 repo의 내부 선례를 찾는 곳: - [reference/decisions.md](reference/decisions.md)와 그 출처 문서 @@ -34,9 +34,9 @@ 1. 목적을 한 문장으로 적고 성공 기준을 정한다. 요청 원문이 있으면 인용한다. 2. 이미 정한 것을 찾는다(3절의 내부 선례). 이미 정해져 있으면 멈추고 그 결정을 보고한다. -3. 현황을 확인한다. 주장마다 출처를 단다: `file:line`, 커밋, 명령 결과. 실제 동작이 궁금하면 별도 worktree에서 탐침 테스트를 desktop으로 돌리고, 탐침 코드는 남기지 않는다. +3. 현황을 확인한다. 주장마다 출처를 단다: `file:line`, 커밋, 명령 결과. 코드 읽기로 동작이 하나로 정해지지 않으면(분기, 동시성, 설정·외부 시스템에 따라 다름) 별도 worktree에서 탐침 테스트를 desktop으로 돌리고, 탐침 코드는 남기지 않는다. 분기 없는 경로이고 기존 테스트가 그 동작을 고정하면 탐침을 생략하고, 그 테스트 이름을 출처로 적는다. 4. 선행 사례 표를 만든다: 출처 · 1차/2차 · 그들이 한 것 · 실패와 비판 · 가져올 것. -5. 대안을 비교한다. 실제로 다른 대안 2~5개(크기에 맞게), 기준(효과, 비용, 되돌리기, 파생 서비스 영향, 기존 결정과 충돌), 권하는 안과 이유. 의존 순서가 있는 변경은 의존 그래프 순서로 따진다. +5. 대안을 비교한다. 실제로 다른 대안 2~5개(크기에 맞게), 기준(효과, 비용, 되돌리기, 파생 서비스 영향, 기존 결정과 충돌), 권하는 안과 이유. 의존 순서가 있는 변경은 의존 그래프 순서로 따진다. 파생 서비스 영향은 파생 서비스 repo에서 바꿀 이름(키, 칸, 타입)을 `git grep`해 쓰는 곳을 센다. 소유자 환경의 파생 서비스 위치는 design-docs `conventions/delegation-loop.md` 11절이다. 6. 반증할 수 있는 가정을 적는다: "이 안이 틀렸다면 어디서 드러나나". 반론과 답도 적는다. 7. 산출물을 둔다. - 이 repo에만 해당: 설계서 `docs/superpowers/specs/-<주제>-design.md`, 되돌리기 비싼 선택이면 `docs/adr/ADR-<영역>-<번호>-<제목>.md`(기존 번호를 잇는다). diff --git a/scripts/check-work-docs.py b/scripts/check-work-docs.py index 0a40e226..716bb9e2 100755 --- a/scripts/check-work-docs.py +++ b/scripts/check-work-docs.py @@ -81,6 +81,16 @@ HISTORY_PATTERNS = [ ("review round prefix (RR-, RR2-, ...)", re.compile(r"\bRR\d*-", re.ASCII)), ("fix bundle name (r2-05a, r9-a, r10-03)", re.compile(r"\br\d{1,2}-(?:\d{2}[a-z]?|[A-Za-z])\b", re.ASCII)), ("review round folder name (round6)", re.compile(r"\bround\d+\b", re.ASCII)), + # A finding number written after the word for review or round, with no folder date in front: + # "리뷰 02-01", "1라운드 06-01", "리뷰 README 13.2, 09-02", "review 2026-11-01 05-15". The number + # must stand alone, so a date such as 2026-11-01 is not a finding number by itself. + ("finding number after a review or round word (리뷰 02-01)", + re.compile(r"(?:리뷰|라운드|(?