Files
clean-architecture-backend-…/docs/improvement/09-working-method.md
T
DongHyeonka 319cff9155 docs(improvement): desktop 공유 잠금과 두 repo의 종료 조건 결정을 적는다
문제: 07장은 desktop 빌드를 "겹치지 않게"라고만 적고 잠금 파일을 정하지
않았다. 짝 프론트도 같은 desktop에서 돌려 부하와 포트(4173·4174)가 겹칠 수
있다. 또 두 repo 매뉴얼은 장 구성이 같은데, 리뷰 반복 종료 조건은 소유자가
"각자 유지"로 정해 서로 다르다. 이 차이가 매뉴얼에 없으면 같은 뼈대를 보고
같은 조건으로 오해한다.

방법: 07장 6절 절차와 규칙에 `flock /tmp/claude-gates/heavy.lock`을 넣고
한 줄 명령을 적는다(총괄 세션 지시). 08장 색인에 "두 repo의 종료 조건"과
"desktop 공유 잠금" 행을 더하고, 누가 칸에 "총괄 지시"·"정책" 뜻을 적는다.
README의 프론트 뼈대 절과 09장 5절에 이 조건만 의도적으로 다르다고 적는다.

검증: 인용 경로·ID·링크·절 번호 대조 스크립트를 다시 돌렸다(새 불일치 없음).
문서 대조 lane은 push 뒤 desktop에서 잠금 아래 다시 돌린다.
2026-11-05 22:04:28 +09:00

9.9 KiB

09. 작업 진행 방식

핵심

큰 개선 작업은 총괄 하나와 여러 하위 작업 단위로 나눠 한다. 총괄은 범위를 정하고, 나누고, 지시하고(brief), 결과를 대조하고, 기록한다. 리뷰·수정·검증 같은 실제 작업은 하위 단위가 자기 worktree에서 한다. 리뷰 → 수정 → 확인 리뷰를 발견이 0이 될 때까지 반복한다.

총괄
 ├─ 범위·기준 커밋 고정, 이전 결정 읽기(08장)
 ├─ 영역·묶음 나누기(2절) ──> brief 쓰기(3절)
 │        ┌──────────────┬──────────────┬──────────────┐
 │        v              v              v              v
 │     하위 A          하위 B          하위 C          하위 D      (각자 worktree·브랜치, RED→GREEN, 영역 검증)
 │        └──────┬───────┴──────────────┴──────────────┘
 │               v
 ├─ 보고를 diff·실행 기록과 대조(4절) ──> 합치기 + 전체 게이트(07장 3절)
 ├─ 리뷰 README에 처리 표·결정·게이트 기록
 └─ 확인 리뷰(수정 diff만) ──> 발견 0? ── 아니면 다시 나누기
                                   └─ 0이면 보고(5절)

하위 작업 단위를 무엇으로 띄우는지는 환경에 묶인 규칙이라 6절 「소유자 환경」에 따로 둔다.

1. 역할

총괄이 한다 하위 단위가 한다
범위·기준 커밋·영역 분할 맡은 영역의 리뷰, 또는 맡은 발견의 수정
brief 작성, 결정 색인 연결 RED → GREEN, 같은 원인의 다른 자리 찾기, 문서 동기화
소유자에게 결정 묻기(근거와 권하는 안을 붙여) 영역 검증(leaf check, 관련 lane)
보고를 diff·실행 기록과 대조 처리 표 한 행 형식의 보고
리뷰 README 기록, 소유자 보고 범위 밖 발견은 고치지 않고 보고
  • 합치기와 전체 게이트도 하위 단위에 맡길 수 있다. r10 수정의 전체 게이트는 별도 작업 단위가 desktop에서 돌렸다 (1103 README 17.1·17.2절).
  • 총괄은 High·Important 이상을 코드에서 직접 다시 확인한다(1101 README 2절).
  • 총괄은 보고를 믿지 않고 확인한다. 보고는 E0 증거다(02장 4절).

