@simplysm/sd-claude 14.0.78 → 14.0.80

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

@@ -0,0 +1,44 @@
+# 코드 설계·변경 규칙
+
+Claude 에이전트가 코드 작성·설계·변경 시 따라야 할 행동 지침이다.
+
+## 인터페이스 설계 시
+
+- 산출물 소비자 표면(공개 API·props·옵션·UI·출력 등)의 단순함이 내부 구현 단순함보다 우선:
+  - 복잡도는 내부로 흡수
+  - 불가능할 경우 사용자 보고 후 결정
+- 내부 구현 난이도 회피를 위해 소비자 요구 완화·근사화 금지:
+  - 난이도는 내부로 흡수
+  - 불가능할 경우 사용자 보고 후 결정
+- 명시 정의 자체를 임의로 단순화하여 처리 금지:
+  - 정확 구현 부담이 크면 단순화안을 사용자에 보고 후 합의
+
+## 변경 전 기존 패턴 조사
+
+변경 전, 변경 영역의 기존 코드 패턴과 개발 매뉴얼을 먼저 조사한다.
+
+- `@simplysm/*` 14.x 패키지 변경 시 → `.claude/references/sd-simplysm14/README.md` 참조
+
+## 라이브러리 우회 금지
+
+- 의존 라이브러리 동작 이상 → 우회 코드 작성 전 라이브러리 측 원인 먼저 조사
+  - 라이브러리 버그·누락 판단 시 → 사용자에게 보고 후 수정 경로 혹은 이슈 발행 제안
+- 우회 코드 작성 금지:
+  - 불가피할 경우, 사용자 보고 후 결정
+
+## 에러 처리 시 throw 원칙
+
+문제 발생 시 throw:
+
+- silent skip 금지 — 예외 캐치 후 대안 없이 진행하면 후속 프로세스가 결손된 채 동작
+- **자동 복구** (예: 의존 미설치 → 설치·재시도 = 완전 동작 회복) 는 silent skip 아님
+
+## 사용자 표면 알림 작성 시 심각도 분류
+
+사용자 표면 알림(로그·토스트·다이얼로그 등)의 심각도 분류 기준:
+
+- `error` (danger): 문제 발생. catch·무시·재시도 여부와 무관하게 "문제가 일어난 사실" 이면 전부 해당
+- `warn`: 문제는 아니지만 사용자가 인지해야 할 중요 알림
+- `info`: 알면 좋은 일반 알림
+- `success`: 정상 완료 알림
+- 안티패턴: 무중단·복구 처리되었다는 이유로 `error` 대신 `warn` 선택 — 분류 기준 오용

package/claude/{sd-check-forbidden-files.py → sd-check-edit.py}

@@ -1,7 +1,8 @@
 import json, sys, os
 
 data = json.load(sys.stdin)
