@simplysm/sd-claude 14.0.61 → 14.0.63

package/claude/rules/sd-clarify.md

@@ -1,6 +1,6 @@
 # sd-clarify: 명확화 지침
 
-결정 사안의 명확성을 분류하고, 불명확한 항목은 사용자 질문을 통해 명확화한다.
+결정 사안의 명확성을 분류하고, 불명확한 항목은 사용자 질문을 통해 확정한다.
 
 결정 사안 = 작업 수행을 위해 확정해야 하는 개별 결정 항목 (의도, 방식, 동작, 값 등).
 
@@ -48,31 +48,38 @@ UI 구조·메뉴/네비게이션·라우팅·도메인 엔터티·네이밍·
 근거 추측 금지:
 
 - 출처 인용은 실제 읽은 좌표만 허용한다.
-- 미확인 출처(예: "~~ 문서에 있을 것", "보통 ~~ 패턴이니")로 VERIFIED/INFERRED-High 분류 금지.
+- 미확인 출처(예: "~~ 문서에 있을 것", "보통 ~~ 패턴이니")로 확정 또는 추론 90% 이상으로 분류 금지.
 - "어차피 모를 것"이라는 판단으로 근거 확인을 건너뛰는 것 금지.
 
 ### 2-2. 명확성 분류
 
 결정 사안을 다음 기준으로 분류한다.
 
-- VERIFIED: 다음 중 하나에 명시된 항목
+- 확정 (100%): 다음 중 하나에 명시된 항목
   - 사용자 직접 발언(현재/이전 턴), 사용자 제공 외부 자료(첨부 문서·회의록·메일 등)
   - 프로젝트 룰·참조 문서(`.claude/rules/`, `CLAUDE.md`, `.claude/references/`)
   - 세션 내 이미 확정된 결정(이전 단계 산출물 spec/plan/wbs, 이전 sd-clarify 답변)
   - 타겟 코드베이스의 코드·타입 정의
-- INFERRED
-  - High: 다음에 기반한 추론
+- 추론 (0~100%): 근거 강도에 따라 % 부여
+  - 근거가 될 수 있는 출처:
     - 타겟 코드베이스(모노레포 동일 워크스페이스 포함)의 동일/유사 패턴
     - 공식 문서·업계 표준·규격(RFC/ISO/W3C/KS)·법률·규제
     - 일반적 도메인 관행, 유사 사례, 외부 프로젝트의 패턴
-  - Medium: 마이그레이션 원본·이전 버전 등 같은 프로젝트의 과거 상태에 기반한 추론
-    - 이전 동작이 신규 요구사항과 일치한다는 보장이 약함
-  - Low: 약한 유추나 제한적 근거에 기반한 추론
-- ASSUMED: 추측에 해당
+    - 마이그레이션 원본·이전 버전 등 같은 프로젝트의 과거 상태
+    - 그 외 약한 유추나 제한적 근거
+- 추측 (0%): 근거 없는 가정
+
+추론 % 사용 규칙:
+
+- 미세 차등(±10% 내)으로 의사결정을 분기하지 않는다.
+- 임계값 1개로만 이진 판단을 한다.
+  - 추론 90% 이상 → 진행
+  - 추론 90% 미만 → 질문 대기열 등록
+- 임계값을 미세 조정해 질문을 회피하지 않는다.
 
 ### 2-3. 근거 재분석
 
-INFERRED-Medium, INFERRED-Low, ASSUMED로 분류된 항목 전부를 재분석한다 (일부만 적용 금지).
+추론 90% 미만 또는 추측으로 분류된 항목 전부를 재분석한다 (일부만 적용 금지).
 항목별 1건씩 처리한다 (그룹·묶음 일괄 처리 금지).
 
 목적: 초기 분류가 부실한 분석에 기반했을 수 있다. 누적 맥락에서 이미 아는 것 이상으로, 해당 건의 근거가 될 수 있는 원본을 완독하여 실제 상황을 파악한 뒤 재분류한다.
@@ -83,13 +90,13 @@ INFERRED-Medium, INFERRED-Low, ASSUMED로 분류된 항목 전부를 재분석
 - 이미 아는 것만으로 확정할 수 없는 부분을 식별한다.
 - 그 부분의 근거가 될 수 있는 원본을 tool로 완독한다. 발췌·부분 읽기가 아니라 해당 원본 전체를 읽는다.
 - 완독한 실제 상황을 기반으로 2-2 기준에 따라 재분류한다.
-  - 근거 발견 시 VERIFIED 또는 INFERRED-High로 격상한다.
-  - 격상 불가 시 ASSUMED를 유지하되, 완독 과정에서 파악한 실제 상황을 기반으로 선택지를 구성한다.
+  - 근거 발견 시 분류를 갱신한다 (확정 또는 추론 % 로 갱신).
+  - 근거 미발견 시 기존 분류를 유지하되, 완독 과정에서 파악한 실제 상황을 기반으로 선택지를 구성한다.
 
 금지:
 
 - "어차피 모를 것"이라는 판단으로 재분석을 건너뛰는 것.
-- 확인하면 바로 알 수 있는 내용을 확인 없이 ASSUMED로 분류해 사용자에게 묻는 것.
+- 확인하면 바로 알 수 있는 내용을 확인 없이 추측으로 분류해 사용자에게 묻는 것.
 - 사용자 발언의 가능성 시사("이미 ~~ 있을 것")를 완독 없이 신규 구조 도입의 근거로 삼는 것.
 
 ### 2-4. 분류 보고
@@ -98,20 +105,20 @@ INFERRED-Medium, INFERRED-Low, ASSUMED로 분류된 항목 전부를 재분석
 
 | 대상 | 원분류 | 재분석분류 | 인용 |
 |---|---|---|---|
-| {식별자/경로:라인} | INFERRED-Low | VERIFIED | path/file.ts:42 — "..." |
-| {식별자2} | ASSUMED | ASSUMED | (없음 — 질문 대기열 등록) |
+| {식별자/경로:라인} | 추론 60% | 확정 | path/file.ts:42 — "..." |
+| {식별자2} | 추측 | 추측 | (없음 — 질문 대기열 등록) |
 
 - 원분류: 근거 확인 직후 분류 결과.
-- 재분석분류: 근거 재분석 후 분류 결과 (격상 또는 유지).
-- 인용: VERIFIED / INFERRED-High만 출처 인용 작성.
-  - ASSUMED는 "(없음 — 질문 대기열 등록)" 표기.
+- 재분석분류: 근거 재분석 후 분류 결과 (갱신 또는 유지).
+- 인용: 확정 / 추론 90% 이상만 출처 인용 작성.
+  - 추측은 "(없음 — 질문 대기열 등록)" 표기.
 
 결정 사안이 다건이면 항목별로 각각 분류하고, 명확/불명확을 한 번에 일괄 보고한다.
 
 분기:
 