2. 나누는 법

  • 영역 분할은 최근 리뷰의 영역 표를 다시 쓴다. 전체 리뷰는 1101 README 9절의 9영역, 재리뷰는 1103 README 2절의 7영역, 확인 리뷰는 4영역(1103/round6/).
  • 두 묶음이 같은 파일을 건드리지 않게 나눈다. 겹치면 합칠 때 손으로 풀어야 한다. 2라운드는 묶음 사이 충돌이 많아 한 묶음을 처음부터 다시 시켰다(1101 README 14.1절 r2-06 "10개 파일 충돌로 baseline2 위에서 다시 작업").
  • 묶음마다 그 시점의 메인 상태에서 시작한다. 3라운드가 2라운드보다 충돌이 적었던 이유다(1101 README 16.1절).
  • 전 leaf의 import를 바꾸는 묶음은 마지막에 혼자 한다(1101 README 15.1절 r3-G).
  • 한 묶음을 너무 크게 만들지 않는다. 알림·파일 서버를 한 묶음으로 묶었다가 마감 안에 검증 보고가 오지 않아 합치지 못했다 (1101 README 14.3절 r2-05a). 그 묶음은 다음 라운드에 다시 올려 합쳤다(1101 README 16절 r3-a).
  • 같은 결함을 두 영역이 보면 한 묶음에만 배정한다. 같은 문장을 두 리뷰가 적은 것은 한 번 고쳤다(1103 README 17절 "RR6-01-07과 RR6-02-03은 같은 runbook 문장이라 한 번 고쳤다").

3. brief에 넣을 것

brief는 하위 단위가 받는 유일한 맥락이다. 빠뜨린 것은 하위 단위가 모른다.

  • 목표와 완료 기준. 무엇이 끝나면 끝인가(01장의 해당 작업 완료 기준).
  • 기준 커밋·브랜치·worktree. 어디서 시작하고 어디에 커밋하나.
  • 범위. pathspec과 발견 ID 목록. 범위 밖 발견은 "고치지 말고 보고"(1103 README 12절 "맡은 Minor 밖은 고치지 않고 보고만 하게 했다").
  • 이미 정한 결정. 08장 색인의 해당 행과 원문 위치. "다시 묻지 말 것".
  • 쓸 스킬. 01장 표에서. 리뷰면 리뷰어 템플릿과 영역 스킬(1103 README 머리말).
  • 심각도 기준(리뷰면). 02장 3절 정의를 그대로 붙인다(1103 README 11절 "심각도 기준을 지침에 적었다").
  • 검증 위치와 명령. 07장 6절 「소유자 환경」, 돌릴 게이트.
  • 하지 말 것. 리뷰는 코드 수정 금지, 다른 브랜치 push 금지, PR·병합 금지, 하위의 하위 위임 금지(환경에 따라).
  • 커밋 허용 여부와 규칙. 08장 4절.
  • 보고 형식. 4절.
  • 막혔을 때. 소유자만 정할 수 있는 것은 근거와 권하는 안을 붙여 묻는다.

4. 보고 형식

하위 단위 → 총괄: 리뷰 README 처리 표의 한 행으로 바로 옮길 수 있게 쓴다(1101 README 13절, 1103 README 6·10·12·16·17절 표).

칸 적을 것
묶음·발견 ID r10-02, RR6-02-01~05
상태 완료 / 부분(무엇이 남았나) / 못 함(이유)
검증 명령과 테스트 수. 예: "redisContainerContractTest 78, PG 계약 31"
RED 수정 전 실패한 테스트 이름과 수
처리 내용 무엇을 바꿨나, 고치다 새로 찾아 고친 것
결정·남은 것 정한 기본값(소유자 확인 대상), 남은 것

함께 줄 것: 브랜치와 커밋 sha, 실행 로그 위치, 범위 밖에서 본 결함.

총괄 → 소유자: 바꾼 것 · 확인한 것(게이트·rc·커밋) · 남은 문제. 남은 문제를 숨기지 않는다(AGENTS.md 「작업 보고 규칙」). 소유자가 이미 아는 외부 일(PR 병합, CI runner 켜기)은 「소유자 일」로 한 번만 적고 남은 문제와 섞지 않는다(1103 README 13.1절 "소유자 일").

5. 리뷰 → 수정 반복과 종료 조건

왜 반복하나: 수정이 새 결함을 만든다. 1차 재리뷰는 원래 리뷰의 수정에서 Important 27건을 찾았고(1103 README 1절), 그 수정을 다시 본 2차 재리뷰도 새 Important를 찾았다(1103 README 9절 표 "이번 라운드가 새로 만든 Important"). round6은 r9 수정의 회귀를 찾았다(1103/RR6-01-01).

