@simplysm/sd-claude 14.0.47 → 14.0.49

package/{claude/references/sd-simplysm14/sd-claude/usage.md → README.md}

@@ -38,7 +38,7 @@ npm install @simplysm/sd-claude
 
 | API | Type | Description |
 |-----|------|-------------|
-| `sd-session-start.sh` | SessionStart / SubagentStart hook | 세션 시작 시 `.claude/rules/*.md`와 `CLAUDE.md` 경로를 출력하여 Claude가 읽도록 안내 |
+| `sd-subagent-start.sh` | SubagentStart hook | subagent 시작 시 `CLAUDE.md` 내용을 출력하여 subagent가 프로젝트 지침을 참조하도록 안내 |
 | `sd-check-write.py` | PreToolUse hook (Write) | 기존 파일에 Write 도구 사용 시 차단하고 Edit 도구 사용을 안내 |
 | `sd-check-bash.py` | PreToolUse hook (Bash) | 금지된 명령어 차단 (git stash/checkout/restore/reset/clean, cd, npx tsc, npx eslint) |
 | `sd-check-forbidden-files.py` | PreToolUse hook (Write/Edit) | `tsconfig.json`, `eslint.config.ts` 등 보호 파일 수정 차단 |
@@ -79,6 +79,6 @@ pnpm add -D @simplysm/sd-claude
 #   rules/sd-claude-rules.md
 #   skills/sd-commit/, sd-check/, ...
 #   references/sd-*.md
