docs(work): cold-read 시험 1회차의 빈틈과 모순을 매뉴얼에 반영한다
문제: 2026-11-06 이력 없는 세션 6개에 이 매뉴얼만 주고 실제 일을
시켰다. 6개 모두 일은 끝냈지만 매뉴얼에서 답을 못 찾은 곳이 세션마다
1~9건 나왔고, 세 곳은 문서끼리 다르게 말했다.
- 리뷰 README를 누가 쓰나: delegate.md는 총괄, improve.md는 리뷰어
- push: README 4절·decisions.md는 "커밋을 허용하면 push도", 정본
delegation-loop.md 11절은 brief가 push를 따로 허용해야 한다
- evidence.md 머리말은 "RR-는 1차 재리뷰"라는데 round2도 RR-를 썼다
고른 방법:
- 리뷰어는 README에 자기 라운드 색인 절 하나만 쓰고, 처리 표·결정의
답·게이트 기록은 총괄이 쓴다(improve.md 4.1, delegate.md 4.2,
decisions.md 2.1)
- 커밋과 push는 brief 7절이 따로 허용한다. 커밋만 허용되면 push하지
않는다. push 없이도 패치와 트리 해시로 desktop에서 검증한다
(operate.md 4.1 「push 전에 검증하기」). 이 방법은 커밋 본문에
desktop 결과를 넣으려는 세션의 빈틈도 닫는다
- evidence.md 머리말을 접두어별 문서로 고친다
- 나머지 빈틈은 그 일을 하는 playbook의 절차 단계나 자주 하는 실수,
reference에 한 줄씩 넣는다. 36행 처리 표는 evidence.md 9절이다
(고침 35, 고치지 않음 1: 새 매뉴얼에 이미 답이 있던 것)
버린 대안: push를 "커밋 허용이면 push도"로 읽기. 정본 11절과 실제
brief(백엔드는 push, design-docs는 push 안 함)가 push를 따로 다룬다.
버린 대안: 빈틈을 모두 자주 하는 실수에 넣기. 10줄 상한을 넘고, 절차의
한 단계인 것은 그 단계에 있어야 읽힌다.
위험·한계:
- 리뷰 README 분담, push를 따로 읽는 것, 하위 세션 Slack은 기본값이다.
소유자가 뒤집을 수 있게 decisions.md에 기본값으로 적었다
- AGENTS.md의 커밋 예외 문장은 이번 범위 밖이라 그대로다. 세부는 이
README 4절을 가리키므로 README가 정한다
- 고친 매뉴얼은 2회차 cold-read 시험 전이다
검증:
- python3 scripts/check-work-docs.py rc=0. 지도 73/120, README 76/80,
improve.md 134/150, 진입 경로 최대 283/350, 본문 이력 0줄
- python3 scripts/check-work-docs.py --links docs CLAUDE.md 결과 링크
432개, 깨진 것 0
- desktop: 바꾼 것을 패치로 기준 커밋 2c8a359d 위에 얹어 노트북과 같은
트리 3d0e5900을 만들고 flock 아래
:app-bootstrap:documentContractTest --rerun rc=0, 66건 실패 0
건너뜀 0, 13초, 직전 1분 부하 3.13
(desktop ~/manual-gap-fix-1-logs/documentContractTest.log)
This commit is contained in:
@@ -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. 소유자 환경
|
||||
|
||||
+4
-3
@@ -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절 양식을 쓴다.
|
||||
|
||||
|
||||
@@ -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,8 +31,8 @@ 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절)와 "발견마다 이번 수정이 만들었나 / 이전부터"를 요구한다.
|
||||
- 대조할 때: 보고의 태스크 이름·테스트 수를 desktop 로그에서 grep으로 찾는다. High·Important 이상은 총괄이 코드에서 직접 다시 확인한다.
|
||||
- 리뷰 결과를 받으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`로 색인이 빠짐없는지 본다. 수정 묶음은 색인에서 배정한다.
|
||||
@@ -58,7 +58,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` | 라이프사이클과 기본 조립 |
|
||||
@@ -97,7 +97,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
|
||||
- 하위 세션의 일을 대신 하지 않는다. 대조에 필요한 읽기와 확인만 직접 한다.
|
||||
- 보고를 그대로 믿지 않는다. 보고는 E0 증거다.
|
||||
- 같은 파일을 두 세션에 맡기지 않는다.
|
||||
- 하위 세션에 main 병합·push, force push, 다른 브랜치 push를 허용하지 않는다.
|
||||
- 하위 세션에 main 병합·main push, force push, 다른 브랜치 push를 허용하지 않는다.
|
||||
- brief에 결정 번호만 쓰지 않는다. 내용을 쓴다.
|
||||
|
||||
## 7. 막혔을 때
|
||||
@@ -114,3 +114,4 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
|
||||
- 영역 문서의 ID를 색인에 손으로 옮기다 빠뜨린다. 색인 검사 스크립트를 돌린다.
|
||||
- 묶음을 너무 크게 만들어 마감 안에 검증 보고가 오지 않는다. 묶음 크기 상한을 지킨다.
|
||||
- 하위 세션이 적은 태스크 이름을 확인하지 않고 소유자에게 옮긴다.
|
||||
- 같은 범위를 두 리뷰에 따로 맡기고(비교 시험 등) ID를 매길 쪽을 정하지 않아, 같은 ID가 다른 결함을 가리킨다. brief에 ID를 매길 리뷰 하나를 정한다(규칙은 [reference/review-criteria.md](reference/review-criteria.md) 10절 「ID」).
|
||||
|
||||
@@ -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 결정 <파일>`로 남은 괄호를 한 번 더 읽고, 못 잡은 꼴은 검사 패턴에 더한다.
|
||||
|
||||
+52
-2
@@ -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,54 @@
|
||||
| `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)
|
||||
|
||||
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`.
|
||||
|
||||
- 세션: 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`(결함 수정).
|
||||
- 출처 칸: `기록 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절. 훅으로는 막지 않는다(보고 문장은 도구 호출이 아니라 훅이 볼 수 없다) |
|
||||
|
||||
- 기준선과 새 매뉴얼의 리뷰 발견은 8건 중 1건만 겹쳤다. 리뷰 방식을 바꿀지는 매뉴얼 규칙으로 넣지 않고 소유자에게 물을 제안으로 남겼다(매뉴얼 수정 세션 보고).
|
||||
- 「자주 하는 실수」에 넣은 줄: `improve.md`(strict lane 탐침), `operate.md`(`--rerun` 범위를 기존 줄에 더함, push 뒤 검증), `docs-writing.md`(`--history` 0을 믿음), `delegate.md`(두 리뷰의 ID).
|
||||
|
||||
+10
-7
@@ -37,14 +37,14 @@
|
||||
### 4.1 리뷰
|
||||
|
||||
1. 범위를 고정한다. 확인 리뷰는 pathspec과 `git diff --stat <base>..<head> -- <pathspec>` 결과를 문서에 적는다.
|
||||
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가 맡겼을 때만 다시 판정한다. 맡기지 않았으면 건수와 위치만 적는다.
|
||||
|
||||
### 4.2 결함 수정
|
||||
|
||||
@@ -68,7 +68,8 @@
|
||||
### 4.4 수정 묶음의 크기
|
||||
|
||||
- 묶음 하나는 리뷰 영역 하나 안이고 발견 8건 이하다. 묶음마다 커밋 하나다.
|
||||
- 확인 리뷰 하나가 보는 수정 diff는 추가 1,500줄 이하다(`git diff --shortstat <base>..<head>`, 테스트 포함, lockfile·스냅숏 같은 생성 파일 제외). 넘으면 확인 리뷰를 나눈다. 묶음 커밋이 따로 있으면 커밋별로, 한 커밋에 여러 영역이 섞였으면 영역 pathspec별로(`git diff --shortstat <base>..<head> -- <pathspec>`) 나눠 각각 상한 안이 되게 한다.
|
||||
- 확인 리뷰 하나가 보는 수정 diff는 추가 1,500줄 이하다(`git diff --shortstat <base>..<head>`, 테스트 포함, lockfile·스냅숏 같은 생성 파일과 리뷰 기록 `docs/reviews/**` 제외). 넘으면 확인 리뷰를 나눈다. 묶음 커밋이 따로 있으면 커밋별로, 한 커밋에 여러 영역이 섞였으면 영역 pathspec별로(`git diff --shortstat <base>..<head> -- <pathspec>`) 나눠 각각 상한 안이 되게 한다. 테스트 파일은 그 테스트가 지키는 코드의 영역에 넣는다.
|
||||
- 나누는 것은 맡긴 쪽이 brief로 한다. 상한을 넘는 범위를 brief 하나로 받았으면, 한 세션이 나눈 단위를 차례로 보고 단위마다 문서 하나를 쓴다. 그렇게 했다고 보고에 적는다.
|
||||
- 왜: 지난 수정 라운드에서 추가 줄이 2,000줄 아래면 다음 확인 리뷰 발견이 9건 이하였고, 5,000줄을 넘으면 19건 이상이었다([evidence.md](evidence.md) 「수정 묶음 크기」). 상한 값은 판단이다. 라운드당 새 결함 수로 다시 맞춘다.
|
||||
- 묶음을 합친 트리는 따로 검증한다([reference/gates.md](reference/gates.md) 「라운드 끝」). 두 묶음의 수정은 한 트리에서 처음 만날 때 새 결함을 만든다.
|
||||
|
||||
@@ -77,7 +78,7 @@
|
||||
리뷰 → 수정 → 확인 리뷰는 아래 넷이 모두 참일 때만 멈춘다.
|
||||
|
||||
1. 마지막 확인 리뷰의 발견이 심각도와 상관없이 0이다. Minor도 기록만 하지 않고 고친다.
|
||||
2. 열린 「Declined to judge」가 0이다.
|
||||
2. 열린 「Declined to judge」가 0이다. 다른 브랜치가 처리했지만 아직 합치지 않은 항목은 합친 트리에서 확인할 때까지 열린 것으로 센다.
|
||||
3. 합친 트리에서 라운드 끝 게이트가 모두 통과했다.
|
||||
4. 리뷰 README의 남은 항목이 0이다. 결정으로 닫은 항목은 결정 위치를 적었다.
|
||||
|
||||
@@ -108,6 +109,7 @@
|
||||
|
||||
- 고치는 법이 공개 동작(응답 코드, 기동 실패 조건, env 키, 파생 서비스 동작)을 바꾸면 고치기 전에 멈추고 묻는다. 형식은 [README](README.md) 5절이다.
|
||||
- RED를 만들 수 없으면(실 vendor가 없다, 머신에 따라 통과한다) 그 사실과 이유를 보고하고 그 발견만 멈춘다.
|
||||
- 계약을 적은 곳끼리(설계서, 포트 Javadoc, 모듈 README, 테스트) 다르게 말하고 [reference/decisions.md](reference/decisions.md)에 결정이 없으면, 어느 쪽도 고르지 않는다. 양쪽 근거를 표로 붙이고 권하는 안과 함께 묻는다. 그 발견만 멈춘다.
|
||||
|
||||
## 8. 보고 형식
|
||||
|
||||
@@ -129,3 +131,4 @@
|
||||
- 색인을 손으로 옮기다 발견이 빠진다. 색인 검사 스크립트를 돌린다.
|
||||
- 보고에 없는 태스크 이름을 적는다. 로그에서 태스크 이름을 grep해 확인한다.
|
||||
- 묶음별 검증으로 합친 트리 검증을 대신한다. 라운드 끝 게이트를 따로 돌린다.
|
||||
- strict lane에 돌릴 탐침을 새 클래스로 만들어 lane이 고르지 않는다. lane은 `build.gradle`의 `requires`(클래스 이름)나 `tag`로 테스트를 고른다. 탐침은 그 lane이 고르는 기존 클래스에 메서드로 넣는다. 탐침도 `-Werror`로 컴파일되니 경고를 남기지 않는다.
|
||||
|
||||
+18
-3
@@ -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. 크기와 사고 순서
|
||||
@@ -60,6 +60,20 @@ git worktree remove ~/workspace/<작업 이름>
|
||||
- RED 확인용 임시 worktree도 같은 방법으로 만들고 끝나면 지운다.
|
||||
- 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절 묶음 전체다.
|
||||
@@ -112,4 +126,5 @@ git worktree remove ~/workspace/<작업 이름>
|
||||
|
||||
- desktop 기존 checkout에서 브랜치를 바꿔 다른 세션의 작업을 방해한다. 자기 worktree를 만든다.
|
||||
- 짧게 끝난 실행을 통과로 적는다. 캐시 재사용인지, 태스크가 실제로 돌았는지 로그로 확인한다.
|
||||
- 빌드 캐시에서 가져온 테스트 결과를 지금 이 환경에서 통과한 증거로 쓴다. 기준 상태를 확인하거나 시간·환경에 민감한 테스트를 볼 때는 그 태스크를 `--rerun`으로 다시 돌린다.
|
||||
- 빌드 캐시에서 가져온 테스트 결과를 지금 이 환경에서 통과한 증거로 쓴다. 기준 상태를 확인하거나 시간·환경에 민감한 테스트를 볼 때는 그 태스크를 `--rerun`으로 다시 돌린다. `--rerun`은 바로 앞 태스크 하나에만 걸린다. 태스크마다 붙인다(`:a:test --rerun :b:test --rerun`).
|
||||
- 커밋하고 push한 뒤 desktop에서 돌려, 결과를 커밋 본문에 못 넣는다. push 전에 패치로 검증한다(4.1절).
|
||||
|
||||
@@ -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절 |
|
||||
|
||||
@@ -56,7 +56,7 @@
|
||||
| 테스트 코드 | 그 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가 따라가지 못한다).
|
||||
|
||||
@@ -126,7 +126,7 @@ cd .. && bash scripts/verify-compose-profile-contracts.sh
|
||||
| 게이트 밖에서 실패한 채 방치된 검사 | `testQualityCheck`(`mainCheck`) |
|
||||
| 실서버 계약이 어느 게이트에도 없음 | lane을 단계에 연결 |
|
||||
| 시간 단언을 끈 채 performance lane 실행 | convention이 단언을 켜고, 끄는 값이나 skip이 있으면 테스트 전에 실패(5절) |
|
||||
| 캐시에서 가져온 결과를 지금 통과한 것으로 셈 | 기준 상태 확인과 시간·환경에 민감한 테스트는 그 태스크를 `--rerun`으로 다시 돌린다 |
|
||||
| 캐시에서 가져온 결과를 지금 통과한 것으로 셈 | 기준 상태 확인과 시간·환경에 민감한 테스트는 그 태스크를 `--rerun`으로 다시 돌린다. `--rerun`은 바로 앞 태스크 하나에만 걸리므로 태스크마다 붙인다 |
|
||||
| 외부 이미지가 사라져 다른 lane 결과까지 가림 | 테스트 이미지를 `src/config/testing/container-images.properties` 한 곳에 digest로 고정, main 단계는 `--continue` |
|
||||
|
||||
게이트 장치 자체를 바꿨으면 일부러 망가뜨린 입력으로 실패하는 것을 본다. 판독기를 바꿨으면 바꾸기 전후로 실제 workflow의 판정이 같은지 비교한다.
|
||||
|
||||
@@ -222,7 +222,7 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼
|
||||
|
||||
## 10. 리뷰 문서 양식
|
||||
|
||||
**위치**: 전체 리뷰는 `docs/reviews/<YYYY-MM-DD>-<종류>/README.md` + 영역 문서 `NN-<영역>.md`. 확인 리뷰는 그 폴더 아래 `roundN/`. 리뷰 문서는 리뷰 시점 기록이다. 수정 뒤에도 영역 문서를 고치지 않고 처리 결과는 README에 적는다.
|
||||
**위치**: 전체 리뷰는 `docs/reviews/<YYYY-MM-DD>-<종류>/README.md` + 영역 문서 `NN-<영역>.md`. 확인 리뷰는 그 폴더 아래 `roundN/NN-<영역>.md`, 영역마다 하나다. 한 리뷰어가 모든 영역을 봐도 영역마다 나눈다. 리뷰 문서는 리뷰 시점 기록이다. 수정 뒤에도 영역 문서를 고치지 않고 처리 결과는 README에 적는다.
|
||||
|
||||
**전체 리뷰 README의 절** (가이드 36.5절 양식에 처리 현황·결정 기록을 더한 것):
|
||||
|
||||
@@ -264,6 +264,8 @@ leaf를 더하거나 옮기거나 지울 때 같은 변경에서 함께 바꾼
|
||||
- 라운드 안에서는 `NN-MM`(영역-순번)이다. 확인 리뷰는 라운드 접두어를 붙여 `RR<n>-NN-MM`으로 쓴다(첫 재리뷰만 `<n>` 없이).
|
||||
- 라운드 밖(다른 문서, 커밋, 주석)에서는 리뷰 폴더 날짜의 월일을 붙인다: `MMDD/<ID>`(가이드 36.3절).
|
||||
- 영역 번호 자리에 `NN` 같은 자리표시자를 남기지 않는다. 리뷰가 끝난 뒤 영역 접두어를 바꾸지 않는다.
|
||||
- 영역 번호는 그 라운드 영역 표의 순번이다. 지난 라운드 번호와 맞추지 않아도 된다. 지난 라운드 영역 하나를 둘로 나누면 뒤에 새 번호를 잇고(04를 나누면 04·05), 「범위」 절에 지난 영역과의 대응을 적는다.
|
||||
- 한 라운드의 ID는 리뷰 하나가 매긴다. 같은 범위를 두 리뷰가 따로 봤으면 brief가 정한 쪽이 정본이다. 다른 쪽 발견은 정본의 다음 번호로 새 ID를 받고, 두 ID의 대응표를 README의 그 라운드 색인 절에 둔다. 다른 쪽 문서를 그대로 합치지 않는다(같은 ID가 다른 결함을 가리킨다).
|
||||
- ID는 리뷰 문서·brief·커밋에서 쓴다. 매뉴얼(`docs/work/`) 본문에는 쓰지 않는다.
|
||||
|
||||
## 11. 판단을 적는 법
|
||||
|
||||
@@ -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/<YYYY-MM-DD>-<주제>-design.md`, 되돌리기 비싼 선택이면 `docs/adr/ADR-<영역>-<번호>-<제목>.md`(기존 번호를 잇는다).
|
||||
|
||||
Reference in New Issue
Block a user