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

Closed
donghyeon.kang wants to merge 10 commits from docs/improvement-manual into main
10 Commits
Author SHA1 Message Date
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
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
DongHyeonka 1c063cbff8 docs: CLAUDE.md와 문서 색인이 개선 작업 매뉴얼을 가리킨다
문제: 새 매뉴얼을 아무 곳에서도 가리키지 않아 리뷰·수정 세션이 찾지
못한다. 문서 색인에 없으면 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에 보내
돌린다.
2026-11-05 22:15:44 +09:00
DongHyeonka 23e04f7383 docs(improvement): 다섯 라운드 리뷰의 반복 결함 패턴 49개를 모은다
문제: 같은 모양의 결함이 라운드마다 다른 영역에서 다시 나오지만,
리뷰를 시작할 때 훑어볼 목록이 없다. 지난 리뷰의 "반복되는 원인"
절은 라운드마다 따로 있다.

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

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

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
2026-11-05 22:15:44 +09:00
DongHyeonka 402fe12231 docs(improvement): 검증 위치·merge 판정 방법과 결정 색인을 적는다
문제: "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 검사는 연결 커밋 뒤.
2026-11-05 22:15:44 +09:00
DongHyeonka 40e3b2f814 docs(improvement): 테스트 구조와 성능 측정의 개선 기준을 적는다
문제: 테스트 결함(변이 생존, 템플릿 원래 상태만 봄, 브라우저 추정·
그리는 중인 화면에 기댐, 고정 경로·포트)이 라운드마다 반복됐다.
가끔 떨어지는 테스트를 "부하 탓"으로 닫았다가 테스트 결함으로
정정한 일이 두 번 있다. 성능 숫자는 측정 조건 없이 남아 비교할 수
없고, lab 게이트는 release 단계에만 있다.

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

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

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
2026-11-05 22:15:44 +09:00
DongHyeonka 05f0083538 docs(improvement): 폴더·모듈 구조와 코드 구조의 개선 기준을 적는다
문제: 구조를 바꿀 때 같이 고칠 정본(layers.md, .dependency-cruiser.json,
INVENTORY)과, 게이트가 막지 못해 다섯 라운드 반복된 코드 결함(실패
분류, 결과 불명 재전송, 손 사본, 지운 코드가 지키던 검사)을 막는
기준이 문서로 묶여 있지 않다.

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

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

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
2026-11-05 22:15:22 +09:00
DongHyeonka 01b4495214 docs(improvement): 이 repo의 결함 정의와 28개 관점 점검 위치를 적는다
문제: 가이드는 공용 일반론이라 이 repo에서 무엇을 결함으로 보고 어떤
등급을 줄지, 28개 관점마다 어디를 볼지 정해져 있지 않다. 라운드마다
같은 모양의 등급 조정을 다시 했다.

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

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

검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
2026-11-05 22:15:22 +09:00
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
DongHyeonka ed6fad9cb9 docs(improvement): 개선 작업 매뉴얼의 정본 표와 읽는 순서를 둔다
문제: 리뷰·수정·리팩터링·최적화를 할 때 기준으로 삼을 이 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에서
돌린다.
2026-11-05 22:15:22 +09:00