-- 근거 명확(VERIFIED / INFERRED-High)만 있음: 출처 인용을 호출자에게 보고하고 종료.
-- 근거 불명확(INFERRED-Medium/Low / ASSUMED) 항목 있음: 질문 대기열에 등록하고 Step 3으로 진행한다.
+- 근거 명확(확정 / 추론 90% 이상)만 있음: 출처 인용을 호출자에게 보고하고 종료.
+- 근거 불명확(추론 90% 미만 / 추측) 항목 있음: 질문 대기열에 등록하고 Step 3으로 진행한다.
 
 ## Step 3: 질문 진행
 
@@ -137,10 +144,16 @@ INFERRED-Medium, INFERRED-Low, ASSUMED로 분류된 항목 전부를 재분석
 - 누락 답변 처리: 사용자가 현재 질문에 답하지 않으면 같은 질문을 다시 묻는다.
   - 누락 항목을 임의 추천안으로 처리하지 않는다.
 - 추가 질문 처리: 답변 수집 중 또는 작업 중 새로 물어봐야 할 항목이 발견되면 질문 대기열에 추가하고, 다시 한 번에 하나씩 질문한다.
-- 질문 정렬: 발견된 질문은 발생 출처(Step/Feature 번호/대상 식별자) 단위로 묶음 분류한다.
-  - 한 묶음을 모두 소진한 뒤 다음 묶음으로 넘어간다.
-  - 진행 중 묶음 내에서 발견된 새 질문은 해당 묶음 끝에 추가한다.
-  - 묶음 간 순서는 의존성·상위→하위 순으로 한다.
+- 질문 정렬: 의존성 → 정보이득 → 발견 출처 순으로 정렬한다.
+  1. 의존성 우선: 상위 결정이 하위에 영향을 미치면 상위 먼저.
+  2. 동일 의존성 내에서 정보이득 상/중/하 내림차순.
+     - 정보이득 = 응답이 후속 작업의 분기·영향 범위를 가르는 정도.
+       - 상: 라우터·스키마·아키텍처 등 광범위 영향
+       - 중: 모듈/컴포넌트 내 영향
+       - 하: 단일 위치 영향
+  3. 동일 정보이득 내에서 발견 출처(Step/Feature 번호/대상 식별자) 단위로 묶음 분류.
+     - 한 묶음을 모두 소진한 뒤 다음 묶음으로 넘어간다.
+     - 진행 중 묶음 내에서 발견된 새 질문은 해당 묶음 끝에 추가한다.
 
 도구 호출:
 
@@ -196,6 +209,16 @@ Step 3의 각 질문은 다음 형식으로 제시한다.
     | B. yyy | 6 | 7 | 9 | `7.3` |
     | C. 수행 안 함 | 2 | 10 | 5 | `5.7` |
     ```
+- 마지막 상황 예시: 결정 묶음의 평가표 직후, `AskUserQuestion` 호출 직전 가로선 사이에 출력한다.
+  - 목적: 사용자가 이 블록만 읽어도 결정 가능하도록.
+  - 예시 가능한 결정:
+    - 구체 입력/상황 1건을 가정한다 (예: "자재 X·Y·Z의 월별 수량이 이렇게 들어 있을 때").
+    - 각 선택지 채택 시 결과를 라인·표·값으로 풀어 비교한다 (예: "지금 동작 — 18줄 / 바꾸면 — 9줄").
+    - 결과 차이가 한눈에 보이도록 동일 입력에 대한 양쪽 결과를 나란히 제시한다.
+  - 예시 불가능한 결정 (추상적 정책·진행 여부 등):
+    - 결정의 의미·영향 범위·각 선택지가 무엇을 보장하고 무엇을 포기하는지 풀어 쓴다.
+    - 길이 제약 없음.
+  - 어휘: 최종 사용자(최종고객) 업무 도메인 표현으로 작성한다. 시스템 내부 용어(코드 식별자·메타 분류·내부 변수명·파일 경로 등) 노출 금지.
 
 ## 인용 형식
 

package/claude/rules/sd-claude-rules.md

@@ -14,13 +14,11 @@
   - 사용자 발언을 그대로 받아쓰는 것은 의도 파악 실패로 간주한다.
 - 내장 도구 적극 활용 (Read/Grep/Glob/Bash/WebFetch/WebSearch/Skill/TaskCreate 등)
 - 사용자 요청의 의도가 불명확할 때는 `sd-clarify` 지침에 따라 명확화한다.
-- 사용자에게 출력하는 글은 사용자(최종고객) 업무 도메인 어휘(표현방식)로 끌어올려 쓴다.
-  - 시스템 내부 용어(행·컬럼·필드·메타 분류·코드 식별자 등) 노출 금지. 
+- **IMPORTANT**: 사용자에게 출력하는 글은 최종 사용자(고객) 업무 도메인 어휘(표현방식)로 최대한 끌어올려 쓴다.
+  - 시스템 내부 용어(행·컬럼·필드·메타 분류·코드 식별자 등) 노출 금지.
   - 사용자가 일상 업무에서 부르는 이름·동사로 바꾼다.
   - 정독·검색 없이 1회독으로 이해되는지로 점검한다.
-- **CRITICAL**: 사용자가 명시하지 않은 행동을 추측으로 진행 하지 말것
-  - 명시적 요청없이 다음 단계를 추측하여 바로 작업 하지 말것
-  - 명시적 요청없이 코드/문서등을 바로 수정하지 말것
+- **CRITICAL**: 명시적 요청없이 코드/문서등을 바로 수정하지 말것
 
 # 질문 vs 수정 분리
 

package/claude/skills/sd-dev/SKILL.md

@@ -34,7 +34,7 @@ sd-wbs → sd-plan → sd-tdd → sd-check → sd-review를 순차 진행하는
 
 ## Step 4: sd-tdd
 
-`/sd-tdd` 스킬을 즉시 수행한다.
+`/sd-tdd` 스킬을 즉시 수행한다. 완료후 다음 단계를 즉시 수행한다.
 
 ## Step 5: sd-check
 
@@ -44,6 +44,8 @@ sd-tdd Step 3-4 `변경 사항 요약`의 `변경 파일 목록`이 비어 있
 
 예: `/sd-check core-common angular`
 
+완료후 다음 단계를 즉시 수행한다.
+
 ## Step 6: sd-review
 
 Task 문서 경로를 인자로 전달하여 feature 구현이 plan대로 되었는지 리뷰한다. sd-tdd Step 3-4 `변경 파일 목록`은 `변경 파일:` 후미에 명시하여 리뷰 대상을 좁힌다.
@@ -59,6 +61,8 @@ sd-review 보고에 확정 이슈가 없으면 이 단계를 스킵하고 Step 7
 
 수정 내역과 미수정 건은 Step 7 완료 보고의 `리뷰 수정 건` / `리뷰 미수정 건` 섹션에 반영한다.
 
+완료후 다음 단계를 즉시 수행한다.
+
 ## Step 7: 완료 보고 양식
 
 모든 단계 완료 후, 아래 양식으로 실행 결과를 대화에 출력한다.

package/claude/skills/sd-plan/SKILL.md

@@ -121,6 +121,20 @@ Feature: Story {번호} {이름}
 
 모든 사용자 결정사항은 `### 설계 결정` 표에 기록한다 (D1, D2, ... 순번 부여).
 