-file_path = data["tool_input"]["file_path"].replace("\\", "/")
+tool_input = data["tool_input"]
+file_path = tool_input["file_path"].replace("\\", "/")
 root = os.getcwd().replace("\\", "/")
 
 BLOCKED_FILES = [

package/claude/{sd-check-bash.py → sd-check-shell.py}

@@ -3,8 +3,8 @@ import json, re, sys
 data = json.load(sys.stdin)
 cmd = data["tool_input"].get("command", "")
 
-# Command position prefix: start of line or after command separator (&&, ||, ;)
-CMD_POS = r"(^|&&|\|\||;)\s*"
+# Command position prefix: start of line or after command separator (&&, ||, ;, |)
+CMD_POS = r"(^|&&|\|\||;|\|)\s*"
 
 BLOCKED = [
     # Blocked git commands

package/claude/settings.json

@@ -1,5 +1,4 @@
 {
-  "outputStyle": "sd-tone",
   "hooks": {
     "PreToolUse": [
       {
@@ -7,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python .claude/sd-check-forbidden-files.py"
+            "command": "python .claude/sd-check-edit.py"
           }
         ]
       },
@@ -21,11 +20,11 @@
         ]
       },
       {
-        "matcher": "Bash",
+        "matcher": "Bash|PowerShell",
         "hooks": [
           {
             "type": "command",
-            "command": "python .claude/sd-check-bash.py"
+            "command": "python .claude/sd-check-shell.py"
           }
         ]
       }

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

@@ -28,6 +28,12 @@ spec.md 화면 1개를 클라이언트 패키지의 화면 컴포넌트 자리
 
 없으면 묻기. spec.md 에 식별자 매칭이 안 되면 §4 화면 목록 표에서 후보 제시 후 확정.
 
+**[gate] 3단계 A (라이브러리 문서) 진입 전엔 3단계 이후 출력 금지**
+
+- 3단계 진입 시 A 부터 Read (B·C 보다 먼저).
+- 스킵 안티패턴 — "참고 코드 부재" 신호 (빈 패키지·답습 화면 없음·client 타겟 비어있음 등) 로 A 건너뛰고 B(본체 소스 grep)·C(부위별 수집) 점프
+- A 미진입 → 3단계 이후 모든 출력 보류
+
 ### 2단계: spec §4.x 분석
 
 §4.x 에서 추출:

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

@@ -11,7 +11,7 @@ spec.md 없이 진행하는 가벼운 코드 작업. 의도 합의가 끝나면
 
 ### 1단계: 의도파악
 
-사용자 발화를 토대로 무엇을 만들거나 바꿀지 합의. **1건씩 질문 → 답변 → 다음 건** (sd-base-rules "결정 근거"). 합의 결과는 대화 메모리에만 (필요 시 사용자가 `/sd-wip`).
+사용자 발화를 토대로 무엇을 만들거나 바꿀지 합의. **1건씩 질문 → 답변 → 다음 건** (sd-base-rules "결정 근거"). 합의 결과는 대화 메모리에만.
 
 다음을 확정해야 진행:
 

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

@@ -1,11 +1,11 @@
 ---
 name: sd-impl
-description: spec.md 의 단위(§4.x 화면 또는 §5.x 자동 처리) 1개를 현재 코드베이스 상태와 비교해 차이만큼 풀 구현(테스트·시연 포함)한다. Use when "화면 풀 구현", "데모를 실 구현으로", "화면 실가동", "자동 처리 풀 구현" 을 요청할 때.
+description: spec.md 의 단위(§4.x 화면 / §5.x 자동 처리 / §6.x 횡단 처리) 1개를 현재 코드베이스 상태와 비교해 차이만큼 풀 구현(테스트·시연 포함)한다. Use when "화면 풀 구현", "데모를 실 구현으로", "화면 실가동", "자동 처리 풀 구현", "횡단 처리 풀 구현" 을 요청할 때.
 ---
 
 # sd-impl
 
-spec.md 단위(§4.x 화면 또는 §5.x 자동 처리) 1개를 현재 코드베이스 상태와 비교해 빠지거나 어긋난 부분만큼 풀 구현한다. 데모 골격이 있으면 보존. 신규/갱신 무관 동일 워크플로. 끝에 사용자 시연으로 회귀를 잡는다.
+spec.md 단위(§4.x 화면 / §5.x 자동 처리 / §6.x 횡단 처리) 1개를 현재 코드베이스 상태와 비교해 빠지거나 어긋난 부분만큼 풀 구현한다. 데모 골격이 있으면 보존. 신규/갱신 무관 동일 워크플로. 끝에 사용자 시연으로 회귀를 잡는다.
 
 ## 본질
 
@@ -19,18 +19,18 @@ spec.md 단위(§4.x 화면 또는 §5.x 자동 처리) 1개를 현재 코드베
 ### 1단계: 입력 확보
 
 - 대상 spec.md 경로
-- 구현할 단위 식별자 — `§4.x` (화면) 또는 `§5.x` (자동 처리)
+- 구현할 단위 식별자 — `§4.x` (화면) / `§5.x` (자동 처리) / `§6.x` (횡단 처리)
 
-없으면 묻기. spec.md 에 식별자 매칭이 안 되면 §4 화면 목록 / §5 자동 처리 목록 표에서 후보 제시 후 확정.
+없으면 묻기. spec.md 에 식별자 매칭이 안 되면 §4 화면 목록 표 / §5 자동 처리 / §6 횡단 처리 헤더 목록에서 후보 제시 후 확정.
 
 ### 2단계: 외부 입력 점검 (BLOCKING)
 
-작업 대상 §4.x/§5.x 와 그가 참조하는 §5/§6/§7/§8 항목 점검:
+작업 대상 §4.x/§5.x/§6.x 와 그가 참조하는 §5/§6/§7/§8/§9 항목 점검:
 
 - **헤더 `[OPEN: 날짜]` 섹션**: 본문이 재분석 포인터일 뿐 임의안 부재 → sd-impl 해소 불가. 사용자 보고 후 **종료**. 사용자가 sd-spec 으로 확정 받은 뒤 sd-impl 재호출.
 - **본문 인라인 `[OPEN]`**: `sd-base-rules` "결정 근거" 적용 — 근거 없으면 1건씩 질문. 답변 후 즉시 spec.md 반영 → 다음 건. 결정이 다른 섹션의 구조 변경(필드 추가, 새 규칙 항목 등)을 요구하면 헤더 OPEN 과 동일 처리: 종료 + sd-spec 재호출. 종료 전 식별·보고:
   - sd-spec 에 넘길 변경 항목 (§ 위치 + 변경 내용)
-  - 그 변경이 영향 미치는 **다른 §4.x/§5.x 단위 목록** — 구조 변경된 §5/§6/§7/§8 항목을 spec 에서 역인용해 수집
+  - 그 변경이 영향 미치는 **다른 §4.x/§5.x/§6.x 단위 목록** — 구조 변경된 §5/§6/§7/§8/§9 항목을 spec 에서 역인용해 수집
   - 영향 단위 중 이미 구현된 것 / 미구현인 것 구분
 - **사용자 제공 예정 자료**: spec 본문에 "사용자 제공 예정" 류로 적힌 파일·값. 사용자 회신 후 진행.
 - **묵시적 모호**: 명시 마커 없지만 spec 본문이 분기·정의·정의식·경계 케이스를 다루지 않는 부분. 4단계 분해 표 작성 중 발견될 가능성 높음. 발견 시 본 단계로 회귀해 인라인 `[OPEN]` 절차 적용.
@@ -49,9 +49,9 @@ spec.md 단위(§4.x 화면 또는 §5.x 자동 처리) 1개를 현재 코드베
 
 풀 구현은 다층 흐름이 한 줄로 가야 일관성이 유지된다. 답습 단위 1개를 통째 답습하는 모델이 아니라, 기준 단위 1개를 잡고 비어있거나 부적합한 계층만 다른 단위에서 보강한다. 계층 간 의존성(모델 → 데이터 접근 → 본체 → 테스트)을 끊지 않으면서, 기준 단위에 부재한 계층의 LLM 단독 처방을 막는다.
 
-**4계층**: 도메인 모델 / 데이터 접근 / 본체(§4.x = 화면 컴포넌트, §5.x = 자동 처리 로직 + 트리거) / 테스트.
+**4계층**: 도메인 모델 / 데이터 접근 / 본체(§4.x = 화면 컴포넌트, §5.x = 자동 처리 로직 + 트리거, §6.x = 횡단 처리 로직 + 부수효과 후크) / 테스트.
 
-**B-1. 기준 단위 선정** (같은 종류 §4.x↔§4.x, §5.x↔§5.x 안에서):
+**B-1. 기준 단위 선정** (같은 종류 §4.x↔§4.x, §5.x↔§5.x, §6.x↔§6.x 안에서):
 
 1. 도메인/sub-app 인접 풀구현 단위 후보 Glob 탐색.
 2. 1개 → 자동 채택. 2개 이상 → 후보 목록 제시 후 사용자 1회 질문. 0개 → 같은 종류 전 범위로 확장 후 동일 규칙.
@@ -75,7 +75,7 @@ spec.md 단위(§4.x 화면 또는 §5.x 자동 처리) 1개를 현재 코드베
 
 ### 4단계: spec 분해 표
 
-대상 §4.x/§5.x 와 참조 §5/§6/§7/§8 본문을 **항목 단위까지 분해**해 표 작성. 표는 assistant 응답으로 출력 (이후 5·6단계 입력).
+대상 §4.x/§5.x/§6.x 와 참조 §5/§6/§7/§8/§9 본문을 **항목 단위까지 분해**해 표 작성. 표는 assistant 응답으로 출력 (이후 5·6단계 입력).
 
 | 항목 | spec 인용 | 현재 코드 상태 | 판정 | 매핑 파일 | 의존 |
 | ---- | --------- | -------------- | ---- | --------- | ---- |
@@ -133,7 +133,7 @@ spec.md 단위(§4.x 화면 또는 §5.x 자동 처리) 1개를 현재 코드베
 - **계층별 정합 점검**: 3-B 의 기준 단위 + 보강 출처 파일을 다시 Read 해 4계층별로 실제 작성분과 비교. 한 계층이라도 채택 패턴과 어긋나면 (임의 변형·새 발명) 수정.
   - 도메인 모델: 필드·타입·제약·네이밍 패턴 일치
   - 데이터 접근: 함수 시그니처·쿼리 패턴·에러 처리 일치
-  - 본체: 컴포넌트 구조·상태·핸들러·의존성 패턴 일치 (§4.x) / 트리거·처리 단계 구조 일치 (§5.x)
+  - 본체: 컴포넌트 구조·상태·핸들러·의존성 패턴 일치 (§4.x) / 트리거·처리 단계 구조 일치 (§5.x) / 부수효과 후크·처리 단계 구조 일치 (§6.x)
   - 테스트: 러너·assertion·mock 패턴 일치
 - **불필요한 코드**: 미사용 import·변수·주석, 요구 없는 옵션·추상화 제거. 작업 결과로 어디서도 참조되지 않는 파일도 포함 (검사 범위는 전체 워크스페이스). **단 파일 단위 삭제는 후보 목록을 사용자에게 보고 → 확정분만 삭제** (dynamic import·마이그레이션·문서 자산 등 보존분 사용자 제외).
 - **매뉴얼 권위 규약**: 3-A Read 한 매뉴얼 위반 항목 수정.
@@ -146,19 +146,20 @@ spec.md 단위(§4.x 화면 또는 §5.x 자동 처리) 1개를 현재 코드베
 
 **dev 서버·외부 프로세스 자체 실행 금지**: assistant 가 직접 `ng serve`·`npm run dev`·`vite`·`pnpm dev` 등으로 dev 서버를 띄우지 않는다. 사용자가 띄워 주소를 회신할 때까지 대기. 사용자가 본 단계 스킵을 지시하거나 시연 불가 환경이 명시되면 본 단계 스킵 후 9단계.
 
-주소 회신 후 `playwright-cli` 로 §4.x/§5.x 동작 시나리오 직접 시연:
+주소 회신 후 `playwright-cli` 로 §4.x/§5.x/§6.x 동작 시나리오 직접 시연:
 
 - 기능 개요·동작 사용자 흐름 1회씩 수행.
 - 화면 항목·와이어프레임 위치와 실제 렌더 비교.
 - §5.x (자동 처리) 는 트리거 발생 → 결과 확인.
+- §6.x (횡단 처리) 는 부수효과 트리거 동작 발동 → 결과·기록 확인.
 
 회귀 발견 시 5단계 회귀 → 수정 → 재시연.
 
 ### 9단계: 완료 보고
 
-- 대상 spec.md 의 해당 §4.x / §5.x 헤더 `[확정: 날짜]` 를 `[확정: 날짜, 구현: 오늘날짜]` 로 확장 (Bash `date +%Y-%m-%d`). 이미 `구현: …` 가 들어있으면 그 날짜만 갱신.
+- 대상 spec.md 의 해당 §4.x / §5.x / §6.x 헤더 `[확정: 날짜]` 를 `[확정: 날짜, 구현: 오늘날짜]` 로 확장 (Bash `date +%Y-%m-%d`). 이미 `구현: …` 가 들어있으면 그 날짜만 갱신.
 - 만들거나 갱신한 파일 목록 보고 (마커 부착한 spec.md 포함).
-- 본 세션에서 §5/§6/§7/§8 공통 자원을 신규/변경했다면, 그 자원을 참조하는 **다른 §4.x/§5.x 중 이미 구현된 것**을 spec 역인용으로 수집해 영향 단위 목록 보고 (재구현 필요 여부 사용자 판단용). 변경 없었으면 생략.
+- 본 세션에서 §5/§6/§7/§8/§9 공통 자원을 신규/변경했다면, 그 자원을 참조하는 **다른 §4.x/§5.x/§6.x 중 이미 구현된 것**을 spec 역인용으로 수집해 영향 단위 목록 보고 (재구현 필요 여부 사용자 판단용). 변경 없었으면 생략.
 - 시연에서 사용자 확인 끝나면 종료.
 
 ## 운용
@@ -167,4 +168,4 @@ spec.md 단위(§4.x 화면 또는 §5.x 자동 처리) 1개를 현재 코드베
 - **사용자 보고 어휘**: 코드 식별자(변수명·SQL 함수명·타입 키워드 등) 노출 금지. 도메인 어휘로 풀어 보고. (output-style `sd-tone` "산출물 소비자 도메인 어휘" 적용)
 - **spec.md 동기화**: sd-impl 이 직접 손대는 spec 변경은 다음 2건뿐. 헤더 OPEN·구조 변경은 2단계 규칙대로 종료 후 sd-spec.
   - 본문 인라인 `[OPEN]` 해소 시 마커를 결정 내용으로 교체 (2단계).
-  - 9단계 완료 시 §4.x/§5.x 헤더 `[확정: …]` 를 `[확정: …, 구현: 날짜]` 로 확장.
+  - 9단계 완료 시 §4.x/§5.x/§6.x 헤더 `[확정: …]` 를 `[확정: …, 구현: 날짜]` 로 확장.

package/claude/skills/sd-impl/references/spec-cross-check.md

@@ -20,7 +20,7 @@ sd-impl 의 spec ↔ 코드 독립 대조를 수행해줘.
 
 **대상**:
 - spec.md 경로: <절대경로>
-- 단위 식별자: <§4.x 또는 §5.x>
+- 단위 식별자: <§4.x / §5.x / §6.x>
 
 **참조 자료**:
 
@@ -37,7 +37,7 @@ sd-impl 의 spec ↔ 코드 독립 대조를 수행해줘.
 
 **작업**:
 
-1. spec.md 의 §<단위> 본문 + 참조 §5/§6/§7/§8 항목을 다시 읽는다.
+1. spec.md 의 §<단위> 본문 + 참조 §5/§6/§7/§8/§9 항목을 다시 읽는다.
 2. 현재 구현 파일을 모두 읽는다.
 3. spec ↔ 코드를 항목 단위로 1:1 대조 (단위 전체 대상. "이번 변경분만" 스코프 제한 없음).
 4. 차이 발견 시 아래 4분류로 보고:

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

@@ -1,45 +1,112 @@
 ---
 name: sd-skill
-description: 사용자가 정의한 작업 도메인을 SKILL.md + references/scripts 묶음으로 생성·수정한다. Use when 새 스킬을 작성하거나 기존 스킬을 수정할 때.
+description: 사용자가 정의한 작업 도메인을 SKILL.md + (필요 시) scripts 묶음으로 생성·수정한다. Use when 새 스킬을 작성하거나 기존 스킬을 수정할 때.
 ---
 
 # 스킬 작성
 
-## 워크플로
+워크플로 = 아래 § 1~6 순서. 처음부터 끝까지 읽으며 그대로 수행.
+
+## 1. 의도 정의
+
+다음 파악. **멀티질문 X — 항목 1건씩 합의** (sd-base-rules):
+
+- 다루는 작업/도메인?
+- 커버 유즈케이스?
+- 실행 스크립트 필요 / 지침만으로 충분?
+- 함께 포함할 참고 자료?
+
+## 2. Eval 시나리오 정의
 
-1. 의도 정의 - 다음을 파악한다. **멀티질문 X — 항목 1건씩 합의** (sd-base-rules "결정거리 1건씩 질문" 적용):
-   - 이 스킬이 다루는 작업/도메인은 무엇인가?
-   - 구체적으로 어떤 유즈케이스를 커버해야 하는가?
-   - 실행 가능 스크립트가 필요한가? 지침만으로 충분한가?
-   - 함께 포함해야 할 참고 자료가 있는가?
+채점 케이스: `evals/golden.jsonl`. 케이스 초기 워크스페이스: `evals/fixtures/<name>/`.
 
-2. Eval 시나리오 정의 (Golden Dataset) - 다음을 작성하라:
-   - 채점 기준이 될 케이스들: `evals/golden.jsonl`
-   - 케이스 시작 시점의 워크스페이스 초기 상태: `evals/fixtures/<name>/`
-   - 상세: [references/eval-authoring.md](references/eval-authoring.md)
-     - **주의**: 타 스킬 eval 확인 및 답습 금지, 이 상세지침만을 따를것
+**주의**: 타 스킬 eval 답습 금지, 아래 룰만 따를 것.
 
-3. 스킬 작성 - 다음을 작성하라:
-   - 간결하고 명확한 지침이 담긴 SKILL.md
-   - 별도의 참고파일 (필요한 경우)
-   - 유틸리티 스크립트 (필요한 경우)
-   - 상세: [references/skill-authoring.md](references/skill-authoring.md)
+### 자동답변 환경
 
-4. Eval 실행 및 판정
-   - 실행: `python .claude/skills/sd-skill/scripts/run_eval.py <대상-스킬-이름>`
-   - 상세 (동작/EVAL_MODE_PREFIX/출력 구조): [references/eval-run.md](references/eval-run.md)
-   - 사용자에게 보고: 전체 PASS/FAIL 카운트와 FAIL 케이스 목록.
+Eval 실행 시 사용자 응답 불가. 대상 스킬은 입력 필요 시점마다 **스스로 답변**하며 끝까지 진행 (대화 흐름·산출물 형식 검증용). 케이스 설계는 이 제약 전제.
 
-5. 스킬 및 Eval 개선
-   - FAIL 케이스의 reason 을 분석해 스킬 혹은 Eval 을 수정한 뒤, 같은 골든 셋 전체를 다시 4단계로 돌린다.
-   - 스킬의 문제인지 Eval 의 문제인지 모호하면 사용자에게 물어본다.
-   - 새로 발견한 실패 패턴은 골든 셋에 케이스로 추가한다.
+- `input` = 1턴 사용자 발화. 후속 응답 가정 X.
+- rubric = 자체 답변 가능 영역만 검증: 산출물 존재/형식/구조·흐름 진행 여부·frontmatter 키 등. *"사용자가 X 를 골랐을 때 Y 가 나오는가"* 처럼 특정 사용자 응답 값 의존 항목 금지 (자체 답변값은 매번 다름).
+- **사용자 응답 발생 자체 의존 rubric 금지**: 대상 스킬이 "사용자 질문"·"OPEN 처리/대기"·"임의 채움 금지" 룰 보유해도, 룰 발현 자체는 eval 검증 불가. 자동답변 환경은 사용자 답변 즉시 생성·진행 → "사용자 질문/대기" 흐름 본질적으로 미발생.
+  - ❌ `"사용자에게 질문하거나 OPEN 처리하는 흐름이 등장하는가"` (자체 답변으로 채운 뒤 진행 = 위반 아니라 환경 정상 동작)
+  - ❌ `"임의 채움 흔적이 없는가"` (자체 답변 자체가 "임의 채움" 으로 보임)
+  - 대응: 케이스 재설계 또는 `input` 본문에 룰 강조 명시 (예: "모호 발견 시 OPEN 마커만 spec 에 박고 종료")
+- fixture = 자체 답변 미차단되게 구성. 외부 시크릿·실시간 API 없이 진행 가능한 초기 상태로.
 
-6. 산출물 가독성 점검 (eval PASS 후)
-   - SKILL.md / references / scripts 를 다시 통독: "Claude 에이전트가 잘 이해하고 따를 수 있게 간결·명확한가? 중복·꾸밈·과한 예시는 없는가?"
-   - **표현·구조 정리만 허용, 의미 변경 금지.** 의미가 바뀌면 4단계로 회귀해 재검증.
+### 근거 제약
 
-## 스킬 구조
+eval 입력/rubric 의 근거 = **검증 대상 SKILL.md (수정 시: 수정 후 버전) 명세뿐**. 이전 버전 동작·대화 메모리의 옛 컨텍스트 인용 금지.
+
+- 검증 대상 명세에 없는 동작 → 입력·rubric 둘 다 등장 X
+- "이전 버전과 다르게 X 하는가" negative rubric 금지. 현재 명세상 X 요구 → `"X 하는가"` 로 직접 검증
+
+### Golden 케이스
+
+`evals/golden.jsonl`, 한 줄 한 케이스:
+
+```json
+{"id": "case-001", "input": "/<skill-name> ...", "rubric": ["체크 질문 1", "체크 질문 2"], "fixture": "<fixture-dir-name>"}
+```
+
+- `id`: 케이스 식별자
+- `input`: 평가 대상 스킬에 전달할 사용자 입력
+- `rubric`: PASS/FAIL 판정 체크 질문 목록
+- `fixture`: 케이스 시작 시점 샌드박스 초기 상태 디렉토리 이름
+
+**케이스 크기**: 한 케이스 작업량이 단일 실행 컨텍스트 소진 정도로 크면 X. eval = 흐름·산출물 형식 검증 목적 → 풀 구현·대량 분석 요구 input 회피, 최소 시연 수준으로 좁힘. 본질이 큰 풀구현 스킬은 input 의 평가 환경 단서로 rubric 검증에 불필요한 워크플로 단계를 명시 스킵.
+
+### Rubric 작성
+
+각 항목 = **PASS/FAIL 판정 가능한 명확한 체크 질문**. 추상 표현 → judge 판단 흔들림 → 회피.
+
+**모호 부사·형용사 회피** ("잘"·"적절히"·"합리적으로"·"명확히" → 기준이 사람마다 다름):
+
+- ❌ `"한국어 지원이 잘 되었는가?"` ("잘" 모호)
+- ✅ `"본문에 한국어 응답 강제 지시가 명시적 문장으로 들어갔는가?"`
+
+**형식 검증 선호** (의미보다 형식·존재 여부 → judge 흔들림 ↓):
+
+- ❌ `"description 이 트리거 조건을 명확히 표현하는가?"`
+- ✅ `"description 끝에 'Use when ~' 형식 문장이 포함되었는가?"`
+
+**관찰 가능 산출물에 묶기** (파일 존재·특정 키 포함·특정 디렉토리 구조 등 tree/events 에서 직접 확인 가능한 사실):
+
+- ✅ `"기존 .claude/skills/review/SKILL.md 파일이 손실되지 않고 보존되었는가?"`
+- ✅ `"SKILL.md frontmatter 에 name·description 키 모두 존재하는가?"`
+
+**명세 어휘 매칭 금지**: 명세 특정 단어를 rubric 에 그대로 박아 정확 매칭 요구 X. LLM 응답은 동의어·다른 표현으로 동일 본질 전달 → 어휘 정확 매칭 = 본질-무관 FAIL 양산. rubric 은 본질(형식·구조·존재 여부)만 검증.
+
+- ❌ `"분해 표 첫 컬럼이 '항목' 인가"` (LLM 이 'ID'·'식별자' 로 출력해도 본질 동일)
+- ✅ `"분해 표가 마크다운 표 형식으로 출력되고 컬럼 6개 모두 존재하는가"`
+
+**도구명 매칭 금지**: "events 에 특정 도구(Glob/Grep/Read 등) 호출이 있는가" 는 그 도구 사용 자체가 본질일 때만. 본질이 "탐색·조사·읽기" 등 행위면 동등 효과의 다른 도구(Bash 의 ls/find/dir/cat 등) 도 PASS.
+
+- ❌ `"events 에 Glob 또는 Grep 호출이 1회 이상 있는가"` (Bash ls/find 로 동등 효과인데 FAIL)
+- ✅ `"events 에 코드베이스 탐색 흔적(Glob·Grep 호출 또는 Bash 의 ls/find/dir 등 동등 명령) 이 1회 이상 있는가"`
+
+### Fixtures
+
+`evals/fixtures/<name>/` = 케이스 시작 시점 샌드박스 초기 상태. 케이스 실행 시 통째로 샌드박스 복사.
+
+- **빈 워크스페이스**: 디렉토리만 (`.gitkeep` 등 자리 표시)
+- **기존 스킬 수정 케이스**: 그 스킬의 SKILL.md + 관련 파일 미리 배치
+
+예: `with-existing-review/.claude/skills/review/SKILL.md` — 케이스 시작 시 review 스킬 기존 존재 상태.
+
+### 케이스 커버리지
+
+골든 셋이 단순 PASS 외 다음 분기 커버 시 회귀 감지 강화:
+
+- 신규 작성 / 기존 수정 각각
+- 워크플로 주요 분기점 (예: 스크립트 필요/불필요, 참조 파일 분리 필요/불필요)
+- 과거 실패 패턴 — FAIL 케이스 reason 분석 후 재발 방지용 추가
+
+## 3. 스킬 작성
+
+간결·명확한 SKILL.md + 별도 참고 파일 (필요 시) + 유틸리티 스크립트 (필요 시).
+
+### 디렉토리 구조
 
 ```
 .claude/
@@ -55,3 +122,116 @@ description: 사용자가 정의한 작업 도메인을 SKILL.md + references/sc
         └── scripts/             # 유틸리티 (선택)
             └── *.py
 ```
+
+### SKILL.md 템플릿
+
+```markdown
+---
+name: skill-name
+description: 기능 설명. Use when [활용상황]
+---
+
+# 스킬 이름
+
+## 워크플로
+
+[단계별 절차]
+```
+
+### description
+
+에이전트의 라우팅 진입점. 에이전트가 description 으로 사용자 요청에 맞는 스킬 호출.
+
+**전달 정보**:
+
+- 이 스킬의 목적
+- 트리거 맥락 (언제·왜)
+- 타 스킬과 구분 단서
+
+**형식**:
+
+- 최대 200자, 한 줄
+- 3인칭
+- 첫 문장: 입력 → 산출물(또는 효과). 내부 처리 단계 금지.
+- 두 번째 문장: "Use when [활용상황]"
+
+**금지**: 내부 단계·알고리즘·사용 도구·로직 흐름 → SKILL.md 본문 워크플로의 몫. description 은 외부 관찰 경계(입력·산출물·트리거)만 노출.
+
+### 스크립트 추가 기준
+
+다음 시 유틸리티 스크립트 추가:
+
+- 동작이 결정론(deterministic)적 (validation·formatting)
+- 코드 생성이 매번 동일
+- 에러 명시 처리 필요
+
+스크립트 → 토큰 절약 + 안정성 개선.
+
+**작성 원칙**:
+
+- Python(`.py`) 으로 작성
+- 내부 에러 처리 X. 에러 즉시 throw.
+
+### 파일 분리 기준
+
+다음 시 별도 파일 분리:
+
+- SKILL.md 분량이 에이전트가 한 자리에서 워크플로 흐름 인식 어려울 만큼 누적
+- 명백히 다른 도메인
+- 거의 안 쓰는 고급 기능
+
+## 4. Eval 실행
+
+### 명령
+
+`python .claude/skills/sd-skill/scripts/run_eval.py <대상-스킬-이름>`
+
+대상 스킬에 `evals/golden.jsonl` + `evals/fixtures/<fixture-name>/` 필요.
+
+### 동작
+
+케이스마다:
+
+1. 격리 작업 공간 준비 (`.claude/` 복사 + fixture 오버레이)
+2. 대상 스킬 실행. `EVAL_MODE_PREFIX` 가 사용자 입력에 prepend 되어, 대상 스킬이 입력 필요 시점마다 스스로 답변하며 끝까지 진행하도록 지시. 자체 답변은 사용자 명시 발언과 동등 취급 (다이얼로그 기반 스킬도 평가 가능, 단 자체 답변이라 흐름·형식 검증용)
+3. 에이전트 동작 기록 + 종료 시점 파일 트리 수집
+4. 별도 평가 에이전트가 rubric 항목별 PASS/FAIL 채점 → 모두 PASS 시 케이스 PASS
+
+### 출력 구조
+
+stdout: summary JSON
+
+- `run_id`, `results_dir`
+- `summary`: total / pass / fail / error
+- `cases[]`: 케이스별 verdict + 결과 dir 경로
+
+각 케이스 결과 파일 (`results_dir/cases/<id>/`):
+
+- `judge_output.json` — rubric 항목별 PASS/FAIL + reason
+- `events.json` — 에이전트 이벤트 시퀀스
+- `tree.json` — 샌드박스 종료 시 파일 트리
+
+## 5. 스킬·Eval 개선
+
+- 보고: 전체 PASS/FAIL 카운트 + FAIL 케이스 목록
+- FAIL reason 분석:
+  - 결과 파일 (`judge_output.json`·`events.json`·`tree.json`) read
+  - 스킬/Eval 어느 쪽 문제인지 판단
+  - 모호 시 사용자 질문
+- 수정 → 같은 골든 셋 전체 § 4 재실행
+- 새 실패 패턴은 골든 셋에 케이스 추가
+
+## 6. 산출물 가독성 점검
+
+eval PASS 후 SKILL.md / references / scripts 재통독: "에이전트가 잘 이해·수행 가능? 중복·꾸밈·과한 예시 없음?"
+
+### 리뷰 체크리스트
+
+- [ ] description 에 트리거 포함? ("Use when ~")
+- [ ] description 에 내부 단계·알고리즘·도구 미포함?
+- [ ] SKILL.md 분량이 에이전트가 한 자리에서 워크플로 인식 가능?
+- [ ] 용어 일관?
+- [ ] 구체 예시 포함?
+- [ ] 참조 깊이 한 단계? (SKILL.md → references/X.md 까지만. references 파일 안에서 또 다른 파일 참조 X)
+
+**표현·구조 정리만, 의미 변경 X.** 의미 변경 시 § 4 회귀.