@simplysm/sd-claude 14.0.41 → 14.0.43

package/claude/references/sd-simplysm14/storage/usage.md

@@ -14,9 +14,9 @@ npm install @simplysm/storage
 
 | API | Type | Description |
 |-----|------|-------------|
-| `StorageProtocol` | type | 지원 프로토콜 유니온 타입 (`"ftp" \| "ftps" \| "sftp"`) |
-| `StorageConnConfig` | interface | 스토리지 연결 설정 (host, port, user, password) |
-| `FileInfo` | interface | 파일/디렉토리 정보 (name, isFile) |
+| `StorageProtocol` | type | 지원 프로토콜 유니온 타입 (`"ftp"` \| `"ftps"` \| `"sftp"`) |
+| `StorageConnConfig` | interface | 스토리지 연결 설정 |
+| `FileInfo` | interface | 파일/디렉토리 정보 |
 | `StorageClient` | interface | 스토리지 클라이언트 공통 인터페이스 |
 
 #### `StorageProtocol`
@@ -25,6 +25,11 @@ npm install @simplysm/storage
 type StorageProtocol = "ftp" | "ftps" | "sftp";
 ```
 
+지원하는 프로토콜을 나타내는 유니온 타입:
+- `"ftp"`: 일반 FTP 프로토콜
+- `"ftps"`: TLS/SSL 암호화 FTP 프로토콜
+- `"sftp"`: SSH 기반 SFTP 프로토콜
+
 #### `StorageConnConfig`
 
 ```typescript