+### 선택적 자료
+
+구현 설계와 함께 개발자 시점 자료를 Task 성격에 따라 선택적으로 포함한다.
+작성 시 해당 references 파일을 읽고 가이드에 따른다.
+
+| 자료 | 작성 위치 | 가이드 | 적용 기준 |
+|---|---|---|---|
+| 시퀀스 다이어그램 | 구현 설계 시작 (영향 범위 다음) | `references/sequence-diagram.md` | client·server·db 등 다중 모듈이 협력하는 Task |
+| DB 모델 변경 표 | 엔티티 섹션 안 | `references/db-model-change.md` | 신규/수정 모델·컬럼·관계가 있는 Task |
+| API/서비스 메서드 명세 | 서비스 / API 섹션 안 | `references/api-spec.md` | 서버 메서드·엔드포인트 신규/변경이 있는 Task |
+| 상태 전이도 (FSM) | 엔티티 섹션 인접 | `references/state-machine.md` | 도메인 객체에 status 컬럼 + 전이 3개 이상인 경우 |
+
+자료가 불필요한 Task면 해당 항목을 생략한다.
+
 ```markdown
 ## 구현 설계
 
@@ -129,14 +143,22 @@ Feature: Story {번호} {이름}
 - 신규: {파일 목록}
 - 수정: {파일 목록}
 
+### 시퀀스 다이어그램 (선택, references/sequence-diagram.md 참조)
+
 ### 엔티티 [근거: ...]
 
 {시그니처 또는 코드}
 
+#### DB 모델 변경 표 (선택, references/db-model-change.md 참조)
+
+#### 상태 전이도 (선택, references/state-machine.md 참조)
+
 ### 서비스 / API [근거: ...]
 
 {시그니처}
 
+#### API/서비스 메서드 명세 (선택, references/api-spec.md 참조)
+
 ### UI [근거: ...]
 
 {구조}

package/claude/skills/sd-plan/references/api-spec.md

@@ -0,0 +1,64 @@
+# API/서비스 메서드 명세 작성 가이드
+
+서비스 / API 섹션 안에 작성. 메서드별 요청·응답·에러·권한을 상세히 정리한다.
+
+## 표현 형식
+
+메서드별로 표 또는 정의 블록으로 작성한다.
+
+| 항목 | 내용 |
+|---|---|
+| 메서드 | `WorkService.createWork(dto): Promise<Work>` |
+| 요청 (CreateWorkDto) | 필드별 타입·필수·검증 규칙 |
+| 응답 (성공) | 응답 타입의 모든 필드 |
+| 에러 케이스 | 에러 타입 + 발생 조건 |
+| 권한 | 호출 가능한 권한 |
+
+## 작성 원칙
+
+- 요청 스키마: 필드명·타입·필수/선택·검증 규칙(길이/범위/형식) 모두 명시.
+- 응답 스키마: 모든 반환 필드. nullable 필드 표시.
+- 에러 케이스: 발생 조건과 에러 타입을 짝으로. 사용자 메시지 또는 에러 코드 포함.
+- 권한: Role 명시 + 조건부 권한(예: "본인 데이터만")이면 조건도 명시.
+- 페이지네이션·정렬·필터가 있는 조회 메서드는 그 옵션도 명시.
+
+## 좋은 예 (작업 등록)
+
+| 항목 | 내용 |
+|---|---|
+| 메서드 | `WorkService.createWork(dto: CreateWorkDto): Promise<Work>` |
+| 요청 | `title (string, 필수, 1~200자, trim)`, `dueDate (Date, 선택, 오늘 이후)`, `assigneeId (uuid, 필수)`, `description (string, 선택, 0~1000자)` |
+| 응답 | `Work { id, title, dueDate (nullable), assigneeId, status: 'pending', createdAt }` |
+| 에러 | `ValidationError` (title 빈/초과, dueDate 과거, description 초과), `NotFoundError` (assigneeId에 해당 User 없음), `PermissionError` (호출자가 ADMIN 아님) |
+| 권한 | `ROLE.ADMIN` |
+
+## 좋은 예 (조회 메서드 — 페이지네이션 포함)
+
+| 항목 | 내용 |
+|---|---|
+| 메서드 | `WorkService.listWorks(query: ListWorksQuery): Promise<{ items: Work[], total: number }>` |
+| 요청 | `status (Work.status, 선택, 다중 선택 가능)`, `assigneeId (uuid, 선택)`, `keyword (string, 선택, title 부분 일치)`, `page (number, 기본 1)`, `pageSize (number, 기본 20, 최대 100)`, `sort (Enum, 기본 'createdAt:desc')` |
+| 응답 | `{ items: Work[], total: number }` |
+| 에러 | `ValidationError` (pageSize 범위 초과) |
+| 권한 | `ROLE.ADMIN` (전체 조회) / `ROLE.STAFF` (`assigneeId = self` 자동 적용) |
+
+## 무엇을 잡아주나
+
+- 검증 규칙 (길이·형식·범위) 명시 — Gherkin Scenario 작성의 기반
+- 에러 케이스 누락 — 어떤 입력에 어떤 에러를 내는지
+- 권한 요구사항 — 누가 호출할 수 있는지, 조건부 권한은 어떤 조건인지
+- 응답 필드 누락 — 클라이언트가 어떤 필드를 받는지
+- nullable·선택 필드 — 클라이언트의 처리 분기
+
+## 나쁜 예
+
+- "title을 받아서 Work 생성" — 검증 규칙·에러 누락
+- 에러 케이스에 "ValidationError 발생"만 기록 (어떤 조건에 발생하는지 모호)
+- 권한 누락 (누구나 호출 가능한지 ADMIN만인지 모호)
+- 응답을 `Work` 한 단어로만 표현 (필드 정보 모호)
+- 페이지네이션 메서드인데 `page`/`pageSize` 기본값·최대값 누락
+
+## 기존 시그니처와의 차이
+
+- 시그니처: `createWork(dto): Promise<Work>` — 함수의 형태만
+- 명세: 검증 규칙 + 에러 케이스 + 권한 + 응답 필드까지 — 함수의 계약 전체

package/claude/skills/sd-plan/references/db-model-change.md

@@ -0,0 +1,45 @@
+# DB 모델 변경 표 작성 가이드
+
+엔티티 섹션 안에 작성. 신규/수정 모델·컬럼·관계·인덱스를 하나의 매트릭스로 정리한다.
+
+## 표현 형식
+
+| 모델 | 변경 종류 | 컬럼·내용 | 인덱스 |
+|---|---|---|---|
+
+컬럼 단위 표현이 더 명확하면 컬럼 단위 행으로 풀어 쓴다.
+
+## 작성 원칙
+
+- 변경 종류: `신규` / `컬럼 추가` / `컬럼 수정` / `컬럼 삭제` / `인덱스 추가/삭제` / `관계 변경`
+- 컬럼은 타입·NULL 여부·기본값·외래키·`ON DELETE` 동작을 모두 명시.
+- 인덱스는 단일/복합 구분, 사용 목적(조회 빈번 컬럼) 명시.
+- 외래키는 `FK → {대상모델}.{컬럼}` 형식. 카스케이드 동작 명시.
+- 컬럼 길이·정밀도는 도메인 값 범위에 충분한지 검토 후 결정.
+
+## 좋은 예 (작업 등록)
+
+| 모델 | 변경 | 컬럼·내용 | 인덱스 |
+|---|---|---|---|
+| `Work` | 신규 | `id (uuid, PK)`, `title (varchar 200, NOT NULL)`, `dueDate (date, NULL)`, `assigneeId (uuid, NOT NULL, FK → User.id)`, `status (varchar 20, NOT NULL, default 'pending')`, `createdAt (datetime, NOT NULL, default NOW())` | `assigneeId`, `status` |
+| `WorkLog` | 신규 | `id (uuid, PK)`, `workId (uuid, NOT NULL, FK → Work.id, ON DELETE CASCADE)`, `userId (uuid, NOT NULL, FK → User.id)`, `action (varchar 20)`, `createdAt (datetime, NOT NULL, default NOW())` | `workId`, `userId` |
+| `User` | 컬럼 추가 | `lastWorkAt (datetime, NULL)` | — |
+
+## 검증 체크리스트
+
+작성 후 다음을 확인한다.
+
+- 모든 외래키에 `ON DELETE` 동작 명시했는가 (`CASCADE` / `RESTRICT` / `SET NULL`)
+- 조회 빈번한 컬럼에 인덱스가 있는가
+- `NOT NULL` 컬럼에 기본값이 있거나 INSERT 시 반드시 채워지는가
+- 신규 테이블의 PK가 정의됐는가
+- 컬럼 타입·길이가 도메인 값 범위에 충분한가
+- 복합 유일 제약(unique)이 필요한 케이스를 놓치지 않았는가
+
+## 나쁜 예
+
+- "Work 테이블 추가" — 컬럼 누락
+- 외래키 동작 명시 안 함 — `ON DELETE CASCADE` vs `RESTRICT` vs `SET NULL` 모호
+- 인덱스 누락 — 조회 자주 하는 컬럼인데 INDEX 없음
+- `NOT NULL`인데 기본값·INSERT 경로 모호 (마이그레이션 시 실패 위험)
+- 길이 미정 (`varchar`만 적고 길이 없음)

package/claude/skills/sd-plan/references/sequence-diagram.md

@@ -0,0 +1,66 @@
+# 시퀀스 다이어그램 작성 가이드
+
+구현 설계 시작(영향 범위 다음)에 작성. 모듈 간 호출 흐름을 mermaid `sequenceDiagram`으로 시각화한다.
+
+## 작성 원칙
+
+- 참여자(`participant`)는 패키지·모듈 단위로 정의 (예: `client-admin`, `server`, `WorkService`, `db-main`).
+- 외부 사용자는 `actor`로 표시.
+- 호출 화살표는 동기 `->>`, 응답 `-->>`. 비동기는 `->>` + `Note`로 명시.
+- 트랜잭션·반복·분기는 `Note`/`alt`/`loop`로 표현.
+- 권한 체크·검증·로그 같은 부수 동작도 메시지로 표시 (자주 누락되는 영역).
+- 한 다이어그램의 메시지 수는 20개 이내. 넘으면 단계별로 분할.
+
+## 좋은 예 (작업 등록)
+
+```mermaid
+sequenceDiagram
+  actor U as 관리자
+  participant UI as client-admin
+  participant API as server (라우터)
+  participant SVC as WorkService
+  participant DB as db-main
+  participant Q as 알림 큐
+
+  U->>UI: 작업 등록 폼 저장
+  UI->>API: createWork(dto)
+  API->>API: 권한 체크 (ROLE.ADMIN)
+  API->>SVC: createWork(dto)
+  SVC->>SVC: dto 검증
+
+  Note over SVC,DB: TX BEGIN (READ COMMITTED)
+  SVC->>DB: INSERT Work
+  SVC->>DB: INSERT WorkLog (action='created')
+  Note over SVC,DB: TX COMMIT
+
+  SVC->>Q: enqueue 담당자 알림 (TX 외부)
+  SVC-->>API: Work
+  API-->>UI: 201 Created
+  UI-->>U: 토스트 + 목록 갱신
+```
+
+## 무엇을 명시해야 하나
+
+- **권한 체크 위치**: 어느 참여자에서? (API 진입? Service?)
+- **트랜잭션 경계**: BEGIN ~ COMMIT을 `Note over`로 명시
+- **외부 호출**: 알림·이메일·외부 API. TX 외부에 둘지 안에 둘지
+- **에러 분기**: 실패 케이스가 핵심이면 `alt`/`else`로 표현
+- **비동기 처리**: 반환을 기다리지 않으면 `Note`로 명시
+
+## 나쁜 예
+
+- `participant`에 클래스명만 (`WorkServiceImpl`) — 모듈/패키지 컨텍스트 누락
+- 권한 체크 누락 (그냥 `SVC.createWork`만 호출하는 걸로 끝)
+- 트랜잭션 경계 표시 없음 (어디서 BEGIN/COMMIT인지 모호)
+- 외부 호출이 TX 안에 있는데 명시 안 됨 (락 길어짐 위험)
+- 한 다이어그램에 모든 시나리오를 욱여넣어 메시지 30개 이상
+
+## sd-wbs mermaid와의 차이
+
+| 구분 | sd-wbs (사용자 시점) | sd-plan 시퀀스 (개발자 시점) |
+|---|---|---|
+| 노드 | 사용자가 인지하는 단계 | 패키지/모듈/클래스 |
+| 동작 라벨 | "도서 검색", "대출 신청" | `findWork(id)`, `createWork(dto)` |
+| 부수 동작 | (없음) | 트랜잭션, 권한 체크, 알림 큐 |
+
+같은 정보를 양쪽에 중복하지 않는다.

package/claude/skills/sd-plan/references/state-machine.md

@@ -0,0 +1,83 @@
+# 상태 전이도 (FSM) 작성 가이드
+
+엔티티 섹션 인접에 작성. 도메인 객체의 내부 상태 머신을 mermaid `stateDiagram-v2` + 전이 표로 정리한다.
+
+## 표현 형식
+
+다이어그램과 표를 함께 작성한다.
+
+### 다이어그램
+
+```mermaid
+stateDiagram-v2
+  [*] --> {초기상태}: {생성 이벤트}
+  {상태} --> {다음상태}: {전이 이벤트}
+  {상태} --> [*]
+```
+
+### 전이 표
+
+| 현재 상태 | 이벤트 | 다음 상태 | 가드 | 사이드 이펙트 |
+|---|---|---|---|---|
+
+## 작성 원칙
+
+- 상태 라벨은 DB `status` 컬럼 값 그대로 사용 (`pending`, `in_progress` 등). 한글 라벨 금지.
+- 전이 이벤트는 메서드명 또는 시스템 이벤트명.
+- 가드: 권한 조건·데이터 조건·타이밍 조건. 비어있으면 `—`.
+- 사이드 이펙트: 알림·로그·외부 호출·다른 컬럼 갱신. 자주 누락되는 영역이라 명시 강제.
+- 모든 가능 전이를 빠짐없이 나열한다 (완전성).
+- 종료 상태(`[*]`)로 가는 경로를 명시.
+
+## 좋은 예 (작업 도메인)
+
+```mermaid
+stateDiagram-v2
+  [*] --> pending: createWork
+  pending --> in_progress: startWork
+  pending --> cancelled: cancelWork
+  in_progress --> completed: completeWork
+  in_progress --> blocked: blockWork
+  in_progress --> cancelled: cancelWork
+  blocked --> in_progress: unblockWork
+  completed --> [*]
+```
+
+| 현재 | 이벤트 | 다음 | 가드 | 사이드 이펙트 |
+|---|---|---|---|---|
+| (initial) | `createWork` | `pending` | — | 담당자 알림 |
+| `pending` | `startWork` | `in_progress` | 호출자 = 담당자 | `startedAt` 기록 |
+| `pending` | `cancelWork` | `cancelled` | 호출자 = `ADMIN` | 담당자 알림 |
+| `in_progress` | `completeWork` | `completed` | 호출자 = 담당자 | 완료 알림 + 보고서 생성 |
+| `in_progress` | `blockWork` | `blocked` | 사유 필수 | 관리자 알림 |
+| `in_progress` | `cancelWork` | `cancelled` | 호출자 = `ADMIN` | 담당자 알림 |
+| `blocked` | `unblockWork` | `in_progress` | 호출자 = 담당자/`ADMIN` | — |
+
+## 검증 체크리스트
+
+작성 후 다음을 확인한다.
+
+- 모든 상태에서 가능한 모든 이벤트가 표에 있는가
+- 종료 상태(`[*]`)로 가는 경로가 정의됐는가
+- 가드 조건의 검증 위치가 명확한가 (Service 안? DB constraint?)
+- 사이드 이펙트가 트랜잭션 내부인지 외부인지 (알림은 보통 TX 외부)
+- 동시성 — 같은 객체에 두 이벤트가 동시에 오면? 락·낙관적 동시성 정책
+
+## 나쁜 예
+
+- 상태 라벨이 한글 (`진행중`) — DB `status` 값과 불일치, sd-wbs와 헷갈림
+- 가드·사이드 이펙트 컬럼 빠진 단순 다이어그램 (전이만 그림)
+- 일부 전이 누락 — 어떤 상태에서 `cancelWork`가 가능한지 모호
+- 종료 상태로 가는 경로 누락
+- 사이드 이펙트(알림·로그)를 트랜잭션 안에 두면서 명시 안 함
+
+## sd-wbs stateDiagram과의 차이
+
+| 구분 | sd-wbs (사용자 시점) | sd-plan FSM (개발자 시점) |
+|---|---|---|
+| 라벨 | "진행 중" (사용자 표시) | `in_progress` (DB 컬럼 값) |
+| 트리거 | "완료 표시" (사용자 동작) | `completeWork` (메서드명) |
+| 가드 | (없음 또는 단순 권한) | 권한·데이터·타이밍 조건 |
+| 사이드 이펙트 | (없음) | 알림·로그·외부 호출 명시 |
+
+같은 객체 상태라도 정보 깊이가 다르다. sd-wbs와 sd-plan에 같은 정보를 중복 작성하지 않는다.

package/claude/skills/sd-review/SKILL.md

@@ -203,4 +203,4 @@ Step 6에서 정리된 결과를 다음 양식으로 사용자에게 보고한
   - 검증 근거 (Step 4에서 확인한 내용)
   - 개선 방향
 
-수정 여부·방식·시점은 호출자가 결정한다. 다음 단계나 코드 수정을 사용자 승인없이 진행하지 않는다.
+수정 여부·방식·시점은 호출자가 결정한다. 명시적 지시 없이 다음 단계나 코드 수정을 진행하지 않는다.

package/claude/skills/sd-wbs/SKILL.md

@@ -14,6 +14,7 @@ WBS는 고객 중심으로 **무엇을 만들어야 하는지(What)** 를 확정
 ## What/How 경계
 
 이 스킬은 비즈니스 요구사항(What)만 분석한다.
+What은 사용자 시점, How는 개발자 시점이다.
 
 **What — 이 스킬에서 반드시 확정 (위임 금지):**
 
@@ -125,6 +126,21 @@ USM의 모든 단위는 **사용자 동작 단위**이다. 다음 분할은 절
 
 사용자 입력이 위 금지 분할(레이어/Actor)을 명시 요청하더라도 그대로 따르지 않는다. USM 패러다임으로 재해석하여 사용자 동작 단위로 분해하고, 재해석 사항을 재해석 목록에 등록한다.
 
+### 선택적 자료
+
+USM 분해와 함께 사용자 시점 자료를 프로젝트 내용에 따라 선택적으로 포함한다.
+작성 시 해당 references 파일을 읽고 가이드에 따른다.
+
+| 자료 | 작성 위치 | 가이드 | 적용 기준 |
+|---|---|---|---|
+| 메뉴 구성 | wbs.md 상단 (Impact Mapping 다음) | `references/menu-structure.md` | 사용자가 보는 메뉴/네비게이션이 있는 경우 |
+| 용어 사전 | wbs.md 상단 (Impact Mapping 다음) | `references/glossary.md` | 도메인 어휘·약어가 다수이거나 동의어 정리가 필요한 경우 |
+| 업무 플로우 (mermaid) | 각 Activity 헤더 직후 | `references/flow-diagram.md` | 사용자 여정·상태 전이가 핵심인 Activity |
+| 와이어프레임 | 해당 Task 또는 Story 안 | `references/wireframe.md` | 사용자가 보는 화면이 있는 Task/Story |
+| 결정 규칙표 | 해당 Task 또는 Story 안 | `references/decision-table.md` | 분기 조건 조합이 많은 Task/Story (mermaid 보완재) |
+
+자료가 불필요한 프로젝트면 해당 섹션을 생략한다.
+
 ### 3-1. Activity Backbone 도출
 
 Activity는 사용자가 시스템과 함께 달성하는 큰 활동(=업무 영역)이다. 사용자 여정의 시간 흐름 또는 업무 묶음을 따라 Backbone을 구성한다.
@@ -136,6 +152,8 @@ Activity는 사용자가 시스템과 함께 달성하는 큰 활동(=업무 영
 
 - "회원 가입/인증" → "도서 검색" → "대출/반납" → "도서 관리"
 
+이 단계에서 작성할 자료(선택): 메뉴 구성, 용어 사전, Activity별 업무 플로우.
+
 ### 3-2. Task 분해
 
 Task는 Activity 안의 사용자 작업이다. 후속 스킬(`/sd-plan`, `/sd-tdd`)의 1 작업 단위이다.
@@ -165,6 +183,8 @@ Task는 Activity 안의 사용자 작업이다. 후속 스킬(`/sd-plan`, `/sd-t
 
 의존성이 없다는 근거를 명시할 수 없으면 의존성이 있는 것으로 간주한다. 과소 설정(블로킹·재작업)이 과대 설정(약간의 직렬화)보다 비용이 크다.
 
