docs(improvement): 리뷰·수정·리팩터링의 기준이 되는 개선 작업 매뉴얼을 둔다 #6

Closed
donghyeon.kang wants to merge 10 commits from docs/improvement-manual into main
Owner

무엇을, 왜

리뷰·결함 수정·리팩터링·성능 최적화·구조 변경·테스트 구조 개선의 기준이 되는 이 repo 전용 매뉴얼을 docs/improvement/에 둔다.

  • 소유자 지시(2026-11-05): 개선 작업의 기준이 되는 매뉴얼이 없으면 매뉴얼부터 만든다.
  • 지금까지 기준이 흩어져 있었다. CLAUDE.md, 공용 리뷰 가이드(docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md), SPEC.md, config/ci/gates.json, 리뷰 README 곳곳, 세션 기록이다. 그래서 작업마다 다시 찾고, 이미 정한 것을 다시 물었다.
  • docs/manual/은 새 기능을 만드는 순서다. 독자가 달라서 따로 둔다.

담은 것(파일 11개):

  • README.md: 목적, 적용 범위, 정본 표(무엇의 정본이 어디인가), 읽는 순서, 결정 기록
  • 01 작업 종류별 절차, 02 리뷰 기준(이 repo의 결함 정의와 28개 관점 점검 위치)
  • 03 폴더·모듈 구조, 04 코드 구조, 05 테스트 구조, 06 성능 측정 기준
  • 07 검증과 게이트(무엇을 언제 어디서, merge 판정 방법), 08 결정과 기록(소유자 결정 색인), 09 작업 진행 방식(세션 분업, 리뷰 중 실행 방식, 반복 종료 조건)
  • 부록: 09241105 리뷰에서 두 번 이상 나온 결함 모양 49개(P-01P-49)

연결:

  • CLAUDE.md 맨 위에 "개선 작업 기준" 절을 더해 매뉴얼을 가리킨다.
  • docs/README.md §1에 improvement/ 링크를 더한다. 이 목록에 있어야 verify:documentation이 매뉴얼의 경로·script·게이트 ID를 검사한다.
  • 1105/12-03 (e9d9c36): CLAUDE.md 전체 리뷰 절차 2단계가 명령 11개를 손으로 적고 있었다. 이 목록으로는 merge 게이트 14개 중 7개(001, 008, 009, 011, 012, 013, 020)가 전혀 돌지 않는다. 그래서 "merge 단계 gateIds 전부를 workflow env로 ci:gate로 하나씩"으로 바꿨다. 2026-11-03 리뷰가 실제 CI에서 항상 실패하던 게이트 둘(1103/11-06, 12-09)을 놓친 경로다.

고른 방법과 버린 대안

  • 규칙을 다시 쓰지 않고 정본을 가리킨다. 매뉴얼과 정본이 다르면 정본이 맞다. 매뉴얼이 처음이자 유일한 기록인 것은 정본 표 마지막 행에 따로 적었다.
  • 장 번호와 파일 이름을 짝 백엔드 매뉴얼과 맞췄다. 두 repo를 오가는 작업자가 같은 장을 찾는다. 반복 종료 조건은 repo마다 다르다(소유자 결정 "각자 유지", 08장 O-12).
  • 위치: docs/improvement/.
    • 버린 대안 1: docs/reviews/ 안에 두기. 다운스트림이 지우는 작업 이력과 섞인다.
    • 버린 대안 2: docs/manual/ 뒤에 장 더하기. 독자가 다르다.
  • 검사 범위: docs/README.md §1 링크로 넣었다.
    • 버린 대안 1: §3 작업 이력에 두기. 검사 밖이다.
    • 버린 대안 2: 검사 스크립트에 목록 추가. 문서만 바꾸는 작업 범위를 넘는다.
  • 리뷰 절차 2단계: 목록을 손으로 적지 않고 gates.json을 가리킨다. 버린 대안은 빠진 명령을 목록에 더 적는 것이다. 다음에 게이트가 바뀌면 다시 갈라진다.