-#   sd-session-start.sh, sd-check-write.py, ...
+#   sd-subagent-start.sh, sd-check-write.py, ...
 #   settings.json  (훅 자동 등록)
 ```

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

@@ -1,10 +1,18 @@
-# CRITICAL: 자주하는 실수
+# CRITICAL: 무단 진행·추측 금지
 
 - 어떠한 경우에도 지침을 무시하고 건너뛰지 않는다. 혼자만의 판단으로 무단 진행 절대(NEVER) 금지
 - 지침이 충돌등의 이유로 애매하면 사용자에게 질문한다.
-- 근거없는 답변 금지. 답변에는 항상 그 근거가 포함되어야 함.
 - 코드를 수정할 때, 왜 그 코드가 문제인지 근거를 먼저 확인하고 수정한다. "일단 바꿔보고 되면 넘어가자" 식의 추측성 시행착오를 절대(NEVER) 금지한다.
 
+# CRITICAL: 사실·지침 날조 금지
+
+**존재하지 않는 것을 지어내지 않는다(NEVER).**
+
+- 인용하는 파일·함수·API·라이브러리 시그니처는 반드시 Read/Grep으로 **직접 확인한 것**만 쓴다. 기억·일반 지식·추측 금지.
+- 사용자가 명시한 적 없는 지침/규칙을 "있는 것처럼" 만들어 따르지 않는다. 룰은 `.claude/rules/`, `CLAUDE.md`, 사용자 발화에만 존재한다. 본인이 추론한 베스트 프랙티스를 "규칙"으로 격상시키지 않는다.
+- 불확실하면 "확인 필요" 또는 "추측"이라 명시하고, 가능하면 도구로 검증한다. 모르면 모른다고 말한다.
+- 답변·코드·계획에 들어가는 모든 사실 주장은 **출처(파일경로:라인 / 도구 결과 / 사용자 발화)** 를 응답에 인라인으로 인용한다. 특히 조회로 얻은 존재·부재 단정은 조회 도구·대상·결과를 응답에 함께 표기한다 (예: "Grep `reverseBits` in `packages/core-common` → 결과 없음"). 출처를 댈 수 없는 주장은 하지 않는다.
+
 # CRITICAL: 변경사항 되돌리기 금지
 
 **git diff에 나타나는 변경사항을 임의로 되돌리지 않는다(NEVER).**
@@ -39,9 +47,16 @@
 
 # 대화 규칙
 
-- 사용자의 질문에 답변만 하라. 절대 임의로 다음단계(특히, 코드변경)로 넘어가지 않는다(NEVER). 답변만 하고 사용자의 명시적 요청을 기다린다.
+- 사용자의 질문에 답변만 하라. 절대 지침 없이 임의로 다음단계(특히, 코드변경)로 넘어가지 않는다(NEVER). 답변만 하고 사용자의 명시적 요청을 기다린다.
 - 사용자의 질문은 동의를 구하는것이 아니다. 무조건적 동의하려하지 말고, 비판적으로 사고하여 답변한다.
-- 사용자의 요청에 대해 `.claude/rules/sd-clarify.md` 지침에 따라, 사용자의 의도를 명확화 한다. (절대 추측하지 않는다.)
+- 사용자 요청의 의도가 불명확할 때는 `/sd-inner-clarify` 스킬을 호출하여 명확화한다. 단순 정보 조회처럼 의도가 명확한 질문에는 위 "답변만 하라" 규칙을 따른다. (절대 추측하지 않는다.)
+- **CRITICAL: 맥락에 맞는 언어로 말한다**. 지금 대화의 층위가 무엇인지 먼저 파악하고 그 층위의 용어로 말한다.
+  - 업무 기능·요구사항 논의 → 업무 용어 (사용자가 화면에서 뭘 하는지)
+  - DB 스키마 설계 → 테이블·컬럼명
+  - 코드 구현 → 함수·클래스명
+  - 층위를 섞지 않는다. 업무 결정을 하면서 DB 컬럼명부터 던지거나, 스키마 설계를 하면서 업무 용어만 쓰지 않는다.
+- **한국 개발 현장 통용 용어 우선**: 한국 개발 현장에서 일반적으로 통용되는 용어를 우선 사용한다. 그런 용어가 없거나 불확실할 때는 한글 음차("시딩") 대신 영어 원문("seeding")을 그대로 쓰고, 처음 쓸 때 한 줄로 풀어 설명한다.
+- 사용자가 "무슨 소린지 모르겠다"는 취지로 되물으면, 같은 말을 반복하지 말고 **한 층위 위**(구현→스키마→업무)로 올라가서 다시 설명한다.
 
 # Playwright
 
@@ -55,14 +70,14 @@
 - 테스트 작성 시 `.claude/references/sd-testing.md`를 읽고 따른다.
 - 프론트엔드 UI 코드 작성·수정 시 `.claude/references/sd-frontend-design.md`를 읽고 따른다.
 - 디버깅 시 `/sd-inner-debug` 스킬을 호출한다.
-- 코딩을 하거나 코드예제를 출력할때는, 반드시 코드베이스의 기존 패턴을 확인하여 통일성있게 안내한다.
+- **CRITICAL: 코딩·코드예제 출력 시, 반드시 Grep/Glob/Read로 코드베이스의 유사 코드를 먼저 검색·확인한 뒤 동일 패턴으로 작성한다.** "이미 알고 있다", "일반적인 패턴이다" 등의 이유로 검색을 생략하는 것은 위반이다.
 - 코드를 수정할 경우 수정에 의한 사이드이펙트를 항상 고려한다. (예, html구조가 바뀌면 css의 selector도 바뀌어야함)
 - 함수 작성 혹은 함수내 기능 추가시 단일 책임 원칙을 따른다. (함수가 이름에서 드러나지 않는 일을 몰래 해선 안됨)
 - `src/`에는 프로덕션 코드만 둔다. 테스트에서만 사용하는 파일(타입 선언, 헬퍼 등)은 `tests/`에 위치시킨다.
 - **barrel export 금지**: `src/` 루트의 `index.ts`를 제외하고, 하위 폴더에 re-export 전용 `index.ts`를 만들지 않는다. 패키지 루트 `index.ts`에서 개별 파일 경로를 직접 export한다.
 - 다른 패키지의 타입등 re-export 금지.
 - **dynamic import (`import()`) 사용 금지**: 조건부 peer dependency 로딩, 외부 ts 파일 읽기 등 정적 import가 불가능한 경우를 제외하고 `import()` 사용 금지. 정적 `import` 문을 사용한다.
-- **CRITICAL: 구조화된 문법 처리 시 파서 사용 필수**: TypeScript/JavaScript, HTML, CSS, JSON, YAML 등 **문법 구조가 정의된 텍스트**를 분석·변환할 때는 반드시 해당 언어의 **공식 파서/AST**(예: TypeScript Compiler API, `@angular/compiler`, `postcss`, `parse5`, `JSON.parse` 등)를 사용한다. 정규식·문자열 치환으로 **우회 금지(NEVER)**. 정규식은 주석·문자열·중첩 구조·이스케이프 등 엣지 케이스에서 반드시 깨지며, "일단 되면 넘어가자" 식 접근의 전형적 사례이다. 파서 사용이 어렵거나 오버헤드가 크다고 판단되면 **사용자에게 먼저 질문**한다.
+- **CRITICAL: 구조화된 문법 처리 시 파서 사용 필수**: TypeScript/JavaScript, HTML, CSS, JSON, YAML 등 **문법 구조가 정의된 텍스트**를 분석·변환할 때는 반드시 해당 언어의 **공식 파서/AST**(예: TypeScript Compiler API, `@angular/compiler`, `postcss`, `parse5`, `JSON.parse` 등)를 사용한다. 정규식·문자열 치환으로 **우회 금지(NEVER)**. 정규식은 주석·문자열·중첩 구조·이스케이프 등 엣지 케이스에서 반드시 깨진다. 파서 사용이 어렵거나 오버헤드가 크다고 판단되면 **사용자에게 먼저 질문**한다.
 - **null/undefined 비교 규칙**: `===`/`!==` 사용이 기본이지만 **null/undefined 비교만 예외**이다. 일반 값 비교는 `===`/`!==`, null/undefined 검사는 `== null`/`!= null`을 사용한다. `=== null`, `!== null`, `=== undefined`, `!== undefined`는 lint 에러이다.
   - `value === "hello"` ○ (일반 값 비교 → `===`)
   - `value == null` ○ (null/undefined 검사 → `==`)
@@ -83,11 +98,11 @@
 
 # @simplysm 패키지 참조
 
-- `@simplysm/*` 패키지 사용 시, 해당 참조문서를 읽고 해당 패키지의 문서 경로를 찾아 읽는다.
-  - v14: `.claude/references/sd-simplysm14.md`
+- `@simplysm/*` 패키지 사용 시, 해당 패키지의 `README.md` 및 `docs/` 문서를 읽는다.
+  - v14: `node_modules/@simplysm/{패키지명}/README.md` (분량이 많은 항목은 `node_modules/@simplysm/{패키지명}/docs/*.md`)
   - v12: `.claude/references/sd-simplysm12.md`
-- 해당 문서에는 지침 및 사용법이 기록되어 있다.
-- 주의사항: 해당 패키지의 `CLAUDE.md`를 읽는것이 아니다.
+- 해당 문서에는 사용법 및 지침이 기록되어 있다.
+- 주의사항: 해당 패키지의 `CLAUDE.md`는 모노레포 **내부 개발자용 컨텍스트**이므로 소비앱에서 이를 읽지 않는다. 소비앱은 `README.md`와 `docs/`만 참조한다.
 - simplysm 패키지의 경우 context7은 구버전일 수 있으니 사용을 지양한다.
 
 # 프로젝트 경계

package/claude/rules/sd-options.md

@@ -1,17 +1,21 @@
 # sd-options: 선택지 제시 규칙
 
-사용자에게 선택지를 제시하는 **모든 상황**에서 아래 규칙을 따른다.
+사용자에게 질문, 제안등 선택지를 제시하는 **모든 상황**에서 아래 규칙을 따른다.
 
 - 각 선택지에 대해 **장단점/트레이드오프/10점 만점 점수**를 포함한다
-- **"수행 안 함"** 옵션을 반드시 포함한다 — 수정/변경을 하지 않는 선택지도 동일하게 장단점과 점수를 매긴다
-- **결정 대상**을 먼저 명시한 뒤, 선택지 정보를 아래 **근거 제시 규칙**에 따라 출력하고, `---` 구분선을 출력한 뒤 `AskUserQuestion`으로 질문한다
+- **"수행 안 함"** 선택지를 반드시 포함한다 — 수정/변경을 하지 않는 경우에도 동일하게 장단점과 점수를 매긴다
+- **결정 대상**을 먼저 명시한 뒤, 선택지 정보를 아래 **근거 제시 규칙**에 따라 출력하고, `---` 구분선을 출력한다.
+- **CRITICAL**: 선택지 출력 후에는 반드시 `AskUserQuestion` tool을 즉시 호출하여 사용자에게 선택을 요구한다
+  - 텍스트로 "진행할까요?", "어떤 걸로 할까요?", "선택해주세요" 등을 묻고 사용자 응답을 기다리는 것은 **위반**이다
 
 ## 결정 대상 명시 규칙
 
 선택지를 나열하기 **전에**, 이 결정이 **어디의 무엇**에 대한 것인지 한 줄로 명시한다.
 
-- 형식: `**결정 대상:** {파일경로:라인번호} — {대상 설명}`
-- 예시: `**결정 대상:** packages/angular/src/controls/input/sd-textfield.ts:45 — validate() 메서드의 에러 처리 방식`
+- 형식: `**결정 대상:** {파일경로:라인번호} — {대상 설명}` (대상이 여러 라인이어도 대표 라인/범위를 반드시 명시)
+- 예시 (단일 라인): `**결정 대상:** packages/angular/src/controls/input/sd-textfield.ts:45 — validate() 메서드의 에러 처리 방식`
+- 예시 (복수 라인): `**결정 대상:** .claude/rules/sd-options.md:8,31 — CRITICAL 키워드 사용 방식`
+- 예시 (범위): `**결정 대상:** .claude/skills/sd-use/SKILL.md:43-68 — 스킬 카탈로그 섹션`
 
 ## 근거 제시 규칙
 
@@ -27,11 +31,12 @@
 ## 복수 결정사항 처리
 
 - **CRITICAL: 결정사항이 여러 개일 경우, 반드시 한 번에 하나의 결정사항만 제시하고, 사용자 선택 후 다음으로 넘어간다.**
+  - 선택지 제시 후 `AskUserQuestion` 호출로 **응답을 완전히 종료**한다. 다음 결정사항은 **새 응답**에서 제시한다 (같은 응답 내 연속 제시 금지)
 - 이전 선택 결과에 따라 후속 결정사항이 변경·추가·삭제될 수 있으므로, 매 단계마다 남은 결정사항을 재평가한다
 - 남은 결정사항이 몇 건인지 알려준다 (예: "1/3건 완료")
 
 ## 점수 기준
 
 - 모든 점수는 **10점 만점**이다
-- LLM이 맥락에 맞는 관점(축)을 3개 이상 선정하여 관점별 점수를 매기고, **평균을 10점 만점으로 표시**한다
+- LLM이 맥락에 맞는 관점(축)을 3개 이상 선정하여 관점별 점수를 매기고, **축별 점수를 반드시 노출한 뒤 평균을 10점 만점으로 함께 표시**한다 (최종 점수만 쓰는 것 금지)
 - **하나의 선택지를 명시적으로 추천** — 추천 사유를 한 줄로 요약

package/claude/sd-subagent-start.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+if [ -f "CLAUDE.md" ]; then
+  echo "Project instructions from CLAUDE.md (auto-injected because subagent context omits it):"
+  echo
+  cat CLAUDE.md
+fi

package/claude/settings.json

@@ -1,16 +1,5 @@
 {
   "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "startup|resume|clear|compact",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash .claude/sd-session-start.sh"
-          }
-        ]
-      }
-    ],
     "PreToolUse": [
       {
         "matcher": "Edit|Write",
@@ -45,7 +34,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "bash .claude/sd-session-start.sh"
+            "command": "bash .claude/sd-subagent-start.sh"
           }
         ]
       }

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

@@ -13,19 +13,28 @@ description: typecheck, lint, test를 실행하고 에러 발생시 사용자
 
 #### 에러 처리 범위
 
-이 **대화(conversation)** 에서, sd-check 호출 전에 Claude가 코드를 수정한 것.
-- git status의 미커밋 변경이나 과거 커밋 변경을 말하는것이 아님.
-- sd-check 내부(typecheck/lint/test 단계)에서의 수정을 말하는것이 아님.
-- **CRITICAL**: sd-check 단독 실행시, 발견된 모든 에러를 수정해야함 (예: test 에러 발견시, typecheck/lint의 수정과는 별개로 모두 수정)
-- sd-check호출전 대화내 수정이 있었던 경우, 해당 수정과 관련된 에러만 수정 대상으로 봄
+발견된 에러가 **수정 대상**인지 판단하는 기준:
+
+- **sd-check 단독 실행 (이 대화에서 sd-check 호출 전 Claude의 코드 수정이 없음)**: 발견된 **모든 에러**가 수정 대상. "수정 대상 외"로 판단하여 스킵 금지(NEVER).
+- **직전 대화 내 코드 수정이 있음**: 해당 수정과 **관련된 에러만** 수정 대상. 무관한 에러는 조용히 스킵하되, 사용자에게 **보고하지 않는다** (그냥 넘어간다).
+
+판단 제외 — "직전 수정"에 해당하지 않는 것:
+- git status의 미커밋 변경, 과거 커밋 변경
+- sd-check 내부(typecheck/lint/test 단계)에서 발생한 수정
 
 #### 에스컬레이션 규칙
 
-**CRITICAL: 동일 에러가 2회 반복되면 즉시 수정을 중단하고 사용자에게 보고한다.**
+**CRITICAL: 아래 2가지 경우에만 사용자에게 보고/선택지 제시한다. 그 외 사유로는 절대(NEVER) 보고·질문·선택지 제시 금지.**
+
+화이트리스트 (이 2가지가 전부):
+1. **동일/유사 에러 2회 반복**: 1회차에 `/sd-inner-debug`로 근본 원인 분석 및 수정 시도 → 2회차 재발 시 중단하고 분석·시도 내역 보고.
+2. **원인 특정 불가**: 추측으로 수정 시도 금지, 즉시 보고.
 
-- 1회차: `/sd-inner-debug` 스킬을 호출하여 근본 원인을 분석하고 수정을 시도한다.
-- 2회차(동일/유사 에러 재발): 수정을 중단하고, 지금까지의 분석 결과와 시도한 수정 내용을 사용자에게 보고한 뒤 판단을 요청한다.
-- 원인을 특정할 수 없는 경우에도 즉시 사용자에게 보고한다. 추측으로 수정 시도 금지.
+**금지 사항 (자주하는 환각)**:
+- "본 작업 범위 밖이므로 보고", "수정 대상 외이므로 보고" 같은 규칙은 **존재하지 않는다**. 화이트리스트에 없는 사유로 보고/선택지 제시 금지.
+- 수정 대상 판단은 위 "에러 처리 범위" 섹션을 그대로 따른다. 임의 해석 금지.
+- 규칙을 인용할 때 기억에 의존하지 말고, 반드시 이 파일을 Read한 원문을 인용한다.
+- 화이트리스트에 없는 사유로 `AskUserQuestion`/선택지 블록을 만들지 않는다.
 
 ### 출력 캡처 규칙
 
@@ -72,7 +81,7 @@ Bash 출력이 길면 잘리므로 **반드시 파일로 리다이렉트**한
 탐지된 check 스크립트:
 1. typecheck → pnpm run typecheck
 2. lint → pnpm run lint
-3. test → pnpm vitest run
+3. test → pnpm vitest run --reporter=dot --silent=passed-only
 ```
 
 탐지된 스크립트가 없으면 오류 메시지를 출력하고 종료한다.
@@ -97,6 +106,28 @@ typecheck 명령어를 실행한다. (`출력 캡처 규칙`에 따라 파일로
 - 에러 발생 시: `에러 분석 및 수정`에 따라, 테스트 실패의 원인을 분석하고 코드를 수정한다.
 - 코드 수정후, 테스트 변경이 누락되었을 수 있음. 의도파악을 위해서 history확인이 필요할 수 있다.
 
-## Step 5: 반복 혹은 완료
+## Step 5: .verify.md 재검증
+
+`에러 처리 범위` 규칙에 따라 대상 `.verify.md`를 결정한다:
+- sd-check 단독 실행: 모든 `.verify.md`
+- 직전 수정 있음: 수정과 관련된 `.verify.md`만
+
+각 `.verify.md`는 체크박스가 없는 검증 항목 명세이다. 항목을 순회하며 LLM이 매번 재수행한다 — 코드를 읽고, 명령을 실행하고, 설정을 확인하여 각 항목의 통과 여부를 판단한다. 판단 결과는 파일에 기록하지 않는다 (파일은 명세 그대로 유지).
+
+- 문제 발견 시: test 실패와 동일하게 `에러 분석 및 수정` 규칙을 따른다.
+
+## Step 6: .spec.md 정합성 확인
+
+`에러 처리 범위` 규칙에 따라 대상 `.spec.md`를 결정한다 (Step 5와 동일).
+
+`.spec.md`는 사용자 수동 검증 문서이다. 각 문서의 전제 조건·수행 절차·기대 결과를 읽고, 관련 코드를 읽어 **의미적 정합성**을 LLM이 추론한다:
+- 절차에 등장하는 UI 요소·메서드·이벤트가 실제 코드에 존재하는가
+- 기대 결과가 현재 코드 동작과 일치하는가
+
+- 불일치 발견 시: 사용자에게 보고한다. **자동 수정 금지** — 코드가 맞는지 문서가 맞는지 LLM이 판단할 수 없으므로 사용자가 결정한다.
+
+## Step 7: 반복 혹은 완료
+
+typecheck, lint, test, `.verify.md` 재검증을 수행하는 동안 코드 수정이 있었으면 `typecheck`부터 다시 시작한다. 수정이 없었으면 완료.
 
-typecheck, lint, test를 수행하는 동안 코드 수정이 있었으면 `typecheck`부터 다시 시작한다. 수정이 없었으면 완료.
+(`.spec.md` 정합성 확인은 코드 수정을 유발하지 않으므로 반복 트리거가 아니다.)

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

@@ -1,17 +1,19 @@
 ---
 name: sd-claude-docs
-description: 프로젝트 분석을 통해 CLAUDE.md와 LLM용 usage 문서를 동시 생성하는 스킬. "init", "CLAUDE.md 생성", "usage 문서 생성", "LLM 문서 만들어줘", "패키지 문서 생성" 등을 요청할 때 사용한다.
-model: claude-sonnet-4-5
+description: 프로젝트 분석을 통해 CLAUDE.md(개발자용)와 README.md/docs(소비자용) 문서를 동시 생성하는 스킬. "init", "CLAUDE.md 생성", "README 생성", "LLM 문서 만들어줘", "패키지 문서 생성" 등을 요청할 때 사용한다.
+effort: low
 ---
 
-# sd-claude-docs: CLAUDE.md + usage 문서 통합 생성
+# sd-claude-docs: CLAUDE.md + README.md/docs 통합 생성
 
-프로젝트를 분석하여 CLAUDE.md(LLM 컨텍스트)와 usage 문서(LLM용 API 문서)를 한 번에 생성한다.
+프로젝트를 분석하여 CLAUDE.md(내부 개발 컨텍스트)와 README.md/docs/(소비자용 API 문서)를 한 번에 생성한다.
 설정 파일, 스크립트, 소스 코드에서 검증 가능한 사실만 추출한다. 기존 문서가 있으면 섹션 단위로 병합한다.
 
-- **라이브러리 프로젝트** (`private: true`가 아닌 패키지가 1개 이상): CLAUDE.md + `.claude/references/sd-{name}{ver}/` usage 문서 생성
+- **라이브러리 프로젝트** (`private: true`가 아닌 패키지가 1개 이상): CLAUDE.md + 각 패키지 내 `README.md`(+ 필요 시 `docs/`)
 - **소비앱** (모든 패키지가 `private: true`): CLAUDE.md만 생성
 
+CLAUDE.md는 모노레포 **내부 개발자(LLM 포함)** 용 컨텍스트이고, README.md + docs/는 **패키지 소비자** 용 API/사용 지침 문서다. 두 문서는 독립적으로 유지한다. 패키지 CLAUDE.md 최상단에는 README.md를 참조하도록 안내 문구를 삽입한다(Step 3에서 규정).
+
 ## 사용법
 
 ```
@@ -64,11 +66,12 @@ model: claude-sonnet-4-5
 - **라이브러리 프로젝트**: `private: true`가 아닌 패키지가 1개 이상 존재
 - **소비앱**: 모든 패키지가 `private: true`
 
-라이브러리 프로젝트인 경우 usage 문서 경로를 결정한다:
-1. 루트 `package.json`의 `name`에서 라이브러리명을 추출한다
-2. 루트 `package.json`의 `version`에서 메이저 버전을 추출한다
-3. usage 문서 경로: `.claude/references/sd-{name}{majorVersion}/` (예: `sd-simplysm14/`)
-4. 인덱스 파일 경로: `.claude/references/sd-{name}{majorVersion}.md` (예: `sd-simplysm14.md`)
+라이브러리 프로젝트인 경우 소비자용 문서의 출력 경로는 **해당 패키지 루트**다:
+- `README.md` → `{패키지 경로}/README.md`
+- 분량이 많은 경우 `{패키지 경로}/docs/*.md`
+- 단일 패키지 프로젝트면 루트가 곧 패키지 경로다 (`./README.md`, `./docs/`)
+
+`private: true` 패키지는 README.md / docs/를 생성하지 않는다 (CLAUDE.md만).
 
 ## Step 2: 분기
 
@@ -82,7 +85,7 @@ root 문서는 생성·변경하지 않는다.
 
 `workspaces` 필드가 없고 `pnpm-workspace.yaml`도 없으면 단일 패키지다.
 패키지별 CLAUDE.md는 생성하지 않는다. 바로 4단계로 진행하여 root 문서를 생성한다.
-라이브러리 프로젝트인 경우 `package-doc-gen.md`의 Step 2~4를 root에 직접 적용하여 `.claude/references/sd-{name}{ver}/usage.md` + `docs/`를 생성한다.
+라이브러리 프로젝트인 경우 `package-doc-gen.md`의 Step 2~4를 root에 직접 적용하여 루트의 `README.md` (+ 분량이 많으면 `docs/*.md`)를 생성한다.
 
 ### 전체 실행 — 모노레포
 
@@ -90,34 +93,33 @@ root 문서는 생성·변경하지 않는다.
 
 ## Step 3: 패키지별 문서 생성 (모노레포)
 
-각 패키지에 대해 **Agent 도구로 subagent(model: `claude-sonnet-4-5`)를 병렬 실행**한다.
+각 패키지에 대해 **Agent 도구로 subagent(effort: `low`)를 병렬 실행**한다.
 하나의 메시지에서 모든 패키지의 Agent 호출을 동시에 보낸다.
 
 ### subagent 프롬프트
 
 ```
-{패키지 경로}의 CLAUDE.md와 usage 문서를 생성한다.
+{패키지 경로}의 CLAUDE.md와 README.md/docs를 생성한다.
 
-## CLAUDE.md 생성
+## CLAUDE.md 생성 (`{패키지 경로}/CLAUDE.md`)
 
 `.claude/skills/sd-claude-docs/references/package-claudemd.md`를 읽고 그 지침을 따른다.
 
 루트 수준 설정 (이 내용과 동일한 정보는 패키지 CLAUDE.md에 반복하지 않는다):
 {1단계에서 추출한 코딩 규칙 및 컴파일러 설정 목록}
 
-## usage 문서 생성 {소비앱이면 이 섹션 생략}
+## README.md / docs/ 생성 {`private: true` 패키지이면 이 섹션 전체 생략}
 
 `.claude/skills/sd-claude-docs/references/package-doc-gen.md`를 읽고 그 지침을 따른다.
-출력 경로: `.claude/references/sd-{name}{ver}/{패키지명}/`
-{private: true인 경우} 이 패키지는 private이므로 usage 문서는 생성하지 않는다.
+출력 경로: `{패키지 경로}/` (README.md는 항상, docs/는 분량 분기 조건에 해당될 때)
 ```
 
-각 subagent는 소스 코드를 한 번 분석하여 CLAUDE.md(Key Patterns)와 usage 문서(API 문서) 모두에 활용한다.
+각 subagent는 소스 코드를 한 번 분석하여 CLAUDE.md(Key Patterns)와 README.md/docs(API 문서) 모두에 활용한다.
 
 ### subagent 반환 정보
 
 - CLAUDE.md 생성 여부
-- usage 문서 생성 여부 + 문서 구조 (usage 단독 / usage + docs/)
+- README.md 생성 여부 + 문서 구조 (README 단독 / README + docs/)
 - API 항목 수
 - 생성된 파일 목록
 
@@ -194,55 +196,25 @@ UI:       angular (Angular)
 - `console.*` 금지, `Buffer` 금지 → `Uint8Array`
 ````
 
-### sd-{name}{ver}.md (라이브러리 프로젝트만)
-
-라이브러리 프로젝트인 경우 `.claude/references/sd-{name}{ver}.md` 인덱스 파일을 생성/갱신한다.
-소비앱인 경우 이 단계를 건너뛴다.
-
-#### 포함할 내용
-
-- 패키지 목록 테이블 (`private: true`인 패키지는 제외)
-- 각 패키지의 usage 문서 경로 링크
-- 라이브러리 사용 시 주요 가이드 (기존 내용이 있으면 병합)
-
-#### 참고 예시
-
-```markdown
-# sd-simplysm14: @simplysm v14 소비앱 가이드
-
-{기존 가이드 내용 보존}
-
-## 패키지별 상세 문서
-
-| 패키지 | 문서 |
-|--------|------|
-| @simplysm/angular | [usage.md](./sd-simplysm14/angular/usage.md) |
-| @simplysm/core-common | [usage.md](./sd-simplysm14/core-common/usage.md) |
-```
-
-#### 병합
-
-기존 `sd-{name}{ver}.md`가 있으면 root CLAUDE.md와 동일한 병합 규칙을 적용한다.
-
 ## Step 5: 결과 보고
 
 ```markdown
 ## sd-claude-docs 결과
 
-| 패키지 | CLAUDE.md | usage 문서 | 구조 | API 항목 수 |
-|--------|-----------|------------|------|-------------|
+| 패키지 | CLAUDE.md | README.md | 구조 | API 항목 수 |
+|--------|-----------|-----------|------|-------------|
 | root | 생성 | — | — | — |
-| sd-simplysm14.md | — | 갱신 | 인덱스 | — |
-| @simplysm/core-common | 갱신 | 갱신 | usage 단독 | 35 |
-| @simplysm/angular | 갱신 | 갱신 | usage + docs/ | 126 |
-| @simplysm/storage | 생성 | 생성 | usage 단독 | 8 |
+| @simplysm/core-common | 갱신 | 갱신 | README 단독 | 35 |
+| @simplysm/angular | 갱신 | 갱신 | README + docs/ | 126 |
+| @simplysm/storage | 생성 | 생성 | README 단독 | 8 |
 | @simplysm/internal | 생성 | — (private) | — | — |
 
 ### 생성된 파일 목록
 - CLAUDE.md (root)
-- .claude/references/sd-simplysm14.md
 - packages/core-common/CLAUDE.md
-- .claude/references/sd-simplysm14/core-common/usage.md
-- .claude/references/sd-simplysm14/core-common/docs/types.md
+- packages/core-common/README.md
+- packages/angular/CLAUDE.md
+- packages/angular/README.md
+- packages/angular/docs/types.md
 - ...
 ```

package/claude/skills/sd-claude-docs/references/package-claudemd.md

@@ -11,6 +11,16 @@
 
 기존 파일이 없으면 병합을 건너뛴다.
 
+## 최상단 안내 문구 (필수)
+
+CLAUDE.md의 **제목(`# CLAUDE.md`) 바로 아래**, 모든 본문 섹션보다 앞에 아래 인용 블록을 삽입한다. 이미 존재하면 갱신하지 않고 그대로 둔다.
+
+```markdown
+> 이 패키지의 사용법 및 지침은 [README.md](./README.md) 및 [docs/](./docs/)를 참조한다.
+```
+
+예외: 해당 패키지가 `private: true`여서 README.md / docs/가 생성되지 않는 경우 이 문구를 삽입하지 않는다.
+
 ## 분석 대상
 
 1. `package.json` — 이름, 설명, dependencies
@@ -46,6 +56,8 @@ CLAUDE.md는 반드시 대화언어로 작성한다. 모호한 표현("적절히
 ````markdown
 # CLAUDE.md
 
+> 이 패키지의 사용법 및 지침은 [README.md](./README.md) 및 [docs/](./docs/)를 참조한다.
+
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 ## Package Overview

package/claude/skills/sd-claude-docs/references/package-doc-gen.md

@@ -1,7 +1,7 @@
 # 패키지 문서 생성 프로세스
 
-이 문서는 단일 패키지에 대한 usage.md 및 docs/ 문서 생성 프로세스를 기술한다.
-subagent가 패키지 경로와 출력 경로(`.claude/references/sd-{name}{ver}/{패키지명}/`)를 전달받아 아래 순서대로 수행한다.
+이 문서는 단일 패키지에 대한 소비자용 `README.md` 및 `docs/` 문서 생성 프로세스를 기술한다.
+subagent가 패키지 경로를 전달받아 아래 순서대로 수행한다. 출력 경로는 항상 해당 **패키지 루트**(`{패키지 경로}/README.md`, `{패키지 경로}/docs/*.md`)이다.
 
 ## Step 2: 엔트리포인트 & Export 체인 추적
 
@@ -74,38 +74,40 @@ region 주석이 없으면, re-export되는 파일의 디렉토리 구조를 카
 
 | 조건 | 문서 구조 |
 |------|-----------|
-| 카테고리 3개 이하 **그리고** API 항목 30개 이하 | usage 단독 |
-| 위 조건에 해당하지 않음 | usage.md (개요+목차) + docs/ (카테고리별 분할) |
+| 카테고리 3개 이하 **그리고** API 항목 30개 이하 | README.md 단독 |
+| 위 조건에 해당하지 않음 | README.md (개요+목차) + docs/ (카테고리별 분할) |
 
 ## Step 4: 문서 생성
 
 ### 작성 원칙
 
+- **기존 문서가 없으면** Step 2 분석 결과로 신규 작성한다. **있으면** `docs/` 하위 모든 파일(서브디렉토리 포함)을 읽어 분석 결과를 기준으로 정합성을 맞춘다.
 - **대화언어로 작성**한다
 - **소스에서 읽은 내용만** 문서화한다 — 시그니처는 직접 복사하고, 존재하지 않는 파라미터·반환 타입·동작을 만들어내지 않는다
-- **기존 문서의 시그니처를 신뢰하지 않는다** — 기존 docs/*.md의 코드블록(시그니처·멤버 이름·타입·required 여부 등)을 그대로 재사용하지 않는다. 반드시 소스 파일을 Read하여 확인한 내용만 작성한다. 단, 소스 코드와 무관한 내용(사용 가이드, 주의사항, 규칙 등)은 그대로 보존한다
+- **기존 문서의 시그니처를 신뢰하지 않는다** — 기존 README.md/docs/**/*.md의 코드블록(시그니처·멤버 이름·타입·required 여부 등)을 그대로 재사용하지 않는다. 반드시 소스 파일을 Read하여 확인한 내용만 작성한다.
+- **소스 코드와 무관한 내용(사용 가이드, 주의사항, 규칙 등)은 보존하는 것이 원칙이되, 현재 소스와 상충하면(없어진 API 언급, 옛 동작 기준 설명, 더 이상 유효하지 않은 규칙 등) 소스 기준으로 수정한다.**
 - **모든 export를 빠짐없이 문서화한다** — Step 2에서 수집한 export 목록의 모든 항목이 문서에 포함되어야 한다. "덜 중요하다"는 이유로 생략하지 않는다
 - **interface/type은 필드별 설명 테이블을 포함한다** — 시그니처만 나열하지 않고, 각 필드의 타입과 설명을 테이블로 작성한다. 소스에 필드가 있는 interface를 빈 `{}`로 표시하는 것은 금지한다 — 필드가 많더라도 모든 필드를 테이블로 나열한다
 - **union type은 discriminant와 각 variant를 설명한다** — discriminated union인 경우, 어떤 필드로 분기되는지와 각 variant를 나열한다
 