+이 단계에서 작성할 자료(선택): 해당 Task의 와이어프레임·결정 규칙표.
+
 ### 3-3. Story 작성
 
 Story는 Task 안의 한 사용자 시나리오이다. 한 줄 사용자 동작 형식으로 작성한다.
@@ -190,6 +210,8 @@ Story는 Task 안의 한 사용자 시나리오이다. 한 줄 사용자 동작
 - 추정 진행, "추후 결정" fallback, 자체 추가 금지.
 - wbs.md 본문에 "후속 확정/보류/추후 결정/협의 필요" 같은 미확정 표현 사용 금지.
 
+이 단계에서 작성할 자료(선택): 해당 Story의 와이어프레임·결정 규칙표 (Task 단위로 부족한 경우).
+
 ## Step 4: 자가검증 (Self-Refine)
 
 1차 산출된 분해 결과를 아래 검증 관점 4가지로 **MUST** 순회 점검하여 발견 항목 목록을 확정한다.
@@ -253,10 +275,20 @@ Backbone 흐름·Story 단위 적정성·양방향 커버리지는 Step 6 격리
     - **Impact:** [행동 변화]
       - **Deliverable:** [산출물]
 
+## 메뉴 구성 (선택)
+
+[references/menu-structure.md 참조]
+
+## 용어 사전 (선택)
+
+[references/glossary.md 참조]
+
 ## USM Backbone
 
 ### Activity 1. [Activity 이름]
 
