Files
clean-architecture-frontend…/CLAUDE.md
T
DongHyeonka e9d9c3694f docs: 리뷰 절차가 merge 단계 게이트 전부를 ci:gate로 돌린다
문제: 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
2026-11-05 22:33:03 +09:00

3.3 KiB

CLAUDE.md

개선 작업 기준

리뷰·결함 수정·리팩터링·성능 최적화·구조 변경·테스트 구조 개선은 docs/improvement/를 기준으로 한다. 작업 종류별 절차, 검증 위치와 merge 판정 방법, 결정 기록, 세션 분업, 반복 결함 패턴이 거기 있다. 리뷰 판정 규칙의 정본은 아래 「리뷰 기준」이고, 매뉴얼은 그것을 가리킨다.

리뷰 기준 (모든 리뷰에 적용)

이 repo를 리뷰할 때는 전체 리뷰든 모듈·PR·diff 리뷰든 docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md를 기준으로 한다.

  • 발견 사항은 가이드의 28개 관점 번호로 분류한다. 결함 하나는 항목 하나로 적고 관련 관점 번호를 모두 붙인다(0.3절). 같은 결함을 여러 번 세지 않는다.
  • 성격(확인된 결함 / 구조적 위험 / 미검증 / 개선 제안), 심각도(CriticalLow), 우선순위(P0P3), 통제 수준(M0M4), 증거(E0E4)를 따로 적는다(35절). 확인하지 못한 것은 M0가 아니라 미확인이다.
  • 발견 사항은 36.3절 양식, 최종 요약은 36.5절 양식, 관점별 판정은 36.2절 표를 쓴다.
  • README와 설계 문서는 주장이다. 근거는 현재 커밋의 코드·설정·실행 결과에서 찾는다(34.1절). 이전 리뷰의 실행 결과를 현재 증거로 재사용하지 않는다.
  • 리뷰에서는 코드를 고치지 않는다. 고치는 작업은 리뷰 문서를 근거로 별도로 진행한다.

이 repo의 리뷰 전제

  • 이 repo는 템플릿(reference implementation)이다. repo 안에 소비자가 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이지 죽은 코드가 아니다. 다만 갈라진 중복 복사본은 문제로 본다.
  • adapter 배럴(src/adapters/*/index.ts)이 공개 경계다.
  • adapter끼리 import할 수 있는 예외는 .dependency-cruiser.json의 kernel 예외(src/adapters/platform/ 폴더 전체, browser-file-storage/result.ts, cross-context-invalidation/index.ts)뿐이다. 새 파일 단위 예외를 제안하지 않는다.
  • 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다. SSR은 없다.

전체 리뷰 절차

  1. 기준 커밋과 가이드 0.1절 전제 표를 먼저 고정한다.
  2. 게이트를 직접 실행하고 결과를 기록한다. config/ci/gates.json의 merge 단계 gateIds 전부(지금 14개)를 workflow와 같은 env(CI=true, VITE_COMMIT_SHA, VITE_BUILD_ID, RELEASE_ID, CI_RUNNER_IMAGE)로 corepack pnpm ci:gate -- FE-GATE-0NN 하나씩 돌린다. documentation 단계의 verify:documentation(FE-GATE-017)은 따로 돌린다. 명령 목록을 여기 손으로 적지 않는다(방법은 docs/improvement/07-verification-gates.md 3절).
  3. 영역별로 서브에이전트를 병렬로 띄운다. 영역 분할은 가장 최근 docs/reviews/*-maturity-review/README.md의 영역 표를 재사용한다.
  4. 각 에이전트는 docs/reviews/<YYYY-MM-DD>-maturity-review/NN-<영역>.md에 결과를 쓴다.
  5. 오케스트레이터는 High 이상 발견을 코드에서 직접 재확인한 뒤 같은 폴더의 README.md에 범위(36.1), 28개 관점 판정표(36.2), 최종 요약(36.5), 발견 색인을 쓴다.