From ee5e19f47f6a6668a475b109cf83bf114fcc691a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 16:58:48 +0900 Subject: [PATCH] =?UTF-8?q?docs(manual):=20SPEC.md=EC=9D=98=20=EA=B3=B5?= =?UTF-8?q?=ED=86=B5=20=EC=99=84=EB=A3=8C=20=EA=B8=B0=EC=A4=80=EC=9D=84=20?= =?UTF-8?q?=EB=A7=A4=EB=89=B4=EC=96=BC=EC=9D=98=20=EC=99=84=EB=A3=8C=20?= =?UTF-8?q?=EA=B8=B0=EC=A4=80=EC=9C=BC=EB=A1=9C=20=EC=98=AE=EA=B8=B4?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 2026-09-25 리뷰 수정 라운드의 요구사항 SPEC.md는 라운드가 0.2.0으로 끝난 기록인데, 그 안의 「공통 완료 기준」(RED→GREEN, 변이 확인, 게이트, INVENTORY, kernel 위치, 포트 추가만, 커밋 하나, 문서 주장의 코드 위치)은 지금도 쓰는 규칙이다. 기록으로 옮기면 규칙이 지울 수 있는 이력 안에만 남는다(소유자 결정 D5, 2026-11-07). 고른 방법: docs/manual/reference/done-criteria.md로 옮기고 매뉴얼 README 표에 더한다. 게이트 여덟 개를 적은 원문 3·4번은 매뉴얼 규칙 (원칙 8, 목록을 복사하지 않음)에 맞춰 정본 config/ci/gates.json과 `ci:gate`를 가리키게 바꿨다. 작업 매뉴얼(docs/work/)은 하네스 세션이 만드는 중이라 이 변경은 개발 매뉴얼에 둔다. 위험: 하네스 세션이 docs/work/에 같은 기준을 두면 둘 중 하나를 가리키게 정리해야 한다. 검증: 문서만 바뀐다. 경로는 뒤의 verify:documentation 실행에서 본다. --- docs/manual/README.md | 3 ++- docs/manual/reference/done-criteria.md | 31 ++++++++++++++++++++++++++ 2 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 docs/manual/reference/done-criteria.md diff --git a/docs/manual/README.md b/docs/manual/README.md index 697d181b..9f345166 100644 --- a/docs/manual/README.md +++ b/docs/manual/README.md @@ -22,7 +22,7 @@ README (이 문서) → 02 결정표 (단계 중 "무엇을 고를지" 막힐 때) → 03 기능 폴더 밖 파일 (폴더 밖을 고쳐야 할 때) → 04 짝 백엔드에 처음 붙이기 (로그인이 필요한 API를 처음 부를 때) - → reference/ (명령 인자, 전역 ID, 패턴, 오류 메시지를 찾아볼 때) + → reference/ (명령 인자, 전역 ID, 패턴, 오류 메시지, 완료 기준을 찾아볼 때) ``` | 문서 | 내용 | @@ -35,6 +35,7 @@ README (이 문서) | [`reference/global-ids.md`](reference/global-ids.md) | 전역 ID 종류, 생성 명령이 만드는 값, 유일성 검사 | | [`reference/patterns.md`](reference/patterns.md) | 기능 개발 패턴과 예제 위치. 예제가 없는 패턴은 "없음" | | [`reference/errors.md`](reference/errors.md) | 생성·조립·레지스트리 검사의 실패 메시지와 고칠 파일 | +| [`reference/done-criteria.md`](reference/done-criteria.md) | 기능 추가나 수정을 끝났다고 하기 전에 맞춰 보는 완료 기준(테스트, 게이트, 구조, 커밋) | ## 자주 나오는 말 diff --git a/docs/manual/reference/done-criteria.md b/docs/manual/reference/done-criteria.md new file mode 100644 index 00000000..c3cf6463 --- /dev/null +++ b/docs/manual/reference/done-criteria.md @@ -0,0 +1,31 @@ +# 완료 기준 + +기능을 더하거나 결함·리뷰 발견을 고친 변경을 "끝났다"고 하기 전에 맞춰 보는 기준이다. +2026-09-25 리뷰 수정 라운드의 공통 완료 기준을 그 라운드 밖에서도 쓰도록 옮겼다. +옮기기 전 원문은 그 라운드의 요구사항(`docs/history/plans/2026-09-25-review-fix-round/SPEC.md`)에 있다. +게이트 목록은 여기에 적지 않고 정본을 가리킨다(원칙 8). + +## 테스트 + +1. 동작을 바꾸는 변경은 재현 테스트가 먼저 실패하고(RED), 고친 뒤 통과한다(GREEN). + - 브라우저 없이 재현할 수 없는 조건은 fake나 fixture로 만든다. + - 브라우저에서만 드러나는 동작이면 Playwright spec을 하나 더한다. +2. 테스트가 결함을 잡지 못한 것(변이가 살아남음)이 문제였으면, 그 변이를 다시 넣었을 때 새 테스트가 실패하는지까지 본다. + +## 게이트 + +3. 변경마다 merge 단계 게이트가 모두 통과한다. + - 목록과 각 게이트가 부르는 명령은 `config/ci/gates.json`이 정본이다. + - 로컬에서는 `corepack pnpm ci:gate -- <게이트 ID>`로 하나씩 돌린다. 돌리는 법은 루트 `README.md`의 「검증」 절에 있다. +4. 여러 변경을 합칠 때(병렬 작업을 통합할 때)는 3에 더해 `corepack pnpm build`와 `corepack pnpm test:sample-removal`도 돌린다. + +## 구조와 계약 + +5. `src/adapters/` 아래 파일을 더하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 같은 변경에서 고친다. `corepack pnpm check:adapter-inventory`가 대조한다. +6. 여러 adapter가 같이 쓰는 로직은 `src/adapters/platform/`(kernel)이나 `src/contracts/`에 둔다. 새 파일 단위 예외 규칙은 만들지 않는다(`.dependency-cruiser.json`). +7. 공개 포트는 더하기만 한다. 기존 시그니처를 깨야 하면 결정 기록(`docs/adr/`)을 남기고 `CHANGELOG.md`에 BREAKING으로 적는다. + +## 커밋과 문서 + +8. 논리적 변경 하나에 커밋 하나다. 리뷰 발견을 고친 커밋은 메시지에 발견 ID를 적는다. 그 변경이 바꾼 파일만 스테이징한다. +9. 문서를 바꾸는 변경은 문서의 주장마다 코드 위치를 가리키는지로 확인한다. 문서와 코드가 다르면 코드가 맞다.