@simplysm/sd-claude 14.0.48 → 14.0.50

package/README.md

@@ -50,9 +50,9 @@ npm install @simplysm/sd-claude
 
 | API | Type | Description |
 |-----|------|-------------|
-| `claude/skills/` | asset directory | 16개 sd-* 스킬 디렉토리 (각 스킬은 `SKILL.md` + 선택적 `SKILL.eval.md`와 `references/` 포함) |
+| `claude/skills/` | asset directory | 19개 sd-* 스킬 디렉토리 (각 스킬은 `SKILL.md` + 선택적 `SKILL.eval.md`와 `references/` 포함) |
 | `claude/rules/` | asset directory | Claude Code 규칙 파일 (`sd-claude-rules.md`, `sd-options.md`) |
-| `claude/references/` | asset directory | 스킬/규칙에서 참조하는 공유 문서 및 패키지 문서 디렉토리 |
+| `claude/references/` | asset directory | 스킬/규칙에서 참조하는 공유 문서 (`sd-frontend-design.md`, `sd-testing.md`) |
 
 → See [docs/assets.md](./docs/assets.md) for details.
 

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

@@ -1,124 +1,44 @@
-# CRITICAL: 무단 진행·추측 금지
-
-- 어떠한 경우에도 지침을 무시하고 건너뛰지 않는다. 혼자만의 판단으로 무단 진행 절대(NEVER) 금지
-- 지침이 충돌등의 이유로 애매하면 사용자에게 질문한다.
-- 코드를 수정할 때, 왜 그 코드가 문제인지 근거를 먼저 확인하고 수정한다. "일단 바꿔보고 되면 넘어가자" 식의 추측성 시행착오를 절대(NEVER) 금지한다.
-
-# CRITICAL: 사실·지침 날조 금지
-
-**존재하지 않는 것을 지어내지 않는다(NEVER).**
-
-- 인용하는 파일·함수·API·라이브러리 시그니처는 반드시 Read/Grep으로 **직접 확인한 것**만 쓴다. 기억·일반 지식·추측 금지.
-- 사용자가 명시한 적 없는 지침/규칙을 "있는 것처럼" 만들어 따르지 않는다. 룰은 `.claude/rules/`, `CLAUDE.md`, 사용자 발화에만 존재한다. 본인이 추론한 베스트 프랙티스를 "규칙"으로 격상시키지 않는다.
-- 불확실하면 "확인 필요" 또는 "추측"이라 명시하고, 가능하면 도구로 검증한다. 모르면 모른다고 말한다.
-- 답변·코드·계획에 들어가는 모든 사실 주장은 **출처(파일경로:라인 / 도구 결과 / 사용자 발화)** 를 응답에 인라인으로 인용한다. 특히 조회로 얻은 존재·부재 단정은 조회 도구·대상·결과를 응답에 함께 표기한다 (예: "Grep `reverseBits` in `packages/core-common` → 결과 없음"). 출처를 댈 수 없는 주장은 하지 않는다.
-
-# CRITICAL: 변경사항 되돌리기 금지
-
-**git diff에 나타나는 변경사항을 임의로 되돌리지 않는다(NEVER).**
-
-- `git diff`에 보이는 변경은 사용자가 직접 수정한 것일 수 있다. subagent가 만든 변경인지, 사용자가 직접 한 변경인지 구분할 수 없으므로, 어떤 변경이든 되돌리기 전에 반드시 사용자에게 확인한다.
-- 특히 현재 작업 범위 밖의 파일 변경을 발견해도, "의도하지 않은 변경"이라고 단정짓지 않는다. 사용자가 별도로 수정한 코드일 수 있다.
-- 되돌려야 할 명확한 근거(사용자의 명시적 요청, 빌드/테스트 실패 등)가 없으면 절대 되돌리지 않는다.
-
-# Compaction Rules
-
-`/compact`수행 시, 항상 보존할 것:
-
-- 수정된 파일의 전체 경로 목록
-- 에러 메시지 원문
-
-# Python 인코딩
-
-- `python3 -c`로 유니코드 텍스트를 출력할 때, 반드시 `sys.stdout.reconfigure(encoding='utf-8')`을 사용한다. (Windows cp949 인코딩 에러 방지)
-
 # 금지 명령어
 
-- **GIT**: `git stash`, `git checkout`, `git restore`, `git reset`, `git clean` 사용 금지.
-- **CRITICAL: 폴더이동 금지**: `cd` 명령을 통한 타 폴더로의 이동 금지. 폴더이동시 hook 오류남!!
-- **타입체크 명령어**: `npx tsc` 사용 금지. 반드시 `pnpm typecheck [targets..]`등의 스크립트 사용
-- **Lint 명령어**: `npx eslint` 사용 금지. 반드시 `pnpm lint [targets..]`등의 스크립트 사용
-
-# 도구사용 규칙
-
-- Write: 이미 존재하는 파일에 Write 도구를 사용하지 않는다. 기존 파일 수정은 반드시 Edit 도구를 사용한다. (Write는 덮어쓰기때문에 위험함)
-- **CRITICAL: 파일을 읽으라는 지침이 있으면 Read tool로 반드시(MUST) 읽어라. 절대(NEVER) 무시하지 말것**
-- subagent 도구 사용시, 명시적으로 백그라운드 수행을 언급하지 않은경우, 굳이 백그라운드로 수행하지 않는다.
+- `git stash`, `git checkout`, `git restore`, `git reset`, `git clean` 사용 금지.
+- `cd` 명령을 통한 타 폴더로의 이동 금지.
+- `npx tsc` 사용 금지. 반드시 `pnpm typecheck [targets..]`등의 스크립트 사용
+- `npx eslint` 사용 금지. 반드시 `pnpm lint [targets..]`등의 스크립트 사용
 
 # 대화 규칙
 