위험과 영향

  • 코드·테스트·설정은 바꾸지 않았다. 바뀐 것은 문서 13개 파일이다.
  • 정본과 매뉴얼 설명이 맞는지는 기계가 검사하지 않는다. verify:documentation은 경로·script·게이트 ID가 있는지만 본다.
  • 4라운드 리뷰 경로(docs/reviews/2026-11-05-maturity-review/)는 백틱 없이 적었다. 아직 main에 없어서다(PR #5). PR #5가 merge되면 백틱을 붙여 검사 범위에 넣는다.
  • 리뷰 시작 비용이 커진다. 2단계가 merge 게이트 14개를 모두 돌리므로 FE-GATE-020만 약 20분이다. 실행 위치와 잠금은 매뉴얼 07장 7절을 따른다.
  • CLAUDE.md에 4줄이 더해져 지난 리뷰 문서가 적은 CLAUDE.md 줄 번호가 4줄씩 밀린다. 리뷰 기록은 고치지 않는다.
  • 루트 AGENTS.md는 추적하지 않는 사본이라 이 변경을 받지 않는다(08장 M-10).
  • 부록의 한계: 1103 이전 라운드는 README와 High 영역 문서만 읽었다. 그래서 Medium·Low 패턴의 근거는 색인 행에서 왔다. "막는 기준 없음"으로 남은 행이 있다.

검증

desktop에서 브랜치 끝 e9d9c36을 검사했다.

  • verify:documentation: 옆에 백엔드 checkout이 없을 때와 있을 때 모두 PASS_SCOPED다. 매뉴얼 11개 파일의 문제는 0건이다.
  • 문서 unit 테스트 22개 통과
  • 로컬 정적 대조: 매뉴얼의 백틱 경로·script·FE-GATE ID 문제 0건
  • 커밋 10개, 제목은 모두 72자 이하, AI 꼬리말 0건

실행하지 않은 것: merge 게이트 14개. 문서만 바꾼 PR이라서다. verify:documentation은 FE-GATE-005·020 안에서도 돈다.

리뷰어가 볼 곳

  • docs/improvement/README.md의 정본 표. 무엇을 이 매뉴얼이 새로 정하는지가 마지막 행에 있다.
  • docs/improvement/09-working-method.md: 세션 분업, 리뷰 중 실행 방식, 반복 종료 조건
  • docs/improvement/07-verification-gates.md: 무거운 실행 위치(desktop)와 merge 판정 방법
  • CLAUDE.md의 두 변경: "개선 작업 기준" 절, 전체 리뷰 절차 2단계

관련

  • 짝 백엔드의 같은 매뉴얼: clean-architecture-backend-template의 docs/improvement/(별도 세션이 작성 중)
  • PR #5: 2026-11-05 리뷰 기록과 P1 수정. 12-03은 이 PR이 고친다
  • docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md, CLAUDE.md 「리뷰 기준」
## 무엇을, 왜 리뷰·결함 수정·리팩터링·성능 최적화·구조 변경·테스트 구조 개선의 기준이 되는 이 repo 전용 매뉴얼을 `docs/improvement/`에 둔다. - 소유자 지시(2026-11-05): 개선 작업의 기준이 되는 매뉴얼이 없으면 매뉴얼부터 만든다. - 지금까지 기준이 흩어져 있었다. `CLAUDE.md`, 공용 리뷰 가이드(`docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`), `SPEC.md`, `config/ci/gates.json`, 리뷰 README 곳곳, 세션 기록이다. 그래서 작업마다 다시 찾고, 이미 정한 것을 다시 물었다. - `docs/manual/`은 새 기능을 만드는 순서다. 독자가 달라서 따로 둔다. 담은 것(파일 11개): - `README.md`: 목적, 적용 범위, 정본 표(무엇의 정본이 어디인가), 읽는 순서, 결정 기록 - `01` 작업 종류별 절차, `02` 리뷰 기준(이 repo의 결함 정의와 28개 관점 점검 위치) - `03` 폴더·모듈 구조, `04` 코드 구조, `05` 테스트 구조, `06` 성능 측정 기준 - `07` 검증과 게이트(무엇을 언제 어디서, merge 판정 방법), `08` 결정과 기록(소유자 결정 색인), `09` 작업 진행 방식(세션 분업, 리뷰 중 실행 방식, 반복 종료 조건) - 부록: 0924~1105 리뷰에서 두 번 이상 나온 결함 모양 49개(P-01~P-49) 연결: - `CLAUDE.md` 맨 위에 "개선 작업 기준" 절을 더해 매뉴얼을 가리킨다. - `docs/README.md` §1에 `improvement/` 링크를 더한다. 이 목록에 있어야 `verify:documentation`이 매뉴얼의 경로·script·게이트 ID를 검사한다. - **1105/12-03** (`e9d9c36`): `CLAUDE.md` 전체 리뷰 절차 2단계가 명령 11개를 손으로 적고 있었다. 이 목록으로는 merge 게이트 14개 중 7개(001, 008, 009, 011, 012, 013, 020)가 전혀 돌지 않는다. 그래서 "merge 단계 `gateIds` 전부를 workflow env로 `ci:gate`로 하나씩"으로 바꿨다. 2026-11-03 리뷰가 실제 CI에서 항상 실패하던 게이트 둘(1103/11-06, 12-09)을 놓친 경로다. ## 고른 방법과 버린 대안 - **규칙을 다시 쓰지 않고 정본을 가리킨다.** 매뉴얼과 정본이 다르면 정본이 맞다. 매뉴얼이 처음이자 유일한 기록인 것은 정본 표 마지막 행에 따로 적었다. - **장 번호와 파일 이름을 짝 백엔드 매뉴얼과 맞췄다.** 두 repo를 오가는 작업자가 같은 장을 찾는다. 반복 종료 조건은 repo마다 다르다(소유자 결정 "각자 유지", 08장 O-12). - **위치:** `docs/improvement/`. - 버린 대안 1: `docs/reviews/` 안에 두기. 다운스트림이 지우는 작업 이력과 섞인다. - 버린 대안 2: `docs/manual/` 뒤에 장 더하기. 독자가 다르다. - **검사 범위:** `docs/README.md` §1 링크로 넣었다. - 버린 대안 1: §3 작업 이력에 두기. 검사 밖이다. - 버린 대안 2: 검사 스크립트에 목록 추가. 문서만 바꾸는 작업 범위를 넘는다. - **리뷰 절차 2단계:** 목록을 손으로 적지 않고 gates.json을 가리킨다. 버린 대안은 빠진 명령을 목록에 더 적는 것이다. 다음에 게이트가 바뀌면 다시 갈라진다. ## 위험과 영향 - **코드·테스트·설정은 바꾸지 않았다.** 바뀐 것은 문서 13개 파일이다. - **정본과 매뉴얼 설명이 맞는지는 기계가 검사하지 않는다.** `verify:documentation`은 경로·script·게이트 ID가 있는지만 본다. - **4라운드 리뷰 경로(`docs/reviews/2026-11-05-maturity-review/`)는 백틱 없이 적었다.** 아직 main에 없어서다(PR #5). PR #5가 merge되면 백틱을 붙여 검사 범위에 넣는다. - **리뷰 시작 비용이 커진다.** 2단계가 merge 게이트 14개를 모두 돌리므로 FE-GATE-020만 약 20분이다. 실행 위치와 잠금은 매뉴얼 07장 7절을 따른다. - **`CLAUDE.md`에 4줄이 더해져** 지난 리뷰 문서가 적은 `CLAUDE.md` 줄 번호가 4줄씩 밀린다. 리뷰 기록은 고치지 않는다. - **루트 `AGENTS.md`는 추적하지 않는 사본이라** 이 변경을 받지 않는다(08장 M-10). - **부록의 한계:** 1103 이전 라운드는 README와 High 영역 문서만 읽었다. 그래서 Medium·Low 패턴의 근거는 색인 행에서 왔다. "막는 기준 없음"으로 남은 행이 있다. ## 검증 desktop에서 브랜치 끝 `e9d9c36`을 검사했다. - `verify:documentation`: 옆에 백엔드 checkout이 없을 때와 있을 때 모두 `PASS_SCOPED`다. 매뉴얼 11개 파일의 문제는 0건이다. - 문서 unit 테스트 22개 통과 - 로컬 정적 대조: 매뉴얼의 백틱 경로·script·FE-GATE ID 문제 0건 - 커밋 10개, 제목은 모두 72자 이하, AI 꼬리말 0건 **실행하지 않은 것:** merge 게이트 14개. 문서만 바꾼 PR이라서다. `verify:documentation`은 FE-GATE-005·020 안에서도 돈다. ## 리뷰어가 볼 곳 - `docs/improvement/README.md`의 정본 표. 무엇을 이 매뉴얼이 새로 정하는지가 마지막 행에 있다. - `docs/improvement/09-working-method.md`: 세션 분업, 리뷰 중 실행 방식, 반복 종료 조건 - `docs/improvement/07-verification-gates.md`: 무거운 실행 위치(desktop)와 merge 판정 방법 - `CLAUDE.md`의 두 변경: "개선 작업 기준" 절, 전체 리뷰 절차 2단계 ## 관련 - 짝 백엔드의 같은 매뉴얼: `clean-architecture-backend-template`의 `docs/improvement/`(별도 세션이 작성 중) - PR #5: 2026-11-05 리뷰 기록과 P1 수정. 12-03은 이 PR이 고친다 - `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, `CLAUDE.md` 「리뷰 기준」
donghyeon.kang added 10 commits 2026-11-05 13:57:12 +00:00
문제: 리뷰·수정·리팩터링·최적화를 할 때 기준으로 삼을 이 repo 전용
문서가 없다. 기준이 CLAUDE.md, 리뷰 가이드, SPEC.md, gates.json,
리뷰 README 곳곳과 세션 기록에 흩어져 있어, 작업마다 다시 찾고
이미 정한 것을 다시 묻는다.

고른 방법: docs/improvement/README.md에 목적, 적용 범위, 정본 표
(무엇의 정본이 어디인가), 읽는 순서, 근거 표기, 결정 기록 M-1~M-10을
둔다. 규칙을 다시 쓰지 않고 정본을 가리킨다. 장 번호·파일 이름은
짝 백엔드 매뉴얼과 같게 맞췄다. 버린 대안: docs/reviews/ 안에 두기
(복사본이 지우는 작업 이력과 섞인다), docs/manual/ 뒤에 장 추가
(독자가 다르다).

위험·한계: 정본과 설명이 맞는지는 검사하지 않는다. 4라운드 리뷰는
아직 main에 없어 그 경로를 백틱 없이 적었다. 합쳐지면 바꿔야 한다.

검증: 로컬 정적 대조로 백틱 경로·script·FE-GATE ID가 있음을 확인했다.
verify:documentation과 문서 unit 테스트는 연결 커밋 뒤 desktop에서
돌린다.
문제: 리뷰·결함 수정·리팩터링·성능·구조·테스트 개선마다 시작 조건과
완료 기준이 어디에도 한곳에 없다. 총괄 세션 운영, 리뷰 중 실행 방식,
수정→리뷰 반복의 멈춤 조건은 사용자 지시와 리뷰 README에만 있다.

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

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

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
문제: 가이드는 공용 일반론이라 이 repo에서 무엇을 결함으로 보고 어떤
등급을 줄지, 28개 관점마다 어디를 볼지 정해져 있지 않다. 라운드마다
같은 모양의 등급 조정을 다시 했다.

고른 방법: 이 repo가 스스로 한 약속(지원 범위, 현재 계약, 게이트,
생성 명령, 제거 가능성, 짝 계약)으로 결함을 정의하고, 지난 라운드의
등급 판정 예(게이트가 틀린 답을 내면 Medium·P1 등), 증거 규칙, 28개
관점별 볼 곳·검사·대표 발견, 지난 발견 재판정 방법, README·영역
문서 절 순서를 적는다. 심각도 체계는 가이드 35.2·35.3 하나만 쓴다.

위험·한계: 관점별 "볼 곳"은 지난 리뷰의 판정표에서 뽑은 것이라
빠진 곳이 있을 수 있다.

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
문제: 구조를 바꿀 때 같이 고칠 정본(layers.md, .dependency-cruiser.json,
INVENTORY)과, 게이트가 막지 못해 다섯 라운드 반복된 코드 결함(실패
분류, 결과 불명 재전송, 손 사본, 지운 코드가 지키던 검사)을 막는
기준이 문서로 묶여 있지 않다.

고른 방법: 03장에 정본 표, 이 repo의 고정 전제(확장 지점 유지,
갈라진 복사본 합치기, 배럴 경계, kernel 예외 셋), 바꿀 때 같이
고칠 것, 문서 위치, 제거 가능성을 적는다. 04장에 판정 규칙 한 곳,
실패 드러내기, 같은 사실 한 곳, 지우거나 바꿀 때, 설정·환경,
동시성, 확장 지점, 수정이 새로 가정하는 것을 적고 부록 패턴을
가리킨다. 새 파일 단위 kernel 예외는 제안하지 않는다.

위험·한계: "모든 대기에는 끝나는 조건이 있다"는 지난 완료 기준을
일반화한 [제안]이다.

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
문제: 테스트 결함(변이 생존, 템플릿 원래 상태만 봄, 브라우저 추정·
그리는 중인 화면에 기댐, 고정 경로·포트)이 라운드마다 반복됐다.
가끔 떨어지는 테스트를 "부하 탓"으로 닫았다가 테스트 결함으로
정정한 일이 두 번 있다. 성능 숫자는 측정 조건 없이 남아 비교할 수
없고, lab 게이트는 release 단계에만 있다.

고른 방법: 05장에 테스트 위치 기준(taxonomy 가리킴), 검출력 확인
(RED·변이·원래 상태 밖 입력·단언 범위), 환경 의존 표, flaky 금지와
조사 절차(반복 실행→실패 기록→결정적 재현→수정→변이), 실행 비용을
적는다. 06장에 세 측정 맥락, 언제 재나, 측정 조건 표, 예산 사이 균형,
숫자를 고칠 때를 적는다. 참조 기능과 함께 지워지는 기록 파일과 측정
스크립트는 이름을 쓰지 않고 그것을 소유한 문서 절을 가리킨다.

위험·한계: 실행 격리(빈 포트·실행별 출력)와 기능 라우트 첫 진입
측정은 [제안]이다. 실행 격리는 결정 대기(1105/12-04)다.

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
문제: "merge 가능" 판정을 고른 스크립트 목록이나 CI=true 없는 env로
해서 실제 러너에서 항상 실패하는 게이트를 놓친 적이 있다. 테스트를
어디서 돌리는지(desktop, 잠금, 되돌림)는 사용자 지시로만 있다. 소유자
결정이 리뷰 README·SPEC.md·ADR·세션 기록에 흩어져 다시 묻게 된다.

고른 방법: 07장에 때별로 돌릴 것, ci:gate로 merge 단계 14개를
workflow env로 돌리는 방법, 가끔 떨어지는 게이트의 기록법, desktop의
FE-GATE-013 처리, CI env에서만 나는 실패, PASS 뒤 실패, 문서 검사의
범위와 도는 곳, 소유자 환경을 적는다. 08장에 결정을 적는 곳, 다시
묻지 않는 규칙, 작업 방식 결정 O-1~O-14와 기술 결정 묶음의 색인,
결정 대기 형식과 지금 열린 D1~D6, 커밋·PR에서 이 repo가 덧붙이는
것을 적는다. 결정 원문은 옮기지 않는다.

위험·한계: 열린 결정 표는 4라운드 시점이다. 다음 라운드가 닫으면
고쳐야 한다. CLAUDE.md 27줄의 리뷰 게이트 목록이 merge 단계와 다르다는
발견(1105/12-03)은 고치지 않고 07장이 merge 단계를 함께 돌리라고만
적는다.

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
문제: 같은 모양의 결함이 라운드마다 다른 영역에서 다시 나오지만,
리뷰를 시작할 때 훑어볼 목록이 없다. 지난 리뷰의 "반복되는 원인"
절은 라운드마다 따로 있다.

고른 방법: 0924 src 리뷰와 0925·0929·1101·1103·1105 성숙도 리뷰에서
두 번 이상 나온 모양을 P-01~P-49로 묶는다. 행마다 모양, 대표 발견
ID, 막는 기준(이 매뉴얼의 장), 관점을 적는다. 한 번만 나온 High
(0929/09-01)는 따로 적는다. 번호는 다시 매기지 않는다.

위험·한계: 1103 이전 라운드는 README와 High 영역 문서만 읽어
Medium·Low의 근거는 색인 행에서 왔다. 막는 기준이 "없음"인 행이
남아 있다.

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
문제: 새 매뉴얼을 아무 곳에서도 가리키지 않아 리뷰·수정 세션이 찾지
못한다. 문서 색인에 없으면 verify:documentation이 매뉴얼의 경로·
script·게이트 ID를 검사하지 않는다.

고른 방법: CLAUDE.md 맨 위에 "개선 작업 기준" 절을 더해 매뉴얼을
가리킨다. 리뷰 기준 절은 그대로 둔다. docs/README.md §1에
improvement/ 폴더 링크를 더해 검사 범위에 넣는다. 같은 검사가
FE-GATE-005의 문서 테스트와 FE-GATE-020의 기능 추가·제거 드릴
안에서도 돈다. 버린 대안: §3 작업 이력에 두기(검사 밖), 검사
스크립트에 목록 추가(문서만 바꾸는 작업).

위험·한계: CLAUDE.md에 4줄이 더해져 리뷰 문서가 적은 CLAUDE.md 줄
번호가 4줄씩 밀린다(리뷰 기록은 고치지 않는다). main checkout의
추적하지 않는 AGENTS.md는 CLAUDE.md 사본인데 이 변경을 받지 않는다.

검증: 로컬 정적 대조로 경로·script·FE-GATE ID가 있음을 확인했다.
verify:documentation과 문서 unit 테스트는 이 커밋을 desktop에 보내
돌린다.
문제: 매뉴얼은 백엔드와 종료 조건이 다르다는 것만 적고 무엇이
다른지 적지 않았다. 프론트는 멈출 조건을 채운 라운드의 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 검사는 이 커밋을 보내 돌린다.
문제: CLAUDE.md 전체 리뷰 절차 2단계가 돌릴 명령 11개를 손으로
적는다. 이 목록은 merge 단계 명령 87개 중 10개만 돌리고, merge
게이트 14개 중 7개(001, 008, 009, 011, 012, 013, 020)는 전혀 돌지
않는다. 명령을 직접 부르면 ci:gate가 하는 로그·증거 검사, 음성
fixture의 기대 실패, workflow env도 빠진다. 2026-11-03 리뷰가 실제
CI에서 항상 실패하던 merge 게이트 둘(1103/11-06, 12-09)을 놓친 경로다.

고른 방법: 2단계를 "config/ci/gates.json의 merge 단계 gateIds 전부를
workflow env로 ci:gate 하나씩, verify:documentation은 따로"로 바꾸고
목록을 손으로 적지 않는다. 자세한 방법은 개선 매뉴얼 07장 3절을
가리킨다. 매뉴얼 01·07장과 부록 P-01에서 옛 목록을 전제로 쓴 문장을
같이 고친다. 줄 수는 그대로라 매뉴얼의 CLAUDE.md 줄 참조는 맞다.
버린 대안: 목록에 빠진 명령을 더 적기(다음에 게이트가 바뀌면 다시
갈라진다). merge 단계를 읽는 명령(ci:gate:stage merge)은 이 작업
범위 밖이라 더하지 않았다.

위험·한계: 리뷰 시작 비용이 커진다(FE-GATE-020만 약 20분). 실행
위치와 잠금은 매뉴얼 07장 7절을 따른다. 추적하지 않는 AGENTS.md는
이 변경을 받지 않는다.

검증: 로컬 정적 대조(매뉴얼의 경로·script·FE-GATE ID 문제 0건).
desktop의 verify:documentation과 문서 unit 테스트는 이 커밋을 보내
돌린다.

Refs: 1105/12-03
donghyeon.kang closed this pull request 2026-11-11 11:25:57 +00:00

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-frontend-template#6