+**업무 플로우 (선택, references/flow-diagram.md 참조)**
+
 #### [ ] Task 1.1 [Task 이름]
 
 **의존성:** 없음
@@ -270,6 +302,10 @@ Backbone 흐름·Story 단위 적정성·양방향 커버리지는 Step 6 격리
 - Impact Mapping Deliverable: "상세 정보 팝업"
 - 요구사항: "팝업 형태로 상세 정보 표시"
 
+**와이어프레임 (선택, references/wireframe.md 참조)**
+
+**결정 규칙표 (선택, references/decision-table.md 참조)**
+
 **Stories:**
 
 ##### Story 1.1.1 상세 정보 팝업 열기

package/claude/skills/sd-wbs/references/decision-table.md

@@ -0,0 +1,66 @@
+# 결정 규칙표 작성 가이드
+
+해당 Task 또는 Story 안에 작성. 조건 조합에 따른 결과를 표로 정리한다. mermaid 분기가 폭발할 때 보완재로 사용한다.
+
+## 사용 시점
+
+다음 중 하나에 해당하면 결정 규칙표를 작성한다.
+
+- 분기 조건이 3개 이상이고 조합이 핵심
+- 같은 결과로 가는 경로가 여러 개 (조건이 다양해도 결과는 같음)
+- 조건 누락·중복을 검증해야 함 (완전성·배타성 확인 필요)
+
+위 조건이 아니면 mermaid 또는 Story 산문으로 충분하다.
+
+## 표현 형식
+
+조건 컬럼 + 결과 컬럼으로 구성한다. 모든 조합을 행으로 나열한다.
+
+| 회원 등급 | 연체 이력 | 보유 권수 | → 대출 가능 | → 최대 대수 |
+|---|---|---|---|---|
+| 일반 | 없음 | < 5 | 가능 | 5권 |
+| 일반 | 없음 | = 5 | 불가 | — |
+| 일반 | 있음 | < 3 | 가능 | 3권 |
+| 일반 | 있음 | ≥ 3 | 불가 | — |
+| VIP | 없음 | < 10 | 가능 | 10권 |
+| VIP | 있음 | < 5 | 가능 | 5권 |
+
+## 작성 원칙
+
+- 조건은 독립적·결정적이어야 한다 (한 조건이 다른 조건을 함의하면 합치거나 분리).
+- 모든 조합을 빠짐없이 나열한다 (완전성). 비어 있는 조합이 있으면 의도된 누락인지 명시.
+- 같은 조건 행이 두 개 이상 있으면 안 된다 (배타성). 중복 발견 시 우선순위 또는 통합 규칙 명시.
+- 결과 컬럼은 `→` 접두로 표시해 조건/결과를 시각적으로 구분한다.
+- 조건 값은 구체 수치·범위로 적는다 (`< 5`, `= 5`, `≥ 3`). "많으면"·"적으면" 같은 추상 표현 금지.
+- "해당 없음"은 빈칸이 아닌 `—`로 명시한다.
+
+## 검증 체크리스트
+
+작성 후 다음을 확인한다.
+
+- 조합 수 = 각 조건 값 개수의 곱 (모든 조합 나열 확인)
+- 같은 조건 조합이 두 행에 있지 않은가 (중복 확인)
+- 결과가 빈칸인 행이 있다면 의도된 것인가 (누락 확인)
+- 조건이 추가되면 행 수가 어떻게 늘어나는가 (확장성 점검)
+
+## mermaid와의 역할 분리
+
+같은 Task/Story에 mermaid와 결정 규칙표가 모두 있으면 다음 원칙으로 역할을 나눈다.
+
+- mermaid: 사용자 작업의 시간 흐름·상태 전이
+- 결정 규칙표: 특정 단계의 분기 조건·결과 조합
+
+같은 정보를 양쪽에 중복하지 않는다. mermaid에서 분기가 복잡한 노드를 결정 규칙표로 위임한다.
+
+## 좋은 예
+
+- "회원 등급 × 연체 이력 × 보유 권수" 3개 조건의 모든 조합 나열
+- 결과가 같은 행을 통합하지 않고 풀어 적어 누락 검증 가능
+- 우선순위가 있는 규칙(예: "VIP는 다른 조건 무시")은 별도 행으로 명시
+
+## 나쁜 예
+
+- "일반 회원은 대출 5권, VIP는 10권" — 산문으로 적어 조합 누락 검출 불가
+- 조건 컬럼에 "회원이 우수하면" 같은 추상 표현
+- 일부 조합만 나열 (예: 연체 이력 "있음" 케이스 누락)
+- mermaid에 똑같은 분기를 또 그려 중복 (역할 분리 위배)