-### Step 4-1: usage.md 생성
+### Step 4-1: README.md 생성
 
-출력 경로: `.claude/references/sd-{name}{ver}/{패키지명}/usage.md`
+출력 경로: `{패키지 경로}/README.md`
 
 ```markdown
-# @simplysm/{package-name}
+# {package-name}
 
 {package.json의 description. 없으면 엔트리포인트의 export 구조에서 추론하여 한 줄 요약}
 
 ## Installation
 
 \`\`\`bash
-npm install @simplysm/{package-name}
+npm install {package-name}
 \`\`\`
 
 ## API Overview
 
-{usage 단독인 경우: 카테고리별로 API 전체 나열 — 4-2 형식과 동일}
+{README.md 단독인 경우: 카테고리별로 API 전체 나열 — 4-2 형식과 동일}
 {docs/ 분할인 경우: 카테고리별 요약 테이블 + docs/ 링크}
 
 ### {Category Name}
@@ -138,7 +140,7 @@ npm install @simplysm/{package-name}
 
 ### Step 4-2: docs/*.md 생성 (분할 대상 패키지만)
 
-카테고리별로 `.claude/references/sd-{name}{ver}/{패키지명}/docs/{category}.md`를 생성한다. 파일명은 카테고리를 영어 kebab-case로 변환한다.
+카테고리별로 `{패키지 경로}/docs/{category}.md`를 생성한다. 파일명은 카테고리를 영어 kebab-case로 변환한다.
 
 ```markdown
 # {Category Name}
