Files
clean-architecture-frontend…/docs/improvement/09-working-method.md
T
DongHyeonka d1b24567bf docs(improvement): 종료 조건의 백엔드 차이와 작은 PR·재판정 규칙을 적는다
문제: 매뉴얼은 백엔드와 종료 조건이 다르다는 것만 적고 무엇이
다른지 적지 않았다. 프론트는 멈출 조건을 채운 라운드의 Medium·Low를
고치고 멈추므로 그 마지막 수정은 확인 리뷰를 받지 않는데, 이 위험이
문서에 없다. 2026-11-05 사용자 지시 두 가지(수정 결과의 "고침"을
다음 리뷰에서 ID별로 재판정, 큰 라운드는 작은 PR로 나누고 소유자가
직접 merge)도 빠져 있다.

고른 방법: 09장 5.2절에 차이(마지막 수정의 확인 리뷰 여부)와, 그래서
마지막 수정도 01장 절차와 merge 판정을 그대로 거친다는 점을 적는다.
5.3절에 "고침은 확정이 아니다", 6절에 PR 크기 규칙(커밋 규칙 5.1절)을
더한다. 08장 결정 색인 O-12를 2026-11-05 소유자 결정 「각자 유지」
문장으로 바꾸고 O-15·O-16을 더한다. README M-7도 맞춘다.

위험·한계: 종료 조건을 통일할지는 정하지 않았다. 소유자 결정대로
각자 유지한다.

검증: 로컬 정적 대조. desktop 검사는 이 커밋을 보내 돌린다.
2026-11-05 22:20:34 +09:00

12 KiB

09. 작업 진행 방식

핵심

큰 개선 작업은 총괄 세션 하나와 하위 세션·서브에이전트 여럿으로 나눈다. 총괄은 맡기고, 모으고, 다시 확인하고, 멈출지 정한다. 하위 세션은 맡은 영역 하나를 끝까지 한다.

총괄(오케스트레이터)
  ├─ 리뷰 라운드: 게이트 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마다 자기 정본을 따른다. 두 기준을 하나로 맞추지 않는다(2026-11-05 소유자 결정 「각자 유지」, README 결정 M-7, 08장 표 O-12).

  • 백엔드와의 차이는 마지막 수정이 확인 리뷰를 받는가다. 백엔드는 리뷰 → 수정 → 확인 리뷰를 발견이 심각도와 상관없이 0이 될 때까지 돌아, 마지막 라운드에서 고친 Medium·Low도 확인 리뷰를 받는다. 프론트는 멈출 조건을 채운 라운드의 Medium·Low를 고치고 멈추므로, 그 마지막 수정은 다음 리뷰를 받지 않는다.
  • 그래서 마지막 수정이 새 결함을 만들면(부록 P-26) 리뷰가 아니라 그 수정의 RED·GREEN 테스트와 merge 게이트 14개만이 잡는다. 마지막 수정도 01장 2절 절차(특히 5단계 "템플릿 원래 상태 밖에서도 확인")와 07장 3절 merge 판정을 그대로 거친다.

5.3 남은 문제 0으로 보고한다

  • 리뷰 발견은 Low까지 고친다. 보고의 "남은 문제"는 0이어야 한다(사용자 지시).
  • 수정 결과를 보고할 때 「고침」은 확정이 아니다. 다음 리뷰가 ID별로 다시 판정한다(5.1절 3단계). 보고서에도 "다음 리뷰에서 재판정"이라고 적는다. 1103 조치의 「고침」 13건이 4라운드에서 「일부」로 정정됐다(2026-11-05 사용자 지시, 총괄 세션 전달).
  • 고칠 수 없는 것은 결정 대기로 남긴다. 이유, 선택지, 결정할 사람을 적는다(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절 머리말).
  6. 큰 라운드는 작은 PR로 나눈다. 라운드 전체를 PR 하나로 올리지 않는다. 자기완결적인 변경 하나(예: 영역 수정 브랜치 하나)를 PR 하나로 낸다. 크기는 대략 100줄이 적당하고 1,000줄이면 너무 크다. 리팩터링과 동작 변경은 PR을 나눈다. 기계적으로 만든 큰 변경은 크기 예외로 두고 만든 명령과 기준 커밋을 적는다(커밋 규칙 5.1절). 소유자가 PR을 직접 merge한다(2026-11-05 사용자 지시, 총괄 세션 전달). 직전 라운드는 발견·결정 24건을 Gitea PR 하나(4번, main 커밋 409d72e)로 올렸다.

공통 지시(모든 수정 세션의 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를 고치고 멈춘다. 못 고친 것은 결정 대기로 남긴다.