package/claude/skills/sd-wbs/references/flow-diagram.md

@@ -0,0 +1,56 @@
+# 업무 플로우 (mermaid) 작성 가이드
+
+Activity 헤더 직후에 작성. 사용자가 따라가는 시간 흐름·상태 전이를 시각화한다.
+
+## 다이어그램 종류 선택
+
+| 표현 대상 | 다이어그램 | 사용 시점 |
+|---|---|---|
+| 사용자 작업의 시간 흐름 | `flowchart` | 여러 단계를 순차 진행하는 Activity |
+| 엔터티의 상태 변화 | `stateDiagram-v2` | 주문·요청·결재 등 상태 lifecycle이 핵심인 경우 |
+| 사용자-시스템 간 주고받음 | `sequenceDiagram` | 외부 시스템 연동·승인 흐름 |
+
+여러 다이어그램이 필요하면 분리해서 각각 작성한다.
+
+## 작성 원칙
+
+- 사용자 시점에서 보이는 단계만 노드로 둔다.
+- 시스템 내부 함수·DB 호출·내부 큐 등은 노드로 두지 않는다.
+- 분기는 의사결정 노드(`{}`)로 표현한다.
+- 노드 라벨은 사용자 도메인 어휘로 작성한다 (시스템 식별자·테이블명 금지).
+- 한 다이어그램의 노드 수는 12개 이내. 넘으면 하위 다이어그램으로 분할한다.
+
+## flowchart 좋은 예
+
+```mermaid
+flowchart LR
+  A[회원이 도서 검색] --> B{대출 가능?}
+  B -- 가능 --> C[대출 신청]
+  B -- 불가 --> D[대기 등록]
+  C --> E[대출 완료]
+```
+
+## stateDiagram 좋은 예
+
+```mermaid
+stateDiagram-v2
+  [*] --> 대출중: 대출 신청
+  대출중 --> 반납완료: 반납
+  대출중 --> 연체: 기한 초과
+  연체 --> 반납완료: 반납
+```
+
+## 나쁜 예
+
+- 노드 라벨에 `getBookById()`·`books 테이블` 같은 시스템 어휘 노출
+- DB 트랜잭션 경계·캐시 무효화 같은 구현 상세 표현
+- 한 다이어그램에 모든 Activity를 욱여넣어 노드 수가 30개를 넘김
+- 분기 결과 라벨 누락 (`Yes`/`No`만 적고 무엇에 대한 판단인지 모호)
+
+## 호환성
+
+mermaid 코드블록은 `wbs.md`에서 GitHub·VS Code 미리보기로 렌더링된다. 호환성을 위해 다음을 지킨다.
+
+- 노드 ID는 영문/숫자만 (한글 ID 금지, 라벨에는 한글 OK)
+- 따옴표·괄호가 라벨에 들어가면 `[...]` 대신 `["..."]` 사용
+- 색상·아이콘 등 확장 문법은 사용 금지 (호환성 우선)

