Files
clean-architecture-frontend…/docs/improvement/09-working-method.md
T
DongHyeonka 44961d7561 docs(improvement): 작업 종류별 절차와 세션 분업·반복 종료 조건을 적는다
문제: 리뷰·결함 수정·리팩터링·성능·구조·테스트 개선마다 시작 조건과
완료 기준이 어디에도 한곳에 없다. 총괄 세션 운영, 리뷰 중 실행 방식,
수정→리뷰 반복의 멈춤 조건은 사용자 지시와 리뷰 README에만 있다.

고른 방법: 01장에 여섯 작업의 시작 조건·단계·산출물·완료 기준을,
09장에 역할, brief, 리뷰 라운드 운영, "게이트는 한 번 돌리고 함께
읽는다", 멈춤 조건(새 High 0·새 P1 0·merge 14개 통과 뒤 그 라운드
Medium·Low 수정), 수정 라운드 운영, 총괄이 자주 한 실수를 적는다.
소유자 환경에 묶인 것은 09장 7절에만 둔다.

위험·한계: 스킬 기록 규칙과 대기 종료 조건 일반화는 [제안]으로
표시했다. 멈춤 기준의 3라운드 상한은 그동안 repo 밖 메모에만 있었다.

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
2026-11-05 22:15:22 +09:00

11 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마다 자기 정본을 따른다. 백엔드는 "발견 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를 고치고 멈춘다. 못 고친 것은 결정 대기로 남긴다.