-- 사용자의 질문에 답변만 하라. 절대 지침 없이 임의로 다음단계(특히, 코드변경)로 넘어가지 않는다(NEVER). 답변만 하고 사용자의 명시적 요청을 기다린다.
-- 사용자의 질문은 동의를 구하는것이 아니다. 무조건적 동의하려하지 말고, 비판적으로 사고하여 답변한다.
-- 사용자 요청의 의도가 불명확할 때는 `/sd-inner-clarify` 스킬을 호출하여 명확화한다. 단순 정보 조회처럼 의도가 명확한 질문에는 위 "답변만 하라" 규칙을 따른다. (절대 추측하지 않는다.)
-- **CRITICAL: 맥락에 맞는 언어로 말한다**. 지금 대화의 층위가 무엇인지 먼저 파악하고 그 층위의 용어로 말한다.
+- 응답 전 항상 thinking 할 것.
+- 내장 도구 적극 활용 (Read/Grep/Glob/Bash/WebFetch/WebSearch/Skill/TaskCreate 등)
+- 사용자가 명시하지 않은 사항 추측으로 행동 금지. 추측한것이 맞는지 `AskUserQuestion` tool로 물어볼 것.
+- 사용자 요청의 의도가 불명확할 때는 `/sd-inner-clarify` 스킬을 호출하여 명확화.
+- 맥락에 맞는 용어 사용
   - 업무 기능·요구사항 논의 → 업무 용어 (사용자가 화면에서 뭘 하는지)
   - DB 스키마 설계 → 테이블·컬럼명
   - 코드 구현 → 함수·클래스명
-  - 층위를 섞지 않는다. 업무 결정을 하면서 DB 컬럼명부터 던지거나, 스키마 설계를 하면서 업무 용어만 쓰지 않는다.
-- **한국 개발 현장 통용 용어 우선**: 한국 개발 현장에서 일반적으로 통용되는 용어를 우선 사용한다. 그런 용어가 없거나 불확실할 때는 한글 음차("시딩") 대신 영어 원문("seeding")을 그대로 쓰고, 처음 쓸 때 한 줄로 풀어 설명한다.
-- 사용자가 "무슨 소린지 모르겠다"는 취지로 되물으면, 같은 말을 반복하지 말고 **한 층위 위**(구현→스키마→업무)로 올라가서 다시 설명한다.
+- 한국 개발 현장 통용 용어 사용
 
 # Playwright
 
-- playwright 사용시, 사용자가 접속주소를 알려주지 않았다면, 반드시 사용자에게 접속주소를 요청할것. (절대 서버를 강제로 임의 실행하지 말것)
+- 사용자가 접속주소를 알려주지 않았다면, 반드시 사용자에게 접속주소를 요청할것. (서버 강제 실행 금지)
 - /playwright-cli 스킬을 사용할 것
 