package/claude/skills/sd-wbs/references/glossary.md

@@ -0,0 +1,44 @@
+# 용어 사전 작성 가이드
+
+`wbs.md` 상단(Impact Mapping 다음)에 작성. 도메인 어휘·약어·동의어를 정리해 후속 sd-plan/sd-tdd가 같은 어휘를 쓰도록 한다.
+
+## 표현 형식
+
+표 형식으로 작성한다.
+
+| 용어 | 정의 | 동의어·약어 | 비고 |
+|---|---|---|---|
+| 대출 | 회원이 도서를 일정 기간 빌리는 행위 | 차입, lending | 최대 14일 |
+| 연체 | 대출 기간을 초과한 상태 | overdue | 1일 = 100원 연체료 |
+| 회원 | 도서관 서비스를 이용하는 등록 사용자 | user, patron | 등급: 일반/VIP |
+| VIP | 연 12회 이상 대출한 회원 | 우수회원 | 대출 한도 2배 |
+
+## 작성 원칙
+
+- 사용자가 일상에서 부르는 이름을 표제어로 둔다.
+- 시스템 내부 용어(테이블명·코드 식별자)는 표제어 금지. 동의어 컬럼에만 등록.
+- 정의는 1줄. 비즈니스 의미가 드러나야 한다 (구현 방식 X).
+- 약어·줄임말·외래어가 있으면 동의어 컬럼에 모두 등록.
+- 임계값·기간·등급 분류 등 구체 수치는 비고 컬럼에 명시.
+
+## 등록 기준
+
+다음 중 하나에 해당하면 등록한다.
+
+- 사용자·이해관계자가 회의·메일·문서에서 2회 이상 사용한 어휘
+- 의미가 헷갈리거나 동의어가 여럿인 어휘
+- 임계값·등급 분류·정책 키워드 (예: "VIP", "연체", "장기 미반납")
+- 후속 단계에서 코드 명명에 영향을 줄 어휘 (영문 표기 통일이 필요)
+
+## 좋은 예
+
+- 표제어 "대출" / 정의 "회원이 도서를 일정 기간 빌리는 행위" / 동의어 "차입, lending" / 비고 "최대 14일"
+- 표제어 "VIP" / 정의 "연 12회 이상 대출한 회원" / 비고 "대출 한도 2배"
+
+## 나쁜 예
+
+- 표제어 `BookLoan` — 시스템 식별자
+- 정의 "Loan 테이블에 행을 INSERT" — 구현 상세
+- 정의 "도서 대출 관련 처리" — 추상적, 비즈니스 의미 없음
+- 동의어·약어 누락 (사용자가 다르게 부르는 이름이 wbs 본문에 그대로 노출)
+- 임계값(예: "VIP 기준 연 12회") 누락 (비고 없으면 후속 단계에서 다시 물어야 함)