@@ -197,12 +199,13 @@ Step 2B에서 스타일 항목이 수집된 경우, `{출력 경로}/docs/stylin
 
 ### Step 4-4: 완전성 및 정확성 검증
 
-문서 생성 후, Step 2에서 수집한 export 목록과 생성된 문서를 대조한다.
+문서 작업 후, Step 2에서 수집한 export 목록과 `docs/` 하위 모든 파일(서브디렉토리 포함) 및 README.md를 대조한다.
 
 #### 완전성 검증
 
-1. export 목록의 각 항목이 usage.md 또는 docs/*.md에 존재하는지 확인한다
+1. export 목록의 각 항목이 README.md 또는 `docs/` 하위 어느 파일(서브디렉토리 포함)에 존재하는지 확인한다
 2. 누락된 항목이 있으면 해당 API를 문서에 추가한다
+3. 문서에 있는 심볼 참조 중 **현재 export에 없는 것**(제거·이름 변경된 API)은 소스 기준으로 수정하거나 제거한다
 
 #### 정확성 검증
 
@@ -237,3 +240,13 @@ Step 2B에서 스타일 항목이 수집된 경우, `{출력 경로}/docs/stylin
 → 소스 기준으로 문서를 수정합니다.
 ```
 
+### Step 4-5: package.json `files` 배열 동기화
+
+생성된 `docs/`가 npm publish에 포함되도록 `{패키지 경로}/package.json`의 `files` 배열을 점검한다.
+
+1. `package.json`에 `files` 필드가 없으면 이 단계를 건너뛴다 (npm이 기본으로 전체 파일을 포함).
+2. `files` 필드가 있으면 아래 규칙으로 동기화한다:
+   - 이번 실행 후 `{패키지 경로}/docs/`가 존재하면, `files` 배열에 `"docs"`가 **없을 때 추가**한다.
+   - 이번 실행 후 `{패키지 경로}/docs/`가 존재하지 않으면(분량 축소로 단독 구조로 전환되었거나 Step 3 판단으로 `docs/`를 생성하지 않은 경우), `files` 배열에 `"docs"`가 **있을 때 제거**한다.
+3. `README.md`는 npm이 `files` 선언과 무관하게 항상 포함하므로 `files`에 추가할 필요가 없다.
+

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

@@ -1,7 +1,7 @@
 ---
 name: sd-commit
 description: 전체 변경사항에 대한 단일 커밋을 생성하는 스킬. "커밋", "commit", "변경사항 커밋" 등을 요청할 때 사용한다.
-model: claude-haiku-4-5
+model: haiku
 ---
 
 # sd-commit: 그룹별 커밋

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

@@ -9,9 +9,11 @@ description: 버그·동작 이상의 근본 원인 분석 및 해결책을 제
 
 `/sd-inner-debug` 스킬을 호출한다.
 
+**CRITICAL: 이 단계에서는 분석과 방안 선택만 수행한다. 코드 수정은 절대(NEVER) 하지 않는다.** 코드 수정은 Step 3에서 `/sd-dev`를 통해서만 수행한다.
+
 ## Step 2: 문서 기록
 
-전체 분석과 선택 결과를 문서에 기록한다.
+Step 1의 분석과 선택 결과를 문서에 기록한다. **코드 수정 전에 반드시 이 단계를 먼저 완료한다.**
 
 ### 출력 경로
 
@@ -48,7 +50,7 @@ description: 버그·동작 이상의 근본 원인 분석 및 해결책을 제
 - **선택 사유:** {사용자 코멘트 또는 선택 근거}
 ```
 
