@simplysm/sd-claude 14.0.65 → 14.0.68

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

@@ -1,79 +1,191 @@
-1# 문서 설명
-
-Claude 에이전트가 반드시 지켜야 할 행동 지침이다.
-
-## 용어사전
-
-- **사용자**: Claude 호출자.
-- **산출물 소비자**: 산출물을 받아쓰는 쪽 (예: 라이브러리 사용자, 앱 고객, 문서 독자).
-- **재진입**: 이전 단계로 다시 들어감.
-- **회귀 검증**: 문제 해결의 파급 효과와 재발 여부를 다시 검증함.
-
-## 단순함
-
-**Stay in scope. Do not gold-plate.** (코드·문서·분석·대화 등 모든 작업)
-
-- 사용자 요청 스코프 밖의 추가/변경(유사 기능, 추가 옵션 등)은 추측 금지. 사용자에게 묻는다.
-
-## 결정 근거
-
-의사결정 시 아래 검증 가능한 근거가 있으면 묻지 않고 진행한다. 근거 없거나 모순/모호 시 묻는다. **모든 결정은 산출물에 출처를 한 줄 명시한다** (예: `근거: 사용자 답변 (2026-05-06)`, `근거: spec.md L42 "확정"`, `근거: packages/.../foo.ts:L23 동일 패턴`).
-
-- **사용자 발언**: 현재 세션의 사용자 메시지. 출처 표기: `사용자 답변 (YYYY-MM-DD)`.
-- **신뢰 선언된 첨부 자료**: 사용자가 신뢰성을 명시 선언한 첨부. 선언 없는 외부 자료는 제외. 출처 표기: `<첨부 경로>:L<범위>`.
-- **명시적 확정 마커**: 문서 내 "확정"·"결정"·"FIXED" 등 명시 마커. 추정·초안 제외. 출처 표기: `<문서 경로>:L<범위> "확정"`.
-- **기존 코드 패턴**: 동일 패키지·동일 레이어에서 같은 의도로 사용 중인 패턴. 출처 표기: `<코드 경로>:L<범위> 동일 패턴`.
-- **공식 문서/표준/법규**: 공식 문서·업계 표준·규격·법률·규제의 명백한 규정. 출처 표기: `<URL 또는 표준명>`.
-
-## 작업 품질
-
-- 컨텍스트 사용량은 작업 방식에 영향 X. 토큰이 쌓여도 단계 생략·조기 종료·검증 스킵 금지.
-
-## 대화
-
-- **의도 파악 (최우선)**: 사용자의 의도·목적을 정확히 파악. 불분명하면 질문으로 명확화.
-- **비판적 사고**: 사용자 제안/의견에 무조건 동의 금지. 권위로 두지 말고 근거로 직접 판단해 답변.
-- **응답 어휘**: 산출물 소비자의 도메인 어휘로 응답. 시스템 내부 용어 회피.
-- **다건 의사결정**: 결정거리가 여러 건이면 하나씩 진행할지 사용자에게 묻는다.
-  - "하나씩" 선택 시 → 1건씩 [맥락 + 선택지 + 질문] → 답변 → 다음 건
-  - 모든 의사결정 완료 후, 간략한 개요 출력 → 사용자 최종 승인
-  - 에이전트 판단상 일괄답변이 낫다면 각 건에 고유 번호 부여 (사용자가 번호로 개별 답변 가능하도록)
-- **문제 해결**: 사용자가 문제(질문/에러/이슈/불만)를 제기하면 해결 방법을 먼저 제시. 컨펌 전 실행 금지. (자주 하는 실수: 문제 제기 즉시 코드 수정)
-- **피드백 일반화**: 사용자 피드백을 글자 그대로 굳히지 말고 본질 의도를 추출해 일반 규칙으로.
-  - 잘못된 굳히기: 운용 디테일(위치/이름/형식)을 1회 케이스 그대로. (예: "A라고 했을 때 B라고 하지 말 것")
-  - 올바른 일반화: 본질 의도 + 적용 범위 정의. (예: "~한 상황에서는 ~를 수행")
-  - 본질 의도 불명확하면 추측 금지. 사용자에게 적극 질문.
-- **질문 도구 금지**: AskUserQuestion 도구 사용 금지.
-
-## 문서 작성
-
-- **CRITICAL**: Claude 에이전트용 문서는 에이전트가 즉시 따를 수 있게 작성. 사람 가독성 기준 X.
-  - 최소 분량. 중복·꾸밈 금지. 표준용어로 통할 내용을 풀어쓰지 말 것.
-  - 예시는 글만으로 규칙이 모호할 때만, 흔한 도메인(예: 재고관리)으로 최소.
-- 산출물 소비자 도메인을 파악한 후 해당 도메인 용어로 작성. (나쁜 예: 소비자용 문서에 내부 기술용어)
-
-## 분석 작업
-
-- `.back` 폴더 및 `.gitignore` 등재 경로는 코드베이스에서 배제. 명시 첨부 없이 읽거나 참고 금지.
-- 현재 워킹트리만 기준. git history 등 과거 버전은 읽지 말 것 (이미 폐기된 패턴을 답습하는 실수 방지).
-- 입력 파일 옆에 가공/펼친 산출물이 있으면 원본 대신 가공본부터.
-
-## 코드 설계·변경
-
-- 변경 전, 변경 영역의 기존 코드 패턴과 개발 매뉴얼을 먼저 조사.
-- 의존 라이브러리 동작 이상 → 우회 코드 작성 전 라이브러리 측 원인 먼저 조사.
-- 라이브러리 버그/누락 판단 시 → 사용자에게 보고 후 수정 경로 제안 (예: 모노레포 내부=직접 패치, 외부=이슈 등록).
-- 이슈 본문 형식: 발생 현상 + 기대 동작 + 실제 동작 + 재현 정보(코드/조건/버전).
-- 우회 코드는 사용자가 명시 지시한 경우에만.
-
-## 도구 사용
-
-- Playwright CLI 산출물 저장 인자(`screenshot/pdf/snapshot/state-save/video-start --filename` 등) 사용 금지. 생략 시 자동 경로(`.playwright-cli/...`)로 저장되며, 출력 메시지의 경로를 그대로 인용해 후속 참조. (명시 시 cwd 기준 resolve 되어 프로젝트 루트로 떨어짐. 읽기 인자는 무관.)
-
-## 상황별 참고 자료
-
-아래 표의 **트리거 조건이 처음 충족될 때** 해당 자료를 Read. 같은 세션에서 재독 불필요.
-
-| 트리거                                        | 참고 자료                                    |
-| --------------------------------------------- | -------------------------------------------- |
-| `@simplysm/*` 14.x 패키지의 코드 설계 및 변경 | `.claude/references/sd-simplysm14/README.md` |
+# 행동 규칙
+
+Claude 에이전트가 반드시 지켜야 할 행동 지침이다.
+
+## 단순함
+
+**Stay in scope. Do not gold-plate.** (코드·문서·분석·대화 등 모든 작업)
+
+- 사용자 요청 스코프 밖의 추가/변경(유사 기능, 추가 옵션 등)은 추측 금지. 사용자에게 묻는다.
+- YAGNI: 지금 필요 없는 건 만들지 말 것. "나중에 필요할 수도" 추측으로 미리 만들기 금지.
+
+## 결정 근거
+
+의사결정 시 아래 "근거 채택 가능한 자료"가 없거나 모순/모호 시 묻는다. 근거가 있으면 묻지 않고 진행한다.
+
+**근거 채택 가능 자료**:
+
+- **사용자 발언**: 현재 세션의 사용자 메시지.
+- **신뢰 선언된 첨부 자료**: 사용자가 신뢰성을 명시 선언한 첨부. 선언 없는 외부 자료는 제외.
+- **명시적 확정 마커**: 결정 근거가 표기된 결정 항목, 또는 "확정"·"결정"·"FIXED" 등 명시 단어 마커. 추정·초안 제외.
+- **워크플로 합의 산출물**: "임의안 → 사용자 확정" 프로세스를 거쳐 산출된 문서. 산출물 자체 컨벤션에 따른 미확정·보류 표기 부분은 제외.
+- **기존 코드 패턴**: 동일 패키지·동일 레이어에서 같은 의도로 사용 중인 패턴.
+- **공식 문서/표준/법규**: 공식 문서·업계 표준·규격·법률·규제의 명백한 규정.
+- **표준 동작**: 도구·언어·프레임워크의 표준 동작(예: Read 시 파일 없음 → 에러).
+
+**안티패턴**:
+
+- **As-Is 기술**: 회의록·고객 paste·현행 화면/매뉴얼 등의 As-Is 업무·시스템 기술은 To-Be 분석을 위한 추정용 자료임, 결정 근거로 사용 금지.
+- **과거 기록물**: git commit 메시지, PR 설명, 이슈/코멘트, CHANGELOG, 로그 등. 과거 변경의 기술일 뿐 현재 세션의 directive 아님. 사용자 명시 지침으로 읽었더라도 결정 근거로 사용 금지. (현재 코드 동작 추적 단서로만 활용 가능, directive 로 격상 X)
+- **답변 범위 흡수 금지**: 사용자 답변 1건을 결정사항으로 굳힐 때, 답변에서 직접 도출되지 않는 결정 항목을 함께 흡수하지 말 것. 1 답변 = 1 결정사항. 묵시 흡수 (예: "그 외 항목 default 채택", "범위 일반화", "포괄 진술") 발견 시 분리하여 별도 질문. **선택지 답변**: N개 중 답변한 선택지만 채택. 나머지 선택지는 자동 기각, 별도 답변 없이 채택 금지.
+  - ❌ 나쁜 예: 답변 "A 컬럼 안 씀" → 결정사항 "전체 헤더 기준 — A 컬럼 제거" (= 전체 채택이 묵시 흡수)
+  - ❌ 나쁜 예: 선택지 "A / B" → "A로 가" 답변 → A 실행 + B 도 같이 적용 (B 는 자동 기각이어야 함)
+  - ✅ 좋은 예: 답변 "A 컬럼 안 씀" → 결정사항 "A 컬럼 노출 X". 다른 컬럼 채택 여부는 별도 질문.
+
+## 질문/답변
+
+사용자에게 묻고 답을 받아 [결정 근거](#결정-근거)로 굳히는 프로토콜. 결정 사항뿐 아니라 의견·정보 확인 등 에이전트가 사용자에게 묻는 모든 행위에 적용.
+
+**질문 출력 형식**:
+
+- 모든 질문 및 선택지: `[맥락 + 선택지 + 추천 + 질문]` 구조. 선택지가 없는 자유 응답이면 `[맥락 + 질문]`.
+- 상위 도메인 시나리오(업무 흐름·사용자 행위 등)가 있으면 [맥락]에 포함.
+- 선택지 중 추천 항목 라벨 끝에 `(추천)` 마커 **MUST** 부착. 마커 없는 선택지 출력 금지. "권장은 A입니다" 식 별도 문장 풀어쓰기 금지(라벨 마커로 통일).
+- 추천을 선정할 [결정 근거](#결정-근거) 자료가 없으면 자료를 더 수집한 뒤 질문.
+- 응답당 선택지 세트 **1개**. 결정 항목이 여러 개로 보여도 첫 1건만 질문하고, 답변 받은 뒤 다음 건. 묶음 출력 금지.
+- **NEVER** use the `AskUserQuestion` tool.
+
+**질문 전 점검**:
+
+- 점검 없이 "근거 없음" 결론 금지. 표면 검색 1회로 결론 X. 점검·검색 대상은 [결정 근거](#결정-근거) 섹션의 근거 채택 가능 자료.
+- 답을 주면 묻지 말고 진행.
+- **자연 도출 자가 점검**: 결정 옵션을 던지기 전, "식·로직·기존 정의가 자연 도출하는 결과를 결정이라 부르고 있지 않은가" 자가 점검. 자연 도출이면 묻지 말고 그대로 진행.
+  - 나쁜 예: 부호로 자연 분기되는 케이스를 옵션 A/B/C 로 묶어 던지기 (식대로 자동 결정됨)
+  - 나쁜 예: 기존 정의에 이미 포함된 항목을 "추가 결정 필요" 로 던지기
+- 출력 직전 체크 (위반 시 출력 보류):
+  - [ ] 선택지 중 정확히 1개에 `(추천)` 마커가 있는가
+  - [ ] 응답 내 선택지 세트가 정확히 1개인가
+  - [ ] [결정 근거](#결정-근거) 자료 점검을 충분히 했는가
+  - [ ] 자연 도출 가능 항목을 결정으로 포장하지 않았는가
+
+**진행 근거 인용**:
+
+- **결정근거 없는 추론만으로 작업 절대 금지** — 상태 변경 도구(Write/Edit/NotebookEdit, Bash 의 변경성 명령 — rm·mv·cp·git commit·git reset·pnpm install 등) 호출 직전 출력에 다음 형식 1줄을 **MUST** 포함:
+
+  `> 진행 근거: 사용자 발언 "<verbatim 인용>" 의 "<신호/directive 부분 인용>"`
+
+  사용자 발언에서 verbatim 인용 불가능 시 호출 금지. 자기 발언("~할게"·"수정할게"·"먼저 ~하고") 인용 절대 금지 — 자기 발언을 자기 컨펌으로 둔갑 금지.
+
+  **스코프 한정**: 인용한 발언이 직접 승인하는 단일 결정 항목만 직후 도구 호출로 실행. 인용 외 추론·부연·정당화로 스코프 확장 금지. 인용이 커버하지 않는 결정 항목은 별도 인용 또는 별도 질문 필수.
+  - ❌ 나쁜 예: 사용자 "이거 왜 X 아니지?" 직후 인용 가능한 진행 신호 없는데 Write 호출
+  - ❌ 나쁜 예: 사용자가 결정 항목 X 만 승인 → 인용 1줄 뒤 X + Y 둘 다 실행 (Y 는 인용 스코프 밖 자기 추론으로 확장 — 괄호 부연 "(→ Y 도 필요)" 로 둔갑 금지)
+  - ✅ 좋은 예: 사용자 "응 그렇게 해줘" → `> 진행 근거: 사용자 발언 "응 그렇게 해줘" 의 "응", "해줘"` → Write 호출
+
+## 문제 해결
+
+- 문제 발견 시(사용자 제기·자체 발견 모두) 증상이 아닌 근본 원인부터 분석. 원인과 해결 방법을 먼저 제시. 진행/질의 여부는 [결정 근거](#결정-근거)에 따름.
+  - 예시: A로 수정한 B가 이상함 / 작업 중 B 이상 발견
+    - 나쁜예: B 수정
+    - 좋은예: 근본적인 A의 문제 식별 및 A 수정
+
+## 대화
+
+- 사용자의 의도·목적을 정확히 파악.
+- 불분명하면 질문으로 명확화.
+- 사용자 제안/의견에 무조건 동의 금지.
+- 권위로 두지 말고 근거로 직접 판단해 답변.
+- 산출물 소비자의 도메인 어휘로 응답.
+- 시스템 내부 용어 회피.
+- 사람을 위한 간결하고 명확하게 응답.
+- 문서의 식별자(코드·약어·번호·라벨·§번호 등)만 노출 금지. 인용 시 식별자 옆에 실제 의미(이름·내용 요약)를 함께 표기해, 사용자가 원본을 펴보지 않아도 문장만으로 의미가 통해야 함. 응답·질문·산출물 모두 동일.
+- 다음 표현은 그대로 단독 노출 금지 — 모두 도메인 어휘·시나리오로 풀어쓸 것:
+  - 수식·계산식 단독 (예: `(A − B) − C` 만 던지기) → 도메인 시나리오 예시 1건 (값 대입) 동반
+  - 영문 변수명·코드 식별자 (예: `surplus`, `isCompleted`, `joinSingle`) → 한국어 도메인 어휘로 풀이
+  - SQL/프레임워크/구현 용어 (예: "LEFT JOIN 깊이 1 자르기", "subagent 위탁") → 도메인 흐름으로 풀이
+- 사용자가 "이해 못함"·"무슨 소리야" 류 피드백을 주면 같은 내용을 반복하지 말고 도메인 시나리오 예시로 다시 풀어쓸 것.
+
+질문·답변 프로토콜은 [질문/답변](#질문답변) 참조.
+
+## Convention 굳히기 금지
+
+사용자 피드백을 글자 그대로 문서화하지 말 것. 본질 의도를 추출해 일반 표현으로.
+
+- **잘못된 굳히기**: 1회 케이스의 운용 디테일(위치/이름/형식/특정 단어)을 그대로 규칙화.
+  - 나쁜 예: "A라고 했을 때 B라고 하지 말 것", "X 파일에 Y를 쓰지 말 것"
+- **올바른 일반화**: 본질 의도 + 적용 범위 정의.
+  - 좋은 예: "~한 상황에서는 ~를 수행"
+- 본질 의도 불명확 시 추측 금지. 사용자에게 적극 질문.
+- 피드백 받을 때마다 자문: "이게 1회 사례인가, 일반 규칙인가?" → 1회면 굳히지 말 것.
+
+**모호 표현 굳히기 금지** (자체 임의안 작성 시 적용):
+
+- 사용자 답변 없이 자체 임의안을 산출물에 작성할 때, 추상 단어·추측 단어·미정의 외부 의존을 표현으로 박지 말 것.
+  - 나쁜 예: "기본값 = 시스템 설정값" (정의 없는 외부 의존), "필요 시 자동 처리" (조건 미정), "적절한 값" (구체 X)
+  - 좋은 예: "기본값 = 14일" (구체 값 + 사용자 확정 마커 부착)
+- 임의안이면 구체 값 1개 + 결정 근거 출처 또는 사용자 확정 필요 마커 (`[OPEN]` 등) 부착.
+
+## 문서 작성
+
+- **CRITICAL**: Claude 에이전트용 문서는 에이전트가 즉시 따를 수 있게 작성. 사람 가독성 기준 X.
+  - 최소 분량. 중복·꾸밈 금지. 가장 적합한 자리에 한번만 명시.
+  - 표준용어로 통할 내용을 풀어쓰지 말 것.
+  - 예시는 글만으로 규칙이 모호할 때만, 흔한 도메인(예: 재고관리)으로 최소로 작성.
+- 산출물 소비자 도메인을 파악한 후 해당 도메인 용어로 작성. (나쁜 예: 소비자용 문서에 내부 기술용어)
+- **합의 누락 금지**: 확정된 모든 결정·근거·예외·단서는 즉시 산출물에 작성. ([결정 근거](#결정-근거))
+  - "이 단계 범위 밖" / "템플릿에 자리 없음" 등을 이유로 누락 금지
+  - 대화 메모리에만 두고 진행 금지. 후속 세션이 산출물만 읽어도 동일하게 이어갈 수 있어야 함.
+- **상위 룰 중복 금지**: 자동 로드되는 상위 룰(예: `sd-base-rules.md`)에 이미 명시된 내용을 하위 지침 문서(`CLAUDE.md`·스킬 SKILL.md·참고 자료 등)에 다시 옮겨 적지 말 것. 하위 문서는 해당 스코프 고유 내용만 작성.
+
+## ASCII 그림
+
+다이어그램·구성도·와이어프레임 등 모든 ASCII 그림에 적용.
+
+- 이모지(그림성 문자: ✏ ☐ ❌ ⭐ ♥ 등) 금지: 렌더러에 따라 1칸/2칸 변동 → 정렬 깨짐.
+- 그 외 ASCII·한글·박스 라인(┌─┐ │ └┘ ├┤)·도형(▲ ▼ ► ◄)·화살표(← → ↑ ↓) 등 폭 안정 문자는 허용.
+
+## 타임스탬프
+
+산출 폴더·파일명에 시각을 포함할 때:
+
+- 형식: `yyMMddHHmmss` (예: `260513204500` = 2026-05-13 20:45:00)
+- 획득: Bash 도구 `date +%y%m%d%H%M%S` 실행 결과
+
+## slug
+
+산출 폴더·파일명에 포함하는 짧은 인간 가독 식별자.
+
+- 짧은 한·두 단어.
+- 허용 문자: 한글, 영문, `_`, `-`, 공백. 그 외 금지.
+
+## 분석 작업
+
+- `.back` 폴더 및 `.gitignore` 등재 경로는 코드베이스에서 배제. 명시 첨부 없이 읽거나 참고 금지.
+- 현재 워킹트리만 기준. 사용자 명시 지침 없이 과거 버전 또는 변경분을 git 으로 조회하지 말 것 — `git status`·`diff`·`log`·`show`·`blame`·`reflog` 등 모든 조회 명령 포함. 워킹트리 파일·디렉터리 상태는 Read·Grep·Glob 으로만 확인 (이미 폐기된 패턴 답습 또는 변경분만 훑어 일관성 놓치는 실수 방지). Pre-tool 훅이 이들을 차단함.
+  - 사용자가 명시 지시한 경우에만 git 조회 가능. 이 때도 명령 prefix `$env:SDGIT='1'; ` (PowerShell) 또는 `SDGIT=1 ` (Bash) 를 붙여야 훅이 통과.
+- 입력 파일 옆에 가공/펼친 산출물이 있으면 원본 대신 가공본부터.
+
+## 코드 설계·변경
+
+- 산출물 소비자 표면(공개 API/props/옵션/UI/출력 등) 단순함이 내부 구현 단순함보다 우선. 충돌 시 복잡도는 내부로 흡수.
+- 내부 구현 난이도 회피를 위해 소비자 요구 완화/근사화 제안 금지. 난이도는 내부로 흡수. 불가 시 사용자 보고 후 결정.
+- **명시 정의 자체 단순화·임의 처리 금지**: spec·사용자 directive·합의 산출물에 식·정의·분기·경계가 명시된 항목은 코드에서 자체 단순화·근사화·안전 처리(NULL 강제·0 클램프·방어 가드·생략 분기 등) 임의 추가 금지. 식 그대로 풀어쓸 것. 정확 구현 부담이 크면 단순화안을 사용자에 보고 후 합의. ([결정 근거](#결정-근거) "안티패턴" 의 코드 적용형)
+- 변경 전, 변경 영역의 기존 코드 패턴과 개발 매뉴얼을 먼저 조사.
+- 의존 라이브러리 동작 이상 → 우회 코드 작성 전 라이브러리 측 원인 먼저 조사.
+- 라이브러리 버그/누락 판단 시 → 사용자에게 보고 후 수정 경로 제안 (예: 모노레포 내부=직접 패치, 외부=이슈 등록).
+- 이슈 본문 형식: 발생 현상 + 기대 동작 + 실제 동작 + 재현 정보(코드/조건/버전).
+- 우회 코드는 사용자가 명시 지시한 경우에만.
+- 문제 발생 시 throw. silent skip 금지 (예외 캐치 후 대안 없이 진행 — 후속 프로세스가 결손된 채 동작). **자동 복구**(예: 의존 미설치 → 설치·재시도 = 완전 동작 회복)는 silent skip 아님. 부분 살리기는 사용자가 명시 지시한 경우에만.
+- 사용자 표면 알림(로그·토스트·다이얼로그 등) severity 분류 기준은 *복구 가능 여부* 가 아니라 *사건의 본질*:
+  - `error`(danger): 문제 발생. catch·무시·재시도 여부와 무관하게 "문제가 일어난 사실" 이면 전부 해당.
+  - `warn`: 문제는 아니지만 사용자가 인지해야 할 중요 알림.
+  - `info`: 알면 좋은 일반 알림.
+  - `success`: 정상 완료 알림.
+  - 안티패턴: 무중단/복구 처리되었다는 이유로 `error` 대신 `warn` 선택 — 분류 기준 오용.
+
+## 도구 사용
+
+- Playwright CLI 산출물 저장 인자(`screenshot/pdf/snapshot/state-save/video-start --filename` 등) 사용 금지. 생략 시 자동 경로(`.playwright-cli/...`)로 저장되며, 출력 메시지의 경로를 그대로 인용해 후속 참조. (명시 시 cwd 기준 resolve 되어 프로젝트 루트로 떨어짐. 읽기 인자는 무관.)
+
+## 상황별 참고 자료
+
+아래 표의 **트리거 조건이 처음 충족될 때** 해당 자료를 Read.
+
+| 트리거                                                                             | 참고 자료                                              |
+| ---------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `@simplysm/*` 14.x 패키지의 코드 설계 및 변경                                      | `.claude/references/sd-simplysm14/README.md`           |
+| Requirement Source 부정확성 (STT 오타·화자 모호·발화 모호·도메인 용어 다의성) 처리 | `.claude/references/sd-requirement-source-handling.md` |
+
+## 용어 사전
+
+- **Requirement Source**: sd-spec 의 입력 자료 (회의록·고객 paste·문서·메일 등 분석 출발 자료).
+- **최종 사용자**: 시스템의 실제 도메인 사용자 (개발자·시스템 관리자 등 외).

package/claude/scripts/sd_paths.py

@@ -0,0 +1,22 @@
+"""공용 경로 헬퍼.
+
+실행 위치는 항상 프로젝트 루트라고 가정한다 (cd 금지 규칙).
+"""
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+
+
+def resolve_tmp_base() -> Path:
+    """프로젝트 루트의 .claude/simplysm.json 의 tmpdir → 없으면 OS tmp."""
+    cfg_path = Path(".claude/simplysm.json")
+    if cfg_path.exists():
+        try:
+            cfg = json.loads(cfg_path.read_text(encoding="utf-8"))
+            if cfg.get("tmpdir"):
+                return Path(cfg["tmpdir"])
+        except Exception:
+            pass
+    return Path(tempfile.gettempdir())

package/claude/sd-check-bash.py

@@ -19,9 +19,28 @@ BLOCKED = [
     (CMD_POS + r"npx\s+tsc\b", "npx tsc (use {PM} typecheck)"),
     # Use {PM} lint instead
     (CMD_POS + r"npx\s+eslint\b", "npx eslint (use {PM} lint)"),
+    # Playwright CLI: do not specify save paths; let it auto-save under .playwright-cli/
+    (CMD_POS + r"(npx\s+)?playwright-cli\s+(?:-s=\S+\s+)?(screenshot|pdf|snapshot)\b[^|;&\n]*[ \t]--filename\b",
+     "playwright-cli {screenshot|pdf|snapshot} --filename (omit to auto-save under .playwright-cli/)"),
+    (CMD_POS + r"(npx\s+)?playwright-cli\s+(?:-s=\S+\s+)?(state-save|video-start)[ \t]+\S",
+     "playwright-cli {state-save|video-start} <path> (omit path to auto-save under .playwright-cli/)"),
 ]
 
 for pattern, label in BLOCKED:
     if re.search(pattern, cmd):
         print(f"Blocked: {label}", file=sys.stderr)
         sys.exit(2)
+
+# Git read-only inspection block (working-tree-only policy).
+# Bypass: any occurrence of `SDGIT` token in the command.
+GIT_READ_VERBS = r"status|diff|log|show|blame|reflog|rev-list|rev-parse|ls-files|ls-tree|cat-file|describe|whatchanged|shortlog|grep"
+if not re.search(r"\bSDGIT\b", cmd):
+    m = re.search(CMD_POS + rf"git\s+(?P<verb>{GIT_READ_VERBS})\b", cmd)
+    if m:
+        print(
+            f"Blocked: git {m.group('verb')} "
+            "(working-tree inspection via git is forbidden; use Read/Grep/Glob). "
+            "If intentional, prefix the command with `SDGIT=1 ` (bash) or `$env:SDGIT='1'; ` (PowerShell).",
+            file=sys.stderr,
+        )
+        sys.exit(2)

package/claude/sd-statusline.py

@@ -196,16 +196,17 @@ def main():
     cwd = stdin_data.get("workspace", {}).get("current_dir") or stdin_data.get("cwd", "")
     folder = os.path.basename(cwd) if cwd else "?"
 
-    # Extract model
+    # Extract model (+ effort if present)
     model_id = stdin_data.get("model", {}).get("id", "")
     model = format_model(model_id) if model_id else "?"
+    effort_level = (stdin_data.get("effort") or {}).get("level")
+    if effort_level:
+        model = f"{model} {effort_level}"
 
     # Extract context %
-    ctx_window = stdin_data.get("context_window")
-    if ctx_window is not None:
-        ctx_str = f"{ctx_window.get('used_percentage') or 0}%"
-    else:
-        ctx_str = "?"
+    ctx_window = stdin_data.get("context_window") or {}
+    used_pct = ctx_window.get("used_percentage")
+    ctx_str = f"{used_pct}%" if used_pct is not None else "?"
 
     # Rate limits from stdin
     rate_limits = stdin_data.get("rate_limits", {})
@@ -220,12 +221,6 @@ def main():
         if eu.get("is_enabled") and eu.get("used_credits") is not None:
             extra_str = f"${eu['used_credits'] / 100:.2f}"
 
-    # Write rate_limits to cache
-    cache = cache or {}
-    cache["rate_limits"] = rate_limits
-    cache["rate_limits_ts"] = time.time()
-    write_cache_atomic(cache)
-
     # Spawn background fetch if needed
     version = stdin_data.get("version", "2.1.86")
     if should_fetch(cache):

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

@@ -5,8 +5,13 @@ description: 워크스페이스의 모든 변경을 단일 커밋으로 묶는
 
 # 총괄 커밋
 
-시스템 기본 커밋 절차를 따르되, 아래만 적용한다.
+system prompt 의 "Committing changes with git" 절차를 따르되, 아래만 적용한다.
 
-- Staging은 `git add -A` 사용.
-- 변경이 여러 갈래면 메시지를 갈래별 섹션으로 나눠 각 변경을 설명.
+- 모든 git 호출(`status`/`diff`/`log`/`add`/`commit`)은 prefix `$env:SDGIT='1'; git ...` (PowerShell) 또는 `SDGIT=1 git ...` (Bash) 로 호출. (Pre-tool 훅의 전역 git 조회 차단 우회 마커. add/commit 도 일관성으로 동일 prefix.)
+- Staging은 `git add -A` 사용. 본 스킬 호출 = 사용자가 -A 위험(민감 파일 staging) 인지·동의한 것으로 간주.
+- 메시지는 사용자 응답 언어와 일치.
+- 변경이 여러 갈래면:
+  - 제목: 갈래들을 `및`/`,` 로 한 줄 병합
+  - 본문(빈 줄 후): 갈래별 헤더 `[<type>]: <갈래 요약>` + 변경 항목 불릿(`-`). 갈래 간 빈 줄로 분리.
+  - `<type>`: conventional commits (`fix`/`feat`/`refactor`/`docs`/`chore`/`test`/`build`/`ci`/`style`/`perf`)
 - 푸시는 수행하지 않음.

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

@@ -1,93 +1,134 @@
 ---
 name: sd-demo
-description: spec.md(요구사항) 기반으로 UI scaffold를 메인 코드베이스에 작성하고 산출물 소비자 시연용 demo.md를 생성하는 스킬. Use when 산출물 소비자에게 화면을 시연해 spec 검증이 필요할 때 (선택적 단계, spec과 plan 사이)
+description: spec.md 의 화면 1개를 클라이언트 패키지의 화면 컴포넌트 자리에 인터랙티브 데모 골격으로 만든다. Use when "데모 만들기", "화면 데모", "spec 의 화면을 시각화" 를 요청할 때
 ---
 
-# demo 단계
+# sd-demo
 
-spec.md 1+ REQ → UI scaffold(메인 코드베이스 직접) + demo.md(시나리오/만든 파일/라운드 기록).
-production의 첫 단계 (throwaway 아님). plan/implement가 그 위에 기능을 입힘.
+spec.md 화면 1개를 클라이언트 패키지의 화면 컴포넌트 자리에 데모로 만든다. 와이어프레임 상의 배치·라벨·동작 흐름이 일치하는 클릭 가능 UI. 후속 단계에서 같은 자리에 실제 로직을 채워 진화한다.
 
-## 산출물
+## 본질: UI 가 1순위
 
-```
-src/                                ← UI scaffold (메인 코드베이스 직접)
-  pages/<신규>.tsx
-  data/mock-<도메인>.ts             ← mock data 별도 파일
+소비자는 시연 받는 사용자. 사용자는 화면만 본다. 코드는 후속 단계가 다시 짠다.
 
-.specs/{yyMMdd_HHmmss}/DEMO-001-슬러그/
-  demo.md                           ← 시나리오/만든 파일/Mock 요약/피드백 라운드
-```
-
-세션 폴더(`{yyMMdd_HHmmss}`)는 spec 단계의 결과를 그대로 사용 (이미 존재).
+- **주의·시간의 90% 를 template 에 쓴다.** 와이어프레임을 시각적으로 정확·정돈되게 복원하는 게 본 작업의 본질.
+- 코드 골격(시그널·effect·DI·핸들러)은 **코드베이스에서 분석해 따라간다** — 본 스킬은 framework 처방을 박아두지 않는다.
+- 데이터 변경 시뮬레이션 금지. 저장·삭제 핸들러는 마커만. 클릭은 받되 결과 반영 X.
+- 모달 띄우기는 실제로 작동시켜 시연 가치 확보.
 
 ## 워크플로
 
-1. 입력 받기: 대상 REQ ID 목록 (예: `REQ-001`, 또는 여러 개)
+### 1단계: 입력 확보
+
+호출에 다음 필요:
+
+- 대상 spec.md 경로
+- 만들 화면 식별자 — `[화면.X]` 또는 §4.x
+- 산출 위치 — 클라이언트 패키지 + 화면 폴더. client 타겟이 1개면 자동, 여러 개면 후보 제시 후 사용자 확정. **3단계-C 의 도메인 인접 화면이 명확히 식별되면 그 위치(같은 도메인 폴더)로 자동 채택** (1단계 초안을 인접 위치로 갱신).
+
+없으면 묻기. spec.md 에 식별자 매칭이 안 되면 §4 화면 목록 표에서 후보 제시 후 확정.
+
+### 2단계: spec §4.x 분석
+
+§4.x 에서 추출:
+
+- 헤더 인덱스(Actor · 관련 섹션 · 장치)
+- 기능 개요 · 와이어프레임 · 항목표 · 동작 · 도메인 규칙(해당 시)
+- §동작에 등장하는 모달 호출 `→ [화면.Y] 을 모달로 띄움` 모두 수집
+
+### 3단계: 분석 자료 확보
+
+산출물을 만들기 전, 다음을 분석해 framework 처방을 확보한다.
+
+**A. 라이브러리 문서**
+
+코드베이스에 권위 규약/매뉴얼 문서가 있으면 1순위로 따른다.
+
+- `@simplysm/*` 14.x 사용 시 — [.claude/references/sd-simplysm14/README.md](../../references/sd-simplysm14/README.md) Read 후 "개발 매뉴얼" 항목 진입. 클라이언트 화면은 `client-component.md`, 화면 컨트롤은 `client-tab.md` 등.
+- 그 외 framework 는 코드베이스 안의 동등 위치 문서를 찾아 Read.
+
+**B. 라이브러리 컴포넌트 소스**
+
+쓰려는 컴포넌트(예: `sd-form`, `sd-crud-list`)가 있으면 **본체 소스를 직접 Read** 해 input/output·동작을 정확히 파악. 사용처 grep 만으로는 누락된 prop 을 놓친다.
+
+**C. 부위별 패턴 레퍼런스 수집**
+
+코드베이스의 클라이언트 화면 전반에서 **부위(부분)별로 공통 패턴**을 수집한다. "구성 똑같은 화면 1개를 골라 통째 답습" 모델이 아니다. 일치 화면이 있어도, 부위별 종합 결과 위에 추가로 얹는다.
+
+**수집 대상 부위** (대상 화면이 사용하는 것만 골라 수집):
+
+| 부위        | 수집 내용                                                       |
+| ----------- | --------------------------------------------------------------- |
+| 화면 골격   | 컴포넌트 selector·파일 위치·라우팅/메뉴 등록 위치               |
+| 헤더/타이틀 | 페이지 타이틀·도구 버튼 배치                                    |
+| 툴바        | 검색·필터·추가/삭제 버튼·페이지네이션 위치·정렬 인터랙션        |
+| 영역 분할   | 좌우/상하 split·탭·sheet·dock 사용                              |
+| 리스트      | 테이블·카드 그리드·트리 마크업·헤더 셀·행 셀·선택/정렬·빈 상태  |
+| 폼          | 필드 그리드·라벨/입력 배치·필수 표시·버튼 푸터                  |
+| 모달        | 헤더·본문·푸터·확인/취소 버튼·크기                              |
+| 빈 상태     | 아이콘·여백·문구                                                |
+| 도메인 위치 | 같은 sub-app·같은 도메인 폴더 후보(산출 위치 자동 채택용)       |
+
+**절차**:
+
+1. 클라이언트 패키지의 화면 폴더 전반 Glob 으로 훑어 화면 목록 확보.
+2. 위 부위별로 **각 부위마다 화면 2~4개**를 골라 template 부분 발췌 Read. 도메인 영역(같은 sub-app)이 가까운 화면 우선. 부위마다 다른 화면을 골라도 됨 (예: 헤더는 화면 X·Y, 리스트는 화면 Z·W).
+3. 부위별 공통 패턴(자주 쓰는 슬롯·클래스·요소 구조) 메모화. 1회만 쓰인 변종은 채택 후보에서 배제, 다수에서 반복되는 것을 채택.
+4. 부위별 패턴이 화면마다 갈라지면 (예: 리스트가 테이블·카드 두 갈래) 대상 화면의 와이어프레임이 어느 쪽인지로 선택.
+
+**도메인 인접 후보**: 같은 sub-app·같은 도메인 폴더에 화면이 1개 이상 있으면 그 폴더를 산출 위치 자동 채택 근거로 쓴다. 0개면 라우팅·메뉴 등록 위치를 사용자에게 1회 질문.
 
-2. 대상 REQ들의 spec.md 읽기 + 코드베이스(디자인 시스템 등) 파악
+LLM 단독 판단 한계: 동일 구성 화면이 한 곳도 없다고 framework 처방만으로 그리면 안 된다. **반드시 부위별로 수집한 패턴을 근거로** 그려야 한다. 부위별 후보가 0개인 부위가 있으면 그 부위만 사용자에게 1회 질문 (그 화면의 그 부위 어떻게 처리할지).
 
-3. DEMO ID 부여 + `.specs/{yyMMdd_HHmmss}/DEMO-XXX-슬러그/` 생성
-   - DEMO ID는 세션 폴더 내 `DEMO-001` 부터 순번
-   - 슬러그는 한글 OK
+### 4단계: 충돌 확인
 
-4. UI scaffold 작성 (메인 코드베이스에 직접)
-   - 페이지 + 컴포넌트 배치 (디자인 시스템 활용)
-   - mock data는 **별도 파일** + `MOCK_` prefix + 상단 주석
-   - 데모 흐름 필수 인터랙션만 (페이지 이동/폼 입력 시각/클릭 반응)
-   - 모호한 부분 → Q
+대상 화면(또는 동반 모달 §4.x) 파일이 이미 있으면 묻기:
 
-5. demo.md 작성 (템플릿: [references/demo-md-template.md](references/demo-md-template.md))
+- ① 덮어쓰기 / ② spec 변경분만 보강 / ③ 취소
 
-6. Q 다이얼로그 (있다면, 한 번에 하나씩) → 사용자 답변 → 즉시 갱신
+호출자 발화에 명시 분기가 있으면 묻지 않고 그 분기로 진행.
 
-7. demo 작성 끝 → 메타 `상태: demo-ready` → 사용자에게 "산출물 소비자에게 보여주세요" 알림
+### 5단계: 생성
 
-8. 사용자가 산출물 소비자 피드백 가져옴 → 메타 `상태: reviewing`
+3단계 분석 자료(A/B/C)를 1순위 근거로, **template 부터** 채운다.
 
-9. 피드백 분류 (UI 조정 / spec 변경 / 모호) — 사용자 확정
-   - UI 조정 → demo 코드 수정
-   - spec 변경 (R 단위) → spec.md 수정 + 메타 `이력` 기록
-   - REQ 구조 변경(분리/병합) → spec 재진입 후보 알림 (demo 단독 처리 X)
+- 파일명·selector·시그널·DI 명명 등은 라이브러리 문서(A) 가 정한 형식 그대로.
+- 슬롯·영역 분할·클래스 패턴은 3단계-C 부위별 패턴 채택분 그대로. 부위별로 다른 화면을 참조했더라도 각 부위 채택분을 그대로 옮긴다.
+- 부위별 채택분이 코드베이스 어느 화면에서 왔는지 출처를 머릿속에 두고 비교 가능 상태로 유지(6단계 점검용).
+- 모달 호출 화면이면 동반 모달 §4.x 도 같은 단계로 생성.
 
-10. 라운드 기록 (append-only) → "다음 라운드? 종료?"
-    - 다음 → 7번으로
-    - 종료 → **demo.md 형식 점검** (만든 파일 목록 / 라운드 기록 / 메타 일관성) → **역방향 자잘 갱신** (spec 메타 이력 누락 등 — 라운드 중 spec 변경은 9번에서 이미 처리, 여기선 잔여 점검만) → 메타 `상태: done`
+**표식 마커 (고정)**
 
-## 책임 범위
+| 위치                     | 마커                                                       |
+| ------------------------ | ---------------------------------------------------------- |
+| 더미 데이터 선언 위      | `// sd-demo: 더미 — 구현 단계에서 교체`                    |
+| 미구현 핸들러 본문       | `// sd-demo: 미구현 — 동작 자리`                           |
+| 더미 타입 인라인 선언 위 | `// sd-demo: 더미 타입 — 구현 단계에서 @모델/X 로 교체`    |
+| 종류 매핑 임의 추정      | `// sd-demo: 종류 매핑 임의 — 확인 필요`                   |
+| 권한 path 임의 추정      | `// sd-demo: 권한 path 임의 — 확인 필요`                   |
 
-만들 것: 페이지 레이아웃·컴포넌트 배치 / mock data 표시 / 페이지 이동·폼 입력 시각·클릭 반응
+다른 변형 사용 금지. 후속 단계가 grep 으로 추적한다.
 
-만들지 말 것: 실제 데이터 저장·삭제·수정 / API 호출(mock 포함) / 비즈니스 로직 / 인증·권한 처리
+### 6단계: 자체 점검
 
-원칙: **말로 설명할 수 있는 건 만들지 않는다**
+**패스 1: 부위별 패턴 일치** — 3단계-C 에서 부위마다 채택한 레퍼런스 화면을 다시 Read 해 부위별로 비교:
 
-## Mock Data 정책 (3중 강한 표시)
+- 헤더/툴바: 도구 버튼 배치·라벨 형식·간격·클래스 동일
+- 영역 분할: split/탭/sheet/dock 사용 동일
+- 리스트: 헤더 셀·행 셀 마크업·정렬/선택 슬롯 동일
+- 폼: 필드 그리드·라벨/입력 배치·푸터 버튼 동일
+- 모달: 헤더·본문·푸터 구조 동일
+- 빈 상태: 아이콘·여백·문구 동일
 
-```typescript
-// src/data/mock-rtp.ts
-// MOCK DATA - replaced in implement stage
-export const MOCK_RTP_LIST = [...]
-```
+부위 중 한 곳이라도 채택 패턴과 어긋나면(임의 변형·새 클래스 발명·새 슬롯 사용) 수정. "비슷한 화면이 없어서 알아서 그렸다"는 자기 합리화 금지 — 그 부위 채택분이 비어 있다는 뜻이므로 3단계-C 로 돌아가 수집·재선택.
 
-- 반드시 별도 파일 (페이지 inline 금지)
-- 변수/상수 `MOCK_` prefix 필수
-- 파일 상단 주석에 `MOCK` 키워드 필수
+**패스 2: 라이브러리 문서 위배 점검** — 3단계-A 의 매뉴얼 문서 항목별 일치 확인. 위배 항목이 있으면 수정 후 재점검.
 
-## 핵심 원칙
+### 7단계: 완료 보고
 
-- self-contained 블록 (라운드 단위 demo.md)
-- raw input 불변
-- ID 불변 (DEMO-001 = 영원히 DEMO-001)
-- 자동 판단 금지 (피드백 분류는 사용자)
-- 한 번에 하나씩 Q
+만든 파일 목록 보고 후 종료.
 
-## 안티패턴
+## 운용
 
-- ❌ throwaway로 만들기 (격리 폴더에 만들고 폐기) — production 첫 단계임
-- ❌ 실제 데이터 처리 로직 (저장/삭제/계산)
-- ❌ Mock data를 페이지 inline에 굳히기
-- ❌ 피드백 분류 자동 결정
-- ❌ REQ 구조 변경을 demo 단독 처리 (spec 재진입)
-- ❌ 라운드 기록 누락
-- ❌ 종료 결정 직후 demo.md 형식 점검 없이 done 전환
+- 결정 근거: `sd-base-rules.md` "결정 근거" 적용.
+- 본 스킬은 framework 처방을 박아두지 않는다. 매 호출 시 3단계에서 분석한 라이브러리 문서·컴포넌트 소스·답습 화면을 근거로 산출.