package/claude/skills/sd-wbs/references/menu-structure.md

@@ -0,0 +1,59 @@
+# 메뉴 구성 (IA) 작성 가이드
+
+`wbs.md` 상단(Impact Mapping 다음)에 작성. 사용자가 보는 메뉴/네비게이션의 위계를 정리한다.
+
+## 표현 형식
+
+다음 두 형식 중 하나를 선택한다.
+
+### 1. 트리 형식
+
+3~4단계 이내의 메뉴 위계를 들여쓰기로 표현한다.
+
+```
+- 도서 관리
+  - 도서 등록
+  - 도서 검색
+  - 도서 수정
+- 회원 관리
+  - 회원 가입
+  - 회원 정보 수정
+- 통계
+  - 대출 현황
+  - 인기 도서
+```
+
+### 2. 표 형식
+
+권한별 차이가 있거나 진입 경로·아이콘 등 부가 정보가 필요하면 표를 쓴다.
+
+| 메뉴 | 하위 메뉴 | 권한 | 비고 |
+|---|---|---|---|
+| 도서 관리 | 등록·검색·수정 | 관리자 | 일반 회원에게는 검색만 노출 |
+| 대출 | 대출 신청·반납 | 회원 이상 | — |
+| 통계 | 대출 현황·인기 도서 | 관리자 | 대시보드 형태 |
+
+## 형식 선택 기준
+
+- 메뉴 항목 5개 이하 + 권한 분기 없음 → 트리 형식
+- 메뉴 항목 6개 이상 또는 권한 분기 있음 → 표 형식
+
+## 작성 원칙
+
+- 사용자가 일상에서 부르는 이름을 메뉴명으로 쓴다 (도메인 어휘 우선).
+- 시스템 라우트 경로(`/admin/books/list`)는 메뉴명에 노출하지 않는다.
+- 권한별 노출 차이가 있으면 표 형식을 사용해 한눈에 비교 가능하게 한다.
+- 메뉴 깊이는 3~4단계 이내. 더 깊어지면 사용자가 길을 잃는다.
+- 정렬 순서는 사용 빈도 또는 업무 흐름. 알파벳·생성 순서 금지.
+
+## 좋은 예
+
+- "대출 관리 → 대출 신청 / 반납 처리 / 연체 알림"
+- 관리자 메뉴와 회원 메뉴를 별도 표로 분리
+
+## 나쁜 예
+
+- `BookListController` 같은 컴포넌트·컨트롤러명을 메뉴로 사용
+- 깊이 5단계 이상 (사용자가 클릭으로 도달 못 함)
+- 사용 빈도와 무관한 알파벳·생성 순서로 정렬
+- "기타"·"관리" 같은 추상 메뉴명 (안에 무엇이 있는지 가늠 불가)

package/claude/skills/sd-wbs/references/wireframe.md

@@ -0,0 +1,64 @@
+# 와이어프레임 작성 가이드
+
+해당 Task 또는 Story 안에 작성. 사용자가 보는 화면의 요소·배치·동작 결과를 텍스트로 표현한다.
+
+## 표현 형식
+
+상황에 맞춰 다음 중 하나를 선택한다.
+
+### 1. ASCII 박스 다이어그램
+
+레이아웃 구조가 핵심일 때 사용.
+
+```
++------------------------------------------+
+|  [로고]   도서명·저자명 검색  [검색]     |  ← 헤더 (검색바)
++------------------------------------------+
+| 카테고리 |  검색 결과 목록               |
+| - 소설   |  [표지] 제목 / 저자 / 상태    |
+| - 비문학 |  [표지] 제목 / 저자 / 상태    |
+| - 잡지   |  ...                          |
++------------------------------------------+
+| 푸터: 페이지네이션 [< 1 2 3 >]           |
++------------------------------------------+
+```
+
+### 2. 영역별 텍스트 명세
+
+요소의 동작·문구가 핵심일 때 사용.
+
+- **헤더**: 로고, 검색바(placeholder "도서명 또는 저자명"), 로그인/마이페이지
+- **사이드바**: 카테고리 목록(소설/비문학/잡지). 클릭 시 결과 필터링
+- **본문**: 검색 결과 카드 리스트. 카드당 표지·제목·저자·상태(대출 가능/대출 중)
+- **푸터**: 페이지네이션 (한 페이지 20건)
+
+## 작성 원칙
+
+- 사용자가 보는 요소만 적는다. 컴포넌트 트리·상태 관리 객체는 sd-plan 영역.
+- 사용자 동작 → 결과를 짝으로 명시한다 (예: "검색 클릭 → 결과 목록 갱신").
+- 빈 상태·오류 상태·로딩 상태가 사용자에게 보이면 별도 항목으로 추가한다.
+- 여러 화면이 한 Task에 속하면 화면별로 와이어프레임을 분리해 작성한다.
+- 입력 폼이면 항목명·필수 여부·검증 규칙을 명시한다 (예: "제목 (필수, 100자 이내)").
+
+## 빈/오류/로딩 상태 표기
+
+```
+[기본 상태]    검색 결과 목록 (위 와이어프레임)
+[빈 상태]      "검색 결과가 없습니다" 안내 + 추천 카테고리 링크
+[로딩 상태]    스켈레톤 카드 5개
+[오류 상태]    "일시적 오류" 안내 + 재시도 버튼
+```
+
+## 좋은 예
+
+- "검색 결과 카드 클릭 → 도서 상세 팝업 열림. 팝업 외부 클릭 시 닫힘."
+- "검색어 0자 입력 시 검색 버튼 비활성화."
+- 입력 폼 필드별 필수 여부와 검증 규칙 명시
+
+## 나쁜 예
+
+- "BookCard 컴포넌트 사용" — 구현 상세 (sd-plan 영역)
+- "Redux store에 results 저장" — 구현 상세
+- 그림 없이 "기본적인 검색 화면" 같은 추상적 표현
+- 동작 결과 누락 (요소만 나열하고 클릭 결과는 모호)
+- 빈/오류 상태 누락 (사용자가 마주칠 화면 일부만 정의)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/sd-claude",
-  "version": "14.0.61",
+  "version": "14.0.63",
   "description": "심플리즘 패키지 - Claude Code 셋업",
   "author": "심플리즘",
   "license": "Apache-2.0",