문제: 리뷰·결함 수정·리팩터링·성능·구조·테스트 개선마다 시작 조건과 완료 기준이 어디에도 한곳에 없다. 총괄 세션 운영, 리뷰 중 실행 방식, 수정→리뷰 반복의 멈춤 조건은 사용자 지시와 리뷰 README에만 있다. 고른 방법: 01장에 여섯 작업의 시작 조건·단계·산출물·완료 기준을, 09장에 역할, brief, 리뷰 라운드 운영, "게이트는 한 번 돌리고 함께 읽는다", 멈춤 조건(새 High 0·새 P1 0·merge 14개 통과 뒤 그 라운드 Medium·Low 수정), 수정 라운드 운영, 총괄이 자주 한 실수를 적는다. 소유자 환경에 묶인 것은 09장 7절에만 둔다. 위험·한계: 스킬 기록 규칙과 대기 종료 조건 일반화는 [제안]으로 표시했다. 멈춤 기준의 3라운드 상한은 그동안 repo 밖 메모에만 있었다. 검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
154 lines
11 KiB
Markdown
154 lines
11 KiB
Markdown
# 09. 작업 진행 방식
|
|
|
|
## 핵심
|
|
|
|
큰 개선 작업은 **총괄 세션 하나와 하위 세션·서브에이전트 여럿**으로 나눈다. 총괄은 맡기고, 모으고, 다시 확인하고,
|
|
멈출지 정한다. 하위 세션은 맡은 영역 하나를 끝까지 한다.
|
|
|
|
```text
|
|
총괄(오케스트레이터)
|
|
├─ 리뷰 라운드: 게이트 1회 실행 → 사본 공유 → 영역 리뷰어 16개 → 실험 목록 → 일괄 실행 → README
|
|
├─ 수정 라운드: 영역별 수정 세션(격리 worktree·브랜치) → 통합 브랜치에 합침 → merge 게이트 14개
|
|
└─ 멈출 조건 판정 → 마지막 Medium·Low 수정 → 보고
|
|
```
|
|
|
|
이 장의 규칙은 2026-11-03~05 사용자 지시와 그때 리뷰 README에 남은 운영 기록이 출처다. 이 장이 그 규칙들의 repo 안
|
|
정본이다(README 결정 M-9).
|
|
|
|
## 1. 역할
|
|
|
|
| 역할 | 하는 일 | 하지 않는 일 |
|
|
| --- | --- | --- |
|
|
| 총괄 세션 | 범위·기준 커밋 고정, 게이트 실행, 영역 분할과 brief, 결과 통합, High·새 P1 재확인, 결정 정리, 멈춤 판정, 보고 | 영역 작업을 직접 다 하기. 총괄은 하위 세션에 맡긴다(사용자 지시) |
|
|
| 하위 세션 | 맡은 영역의 리뷰 또는 수정. 자기 worktree·브랜치에서 일하고 결과를 보고 | 다른 영역 파일 수정, push·PR, 범위 밖 수정 |
|
|
| 서브에이전트 | 한 번에 끝나는 조사·추출·리뷰. 결과를 파일로 남기고 짧게 보고 | 결정, 커밋 |
|
|
|
|
- 하위 세션이 결정이 필요한 것을 만나면 총괄에 한 번 묻고 기다린다. 스스로 정하지 않는다.
|
|
- 짝 백엔드 repo(`clean-architecture-backend-template`)는 읽기만 한다. stage·commit·push하지 않는다(사용자 지시).
|
|
백엔드에 넘길 것은 리뷰 README 「남은 문제」에 "백엔드에 넘길 것"으로 적는다(1103 README 14.7절).
|
|
|
|
## 2. brief 쓰는 법
|
|
|
|
하위 세션이 아는 것은 brief뿐이다. 다음을 넣는다.
|
|
|
|
1. 목표 한 문장과 끝났다고 볼 조건.
|
|
2. 기준 커밋·브랜치·작업 위치(worktree 경로).
|
|
3. 읽을 정본과 지난 기록의 위치(이 매뉴얼 장 번호로).
|
|
4. 하지 말 것: 리뷰면 코드 수정, 수정이면 범위 밖 파일·push·PR, 공통으로 짝 백엔드 쓰기.
|
|
5. 실행 위치와 잠금(07장 7절).
|
|
6. 보고 형식: 바꾼 것, 확인한 것(명령과 결과), 남은 것. 결론을 미리 주지 않는다. 총괄이 만든 변경을 리뷰시킬 때는
|
|
코드만 주고 결론은 주지 않는다(1103 README 10.5절 머리말).
|
|
|
|
## 3. 리뷰 라운드 운영
|
|
|
|
1. 총괄이 기준 커밋을 고정하고 게이트를 **한 번** 돌린다(07장 3절).
|
|
2. 출력과 `artifacts/`·`dist/`·`test-results/`를 읽기 전용 사본으로 뜬다. 4라운드는 desktop의
|
|
/tmp/claude-gates/r4/snap/ 에 두었다(1105 README 11.4절).
|
|
3. 영역 리뷰어를 병렬로 띄운다. 영역 표는 가장 최근 README의 것을 다시 쓴다(16개 영역, 1105 README 11.2절).
|
|
4. 리뷰어는 코드와 사본만으로 판정하고, 더 필요한 실험을 목록으로 낸다(4절).
|
|
5. 총괄이 실험을 일괄로 돌리고 결과를 영역에 돌려준다.
|
|
6. 총괄이 High 이상·새 P1을 직접 다시 확인하고 README를 쓴다(02장 6절).
|
|
|
|
## 4. 리뷰 중 실행 — 한 번 돌리고 함께 읽는다
|
|
|
|
사용자 결정이다: 필요할 때만, 묶어서, 실행마다 환경을 되돌린다(1105 README 11.4절, 2026-11-05).
|
|
|
|
- **게이트는 한 번.** 리뷰어마다 같은 빌드·테스트를 다시 돌리지 않는다. 4라운드 처음에 영역 리뷰어 16개가 각자
|
|
desktop에서 실행하게 했다가 잠금 줄에 30여 건이 섰고 32건을 취소했다(1105 README 11.5절 첫 행).
|
|
- **추가 실험은 목록으로.** 항목마다 ID, 명령, env, 시간 상한, 필요하면 변이 패치를 적는다.
|
|
- **같은 명령은 한 번만.** 두 영역이 같은 변이를 원하면 한 번 돌리고 결과를 함께 쓴다(1105 README 11.4절 셋째 줄).
|
|
- **실험마다 작업 폴더를 되돌린다.** 항목 앞뒤로 추적 파일을 기준 커밋으로 되돌리고 추적 안 된 파일을 지운다
|
|
(`node_modules`는 둔다). 4라운드 78항목 모두 `restore=clean`이었다.
|
|
- **복제본을 늘려 해결하지 않는다.** 한 checkout에서 두 실행이 부딪히는 원인은 고정 출력 경로·고정 포트라는 템플릿
|
|
결함이다(1105/12-04, 부록 P-06). 복제본을 늘리면 그 결함을 가리고 디스크·설치 비용만 는다.
|
|
|
|
4라운드의 일괄 실행기와 그 사용법은 같은 세션 그룹의 공유 노트에 있다(07장 7절).
|
|
|
|
## 5. 반복과 종료
|
|
|
|
### 5.1 반복
|
|
|
|
리뷰 → 수정 → 다음 라운드 리뷰를 반복한다(2026-11-04 사용자 결정). 라운드 하나의 순서:
|
|
|
|
1. 수정을 통합 브랜치에 합친다(6절).
|
|
2. merge 게이트 14개를 돌린다(07장 3절).
|
|
3. 전체 리뷰를 한 번 더 한다. 지난 발견 전부를 ID별로 다시 판정하고 새 발견을 찾는다. 수정 세션의 "고침" 보고를
|
|
그대로 믿지 않는다. 1103 조치에서 "고침"으로 적은 것 중 13건이 4라운드에서 "일부"로 정정됐다
|
|
(1105 README 3.1절).
|
|
4. 발견을 고친다.
|
|
|
|
- 라운드 사이에 새 기능이나 큰 구조 변경을 넣지 않는다. 넣으면 발견 수가 줄어드는지 볼 수 없다.
|
|
- 라운드마다 새 발견 수를 High·Medium·Low와 P1로 나눠 앞 라운드와 비교한다(1105 README 4절 표).
|
|
|
|
### 5.2 멈출 조건
|
|
|
|
다음 셋을 모두 채운 라운드에서 멈춘다(2026-11-04 사용자 결정).
|
|
|
|
1. 그 라운드의 **새 High 0**.
|
|
2. 그 라운드의 **새 P1 0**.
|
|
3. **merge 게이트 14개 통과**(07장 3절 방법. 고른 스크립트 목록으로 판정하지 않는다).
|
|
|
|
조건을 채워도 바로 끝내지 않는다. **그 라운드의 Medium·Low를 고치고** 멈춘다. 4라운드(1105)는 새 High 0이지만 새
|
|
P1이 3건이고 FE-GATE-013이 desktop에서 실패해 조건을 채우지 못했다(1105 README 2.2절, 11.1절).
|
|
|
|
멈춤 기준은 repo마다 자기 정본을 따른다. 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 두 기준을 하나로 맞추지 않는다
|
|
(2026-11-05 소유자 결정 「각자 유지」, README 결정 M-7).
|
|
|
|
### 5.3 남은 문제 0으로 보고한다
|
|
|
|
- 리뷰 발견은 Low까지 고친다. 보고의 "남은 문제"는 0이어야 한다(사용자 지시).
|
|
- 고칠 수 없는 것은 **결정 대기**로 남긴다. 이유, 선택지, 결정할 사람을 적는다(08장 4절 형식). "나중에", "범위 밖"
|
|
같은 이유 없는 이월은 남기지 않는다.
|
|
- 개선 제안(결함이 아닌 것)도 열린 채 두지 않는다. 받아서 하거나, 하지 않는 이유를 결정으로 남긴다.
|
|
|
|
### 5.4 반복 상한
|
|
|
|
1103 수정 라운드 뒤로 세 라운드를 더 돌아도 멈출 조건에 닿지 않으면 멈추고, 왜 수렴하지 않는지 소유자에게
|
|
보고한다(2026-11-04 사용자 결정). 4라운드(1105)가 그 첫째다. 이 상한은 그동안 repo 밖 작업 메모에만 있었다.
|
|
|
|
## 6. 수정 라운드 운영
|
|
|
|
1. 통합 브랜치를 만든다: `fix/maturity-review-<YYYY-MM-DD>`(리뷰 날짜). 예: `fix/maturity-review-2026-11-03`
|
|
(1103 README 14.1절).
|
|
2. 영역별 수정 세션이 격리 worktree의 `fix/r<MMDD>-<이름>` 브랜치에서 RED 테스트부터 고치고 커밋한다(wave 1).
|
|
다른 수정에 기대는 묶음은 그 수정이 합쳐진 뒤 시작한다(wave 2). CHANGELOG·문서는 마지막에 한 세션이 다시 쓴다
|
|
(wave 3).
|
|
3. 총괄이 브랜치를 `--no-ff`로 하나씩 합치고, 합칠 때마다 빠른 게이트를 돌린다(07장 2절). 합친 뒤에만 생긴 실패는
|
|
README 「통합에서 생긴 것」에 커밋과 함께 적는다(1103 README 14.3절).
|
|
4. 통합 브랜치에서 merge 게이트 14개를 돌린다. `ci:gate`는 첫 실패에서 멈추므로 고칠 때마다 다시 돌리고, 회차별
|
|
결과를 표로 남긴다(1103 README 14.5절).
|
|
5. push·PR 본문·최종 보고는 총괄(또는 리뷰를 맡긴 세션)이 한다. 수정 세션은 하지 않는다(1103 README 14절 머리말).
|
|
|
|
공통 지시(모든 수정 세션의 brief에 넣는다): RED 먼저, 논리적 변경 하나에 커밋 하나, 커밋 규칙, AI 꼬리말 금지,
|
|
`corepack pnpm`, 무거운 실행은 공유 잠금(1103 README 14.1절 셋째 줄).
|
|
|
|
## 7. 소유자 환경
|
|
|
|
이 절은 이 repo 소유자의 도구에 묶인 규칙이다. 복사한 프로젝트는 이 절을 자기 환경으로 바꾼다(README 결정 M-4).
|
|
|
|
- 세션 도구: Claude Code 데스크톱 앱. 총괄은 하위 세션을 띄우고, 하위 세션은 막힐 때 총괄에 한 번 묻는다.
|
|
- 공유 노트: 같은 세션 그룹은 repo 밖 공유 노트 폴더에 큰 발견과 인계 메모를 남긴다. 메시지에 길게 붙이지 않는다.
|
|
예: 4라운드 리뷰 위치·일괄 실행기 사용법, FE-GATE-008 원인 조사 두 건.
|
|
- 실행 위치와 잠금: 07장 7절.
|
|
- 보고: 작업 완료 보고는 "변경 / 확인 / 남은 문제" 세 줄이다. 소유자의 전역 지시가 정본이다(repo 밖).
|
|
|
|
## 8. 총괄이 자주 한 실수
|
|
|
|
리뷰 README의 「오케스트레이터 자신의 실수」 절에서 모았다. 같은 실수를 막는 규칙은 오른쪽 장에 있다.
|
|
|
|
| 실수 | 결과 | 막는 규칙 |
|
|
| --- | --- | --- |
|
|
| 게이트 목록을 지난 라운드 목록에서 가져왔다 | 실제 러너에서 항상 실패하는 merge 게이트 둘을 놓쳤다(1103 README 10.5절) | 07장 3절: merge 단계 `gateIds`로 돌린다 |
|
|
| 판정 표를 짝 백엔드 문서만으로 정했다 | 업무 거절이 트랜잭션 전에 난다는 사실을 놓쳐 High를 만들었다(1103/03-01) | 04장 4절: 짝 사실은 코드까지 따라간다 |
|
|
| 다운스트림 파일을 열지 않고 이름으로 추정했다 | CHANGELOG에 틀린 이행 안내(1103/14-02) | 08장 4절: 확인하지 않은 것은 "미확인"으로 |
|
|
| 지운 코드의 실행 동작만 찾았다 | 지운 검사·테스트가 지키던 동작을 놓쳤다(1103/07-01, 10-04) | 04장 5절: 지울 때는 그 코드가 지키던 것을 찾는다 |
|
|
| 영역 리뷰어마다 desktop에서 실행하게 했다 | 잠금 줄 30여 건, 32건 취소(1105 README 11.5절) | 4절 |
|
|
| `verify:documentation`을 옆 checkout 없는 임시 worktree에서 `pnpm`으로 돌렸다 | pnpm이 재설치를 시도하다 TTY 없음으로 멈춰 결과가 무효(1105 README 11.5절) | 07장 6절 |
|
|
| 제거 드릴을 `npm run`으로 돌렸다 | 모든 검사가 `Unknown command`로 실패, 결과를 버렸다(1103 README 10.4절) | 07장 1절: `corepack pnpm`만 쓴다 |
|
|
|
|
## 지금 이해하면 되는 것
|
|
|
|
- 총괄은 맡기고 모으고 다시 확인한다. 영역 작업은 하위 세션이 한다.
|
|
- 리뷰 중 실행은 총괄이 한 번 돌리고 모두가 함께 읽는다. 추가 실험은 목록으로 모아 일괄로 돌린다.
|
|
- 새 High 0·새 P1 0·merge 14개 통과면 그 라운드의 Medium·Low를 고치고 멈춘다. 못 고친 것은 결정 대기로 남긴다.
|