확인 리뷰의 범위: 저장소 전체가 아니라 그 수정 커밋만 본다. 전 영역은 이미 봤고, 남은 위험은 "수정이 새 결함을 만든다"이기 때문이다(1103 README 9절). 수정 diff가 건드린 동작의 주변 코드는 함께 읽는다(02장 8.2절 「범위」).

종료 조건 — 모두 만족해야 끝난다.

  1. 마지막 확인 리뷰의 발견이 심각도와 상관없이 0이다.
  2. 열린 「Declined to judge」 항목이 없다. 판단하지 않은 항목은 총괄이 다음 묶음에 배정하거나 결정으로 닫았다.
  3. 합친 트리에서 07장 3절 전체 묶음이 통과했다.
  4. 리뷰 README의 "남음" 항목이 0이다. 결정으로 닫은 것은 결정 위치가 적혀 있다.

예전 멈춤 기준("새 Important 0이면 멈춤", "Minor는 기록만")은 소유자가 거뒀다(1103 README 16절, 08장 1절).

이 종료 조건은 이 repo의 것이다. 짝 프론트 repo는 다른 종료 조건을 쓴다. 소유자가 두 repo의 조건을 "각자 유지"로 정했다 (08장 1절 「두 repo의 종료 조건」). 장 구성은 같고 이 조건만 다르다.

코드로 고칠 수 없는 것: 소유자 결정이 필요한 것만 남을 수 있다. 그것은 근거와 권하는 안을 붙여 질문으로 보고한다. 질문이 답을 받으면 다시 고치기로 돌아간다.

종료 조건을 미리 정한다: 라운드를 시작할 때 그 라운드의 멈춤 조건을 README에 적는다(1103 README 9.1절 끝 문단처럼). 이 매뉴얼의 종료 조건과 다르면 이 매뉴얼을 따른다.

6. 소유자 환경 — 세션 분업

이 절은 이 repo 소유자의 작업 도구에 묶인 규칙이다. 파생 프로젝트는 이 절만 자기 환경으로 바꾼다(README 결정 M-6). 출처: 2026-11-05 총괄 세션 brief(README 결정 M-9).

  • 총괄 세션은 지휘만 한다. 하위 작업 단위는 Claude 데스크톱 앱의 하위 세션(별도 세션, 사용자가 열어 보고 멈출 수 있다)으로 띄운다. 세션 안의 하위 에이전트(subagent)로 돌리지 않는다.
  • 하위 세션 안에서 다시 하위 에이전트를 띄우지 않는다. 넓은 조사는 그 세션이 직접 나눠 읽는다. 지난 라운드도 사용량 한도 때문에 하위 에이전트 없이 진행했다(1101 README 16절 "하위 에이전트는 쓰지 않았다(지난 라운드 사용량 한도)", 1103 README 6절 "하위 에이전트 없음").
  • 세션마다 자기 worktree와 브랜치를 쓴다. 같은 checkout을 두 세션이 동시에 쓰지 않는다. desktop checkout은 예외로 함께 쓰므로 07장 6절 절차를 따른다.
  • 세션끼리는 공유 노트 폴더로 큰 결과를 넘긴다. 탐침 코드와 실행 로그처럼 메시지에 넣기 큰 것은 노트 폴더에 두고 위치만 보고한다(1103/round6/01-core-inbound.md "탐침 코드와 결과 파일은 공유 노트 폴더 rr6-01-probes/에").
  • 짝 프론트 repo의 일은 프론트 쪽 총괄 세션을 거친다. 계약 변경은 인계 문서로 넘긴다(1101 README 16.3절 "프론트 인계").

지금 이해하면 되는 것

  • 총괄은 나누고·지시하고·대조하고·기록한다. 일은 하위 단위가 자기 worktree에서 한다.
  • brief는 하위 단위의 유일한 맥락이다. 결정·범위·검증 위치·보고 형식을 빠뜨리지 않는다.
  • 확인 리뷰는 수정 diff만 보고, 발견 0 + Declined 0 + 전체 게이트 통과 + "남음" 0일 때 끝난다.