@@ -39,9 +44,9 @@ interface StorageConnConfig {
 | Field | Type | Description |
 |-------|------|-------------|
 | `host` | `string` | 서버 호스트 주소 |
-| `port` | `number \| undefined` | 포트 번호 (생략 시 프로토콜 기본값 사용) |
+| `port` | `number \| undefined` | 포트 번호. 생략 시 프로토콜 기본값 사용 (FTP: 21, FTPS: 21, SFTP: 22) |
 | `user` | `string \| undefined` | 사용자 이름 |
-| `password` | `string \| undefined` | 비밀번호. SFTP에서 생략하면 SSH agent + `~/.ssh/id_ed25519` 키 파일 인증 시도 |
+| `password` | `string \| undefined` | 비밀번호. SFTP에서 생략하면 SSH agent (`SSH_AUTH_SOCK` 환경변수) + `~/.ssh/id_ed25519` 키 파일 인증을 순서대로 시도 |
 
 #### `FileInfo`
 
@@ -54,7 +59,7 @@ interface FileInfo {
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `name` | `string` | 파일 또는 디렉토리 이름 |
+| `name` | `string` | 파일 또는 디렉토리의 이름 |
 | `isFile` | `boolean` | `true`이면 파일, `false`이면 디렉토리 |
 
 #### `StorageClient`
@@ -78,23 +83,23 @@ interface StorageClient {
 
 | Method | Parameters | Return | Description |
 |--------|-----------|--------|-------------|
-| `connect` | `config: StorageConnConfig` | `Promise<void>` | 서버에 연결 |
-| `mkdir` | `dirPath: string` | `Promise<void>` | 디렉토리 생성 (부모 디렉토리 자동 생성) |
-| `rename` | `fromPath: string, toPath: string` | `Promise<void>` | 파일/디렉토리 이름 변경 |
+| `connect` | `config: StorageConnConfig` | `Promise<void>` | 스토리지 서버에 연결. 연결 해제 전 한 번만 호출 가능 |
+| `mkdir` | `dirPath: string` | `Promise<void>` | 디렉토리 생성. 부모 디렉토리가 없으면 함께 생성 |
+| `rename` | `fromPath: string, toPath: string` | `Promise<void>` | 파일/디렉토리 이름 변경 또는 이동 |
 | `list` | `dirPath: string` | `Promise<FileInfo[]>` | 디렉토리 내 파일/디렉토리 목록 조회 |
 | `readFile` | `filePath: string` | `Promise<Bytes>` | 파일 내용을 `Bytes`(`Uint8Array`)로 읽기 |
-| `exists` | `filePath: string` | `Promise<boolean>` | 파일/디렉토리 존재 여부 확인 |
-| `put` | `localPathOrBuffer: string \| Bytes, storageFilePath: string` | `Promise<void>` | 로컬 파일 경로 또는 바이트 데이터를 원격에 업로드 |
-| `uploadDir` | `fromPath: string, toPath: string` | `Promise<void>` | 로컬 디렉토리 전체를 원격에 업로드 |
+| `exists` | `filePath: string` | `Promise<boolean>` | 파일/디렉토리 존재 여부 확인. 모든 예외는 `false` 반환 |
+| `put` | `localPathOrBuffer: string \| Bytes, storageFilePath: string` | `Promise<void>` | 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드 |
+| `uploadDir` | `fromPath: string, toPath: string` | `Promise<void>` | 로컬 디렉토리 전체를 원격 경로에 업로드 |
 | `remove` | `filePath: string` | `Promise<void>` | 파일 삭제 |
-| `close` | (없음) | `Promise<void>` | 연결 종료 |
+| `close` | 없음 | `Promise<void>` | 연결 종료. 이미 종료된 상태에서 호출해도 안전 |
 
 ### Clients
 
 | API | Type | Description |
 |-----|------|-------------|
-| `FtpStorageClient` | class | FTP/FTPS 프로토콜 스토리지 클라이언트 (`basic-ftp` 기반) |
-| `SftpStorageClient` | class | SFTP 프로토콜 스토리지 클라이언트 (`ssh2-sftp-client` 기반) |
+| `FtpStorageClient` | class | FTP/FTPS 프로토콜 스토리지 클라이언트 (`basic-ftp` 라이브러리 기반) |
+| `SftpStorageClient` | class | SFTP 프로토콜 스토리지 클라이언트 (`ssh2-sftp-client` 라이브러리 기반) |
 
 #### `FtpStorageClient`
 
@@ -106,10 +111,14 @@ class FtpStorageClient implements StorageClient {
 }
 ```
 
-- `_secure` 생성자 매개변수: `true`이면 FTPS, `false`이면 FTP 사용
-- 미연결 상태에서 메서드를 호출하면 `SdError`를 던진다
-- `exists()`는 먼저 `size()` 명령으로 파일을 O(1) 확인하고, 실패 시 부모 디렉토리 목록을 조회하여 디렉토리 존재 여부를 확인한다. 모든 예외에 대해 `false`를 반환한다
-- `close()`는 이미 종료된 상태에서 호출해도 안전하다
+**생성자**:
+- `_secure`: `true`이면 FTPS (TLS/SSL 암호화), `false`이면 FTP (기본값)
+
+**특징**:
+- `connect()`로 연결 후 메서드 호출. 미연결 상태에서 호출하면 `SdError` 발생
+- `exists()`는 먼저 `size()` 명령으로 파일을 O(1) 성능으로 확인하고, 실패 시 부모 디렉토리 목록을 조회하여 디렉토리 존재 여부 확인. 모든 예외는 `false` 반환
+- 슬래시가 없는 경로(예: `file.txt`)는 루트 디렉토리(`/`)에서 검색
+- `close()`는 이미 종료된 상태에서 호출해도 안전 (오류 미발생)
 
 #### `SftpStorageClient`
 
@@ -121,16 +130,23 @@ class SftpStorageClient implements StorageClient {
 }
 ```
 
-- `password`가 있으면 패스워드 인증, 없으면 SSH agent(`SSH_AUTH_SOCK`) + `~/.ssh/id_ed25519` 키 파일 인증을 순서대로 시도한다
-- 미연결 상태에서 메서드를 호출하면 `SdError`를 던진다
-- `exists()`는 `ssh2-sftp-client`의 `exists()` 반환값(`false | 'd' | '-' | 'l'`)으로 판단한다
-- `close()`는 이미 종료된 상태에서 호출해도 안전하다
+**인증 메커니즘**:
+- `password`가 있으면 패스워드 인증 사용
+- `password`가 없으면 다음 순서대로 시도:
+  1. SSH agent (`SSH_AUTH_SOCK` 환경변수 설정 시)
+  2. `~/.ssh/id_ed25519` 개인키 파일 인증
+  3. privateKey 파싱 실패 시 (암호화된 키 등) agent만으로 재시도
+
+**특징**:
+- `connect()`로 연결 후 메서드 호출. 미연결 상태에서 호출하면 `SdError` 발생
+- `exists()`는 `ssh2-sftp-client`의 `exists()` 반환값 (`false | 'd' | '-' | 'l'`)을 검사하여 존재 여부 판단. 모든 예외는 `false` 반환
+- `close()`는 이미 종료된 상태에서 호출해도 안전 (오류 미발생)
 
 ### Factory
 
 | API | Type | Description |
 |-----|------|-------------|
-| `StorageFactory` | class | 프로토콜에 따른 클라이언트 생성 및 연결 생명주기 관리 팩토리 |
+| `StorageFactory` | class | 프로토콜별 클라이언트 생성 및 연결 생명주기 자동 관리 |
 
 #### `StorageFactory`
 
@@ -146,17 +162,25 @@ class StorageFactory {
 }
 ```
 
+**메서드**:
+- `StorageFactory.connect<R>()` (정적 메서드)
+
+**파라미터**:
+
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `type` | `StorageProtocol` | 프로토콜 (`"ftp"`, `"ftps"`, `"sftp"`) |
+| `type` | `StorageProtocol` | 프로토콜 타입 (`"ftp"`, `"ftps"`, `"sftp"`) |
 | `config` | `StorageConnConfig` | 연결 설정 |
-| `fn` | `(storage: StorageClient) => R \| Promise<R>` | 연결된 클라이언트를 받아 작업을 수행하는 콜백 |
+| `fn` | `(storage: StorageClient) => R \| Promise<R>` | 연결된 클라이언트를 받아 작업을 수행하는 콜백. 반환값은 `Promise<R>` 형태로 래핑되어 반환됨 |
 
-콜백 완료 또는 예외 발생 시 연결이 자동으로 종료된다.
+**동작**:
+- `fn` 콜백이 완료되거나 예외를 발생시키면 연결이 자동으로 종료됨
+- `fn`에서 발생한 예외는 그대로 전파됨
+- 반환값: 콜백의 반환값
 
 ## Usage Examples
 
-### StorageFactory.connect로 파일 업로드
+### SFTP로 파일 업로드 (StorageFactory 사용 권장)
 
 ```typescript
 import { StorageFactory } from "@simplysm/storage";
@@ -171,7 +195,9 @@ await StorageFactory.connect(
 );
 ```
 
-### 파일 목록 조회 및 다운로드
+콜백이 완료되거나 예외가 발생하면 자동으로 연결이 종료된다.
+
+### FTP로 파일 목록 조회 및 다운로드
 
 ```typescript
 import { StorageFactory } from "@simplysm/storage";
@@ -184,18 +210,38 @@ const files = await StorageFactory.connect(
     for (const file of list.filter((f) => f.isFile)) {
       const content = await storage.readFile(`/data/${file.name}`);
       // content는 Bytes (Uint8Array)
+      console.log(`Read ${file.name}: ${content.length} bytes`);
     }
     return list;
   },
 );
 ```
 
+### FTPS로 파일 이름 변경
+
+```typescript
+import { StorageFactory } from "@simplysm/storage";
+
+await StorageFactory.connect(
+  "ftps",
+  { host: "ftps.example.com", user: "user", password: "pass" },
+  async (storage) => {
+    const exists = await storage.exists("/remote/file.txt");
+    if (exists) {
+      await storage.rename("/remote/file.txt", "/remote/backup.txt");
+    }
+  },
+);
+```
+
 ### 클라이언트 직접 사용 (수동 생명주기 관리)
 
+클라이언트를 직접 인스턴스화하여 수동으로 연결 생명주기를 관리할 수 있다. 하지만 연결 누수 위험이 있으므로 `StorageFactory.connect` 사용을 권장한다.
+
 ```typescript
 import { FtpStorageClient } from "@simplysm/storage";
 
-const client = new FtpStorageClient(true); // FTPS
+const client = new FtpStorageClient(true); // FTPS 사용
 try {
   await client.connect({ host: "ftps.example.com", user: "user", password: "pass" });
   const exists = await client.exists("/remote/file.txt");
@@ -206,3 +252,50 @@ try {
   await client.close();
 }
 ```
+
+### SSH 키 인증으로 SFTP 연결 (비밀번호 생략)
+
+`password`를 생략하면 SSH agent와 `~/.ssh/id_ed25519` 키 파일을 사용하여 인증한다.
+
+```typescript
+import { StorageFactory } from "@simplysm/storage";
+
+await StorageFactory.connect(
+  "sftp",
+  { host: "sftp.example.com", user: "user" }, // password 생략
+  async (storage) => {
+    const list = await storage.list("/home/user");
+    console.log(`Files: ${list.map((f) => f.name).join(", ")}`);
+  },
+);
+```
+
+### 바이트 데이터로 파일 업로드
+
+```typescript
+import { StorageFactory } from "@simplysm/storage";
+
+const data = new Uint8Array([0x48, 0x65, 0x6c, 0x6c, 0x6f]); // "Hello"
+
+await StorageFactory.connect(
+  "sftp",
+  { host: "sftp.example.com", user: "user", password: "pass" },
+  async (storage) => {
+    await storage.put(data, "/remote/file.bin");
+  },
+);
+```
+
+### 로컬 디렉토리 전체 업로드
+
+```typescript
+import { StorageFactory } from "@simplysm/storage";
+
+await StorageFactory.connect(
+  "ftp",
+  { host: "ftp.example.com", user: "user", password: "pass" },
+  async (storage) => {
+    await storage.uploadDir("/local/folder", "/remote/backup");
+  },
+);
+```

package/claude/references/sd-testing.md

@@ -2,11 +2,107 @@
 
 ## 모킹 원칙
 
-- **CRITICAL: 모든 코드는 기본적으로 실제로 실행시킨다.** 테스트 환경에서 물리적으로 실행 불가능한 것(실제 네트워크 서버, 하드웨어 장치, 사용자 상호작용 UI 등)만 어쩔 수 없이 모킹한다.
-- 모킹 여부를 판단할 때 "이걸 모킹하면 편하다"가 아니라 **"이걸 모킹 안 하면 테스트가 물리적으로 돌아갈 수 없는가?"** 를 기준으로 한다. 답이 "돌아간다"이면 모킹하지 않는다.
+**CRITICAL: 모든 코드는 기본적으로 실제로 실행시킨다. mock은 최후의 수단이다.**
+
+### 모킹 결정 플로우차트
+
+mock을 작성하기 **전에** 반드시 아래 순서로 판단한다:
+
+1. **이 의존성을 실제로 실행하면 테스트가 물리적으로 돌아가는가?**
+   - 돌아간다 → **모킹 금지. 실제 코드를 실행한다.**
+   - 돌아가지 않는다 → 2번으로
+2. **왜 물리적으로 불가능한가? 아래 화이트리스트에 해당하는가?**
+   - 해당한다 → 모킹 허용 (최소 범위로)
+   - 해당하지 않는다 → **모킹 금지. 테스트 설계를 재고한다.**
+
+### 모킹 허용 화이트리스트
+
+아래 항목**만** 모킹이 허용된다. 이 목록에 없으면 모킹하지 않는다:
+
+| 허용 대상 | 예시 | 이유 |
+|-----------|------|------|
+| 외부 네트워크 요청 | HTTP API 호출, WebSocket 서버 연결 | 외부 서버가 테스트 환경에 없음 |
+| 데이터베이스 연결 | DB 커넥션, 쿼리 실행 | DB 인스턴스가 테스트 환경에 없을 때만 (Docker로 띄울 수 있으면 실제 DB 사용) |
+| 하드웨어/OS 의존 | USB 장치, 파일시스템의 특수 권한, 네이티브 플러그인 | 물리 장치가 없음 |
+| 타이머/시간 | `Date.now()`, `setTimeout` | `vi.useFakeTimers()`로 제어 (이것은 mock이 아닌 테스트 유틸리티) |
+
+**다음은 모킹 대상이 아니다:**
+- 같은 패키지의 다른 모듈/클래스 → 실제 인스턴스를 생성해서 사용
+- 유틸리티 함수, 순수 함수 → 그냥 실행
+- 설정/config 객체 → 테스트용 실제 값을 만들어서 주입
+- 에러 핸들링 로직 → 실제 에러를 발생시켜서 테스트
+- 이벤트 핸들러/콜백 → 실제로 이벤트를 발생시켜서 테스트
+
+### 모킹 세부 규칙
+
 - `vi.mock()` 하나가 모듈 전체를 대체하므로, 순수 함수까지 함께 가짜로 바뀐다. 혼합 모듈은 `importOriginal`로 실제 구현을 최대한 살린다.
-- **모킹이 실제 로직을 복제하면 모킹이 불필요하다는 증거다.** 예: `err: { message: (e) => e?.message ?? String(e) }` — 원본과 동일한 코드를 모킹에 작성하고 있다면 실제 모듈을 그대로 쓴다.
-- **호출 여부만 확인하려면 `vi.mock()`이 아니라 `vi.spyOn()`을 쓴다.** mock은 구현을 가짜로 대체하고, spy는 실제 코드를 실행하면서 호출을 추적한다. 실제 동작을 유지한 채 "호출됐는가"만 검증하려면 항상 spy를 쓴다.
+- **모킹이 실제 로직을 복제하면 모킹이 불필요하다는 증거다.** 모킹 코드가 원본 코드와 동일하거나 유사하면, 그 모킹을 삭제하고 실제 모듈을 쓴다.
+- **호출 여부만 확인하려면 `vi.mock()`이 아니라 `vi.spyOn()`을 쓴다.** mock은 구현을 가짜로 대체하고, spy는 실제 코드를 실행하면서 호출을 추적한다.
+
+### Bad/Good 예시
+
+#### 예시 1: 같은 패키지의 유틸리티 함수
+
+```typescript
+// ❌ BAD: 실행 가능한 유틸 함수를 모킹
+vi.mock("../utils/string-utils", () => ({
+  formatName: vi.fn().mockReturnValue("formatted"),
+}));
+
+test("이름을 포맷한다", () => {
+  const result = service.process("raw");
+  expect(formatName).toHaveBeenCalledWith("raw");  // 구현 결합
+  expect(result).toBe("formatted");
+});
+```
+
+```typescript
+// ✅ GOOD: 실제 유틸 함수를 실행
+import { formatName } from "../utils/string-utils";
+
+test("이름을 포맷한다", () => {
+  const result = service.process("raw");
+  expect(result).toBe("Raw");  // 실제 결과를 검증
+});
+```
+
+#### 예시 2: 클래스 의존성
+
+```typescript
+// ❌ BAD: 같은 패키지의 클래스를 통째로 모킹
+const mockParser = {
+  parse: vi.fn().mockReturnValue({ type: "text", value: "hello" }),
+  validate: vi.fn().mockReturnValue(true),
+};
+
+test("파서를 사용해 변환한다", () => {
+  const converter = new Converter(mockParser as any);
+  converter.convert("hello");
+  expect(mockParser.parse).toHaveBeenCalled();  // 구현 결합
+});
+```
+
+```typescript
+// ✅ GOOD: 실제 파서 인스턴스를 사용
+test("파서를 사용해 변환한다", () => {
+  const parser = new Parser();
+  const converter = new Converter(parser);
+  const result = converter.convert("hello");
+  expect(result).toEqual({ type: "text", value: "hello" });  // 동작 결과를 검증
+});
+```
+
+#### 예시 3: 외부 API (모킹이 정당한 경우)
+
+```typescript
+// ✅ OK: 외부 HTTP 서버는 테스트 환경에 없으므로 모킹 허용
+vi.spyOn(httpClient, "get").mockResolvedValue({ status: 200, data: { id: 1 } });
+
+test("사용자 정보를 조회한다", async () => {
+  const user = await userService.getUser(1);
+  expect(user.id).toBe(1);  // 반환값을 검증 (호출 여부가 아님)
+});
+```
 
 ## 검증 원칙
 

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

@@ -3,7 +3,15 @@
 - 어떠한 경우에도 지침을 무시하고 건너뛰지 않는다. 혼자만의 판단으로 무단 진행 절대(NEVER) 금지
 - 지침이 충돌등의 이유로 애매하면 사용자에게 질문한다.
 - 근거없는 답변 금지. 답변에는 항상 그 근거가 포함되어야 함.
-- 문제의 원인을 지멋대로 추측하지 말것. 코드 문제면 코드베이스 검토 반드시 수행해야함.
+- 코드를 수정할 때, 왜 그 코드가 문제인지 근거를 먼저 확인하고 수정한다. "일단 바꿔보고 되면 넘어가자" 식의 추측성 시행착오를 절대(NEVER) 금지한다.
+
+# CRITICAL: 변경사항 되돌리기 금지
+
+**git diff에 나타나는 변경사항을 임의로 되돌리지 않는다(NEVER).**
+
+- `git diff`에 보이는 변경은 사용자가 직접 수정한 것일 수 있다. subagent가 만든 변경인지, 사용자가 직접 한 변경인지 구분할 수 없으므로, 어떤 변경이든 되돌리기 전에 반드시 사용자에게 확인한다.
+- 특히 현재 작업 범위 밖의 파일 변경을 발견해도, "의도하지 않은 변경"이라고 단정짓지 않는다. 사용자가 별도로 수정한 코드일 수 있다.
+- 되돌려야 할 명확한 근거(사용자의 명시적 요청, 빌드/테스트 실패 등)가 없으면 절대 되돌리지 않는다.
 
 # Compaction Rules
 
@@ -33,7 +41,7 @@
 
 - 사용자의 질문에 답변만 하라. 절대 임의로 다음단계(특히, 코드변경)로 넘어가지 않는다(NEVER). 답변만 하고 사용자의 명시적 요청을 기다린다.
 - 사용자의 질문은 동의를 구하는것이 아니다. 무조건적 동의하려하지 말고, 비판적으로 사고하여 답변한다.
-- 사용자의 요청에 대해 `.claude/references/sd-clarify.md`를 읽고, 사용자의 의도를 명확화 한다. (절대 추측하지 않는다.)
+- 사용자의 요청에 대해 `.claude/rules/sd-clarify.md` 지침에 따라, 사용자의 의도를 명확화 한다. (절대 추측하지 않는다.)
 
 # Playwright
 
@@ -46,7 +54,7 @@
 - `@angular/*` 패키지를 사용할 때 `angular-cli` mcp를 활용하여, 표준 사용법을 확인하여 따른다.
 - 테스트 작성 시 `.claude/references/sd-testing.md`를 읽고 따른다.
 - 프론트엔드 UI 코드 작성·수정 시 `.claude/references/sd-frontend-design.md`를 읽고 따른다.
-- 디버깅 시 `.claude/references/sd-debug.md`를 읽고 따른다.
+- 디버깅 시 `/sd-inner-debug` 스킬을 호출한다.
 - 코딩을 하거나 코드예제를 출력할때는, 반드시 코드베이스의 기존 패턴을 확인하여 통일성있게 안내한다.
 - 코드를 수정할 경우 수정에 의한 사이드이펙트를 항상 고려한다. (예, html구조가 바뀌면 css의 selector도 바뀌어야함)
 - 함수 작성 혹은 함수내 기능 추가시 단일 책임 원칙을 따른다. (함수가 이름에서 드러나지 않는 일을 몰래 해선 안됨)
@@ -54,9 +62,15 @@
 - **barrel export 금지**: `src/` 루트의 `index.ts`를 제외하고, 하위 폴더에 re-export 전용 `index.ts`를 만들지 않는다. 패키지 루트 `index.ts`에서 개별 파일 경로를 직접 export한다.
 - 다른 패키지의 타입등 re-export 금지.
 - **dynamic import (`import()`) 사용 금지**: 조건부 peer dependency 로딩, 외부 ts 파일 읽기 등 정적 import가 불가능한 경우를 제외하고 `import()` 사용 금지. 정적 `import` 문을 사용한다.
+- **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` 발생
@@ -67,7 +81,8 @@
 
 # @simplysm 패키지 참조
 
-- `@simplysm/*` 패키지 사용 시, `.claude/references/sd-simplysm{메이저버전}.md`를 읽고 해당 패키지의 문서 경로를 찾아 읽는다
+- `@simplysm/*` 패키지 사용 시, `.claude/references/sd-simplysm{메이저버전}.md`를 읽고 해당 패키지의 문서 경로를 찾아 읽는다.
+  - 주의사항: 해당 패키지의 `CLAUDE.md`를 읽는것이 아니다.
 - simplysm 패키지의 경우 context7은 구버전일 수 있으니 사용을 지양한다
 
 # 프로젝트 경계

package/claude/sd-check-write.py

@@ -3,5 +3,5 @@ import json, os, sys
 data = json.load(sys.stdin)
 file_path = data["tool_input"]["file_path"]
 if os.path.isfile(file_path):
-    print(f"File already exists. Use the Edit tool instead of overwriting: {file_path}", file=sys.stderr)
+    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)

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

@@ -9,21 +9,21 @@ description: typecheck, lint, test를 실행하고 에러 발생시 사용자
 
 ### 에러 분석 및 수정
 
-에러 분석: @.claude/references/sd-debug.md
+에러 분석: `/sd-inner-debug` 스킬을 호출한다.
 
 #### 에러 처리 범위
 
 이 **대화(conversation)** 에서, sd-check 호출 전에 Claude가 코드를 수정한 것.
 - git status의 미커밋 변경이나 과거 커밋 변경을 말하는것이 아님.
 - sd-check 내부(typecheck/lint/test 단계)에서의 수정을 말하는것이 아님.
-- sd-check 단독 실행시 발견된 모든 에러를 수정해야함
+- **CRITICAL**: sd-check 단독 실행시, 발견된 모든 에러를 수정해야함 (예: test 에러 발견시, typecheck/lint의 수정과는 별개로 모두 수정)
 - sd-check호출전 대화내 수정이 있었던 경우, 해당 수정과 관련된 에러만 수정 대상으로 봄
 
 #### 에스컬레이션 규칙
 
 **CRITICAL: 동일 에러가 2회 반복되면 즉시 수정을 중단하고 사용자에게 보고한다.**
 
-- 1회차: sd-debug.md에 따라 근본 원인을 분석하고 수정을 시도한다.
+- 1회차: `/sd-inner-debug` 스킬을 호출하여 근본 원인을 분석하고 수정을 시도한다.
 - 2회차(동일/유사 에러 재발): 수정을 중단하고, 지금까지의 분석 결과와 시도한 수정 내용을 사용자에게 보고한 뒤 판단을 요청한다.
 - 원인을 특정할 수 없는 경우에도 즉시 사용자에게 보고한다. 추측으로 수정 시도 금지.
 
@@ -63,13 +63,16 @@ Bash 출력이 길면 잘리므로 **반드시 파일로 리다이렉트**한
 | 3    | lint, eslint               | 린트      |
 | 4    | test, jest, vitest, mocha  | 테스트    |
 
+**typecheck와 lint는 동시수행할 수 있는 `script`가 있다면 하나로 묶어 동시수행**
+- Step 2 + Step 3가 하나의 Step으로 병합됨 (예: `pnpm check`)
+
 ### 1-3. 탐지 결과 표시
 
 ```
 탐지된 check 스크립트:
 1. typecheck → pnpm run typecheck
 2. lint → pnpm run lint
-3. test → pnpm run test
+3. test → pnpm vitest run
 ```
 
 탐지된 스크립트가 없으면 오류 메시지를 출력하고 종료한다.

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

@@ -1,6 +1,8 @@
 ---
 name: sd-claude-docs
 description: 프로젝트 분석을 통해 CLAUDE.md와 LLM용 usage 문서를 동시 생성하는 스킬. "init", "CLAUDE.md 생성", "usage 문서 생성", "LLM 문서 만들어줘", "패키지 문서 생성" 등을 요청할 때 사용한다.
+model: sonnet[1m]
+effort: low
 ---
 
 # sd-claude-docs: CLAUDE.md + usage 문서 통합 생성
@@ -67,7 +69,7 @@ description: 프로젝트 분석을 통해 CLAUDE.md와 LLM용 usage 문서를
 1. 루트 `package.json`의 `name`에서 라이브러리명을 추출한다
 2. 루트 `package.json`의 `version`에서 메이저 버전을 추출한다
 3. usage 문서 경로: `.claude/references/sd-{name}{majorVersion}/` (예: `sd-simplysm14/`)
-4. 인덱스 파일 경로: `.claude/rules/sd-{name}{majorVersion}.md` (예: `sd-simplysm14.md`)
+4. 인덱스 파일 경로: `.claude/references/sd-{name}{majorVersion}.md` (예: `sd-simplysm14.md`)
 
 ## Step 2: 분기
 
@@ -89,7 +91,8 @@ root 문서는 생성·변경하지 않는다.
 
 ## Step 3: 패키지별 문서 생성 (모노레포)
 
-각 패키지에 대해 **Agent 도구로 subagent를 병렬 실행**한다. 하나의 메시지에서 모든 패키지의 Agent 호출을 동시에 보낸다.
+각 패키지에 대해 **Agent 도구로 subagent(model: `sonnet`, effort: `low`)를 병렬 실행**한다.
+하나의 메시지에서 모든 패키지의 Agent 호출을 동시에 보낸다.
 
 ### subagent 프롬프트
 
@@ -172,7 +175,7 @@ pnpm watch [targets..]                   # 라이브러리 패키지를 watch
 ### 코드 품질
 
 ```bash
-pnpm check [targets..]                   # 전체 검사 (typecheck + lint + test 병렬)
+pnpm check [targets..]                   # 전체 검사 (typecheck + lint 병렬)
 pnpm typecheck [targets..]               # TypeScript 타입 체크
 ```
 
@@ -194,7 +197,7 @@ UI:       angular (Angular)
 
 ### sd-{name}{ver}.md (라이브러리 프로젝트만)
 
-라이브러리 프로젝트인 경우 `.claude/rules/sd-{name}{ver}.md` 인덱스 파일을 생성/갱신한다.
+라이브러리 프로젝트인 경우 `.claude/references/sd-{name}{ver}.md` 인덱스 파일을 생성/갱신한다.
 소비앱인 경우 이 단계를 건너뛴다.
 
 #### 포함할 내용

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

@@ -83,6 +83,7 @@ region 주석이 없으면, re-export되는 파일의 디렉토리 구조를 카
 
 - **대화언어로 작성**한다
 - **소스에서 읽은 내용만** 문서화한다 — 시그니처는 직접 복사하고, 존재하지 않는 파라미터·반환 타입·동작을 만들어내지 않는다
+- **기존 문서의 시그니처를 신뢰하지 않는다** — 기존 docs/*.md의 코드블록(시그니처·멤버 이름·타입·required 여부 등)을 그대로 재사용하지 않는다. 반드시 소스 파일을 Read하여 확인한 내용만 작성한다. 단, 소스 코드와 무관한 내용(사용 가이드, 주의사항, 규칙 등)은 그대로 보존한다
 - **모든 export를 빠짐없이 문서화한다** — Step 2에서 수집한 export 목록의 모든 항목이 문서에 포함되어야 한다. "덜 중요하다"는 이유로 생략하지 않는다
 - **interface/type은 필드별 설명 테이블을 포함한다** — 시그니처만 나열하지 않고, 각 필드의 타입과 설명을 테이블로 작성한다. 소스에 필드가 있는 interface를 빈 `{}`로 표시하는 것은 금지한다 — 필드가 많더라도 모든 필드를 테이블로 나열한다
 - **union type은 discriminant와 각 variant를 설명한다** — discriminated union인 경우, 어떤 필드로 분기되는지와 각 variant를 나열한다
@@ -194,23 +195,45 @@ Step 2B에서 스타일 항목이 수집된 경우, `{출력 경로}/docs/stylin
 | `flex-direction` | `@mixin flex-direction($dir)` | {설명} |
 ```
 
-### Step 4-4: 완전성 검증
+### Step 4-4: 완전성 및 정확성 검증
 
-문서 생성 후, Step 2에서 수집한 export 목록과 생성된 문서를 대조한다:
+문서 생성 후, Step 2에서 수집한 export 목록과 생성된 문서를 대조한다.
+
+#### 완전성 검증
 
 1. export 목록의 각 항목이 usage.md 또는 docs/*.md에 존재하는지 확인한다
 2. 누락된 항목이 있으면 해당 API를 문서에 추가한다
-3. 검증 결과를 표시한다:
+
+#### 정확성 검증
+
+문서의 각 API 항목에 대해, 해당 소스 파일을 Read로 다시 읽어 아래 항목을 대조한다:
+
+| 검증 항목 | 확인 내용 |
+|-----------|-----------|
+| 클래스/함수명 | 제네릭 파라미터 포함 일치 여부 |
+| 멤버 이름 | input/output/model/signal/computed/method 이름 일치 여부 |
+| 멤버 종류 | `input()` vs `model()` vs `output()` vs `signal()` 등 구분 정확성 |
+| 타입 | 파라미터 타입, 반환 타입 일치 여부 |
+| required 여부 | `input()` vs `input.required()` 구분 정확성 |
+| 기본값 | 기본값이 있는 경우 정확한 값 |
+
+불일치가 발견되면 **소스 코드를 기준으로** 문서를 수정한다.
+
+파일 수가 많으면(20개 이상) Agent 도구로 파일 그룹별 병렬 검증을 수행한다.
+
+#### 검증 결과 표시
 
 ```
 완전성 검증: 52/52 API 문서화됨
+정확성 검증: 52/52 API 시그니처 일치
 ```
 
-누락이 있는 경우:
+불일치가 있는 경우:
 
 ```
-완전성 검증: 50/52 API 문서화됨
-누락: MissingType, MissingFunction
-→ 누락된 API를 문서에 추가합니다.
+완전성 검증: 52/52 API 문서화됨
+정확성 검증: 50/52 API 시그니처 일치
+불일치: SdPermissionTable (items→permissions, value→permRecord), SdBarcode (value: required→optional)
+→ 소스 기준으로 문서를 수정합니다.
 ```
 

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

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

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

@@ -7,7 +7,7 @@ description: 버그·동작 이상의 근본 원인 분석 및 해결책을 제
 
 ## Step 1: 근본 원인 분석
 
-@.claude/references/sd-debug.md 를 읽고 따른다.
+`/sd-inner-debug` 스킬을 호출한다.
 
 ## Step 2: 문서 기록
 

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

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

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

@@ -42,7 +42,7 @@ sd-wbs → sd-plan → sd-tdd → sd-check → sd-review를 순차 진행하는
 
 ## Step 6: sd-review
 
-`.claude/references/sd-review.md` 를 읽고, 발견사항에 대해 수정한다.
+`/sd-inner-review` 스킬을 호출하고, 발견사항에 대해 수정한다.
 
 - wbs/feature 문서를 읽고 잘 구현되었는지 함께 검토한다.
 - 수정사항이 있는 경우, `/sd-check` 스킬을 재 수행한다.

package/claude/skills/sd-doc-extract/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: sd-doc-extract
 description: 문서 파일(docx, xlsx, xlsb, pptx, pdf, eml, msg)에서 텍스트, 이미지, 임베디드 파일을 추출하는 스킬. "문서 추출", "문서 분해", "docx 분석", "PDF 내용 뽑아줘", "eml 파일 추출" 등을 요청할 때 사용한다.
+model: sonnet
+effort: low
 ---
 
 # sd-doc-extract: 문서 분해/추출