-## Step 3: 완료 후 행동
+## Step 3: 수정 개발
 
 1. 대화에 출력파일(`debug.md`) 파일 경로를 표시한다.
-2. `/sd-dev` 스킬을 호출하여 수정 개발을 시작한다.
+2. `/sd-dev` 스킬을 호출하여 수정 개발을 시작한다. **코드 수정은 반드시 이 단계에서 `/sd-dev`를 통해서만 수행한다.**

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

@@ -1,7 +1,7 @@
 ---
 name: sd-deliverable
 description: 코드 분석 기반으로 사용자 매뉴얼(md)과 SIT 문서(md)를 생성·업데이트하는 스킬. "매뉴얼 만들어줘", "SIT 문서 만들어줘", "산출물 생성", "매뉴얼 업데이트" 등을 요청할 때 사용한다.
-model: claude-sonnet-4-5
+effort: low
 ---
 
 # sd-deliverable: 매뉴얼 & SIT 생성

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

@@ -5,7 +5,8 @@ description: 요구명세 → 구현계획 → TDD 개발 → 체크 → 리뷰
 
 # sd-dev: 통합 개발 프로세스
 
-sd-wbs → sd-plan → sd-tdd → sd-check → sd-review를 순차 진행하는 오케스트레이터
+sd-wbs → sd-plan → sd-tdd → sd-check → sd-review를 순차 진행하는 오케스트레이터.
+**CRITICAL**: Step간 진행은 사용자 확인없이 즉시 다음 Step으로 진행한다.
 
 ## 공통 규칙
 
