구현부터 시작하다 보니 여러 가지 관점의 누락이 발생하여 설계서를 작성하기로 했습니다.

작성과 확인을 반복하고 있었습니다만, 역시 매번 하는 것은 번거롭다는 생각에 커맨드 하나만 입력하면 지적해 주는 커맨드를 작성했습니다.

Q. 설계서 리뷰를 할 수 있도록 커스텀 커맨드를 만들고 싶습니다. 무엇을 준비해야 하는지 알려주세요.

Claude로부터의 질문과 답변:

이러한 상호작용을 Claude와 진행한 결과, 다음과 같은 파일이 생성되었습니다.

.claude/commands/design-review.md

---
description: 지정한 설계서 파일을 docs/README.md의 규칙에 따라 리뷰한다 (설계서 내의 정합성 체크. 파일은 변경하지 않음)
---
...

작성한 커스텀 슬래시 커맨드 (Slash Command)를 실행하면, 다음과 같이 지적해 주게 되었습니다.

/design-review docs/basic-design/screens/attendance-index.html

1. 휴게 시간대 항목 수가 일치하지 않음

기본 설계의 목업 (Mockup) (attendance-index.html:141-146)

)은 '휴게 시간대'에 4개 항목(점심시간·기타 휴게1·기타 휴게2·심야 휴게)을 표시하고 있으나, 상세 설계의 WorkInfoDto 필드 목록 (attendance-index.html:92-101)

)에는 3세트밖에 정의되어 있지 않음 (breakStartTime / breakEndTime = 점심시간, break2StartTime / break2EndTime = 기타 휴게1, nightBreakStartTime / nightBreakEndTime = 심야 휴게). '기타 휴게2'에 대응하는 필드가 상세 설계에서 누락됨.

수정안: 상세 설계에 break3StartTime / break3EndTime (가칭)을 추가하거나, 기본 설계의 목업에서 '기타 휴게2' 행을 삭제하여 1개 항목으로 맞춤.

2. '심야' 시간대 표기가 선언된 타입과 모순됨

기본 설계 목업은 심야 시간대를 22:00 〜 29:00 (24시를 넘긴 익일 오버플로 표기)로 나타내고 있으나 (attendance-index.html:136),

상세 설계에서는 nightStartTime / nightEndTime의 타입을 LocalTime (java.time.LocalTime은 0:00~23:59:59만 표현 가능)으로 정의하고 있음. 29:00와 같은 값을 이 타입으로 어떻게 다룰지 (날짜를 넘기는 계산 로직)가 명시되어 있지 않음.

수정안: 타입을 유지하면서 '익일 플래그'를 별도로 갖게 하거나, 구현 메모에 날짜를 넘기는 처리를 추가함.

문제 없음 — 기본 정보란의 '이동 대상'은 1행뿐이며, 엔드포인트 (Endpoint) 목록의 중복 기재 없음

문제 없음 — 색상·서식은 자연어로 설명되어 있으며, th:class · DB 컬럼명 · CSS 클래스명 등의 기술 정보는 상세 설계 측에만 기재되어 깔끔하게 분리되어 있음

문제 없음 — '근무 정보 패널'의 미구현 상태가 기본 설계·상세 설계 양쪽 모두에 명시되어 있으며, implementation-gap-audit.md로의 링크도 걸려 있음. AttendanceRowDto의 미사용 필드도 상세 설계에 주석 처리됨

위의 A-1을 제외하고, 항목명 (규정 근무 시간·당사 규정 근무 시간·초과 공제 판정 등)은 목업과 필드 목록이 일치함

매번 관점을 말하지 않아도 설계 리뷰를 해 주게 되었습니다.

설계 리뷰뿐만 아니라 소스 리뷰도 할 수 있도록 해 나가려고 합니다!