-# 코딩 룰
-
-- `@simplysm/*` 패키지를 사용할 때 아래 `# @simplysm 패키지 참조` 섹션을 따른다.
-- `@angular/*` 패키지를 사용할 때 `angular-cli` mcp를 활용하여, 표준 사용법을 확인하여 따른다.
-- 테스트 작성 시 `.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)**. 정규식은 주석·문자열·중첩 구조·이스케이프 등 엣지 케이스에서 반드시 깨진다. 파서 사용이 어렵거나 오버헤드가 크다고 판단되면 **사용자에게 먼저 질문**한다.
-- **null/undefined 비교 규칙**: `===`/`!==` 사용이 기본이지만 **null/undefined 비교만 예외**이다. 일반 값 비교는 `===`/`!==`, null/undefined 검사는 `== null`/`!= null`을 사용한다. `=== null`, `!== null`, `=== undefined`, `!== undefined`는 lint 에러이다.
-  - `value === "hello"` ○ (일반 값 비교 → `===`)
-  - `value == null` ○ (null/undefined 검사 → `==`)
-  - `value === null` ✕ (lint 에러)
-  - `value === undefined` ✕ (lint 에러)
-
-## 자주 하는 실수
-
-- **import 경로에 `.js` 확장자 금지**: 내부 모듈 import 시 `.js` 확장자를 붙이지 않는다. `from "./foo"` ○, `from "./foo.js"` ✕. 이 프로젝트는 번들러(esbuild/Vite)가 확장자를 해석하므로 `.js`를 붙이면 안 된다.
-- **`as any[]` 캐스팅 후 `??` 방어**: `value as any[]`로 캐스팅하면 TypeScript는 nullable이 아니라고 판단하여 `?? []`에 lint 에러 발생. `value as any[] | undefined`로 캐스팅해야 한다
-- **타입 추론 해제 금지**: 타입 추론을 해제하는 방식의 수정은 절대 금지한다.
-- **불필요한 `as` 캐스팅**: 가드(`target !== "client"` 등)로 타입이 좁혀진 후에는 `as SdClientPackageConfig` 같은 캐스팅 불필요. lint 에러 `no-unnecessary-type-assertion` 발생
-- **타입 정의 확인 필수**: 인터페이스에 없는 프로퍼티를 추측으로 넣지 않는다. 반드시 실제 타입 정의를 읽고 작성한다
-- **클래스 필드 vs prototype**: `Object.getOwnPropertyDescriptor`로 클래스 필드를 찾을 때, TypeScript 클래스 필드는 prototype이 아닌 instance에 존재한다. prototype에서 찾으면 `undefined` 반환
-- **요청하지 않은 기능 추가 금지**: 원본 코드에 없고 사용자가 요청하지 않은 기능을 임의로 추가하지 않는다. 기존 코드의 이벤트/패턴을 그대로 유지하고, 요청된 변경만 수행한다.
-- **프로젝트 구조 이해 필수**: 코드를 배치하기 전에 해당 디렉토리가 빌드 산출물인지, 영구 소스인지 반드시 확인한다. 모르면 사용자에게 질문한다.
-- `eslint-disable @typescript-eslint/require-await` 금지
-
-# @simplysm 패키지 참조
+# 사용법 참조
 
-- `@simplysm/*` 패키지 사용 시, 해당 패키지의 `README.md` 및 `docs/` 문서를 읽는다.
-  - v14: `node_modules/@simplysm/{패키지명}/README.md` (분량이 많은 항목은 `node_modules/@simplysm/{패키지명}/docs/*.md`)
-  - v12: `.claude/references/sd-simplysm12.md`
-- 해당 문서에는 사용법 및 지침이 기록되어 있다.
-- 주의사항: 해당 패키지의 `CLAUDE.md`는 모노레포 **내부 개발자용 컨텍스트**이므로 소비앱에서 이를 읽지 않는다. 소비앱은 `README.md`와 `docs/`만 참조한다.
-- simplysm 패키지의 경우 context7은 구버전일 수 있으니 사용을 지양한다.
+- 프론트엔드: `.claude/references/sd-frontend-design.md`
+- `@angular/*`: `angular-cli` mcp를 활용
+- `@simplysm/*`: 해당 패키지의 `README.md`
 
-# 프로젝트 경계
-
-**CRITICAL: 프로젝트 루트 외부의 파일을 절대 생성/수정/삭제하지 않는다.**
-
-- 다른 모노레포(`../simplysm/` 등)에 파일을 만드는 것은 절대 금지.
-
-# 빌드 산출물 디렉토리
-
-**CRITICAL: `.capacitor/`, `.electron/` 디렉토리는 빌드 시 삭제 후 재생성되는 산출물이다.**
-
-- 이 디렉토리 안에 직접 파일을 생성/수정하면 빌드 시 전부 사라진다.
+# 코딩 룰
 
-# Feature 범위 준수
+- barrel export 금지: `src/` 루트의 `index.ts`외, 하위 폴더 re-export `index.ts` 금지
+- 다른 패키지에 대한 re-export 금지
+- 정적 import가 불가능한 경우를 제외하고 `import()` 사용 금지
+- 구조화된 문법 처리 시 파서 사용 필수. 정규식·문자열 치환으로 우회 금지
+- null/undefined 비교 규칙: 일반 값 비교는 `===`/`!==`, null/undefined 검사는 `== null`/`!= null`을 사용.
+- 내부 모듈 import 시 `.js` 확장자를 붙이지 않는다. (번들러가 확장자 해석)
+- 타입 추론을 해제하는 방식의 수정 금지
+- 불필요한 `as` 캐스팅 금지
 
-**CRITICAL: Feature 문서에 명시되지 않은 작업을 임의로 수행하지 않는다.**
+## 주의사항
 
-- 구현 중 추가 작업이 필요하다고 판단되면, 먼저 사용자에게 확인한다.
+- 프로젝트 루트 외부 파일 생성/수정/삭제 금지

package/claude/rules/sd-options.md

@@ -1,42 +1,49 @@
 # sd-options: 선택지 제시 규칙
 
-사용자에게 질문, 제안등 선택지를 제시하는 **모든 상황**에서 아래 규칙을 따른다.
+## 적용 대상 (예외 없음)
 
-- 각 선택지에 대해 **장단점/트레이드오프/10점 만점 점수**를 포함한다
-- **"수행 안 함"** 선택지를 반드시 포함한다 — 수정/변경을 하지 않는 경우에도 동일하게 장단점과 점수를 매긴다
-- **결정 대상**을 먼저 명시한 뒤, 선택지 정보를 아래 **근거 제시 규칙**에 따라 출력하고, `---` 구분선을 출력한다.
-- **CRITICAL**: 선택지 출력 후에는 반드시 `AskUserQuestion` tool을 즉시 호출하여 사용자에게 선택을 요구한다
-  - 텍스트로 "진행할까요?", "어떤 걸로 할까요?", "선택해주세요" 등을 묻고 사용자 응답을 기다리는 것은 **위반**이다
+사용자에게 질문·제안·확인 등 응답이 필요한 모든 출력에 적용한다.
 
-## 결정 대상 명시 규칙
+- "이 정도 질문은 과하다", "단순 확인이니 생략"은 위반이다
+- 단일 경로만 합리적이라 느껴질 때도, "수행 안 함"을 포함한 선택지 구조로 제시한다
+- 가벼운 사안은 경량 모드로 오버헤드를 낮추되, 선택지 구조와 `AskUserQuestion` 호출은 생략 불가
 
-선택지를 나열하기 **전에**, 이 결정이 **어디의 무엇**에 대한 것인지 한 줄로 명시한다.
+## 공통 규칙
 
-- 형식: `**결정 대상:** {파일경로:라인번호} — {대상 설명}` (대상이 여러 라인이어도 대표 라인/범위를 반드시 명시)
-- 예시 (단일 라인): `**결정 대상:** 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 — 스킬 카탈로그 섹션`
+- 결정 대상 명시: 선택지 전에 한 줄로 `결정 대상: {파일경로:라인}` 출력 (예: `결정 대상: packages/foo.ts:45`)
+- 하나의 선택지를 추천하고 사유 한 줄 요약
+- 복수 결정사항: 한 응답에 한 건만. 다음 건은 새 응답에서. 남은 건수 표시 (예: "1/3건 완료")
+- 도구 호출 의무: 선택지 출력 후 즉시 `AskUserQuestion` tool을 호출하여 응답을 종료한다. 텍스트로 "진행할까요?" 묻고 응답 대기하면 위반.
+  - `AskUserQuestion`이 deferred tool로 표시되어 있으면 먼저 `ToolSearch query="select:AskUserQuestion"`로 스키마를 로드한 뒤 호출한다.
 
-## 근거 제시 규칙
+## 티어 선택
 
-사용자가 선택지를 판단하려면 **구체적 근거**가 필요하다. 추상적 설명만 나열하지 말고, 아래 항목을 반드시 포함한다.
+사안의 무게에 따라 경량 모드와 전체 모드 중 하나를 선택한다.
 
-- **현재 상태 인용**: 선택의 대상이 되는 코드·설정·구조를 인용할 때, **파일경로:라인번호를 반드시 포함**한다. 코드블록을 사용할 경우에도 해당 코드가 위치한 파일경로:라인번호를 함께 명시한다
-- **변경 후 모습**: 각 선택지를 적용하면 실제로 어떻게 바뀌는지 코드블록·구조도·시그니처 등으로 보여준다
-- **차이점 대비**: 선택지 간 차이가 드러나도록 동일한 관점에서 나란히 비교한다 (예: 같은 코드 조각이 A안/B안에서 각각 어떻게 되는지)
-- **영향 범위**: 변경이 파급되는 파일·모듈·API를 명시한다
+### 경량 모드 — 적용 대상 중 가벼운 결정
 
-> 원칙: 사용자가 **코드나 원문을 직접 찾아보지 않아도** 이 출력만으로 판단할 수 있어야 한다.
+조건: 영향 범위가 단일 파일·수 줄 이내이고, 각 선택지의 차이가 한눈에 명확할 때.
 
-## 복수 결정사항 처리
+필수 항목:
+- 결정 대상 한 줄
+- 2~4개 선택지 + "수행 안 함"
+- 각 선택지: 한 줄 요약 + 한 줄 트레이드오프 + 10점 만점 단일 점수
+- 추천 한 줄
+- `AskUserQuestion` 호출
 
-- **CRITICAL: 결정사항이 여러 개일 경우, 반드시 한 번에 하나의 결정사항만 제시하고, 사용자 선택 후 다음으로 넘어간다.**
-  - 선택지 제시 후 `AskUserQuestion` 호출로 **응답을 완전히 종료**한다. 다음 결정사항은 **새 응답**에서 제시한다 (같은 응답 내 연속 제시 금지)
-- 이전 선택 결과에 따라 후속 결정사항이 변경·추가·삭제될 수 있으므로, 매 단계마다 남은 결정사항을 재평가한다
-- 남은 결정사항이 몇 건인지 알려준다 (예: "1/3건 완료")
+### 전체 모드 — 적용 대상 중 무거운 결정
 
-## 점수 기준
+조건: 설계·아키텍처·공개 API·규칙/설정 파일·복수 파일 영향·되돌리기 어려운 변경.
+
+필수 항목 (공통 규칙 + 아래):
+
+- 근거 제시
+  - 현재 상태 인용: 파일경로:라인번호 필수. 코드블록 사용 시에도 경로:라인 병기
+  - 변경 후 모습: 코드블록·구조도·시그니처로 제시
+  - 차이점 대비: 동일 관점에서 선택지 나란히 비교
+  - 영향 범위: 파급되는 파일·모듈·API 명시
+  - 원칙: 사용자가 원문을 찾지 않아도 이 출력만으로 판단 가능해야 한다
+- 축별 점수
+  - 맥락에 맞는 관점(축) 3개 이상 선정
+  - 축별 점수를 반드시 노출한 뒤 평균을 10점 만점으로 병기 (최종 점수만 쓰는 것 금지)
 
-- 모든 점수는 **10점 만점**이다
-- LLM이 맥락에 맞는 관점(축)을 3개 이상 선정하여 관점별 점수를 매기고, **축별 점수를 반드시 노출한 뒤 평균을 10점 만점으로 함께 표시**한다 (최종 점수만 쓰는 것 금지)
-- **하나의 선택지를 명시적으로 추천** — 추천 사유를 한 줄로 요약

package/claude/sd-cache-read-hash.py

@@ -0,0 +1,18 @@
+import hashlib, json, os, sys
+
+data = json.load(sys.stdin)
+tool_input = data["tool_input"]
+file_path = tool_input.get("file_path", "")
+session_id = data.get("session_id", "unknown")
+
+if not file_path or not os.path.isfile(file_path):
+    sys.exit(0)
+
+file_hash = hashlib.sha256(open(file_path, "rb").read()).hexdigest()
+path_hash = hashlib.sha256(os.path.normpath(file_path).encode()).hexdigest()
+
+cache_dir = os.path.join(".tmp", "read_hash", session_id)
+os.makedirs(cache_dir, exist_ok=True)
+
+with open(os.path.join(cache_dir, path_hash), "w") as f:
+    f.write(file_hash)

package/claude/sd-check-write.py

@@ -1,7 +1,19 @@
-import json, os, sys
+import hashlib, json, os, sys
 
 data = json.load(sys.stdin)
 file_path = data["tool_input"]["file_path"]
+session_id = data.get("session_id", "unknown")
+
 if os.path.isfile(file_path):
-    print(f"CRITICAL: This file already exists. NEVER delete/rm the file and retry with Write. You MUST use the Edit tool instead: {file_path}", file=sys.stderr)
-    sys.exit(2)
+    path_hash = hashlib.sha256(os.path.normpath(file_path).encode()).hexdigest()
+    cache_file = os.path.join(".tmp", "read_hash", session_id, path_hash)
+
+    cached_hash = ""
+    if os.path.isfile(cache_file):
+        cached_hash = open(cache_file, "r").read().strip()
+
+    current_hash = hashlib.sha256(open(file_path, "rb").read()).hexdigest()
+
+    if cached_hash != current_hash:
+        print(f"CRITICAL: File content has changed or was never Read. You MUST Read the file first, then MUST REVISE your Write content based on the current file content before retrying: {file_path}", file=sys.stderr)
+        sys.exit(2)

package/claude/settings.json

@@ -29,6 +29,17 @@
         ]
       }
     ],
+    "PostToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python .claude/sd-cache-read-hash.py"
+          }
+        ]
+      }
+    ],
     "SubagentStart": [
       {
         "hooks": [

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

@@ -16,9 +16,9 @@ description: typecheck, lint, test를 실행하고 에러 발생시 사용자
 발견된 에러가 **수정 대상**인지 판단하는 기준:
 
 - **sd-check 단독 실행 (이 대화에서 sd-check 호출 전 Claude의 코드 수정이 없음)**: 발견된 **모든 에러**가 수정 대상. "수정 대상 외"로 판단하여 스킵 금지(NEVER).
-- **직전 대화 내 코드 수정이 있음**: 해당 수정과 **관련된 에러만** 수정 대상. 무관한 에러는 조용히 스킵하되, 사용자에게 **보고하지 않는다** (그냥 넘어간다).
+- **대화세션내 코드 수정이 있음**: 해당 수정과 **관련된 에러만** 수정 대상. 무관한 에러는 조용히 스킵하되, 사용자에게 **보고하지 않는다** (그냥 넘어간다).
 
-판단 제외 — "직전 수정"에 해당하지 않는 것:
+판단 제외 — "대화세션내 수정"에 해당하지 않는 것:
 - git status의 미커밋 변경, 과거 커밋 변경
 - sd-check 내부(typecheck/lint/test 단계)에서 발생한 수정
 
@@ -81,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
 ```
 
 탐지된 스크립트가 없으면 오류 메시지를 출력하고 종료한다.
@@ -108,4 +108,4 @@ typecheck 명령어를 실행한다. (`출력 캡처 규칙`에 따라 파일로
 
 ## Step 5: 반복 혹은 완료
 
-typecheck, lint, test를 수행하는 동안 코드 수정이 있었으면 `typecheck`부터 다시 시작한다. 수정이 없었으면 완료.
+typecheck, lint, test 수행 중 코드 수정이 있었으면 `typecheck`부터 다시 시작한다. 수정이 없었으면 완료.

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

@@ -6,13 +6,12 @@ effort: low
 
 # sd-claude-docs: CLAUDE.md + README.md/docs 통합 생성
 
-프로젝트를 분석하여 CLAUDE.md(내부 개발 컨텍스트)와 README.md/docs/(소비자용 API 문서)를 한 번에 생성한다.
-설정 파일, 스크립트, 소스 코드에서 검증 가능한 사실만 추출한다. 기존 문서가 있으면 섹션 단위로 병합한다.
+프로젝트를 분석하여 **CLAUDE.md**(모노레포 내부 개발자용 컨텍스트)와 **README.md + docs/**(패키지 소비자용 API 문서)를 한 번에 생성·갱신한다. 설정 파일·스크립트·소스 코드에서 검증 가능한 사실만 추출하며, 기존 문서는 섹션 단위로 병합한다.
 
-- **라이브러리 프로젝트** (`private: true`가 아닌 패키지가 1개 이상): CLAUDE.md + 각 패키지 내 `README.md`(+ 필요 시 `docs/`)
+- **라이브러리 프로젝트** (`private: true`가 아닌 패키지 1개 이상 존재): CLAUDE.md + 각 패키지 `README.md` (+ 분량 조건에 해당 시 `docs/{category}/{entry}.md` 트리)
 - **소비앱** (모든 패키지가 `private: true`): CLAUDE.md만 생성
 
-CLAUDE.md는 모노레포 **내부 개발자(LLM 포함)** 용 컨텍스트이고, README.md + docs/는 **패키지 소비자** 용 API/사용 지침 문서다. 두 문서는 독립적으로 유지한다. 패키지 CLAUDE.md 최상단에는 README.md를 참조하도록 안내 문구를 삽입한다(Step 3에서 규정).
+**두 문서의 독립성.** CLAUDE.md는 **모노레포 내부 개발자(LLM 포함)**용, README.md + docs/는 **패키지 소비자**용이다. 대상·관점이 달라 중복되지 않는다. README.md + docs/는 **wiki 스타일**로 구성한다 — 각 export된 class/component(Entry)는 자체 md 파일로 분리되어, 소비자(특히 LLM)가 필요한 Entry 하나만 조회할 수 있게 한다. README.md는 인덱스, 상세는 각 Entry 파일에 둔다.
 
 ## 사용법
 
@@ -21,7 +20,33 @@ CLAUDE.md는 모노레포 **내부 개발자(LLM 포함)** 용 컨텍스트이
 /sd-claude-docs angular      ← packages/angular 만
 ```
 
-## Step 1: 프로젝트 설정 분석
+## 공통 규칙
+
+### 작성 언어
+
+모든 문서는 **대화언어**로 작성한다. "적절히", "필요에 따라", "상황에 따라" 같은 모호한 표현을 사용하지 않는다.
+
+### 문서 병합 규칙
+
+기존 문서가 있으면 섹션(`##` 제목) 단위로 비교한다.
+
+1. 동일 주제의 기존 섹션 → 새 콘텐츠로 **대체**
+2. 대응 섹션이 없는 기존 섹션 → 그대로 **보존**
+3. 기존 섹션 위치를 유지하고, 새로 생성된 섹션은 마지막 기존 섹션 **뒤에** 추가
+
+### 출력 경로 규칙
+
+라이브러리 프로젝트에서 패키지 소비자용 문서는 **해당 패키지 루트**에 위치한다.
+
+| 구분 | CLAUDE.md | README.md | docs/ |
+|------|-----------|-----------|-------|
+| 모노레포 (각 패키지) | `{패키지 경로}/CLAUDE.md` | `{패키지 경로}/README.md` | `{패키지 경로}/docs/{category}/{entry}.md` |
+| 모노레포 루트 | `./CLAUDE.md` | — | — |
+| 단일 패키지 (루트=패키지) | `./CLAUDE.md` | `./README.md` | `./docs/{category}/{entry}.md` |
+
+`private: true` 패키지는 README.md / docs/를 생성하지 않는다 (CLAUDE.md만).
+
+## Step 1: 사전 분석
 
 ### 1-1. 패키지 매니저 감지
 
@@ -37,11 +62,11 @@ CLAUDE.md는 모노레포 **내부 개발자(LLM 포함)** 용 컨텍스트이
 루트 `package.json`의 `scripts` 섹션을 읽고 각 스크립트의 CLI 도구를 분석한다.
 
 - **잘 알려진 도구** (`tsc`, `vitest`, `eslint`, `prettier`, `playwright` 등): 명령어를 그대로 기록
-- **커스텀 CLI 또는 프로젝트 내부 스크립트** (예: `tsx packages/.../cli.ts`): Bash에서 `--help`를 먼저 실행한다(5초 타임아웃). `--help`로 하위 명령어와 주요 옵션을 파악할 수 있으면 그 결과를 사용한다. `--help`가 실패하거나 유용한 정보가 없을 때에만 소스 코드를 Read로 분석한다
+- **커스텀 CLI** (예: `tsx packages/.../cli.ts`): Bash에서 `--help`를 먼저 실행한다 (5초 타임아웃). 유용한 정보가 있으면 그 결과를 사용한다. `--help`가 실패하거나 정보가 부족할 때만 소스 코드를 Read로 분석한다.
 
 ### 1-3. 코딩 규칙 추출
 
-프로젝트 루트에서 아래 설정 파일을 찾아 읽는다 (없는 파일은 건너뛴다):
+아래 설정 파일을 찾아 읽는다 (없는 파일은 건너뛴다):
 
 - ESLint: `eslint.config.*`, `.eslintrc.*`
 - Prettier: `.prettierrc*`, `prettier.config.*`
@@ -49,113 +74,99 @@ CLAUDE.md는 모노레포 **내부 개발자(LLM 포함)** 용 컨텍스트이
 - TypeScript: `tsconfig.json` → `compilerOptions`
 - Stylelint: `.stylelintrc*`, `stylelint.config.*`
 
-아래 기준으로 규칙을 선별한다:
+선별 기준:
 
-- 도구의 기본값과 다른 설정 (예: TypeScript `verbatimModuleSyntax: true`, Prettier `printWidth: 100`)
+- 도구 기본값과 다른 설정 (예: TypeScript `verbatimModuleSyntax: true`, Prettier `printWidth: 100`)
 - error 수준의 비표준 규칙 (예: `no-console: error`)
 - 특정 API를 금지하거나 요구하는 규칙 (예: `Buffer` 금지 → `Uint8Array` 사용)
 
-### 1-4. .claude/rules/ 스캔
+### 1-4. `.claude/rules/` 스캔
 
-`.claude/rules/` 디렉토리가 존재하면 모든 `.md` 파일을 읽는다. 이미 다루고 있는 주제를 목록화한다. 해당 주제는 **CLAUDE.md에서 제외**한다 — 파일 간 규칙 중복은 LLM이 고유한 지침 대신 중복 컨텍스트를 처리하게 되어 지침의 효과를 약화시킨다.
+디렉토리가 존재하면 모든 `.md` 파일을 읽어 이미 다루고 있는 주제를 목록화한다. 해당 주제는 **CLAUDE.md에서 제외**한다 — 파일 간 규칙 중복은 LLM이 고유 지침 대신 중복 컨텍스트를 처리하게 되어 지침의 효과를 약화시킨다.
 
 ### 1-5. 프로젝트 유형 감지
 
-모노레포인 경우 모든 패키지의 `package.json`을, 단일 패키지인 경우 루트 `package.json`을 확인한다.
+모노레포면 모든 패키지의 `package.json`을, 단일 패키지면 루트 `package.json`을 확인한다.
 
-- **라이브러리 프로젝트**: `private: true`가 아닌 패키지가 1개 이상 존재
+- **라이브러리 프로젝트**: `private: true`가 아닌 패키지가 1개 이상
 - **소비앱**: 모든 패키지가 `private: true`
 
-라이브러리 프로젝트인 경우 소비자용 문서의 출력 경로는 **해당 패키지 루트**다:
-- `README.md` → `{패키지 경로}/README.md`
-- 분량이 많은 경우 `{패키지 경로}/docs/*.md`
-- 단일 패키지 프로젝트면 루트가 곧 패키지 경로다 (`./README.md`, `./docs/`)
-
-`private: true` 패키지는 README.md / docs/를 생성하지 않는다 (CLAUDE.md만).
+## Step 2: 처리 대상 결정
 
-## Step 2: 분기
+인자 유무와 워크스페이스 구성으로 **처리 대상 패키지 경로 목록**을 확정한다. 단일 패키지 프로젝트는 루트를 "가상 패키지"로 취급하여 동일 프로세스를 적용한다 (자기참조 없음).
 
-### 패키지명 지정 시
+| 경우 | 처리 대상 | Step 4 수행 |
+|------|-----------|-------------|
+| 인자 있음 | `packages/{인자}/package.json`이 존재하면 해당 1개 경로. 없으면 사용자에게 알리고 종료. | 건너뜀 |
+| 인자 없음 + 모노레포 | `packages/` 하위 모든 패키지 경로 | 수행 |
+| 인자 없음 + 단일 패키지 | 루트 경로 1개 (루트 = 패키지) | 건너뜀 |
 
-`packages/{패키지명}/package.json`이 존재하는지 확인한다. 없으면 사용자에게 알린다.
-존재하면 해당 패키지에 대해 subagent 1개를 실행한다 (3단계의 subagent 프롬프트와 동일).
-root 문서는 생성·변경하지 않는다.
+## Step 3: 각 패키지 처리
 
-### 전체 실행 — 단일 패키지 프로젝트
+### 3-1. 소스 병합
 
-`workspaces` 필드가 없고 `pnpm-workspace.yaml`도 없으면 단일 패키지다.
-패키지별 CLAUDE.md는 생성하지 않는다. 바로 4단계로 진행하여 root 문서를 생성한다.
-라이브러리 프로젝트인 경우 `package-doc-gen.md`의 Step 2~4를 root에 직접 적용하여 루트의 `README.md` (+ 분량이 많으면 `docs/*.md`)를 생성한다.
+subagent가 개별 파일을 하나씩 Read하는 대신 병합 파일 1회 Read로 전체 소스를 파악할 수 있게 한다. 컨텍스트 소비를 대폭 줄이는 핵심 단계이다.
 
-### 전체 실행 — 모노레포
+각 패키지에 대해 Bash로 실행 (여러 패키지면 병렬):
 
-`packages/` 하위의 모든 패키지를 탐색하여 전체를 처리 대상으로 한다. 3단계로 진행한다.
+```bash
+bash .claude/skills/sd-claude-docs/merge-source.sh {패키지경로} ./tmp/{패키지명}-source.txt
+```
 
-## Step 3: 패키지별 문서 생성 (모노레포)
+### 3-2. subagent 병렬 실행
 
-각 패키지에 대해 **Agent 도구로 subagent(effort: `low`)를 병렬 실행**한다.
-하나의 메시지에서 모든 패키지의 Agent 호출을 동시에 보낸다.
+처리 대상 목록의 각 경로에 대해 **Agent 도구로 subagent(effort: `low`)를 병렬 실행**한다. 하나의 메시지에서 모든 Agent 호출을 동시에 보낸다.
 
-### subagent 프롬프트
+#### subagent 프롬프트
 
 ```
-{패키지 경로}의 CLAUDE.md와 README.md/docs를 생성한다.
+{패키지 경로}의 CLAUDE.md와 README.md/docs를 생성·갱신한다.
 
-## CLAUDE.md 생성 (`{패키지 경로}/CLAUDE.md`)
+`.claude/skills/sd-claude-docs/references/package-docs.md`를 읽고 그 지침을 따른다.
 
-`.claude/skills/sd-claude-docs/references/package-claudemd.md`를 읽고 그 지침을 따른다.
-
-루트 수준 설정 (이 내용과 동일한 정보는 패키지 CLAUDE.md에 반복하지 않는다):
-{1단계에서 추출한 코딩 규칙 및 컴파일러 설정 목록}
-
-## README.md / docs/ 생성 {`private: true` 패키지이면 이 섹션 전체 생략}
-
-`.claude/skills/sd-claude-docs/references/package-doc-gen.md`를 읽고 그 지침을 따른다.
-출력 경로: `{패키지 경로}/` (README.md는 항상, docs/는 분량 분기 조건에 해당될 때)
+전달 사항:
+- 패키지 경로: {패키지 경로}
+- 소스 병합 파일: {./tmp/{패키지명}-source.txt의 절대 경로}
+- 루트 수준 설정 (이 내용과 중복되는 정보는 패키지 CLAUDE.md에 반복하지 않는다):
+  {Step 1에서 추출한 코딩 규칙·컴파일러 설정 목록}
 ```
 
-각 subagent는 소스 코드를 한 번 분석하여 CLAUDE.md(Key Patterns)와 README.md/docs(API 문서) 모두에 활용한다.
+각 subagent는 소스 병합 파일을 한 번 Read하여 CLAUDE.md(Key Patterns)와 README.md/docs(API 문서) 모두에 활용한다.
 
 ### subagent 반환 정보
 
-- CLAUDE.md 생성 여부
-- README.md 생성 여부 + 문서 구조 (README 단독 / README + docs/)
-- API 항목 수
+- 패키지 경로
+- CLAUDE.md 생성/갱신/건너뜀 여부
+- README.md 생성/갱신/건너뜀 여부 + 구조 (README 단독 / README + docs 트리)
+- Entry 수 / 총 API 항목 수
 - 생성된 파일 목록
 
-## Step 4: root 문서 생성
+## Step 4: 루트 CLAUDE.md 생성
 
-### root CLAUDE.md
+Step 2의 "Step 4 수행" 열이 "수행"인 경우에만 진행한다.
 
-1단계의 정보를 조합하여 루트 CLAUDE.md 콘텐츠를 생성한다. `.claude/rules/`에서 이미 다루고 있는 주제(1-4단계에서 감지)는 제외한다.
+### 4-1. 콘텐츠 구성
 
-**모노레포인 경우**: 3단계에서 생성된 각 패키지의 `CLAUDE.md`를 Read하여 참고한다. 패키지별 CLAUDE.md에 이미 기술된 상세 내용(아키텍처, 패턴 등)은 루트에 중복 기술하지 않고, 아키텍처 섹션에서 패키지 간 의존 관계와 역할 요약만 포함한다.
+Step 1 결과와 Step 3의 각 패키지 CLAUDE.md를 조합하여 루트 CLAUDE.md를 생성한다. `.claude/rules/`에서 이미 다루는 주제(1-4에서 감지)는 **제외**한다. 패키지 CLAUDE.md에 기술된 상세(아키텍처, 패턴 등)는 루트에 중복하지 않고, 아키텍처 섹션에서 패키지 간 의존 관계와 역할 요약만 포함한다.
 
 #### 포함할 섹션
 
-- **프로젝트 정보**: `package.json`의 `name`과 `description`, 패키지 매니저
-- **모노레포 구조**: `workspaces` 필드 또는 `pnpm-workspace.yaml`이 있으면 워크스페이스 경로를 나열하고 각 패키지를 간략히 설명 (패키지당 10단어 이내)
-- **기술 스택**: `dependencies`/`devDependencies`의 주요 라이브러리 — 프레임워크, 번들러, 테스트 도구 (최대 10개)
-- **명령어**: 1-2단계의 스크립트를 bash 코드 블록으로 포매팅하고 인라인 주석 추가, 카테고리별 그룹화
-- **아키텍처**: 모노레포인 경우 패키지별 CLAUDE.md에서 역할을 읽어 패키지 간 의존 관계를 요약한다
-- **코딩 규칙**: 1-3단계에서 선별한 규칙을 불릿 리스트로 포매팅
+- **프로젝트 정보**: 루트 `package.json`의 `name`/`description`, 패키지 매니저
+- **모노레포 구조**: 워크스페이스 경로 나열, 각 패키지 10단어 이내 요약
+- **기술 스택**: 주요 프레임워크·번들러·테스트 도구 (최대 10개)
+- **명령어**: 1-2의 스크립트를 카테고리별 bash 코드 블록으로 포매팅, 인라인 주석 추가
+- **아키텍처**: 패키지 간 의존 관계 및 역할 요약
+- **코딩 규칙**: 1-3에서 선별한 규칙을 불릿 리스트로 포매팅
 
-실질적 내용이 없는 섹션은 생략한다. 프로젝트에 필요하면 위 목록에 없는 섹션도 추가한다 (예: 통합 테스트).
+실질적 내용이 없는 섹션은 생략한다. 필요 시 위 외 섹션도 추가한다 (예: 통합 테스트).
 
-#### 병합
+### 4-2. 병합
 
-- **기존 파일이 없는 경우**: 바로 저장
-- **기존 파일이 있는 경우**:
-  1. 기존 파일을 읽는다
-  2. 새 콘텐츠와 기존 콘텐츠를 섹션(`##` 제목) 단위로 비교한다
-  3. 병합 규칙:
-     - 생성된 섹션과 동일한 주제의 기존 섹션 → 새 콘텐츠로 **대체**
-     - 생성된 대응 섹션이 없는 기존 섹션 → 그대로 **보존**
-     - 기존 섹션의 위치를 보존한다. 새로 생성된 섹션은 반드시 마지막 기존 섹션 뒤에 추가한다
+공통 규칙의 "문서 병합 규칙"을 적용한다.
 
-#### 참고 예시
+### 참고 예시
 
-아래의 **섹션 구조와 포매팅 스타일**을 따른다. **CLAUDE.md는 반드시 대화언어로 작성한다.**
+아래 **섹션 구조와 포매팅 스타일**을 따른다.
 
 ````markdown
 # Simplysm
@@ -164,8 +175,6 @@ pnpm 모노레포. 패키지 경로: `packages/*`, 테스트: `tests/*`
 
 ## 명령어
 
-모든 명령어는 내부적으로 `pnpm sd-cli <command>`를 실행한다.
-
 ### 개발
 
 ```bash
@@ -176,7 +185,7 @@ pnpm watch [targets..]                   # 라이브러리 패키지를 watch
 ### 코드 품질
 
 ```bash
-pnpm check [targets..]                   # 전체 검사 (typecheck + lint 병렬)
+pnpm check [targets..]                   # 전체 검사
 pnpm typecheck [targets..]               # TypeScript 타입 체크
 ```
 
@@ -186,7 +195,7 @@ pnpm typecheck [targets..]               # TypeScript 타입 체크
 
 ```
 UI:       angular (Angular)
-서비스:   service-server (Fastify) / service-client / service-common
+서비스:   service-server / service-client / service-common
 코어:     core-common (중립) / core-browser / core-node
 ```
 
@@ -201,20 +210,20 @@ UI:       angular (Angular)
 ```markdown
 ## sd-claude-docs 결과
 
-| 패키지 | CLAUDE.md | README.md | 구조 | API 항목 수 |
+| 패키지 | CLAUDE.md | README.md | 구조 | Entry / API |
 |--------|-----------|-----------|------|-------------|
 | root | 생성 | — | — | — |
-| @simplysm/core-common | 갱신 | 갱신 | README 단독 | 35 |
-| @simplysm/angular | 갱신 | 갱신 | README + docs/ | 126 |
-| @simplysm/storage | 생성 | 생성 | README 단독 | 8 |
+| @simplysm/core-common | 갱신 | 갱신 | README 단독 | 8 / 35 |
+| @simplysm/angular | 갱신 | 갱신 | README + docs 트리 | 72 / 126 |
 | @simplysm/internal | 생성 | — (private) | — | — |
 
 ### 생성된 파일 목록
 - CLAUDE.md (root)
 - packages/core-common/CLAUDE.md
 - packages/core-common/README.md
+- packages/core-common/docs/utils/string-utils.md
 - packages/angular/CLAUDE.md
 - packages/angular/README.md
-- packages/angular/docs/types.md
+- packages/angular/docs/{category}/{entry}.md …
 - ...
 ```