@@ -30,7 +31,7 @@ sd-wbs → sd-plan → sd-tdd → sd-check → sd-review를 순차 진행하는
 
 ## Step 3: sd-plan
 
-`/sd-plan` 스킬을 즉시 수행한다. 완료 후 즉시 Step 4로 진행한다.
+`/sd-plan` 스킬을 즉시 수행한다. 완료 후 사용자 확인 없이 즉시 Step 4로 진행한다.
 
 ## Step 4: sd-tdd
 
@@ -42,7 +43,7 @@ sd-wbs → sd-plan → sd-tdd → sd-check → sd-review를 순차 진행하는
 
 ## Step 6: sd-review
 
-`/sd-inner-review` 스킬을 호출하고, 발견사항에 대해 수정한다.
+`/sd-inner-review` 스킬을 호출하고, **모든** 발견사항에 대해 수정한다.
 
 - wbs/feature 문서를 읽고 잘 구현되었는지 함께 검토한다.
 - 수정사항이 있는 경우, `/sd-check` 스킬을 재 수행한다.
@@ -68,12 +69,16 @@ sd-wbs → sd-plan → sd-tdd → sd-check → sd-review를 순차 진행하는
 
 ### 변경 파일
 - {파일 경로 목록}
-```
 
-### 최종 리뷰 안내
+<!-- 아래 두 섹션 중 조건에 맞는 정확히 하나만 출력한다 -->
+
+### 남은 Feature  <!-- 미완료(`[ ]`) Feature가 1개 이상일 때만 출력 -->
+- {번호} {제목} (의존성: {있으면 명시})
+
+### 최종 리뷰 안내  <!-- 모든 Feature가 완료(`[x]`)일 때만 출력 -->
+`/sd-review {wbs디렉토리경로}/*.md 가 잘 구현되었는지, 문제는 없는지 최종 심층 리뷰`
+```
 
-wbs.md를 **다시 읽어서** Feature 체크박스를 확인:
+**MUST:** 완료 보고 출력 직전에 **반드시(MUST) wbs.md의 현재 상태를 다시 읽어** Feature 체크박스(`[x]`/`[ ]`)를 확인한 뒤, 위 두 섹션 중 조건에 맞는 정확히 하나만 출력한다.
 
-- 모든 Feature가 완료(`[x]`)된 경우, `/sd-review`를 사용한 최종 심층 리뷰를 안내한다.
-  (예: `/sd-review {wbs디렉토리경로}/*.md 가 잘 구현되었는지, 문제는 없는지 최종 심층 리뷰`)
-- 그 외의 경우에는 남은 Feature목록 및 각 Feature의 의존성을 안내한다.
+**NEVER:** 미완료(`[ ]`) Feature가 1개라도 남아 있으면 `/sd-review`를 어떤 형태로도(조건부·제안·예시 포함) 언급하지 않는다. "모든 Feature가 끝난 뒤 /sd-review를 권장" 같은 조건부 안내도 금지한다.