From d1b24567bf4d10a55597f86c1a3b62efdd0271b1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:20:34 +0900 Subject: [PATCH] =?UTF-8?q?docs(improvement):=20=EC=A2=85=EB=A3=8C=20?= =?UTF-8?q?=EC=A1=B0=EA=B1=B4=EC=9D=98=20=EB=B0=B1=EC=97=94=EB=93=9C=20?= =?UTF-8?q?=EC=B0=A8=EC=9D=B4=EC=99=80=20=EC=9E=91=EC=9D=80=20PR=C2=B7?= =?UTF-8?q?=EC=9E=AC=ED=8C=90=EC=A0=95=20=EA=B7=9C=EC=B9=99=EC=9D=84=20?= =?UTF-8?q?=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 매뉴얼은 백엔드와 종료 조건이 다르다는 것만 적고 무엇이 다른지 적지 않았다. 프론트는 멈출 조건을 채운 라운드의 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 검사는 이 커밋을 보내 돌린다. --- docs/improvement/08-decisions-records.md | 6 +++++- docs/improvement/09-working-method.md | 19 +++++++++++++++++-- docs/improvement/README.md | 2 +- 3 files changed, 23 insertions(+), 4 deletions(-) diff --git a/docs/improvement/08-decisions-records.md b/docs/improvement/08-decisions-records.md index d9b224d6..3cbfc492 100644 --- a/docs/improvement/08-decisions-records.md +++ b/docs/improvement/08-decisions-records.md @@ -60,9 +60,11 @@ | O-9 | 2026-11-04 | 수정 → 리뷰를 반복한다. 새 High 0·새 P1 0·merge 게이트 14개 통과면 그 라운드의 Medium·Low를 고치고 멈춘다. 세 라운드를 더 돌아도 닿지 않으면 멈추고 이유를 보고한다 | repo 밖 | 09장 5절 | | O-10 | 2026-11-05 | 테스트·게이트는 노트북에서 돌리지 않고 desktop checkout에서 돌린다 | repo 밖 | 07장 7절 | | O-11 | 2026-11-05 | 리뷰 중 실행은 게이트를 한 번 돌리고 산출물을 함께 읽는다. 추가 실험은 목록으로 모아 같은 명령은 한 번만, 실험마다 작업 폴더를 되돌리며 일괄로. 작업 폴더 복제본을 늘려 해결하지 않는다 | 1105 README 11.4절 | 09장 4절 | -| O-12 | 2026-11-05 | 멈춤 기준은 repo마다 자기 정본을 따른다(「각자 유지」) | repo 밖(백엔드 세션 전달) | 09장 5.2절 | +| O-12 | 2026-11-05 | 백엔드와 다른 종료 조건을 각자 유지한다(「각자 유지」). 백엔드는 발견 0까지 확인 리뷰를 반복하고, 프론트는 O-9대로 한다. 차이는 마지막 라운드의 Medium·Low 수정이 확인 리뷰를 받는가다 | repo 밖(백엔드 총괄 세션 전달) | 09장 5.2절 | | O-13 | 상시 | 짝 백엔드 repo는 읽기만 한다. stage·commit·push하지 않는다 | 1103 README 14.2절 D1 「이유」 | 09장 1절 | | O-14 | 상시 | 리뷰에서는 코드를 고치지 않는다 | `CLAUDE.md` 15줄 | 01장 1절 | +| O-15 | 2026-11-05 | 수정 결과의 「고침」을 그대로 믿지 않는다. 다음 리뷰에서 ID별로 다시 판정한다 | repo 밖(프론트 총괄 세션 전달). 근거 사례는 1105 README 3.1절 | 09장 5.1·5.3절 | +| O-16 | 2026-11-05 | 큰 라운드는 작은 PR로 나눈다(커밋 규칙 5.1절). 소유자가 PR을 직접 merge한다 | repo 밖(프론트 총괄 세션 전달) | 09장 6절, 이 장 6절 | ### 4.2 기술 결정 (리뷰 라운드) @@ -115,6 +117,8 @@ 가정하는 것을 적는다(01장 2절). - **AI 꼬리말 금지:** 4.1절 O-4. - **push·PR:** 수정 세션은 하지 않는다. 총괄이나 리뷰를 맡긴 세션이 한다(09장 6절). +- **PR 크기:** 자기완결적인 변경 하나에 PR 하나. 라운드 전체를 PR 하나로 올리지 않는다(커밋 규칙 5.1절, 표 O-16). + PR 본문은 커밋 규칙 5.3절의 여섯 칸을 쓰고, 「위험과 영향」과 「검증」은 비우지 않는다. merge는 소유자가 한다. ## 지금 이해하면 되는 것 diff --git a/docs/improvement/09-working-method.md b/docs/improvement/09-working-method.md index 53c116ee..f6663664 100644 --- a/docs/improvement/09-working-method.md +++ b/docs/improvement/09-working-method.md @@ -91,12 +91,22 @@ 조건을 채워도 바로 끝내지 않는다. **그 라운드의 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). +멈춤 기준은 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절 형식). "나중에", "범위 밖" 같은 이유 없는 이월은 남기지 않는다. - 개선 제안(결함이 아닌 것)도 열린 채 두지 않는다. 받아서 하거나, 하지 않는 이유를 결정으로 남긴다. @@ -118,6 +128,11 @@ P1이 3건이고 FE-GATE-013이 desktop에서 실패해 조건을 채우지 못 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절 셋째 줄). diff --git a/docs/improvement/README.md b/docs/improvement/README.md index 3b3649c8..b63859ec 100644 --- a/docs/improvement/README.md +++ b/docs/improvement/README.md @@ -130,7 +130,7 @@ | M-4 | 복사 뒤 지워도 되는 문서 목록에 넣지 않는다 | 복사한 프로젝트도 리뷰·수정·최적화를 한다. 소유자 환경에 묶인 규칙은 07장 7절과 09장 7절 「소유자 환경」에만 두어, 복사본은 그 두 절만 바꾸면 된다 | 루트 `README.md` 삭제 목록에 추가 | | M-5 | 심각도 체계는 가이드 35.2절(Critical~Low)과 35.3절(P0~P3) 하나만 쓴다 | 이 repo의 다섯 라운드가 모두 이 체계로 적혔다. 백엔드는 확인 리뷰에 Critical/Important/Minor를 더 쓰지만, 이 repo에는 그 이력이 없다. 소유자 지시의 "Minor"는 Low로 읽는다(09장 5절) | 백엔드처럼 두 체계 | | M-6 | 08장의 결정 표는 색인이다. 한 줄 요약과 출처만 둔다 | 결정 원문을 옮겨 쓰면 갈라진 복사본이 된다(부록 P-14) | 결정 원문 이동 | -| M-7 | 반복 종료 조건은 소유자 문장 그대로 쓴다(09장 5.2절) | 2026-11-04 사용자 결정의 문장이다. 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 2026-11-05 소유자 결정 「각자 유지」가 repo마다 자기 기준을 따르고 하나로 맞추지 않게 정했다 | 백엔드 문장으로 통일 | +| M-7 | 반복 종료 조건은 소유자 문장 그대로 쓴다(09장 5.2절) | 2026-11-04 사용자 결정의 문장이다. 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 차이는 마지막 라운드의 Medium·Low 수정이 확인 리뷰를 받는가다(프론트는 받지 않는다). 2026-11-05 소유자 결정 「각자 유지」가 두 기준을 각자 유지하게 정했다(08장 표 O-12) | 백엔드 문장으로 통일 | | M-8 | repo 밖 문서(커밋 규칙, 백엔드 매뉴얼)는 링크 대신 평문이나 코드 표기 | `verify:documentation`은 repo 밖 링크를 옆 checkout에서 찾는다. 옆 checkout이 없거나 다른 커밋이면 결과가 기계마다 달라진다(1105/12-02) | 상대 링크 | | M-9 | "Low도 고친다", "총괄은 하위 세션에 맡긴다", "리뷰 중 실행은 한 번 돌리고 함께 읽는다"는 2026-11-03~05 사용자 지시다. 09장이 이 규칙들의 repo 안 정본이 된다 | 규칙이 세션 기록과 리뷰 README 곳곳에만 있었다 | | | M-10 | 루트 `AGENTS.md`는 건드리지 않는다 | main checkout에 추적하지 않는 파일로 있고(`git ls-files AGENTS.md`가 비어 있다) 내용은 `CLAUDE.md`와 같다. 추적 대상이 아니라 이 작업의 범위 밖이다 | `AGENTS.md`도 고치기 |