@simplysm/sd-claude 13.0.85 → 13.0.87

package/README.md

@@ -1,43 +1,173 @@
 # @simplysm/sd-claude
 
-> Simplysm Claude Code asset installer
+Claude Code용 `.claude/` 디렉토리 에셋(rules, skills, hooks) 설치/동기화 도구.
 
-A postinstall hook that provisions [Claude Code](https://docs.anthropic.com/en/docs/claude-code) projects with shared skills, rules, hooks, and a status line.
+`pnpm install` 시 `postinstall` 훅으로 자동 실행되어 프로젝트에 Simplysm Claude Code 환경을 구성한다.
 
-On `npm install` (postinstall), the package automatically copies its bundled `sd-*` assets into the consuming project's `.claude/` directory and configures `settings.json` with the status line and session-start hook.
+## 설치
 
-## Bundled Assets
+```bash
+npm install @simplysm/sd-claude
+# 또는
+pnpm add @simplysm/sd-claude
+```
 
-The following assets are installed into the project's `.claude/` directory.
+설치 시 `postinstall` 훅이 자동으로 `.claude/` 에셋을 프로젝트에 복사한다.
 
-### Skills
+## CLI
 
-| Skill | Trigger | Description |
-|-------|---------|-------------|
-| `sd-commit` | `/sd-commit` | Stages changes, generates a Conventional Commits message, and commits |
-| `sd-check` | `/sd-check` | Runs `check` script (typecheck + lint + test), auto-fixes code errors in a loop via `sd-debug` |
-| `sd-plan` | `/sd-plan` | Generates a fully clarified implementation plan through iterative Q&A |
-| `sd-debug` | `/sd-debug` | Analyzes errors/stack traces, diagnoses root cause, then delegates to `sd-plan` |
-| `sd-review` | `/sd-review` | Scans code for potential bugs across 5 categories, then plans and applies fixes |
-| `sd-simplify` | `/sd-simplify` | Reviews code for simplification opportunities, then plans and applies changes |
-| `sd-api-review` | `/sd-api-review` | Compares public API against standards and popular libraries, proposes naming/structure improvements |
-| `sd-init` | `/sd-init` | Auto-generates `CLAUDE.md` by analyzing the project's scripts, dependencies, and lint config |
-| `sd-readme` | `/sd-readme` | Generates README.md documentation for monorepo packages |
-| `sd-document` | `/sd-document` | Reads/writes `.docx`, `.xlsx`, `.pptx`, `.pdf` files via Python extraction scripts |
-| `sd-email-analyze` | `/sd-email-analyze` | Parses `.eml`/`.msg` email files, extracts headers, body, inline images, and attachments |
+```bash
+# 수동으로 에셋 설치 실행
+npx sd-claude postinstall
+# 또는
+pnpm sd-claude postinstall
+```
 
-### Rules
+**지원 명령어:**
 
-| Rule file | Purpose |
-|-----------|---------|
-| `sd-claude-rules.md` | Enforces YAGNI, no unsolicited code edits, Playwright output directory |
-| `sd-simplysm-usage.md` | Directs Claude to read package README.md files for `@simplysm/*` API details |
+| 명령어 | 설명 |
+|---|---|
+| `postinstall` | `.claude/` 디렉토리에 `sd-*` 에셋을 설치하고 `settings.json`을 구성 |
 
-### Hooks & Status Line
+## 동작 방식
 
-| Asset | Description |
-|-------|-------------|
-| `sd-session-start.sh` | Session-start hook that reminds Claude to read `.claude/rules/*.md` and `CLAUDE.md` |
-| `sd-statusline.py` | Status line script showing: folder name, model, context %, 5h usage %, 7d usage % |
+### postinstall -- 에셋 설치
 
-The status line fetches usage data from the Anthropic API in the background (every 3 minutes) and caches results in `~/.claude/statusline-cache.json`.
+`pnpm install` 시 자동으로 실행된다. 실패해도 `pnpm install`을 차단하지 않는다.
+
+**실행 흐름:**
+
+1. 프로젝트 루트를 탐색한다 (`INIT_CWD` > `node_modules` 경로 역추적 > `cwd()`)
+2. simplysm 모노레포에서 동일 major 버전이면 스킵한다 (소스를 직접 사용)
+3. 패키지의 `claude/` 디렉토리에서 `sd-*` 에셋을 수집한다
+4. 프로젝트 `.claude/` 내 기존 `sd-*` 항목을 삭제한 뒤 새로 복사한다
+5. `.claude/settings.json`에 statusLine과 SessionStart 훅을 설정한다
+
+**프로젝트 루트 탐색 우선순위:**
+
+```
+INIT_CWD 환경변수 → node_modules 경로에서 역추적 → process.cwd()
+```
+
+**settings.json 자동 설정 내용:**
+
+```jsonc
+{
+  // statusLine: 항상 덮어쓰기
+  "statusLine": {
+    "type": "command",
+    "command": "python .claude/sd-statusline.py"
+  },
+  // SessionStart: sd-session-start 훅이 없으면 추가, 있으면 갱신
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [{ "type": "command", "command": "bash .claude/sd-session-start.sh" }]
+      }
+    ]
+  }
+}
+```
+
+기존에 루트 레벨 `SessionStart` 키가 있으면 `hooks.SessionStart`로 마이그레이션한다.
+
+### prepack -- 에셋 동기화
+
+`npm publish` / `pnpm pack` 전에 자동으로 실행된다.
+
+1. 프로젝트 `.claude/` 디렉토리에서 `sd-*` 에셋을 수집한다
+2. 패키지의 `claude/` 디렉토리를 초기화(삭제)한 뒤 복사하여 배포에 포함한다
+
+## 설치되는 에셋
+
+### 에셋 탐색 규칙
+
+- `.claude/` 디렉토리에서 `sd-*` 패턴의 파일/디렉토리를 자동 감지
+- 루트 레벨과 1단계 하위 디렉토리를 스캔
+- 예: `.claude/sd-statusline.py`, `.claude/skills/sd-commit/`, `.claude/rules/sd-readme.md`
+
+### 포함 에셋 목록
+
+**스크립트:**
+
+| 파일 | 설명 |
+|---|---|
+| `sd-statusline.py` | Claude Code 상태 표시줄. 폴더명, 모델, 컨텍스트 사용률, API quota(5h/7d) 표시 |
+| `sd-session-start.sh` | 세션 시작 시 `.claude/rules/*.md`와 `CLAUDE.md` 파일 목록을 출력 |
+
+**Rules (`.claude/rules/`):**
+
+| 파일 | 설명 |
+|---|---|
+| `sd-claude-rules.md` | 질문 응답/문제해결 원칙 (편법 금지, 근본 원인 추적) |
+| `sd-readme.md` | `@simplysm/*` 패키지 사용 시 README.md 참조 규칙 |
+
+**Skills (`.claude/skills/`):**
+
+| 스킬 | 설명 |
+|---|---|
+| `sd-audit` | 코드베이스 점검 및 개선 사항 도출 |
+| `sd-check` | typecheck + lint(fix) + 단위test 순차 수행 및 자동 수정 |
+| `sd-commit` | `[type] scope` 형식의 커밋 메시지 생성 및 커밋 |
+| `sd-debug` | 버그/에러의 근본 원인 분석 및 `debug.md` 저장 |
+| `sd-document` | `.docx/.xlsx/.pptx/.pdf` 파일 분석 및 생성 |
+| `sd-email-analyze` | `.eml/.msg` 이메일 파일 분석 (헤더/본문/첨부파일 추출) |
+| `sd-init` | 프로젝트 설정 분석 후 `CLAUDE.md` 자동 생성 |
+| `sd-plan` | 요구분석서/점검 결과 기반 TDD 구현계획서 작성 |
+| `sd-plan-dev` | 구현계획서 기반 TDD 방식 실제 구현 수행 |
+| `sd-readme` | LLM 인덱싱용 `README.md` 및 `docs/` 생성 |
+| `sd-spec` | 사용자 요청과 코드베이스 분석 후 요구분석서 작성 |
+| `sd-test` | TDD 테스트 작성 및 실행 |
+| `sd-use` | 요청 내용에 적합한 `sd-*` 스킬 자동 매칭 및 실행 |
+
+## 내부 API
+
+### sd-entries.mjs
+
+에셋 탐색 유틸리티. `postinstall.mjs`와 `sync-claude-assets.mjs`에서 공유한다.
+
+```js
+import { forEachSdEntry, collectSdEntries } from "./sd-entries.mjs";
+
+// 콜백 방식: sd-* 항목을 순회
+forEachSdEntry(dir, (relativePath) => {
+  // relativePath 예: "sd-statusline.py", "skills/sd-commit"
+});
+
+// 배열 반환 방식: sd-* 항목의 상대 경로 목록
+const entries = collectSdEntries(dir);
+// ["sd-statusline.py", "rules/sd-readme.md", "skills/sd-commit", ...]
+```
+
+**`forEachSdEntry(dir, callback)`**
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `dir` | `string` | 스캔할 기본 디렉토리 |
+| `callback` | `(relativePath: string) => void` | 각 `sd-*` 항목의 상대 경로를 전달받는 콜백 |
+
+**`collectSdEntries(dir)`**
+
+| 매개변수 | 타입 | 설명 |
+|---|---|---|
+| `dir` | `string` | 스캔할 기본 디렉토리 |
+| **반환** | `string[]` | `sd-*` 항목의 상대 경로 배열 |
+
+## sd-statusline.py 상세
+
+Claude Code 하단 상태 표시줄에 다음 정보를 표시한다.
+
+```
+폴더명 | 모델명 | 컨텍스트% | 5h사용%(리셋시간) | 7d사용%(리셋시간)
+```
+
+**예시:** `my-project | Opus 4.6 | 23% | 45%(2h30m) | 12%(5d3h)`
+
+**동작 원리:**
+
+- Claude Code가 stdin으로 전달하는 JSON에서 폴더명, 모델ID, 컨텍스트 사용률을 추출
+- API quota는 `~/.claude/statusline-cache.json`에 캐시하며 3분 간격으로 갱신
+- quota 조회는 백그라운드 프로세스로 실행하여 상태 표시줄 응답 지연을 방지
+- 파일 락(`~/.claude/statusline-cache.lock`)으로 동시 갱신을 방지
+- Windows(`msvcrt`)와 Unix(`fcntl`) 모두 지원

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

@@ -1,18 +1,21 @@
-## Request Handling Rules
+# 사용자의 질문
 
-- Never modify code unless the user explicitly requests changes. (No autonomous decisions in response to questions, etc.)
+- 사용자가 선택에 대한 고민을 물어보면, 각 선택에 대해 10점만점의 점수를 매겨 사용자에게 판단을 돕는다.
+- 사용자의 질문을 바로 수정하지 않는다. 질문에 대한 답을 하고 사용자의 명시적 수정요청을 기다린다.
 
-## Code Writing Rules
+# 문제해결
 
-- Follow the YAGNI principle.
+**핵심 원칙 — 편법/우회방법 절대 금지:**
+- 증상을 숨기는 해결이 아닌, 원인 자체를 제거하는 방향으로 분석한다
+- 예: `setTimeout` 추가, `try-catch`로 에러 무시, 플래그 변수로 조건 우회 등은 편법이다
+- 반드시 "왜 이 문제가 발생하는가?"를 근원까지 추적한다
 
-## Playwright Rules
+# AskUserQuestion 도구 사용
 
-- All Playwright output (screenshots, PDFs, downloads, etc.) must be saved to the `.tmp/playwright/` directory.
-- When using Playwright MCP tools with a `filename` parameter, always prefix the filename with `.tmp/playwright/` (e.g., `filename: ".tmp/playwright/my-screenshot.png"`).
-- Never pass a bare filename without the `.tmp/playwright/` path prefix.
+`AskUserQuestion` 도구사용전에 무조건 `---`를 마지막 라인에 출력할 것.
 
-## Documentation Rules for LLMs
-
-- Write in English. (including code comments)
+# Compaction Rules
 
+`/compact`수행 시, 항상 보존할 것:
+- 수정된 파일의 전체 경로 목록
+- 에러 메시지 원문

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

@@ -1,7 +1,12 @@
-# Simplysm Library Issue Reporting
+# Simplysm 라이브러리 이슈 리포트
 
-Source code for `@simplysm/*` packages can be found in `node_modules/@simplysm/`. If debugging reveals the root cause is in the simplysm library itself, generate a GitHub issue-formatted text (title, reproduction steps, expected behavior, actual behavior) and display it to the user.
+`@simplysm/*` 소스 코드는 `node_modules/@simplysm/`에 있다.
 
-**Report facts only — do not suggest fixes or include code location hints. Do not auto-submit the issue — only display the text.**
+디버깅 결과 근본 원인이 simplysm 라이브러리에 있으면, GitHub 이슈 형식(제목, 재현 절차, 기대 동작, 실제 동작)으로 작성하여 사용자에게 표시한다.
 
-The issue body must NEVER include internal analysis of library code (class names, variable names, style properties, inheritance chains, etc.). Only describe user-observable symptoms.
+## 규칙
+
+- 사실만 보고한다. 수정 방안이나 코드 위치 힌트를 포함하지 않는다.
+- 이슈를 자동 제출하지 않는다. 텍스트만 표시한다.
+- 라이브러리 내부 분석(클래스명, 변수명, 상속 체인 등)을 포함하지 않는다. 사용자가 관찰 가능한 증상만 기술한다.
+- 이슈 리포트는 대화에서 사용 중인 언어로 작성한다.

package/claude/rules/sd-readme.md

@@ -0,0 +1,5 @@
+# @simplysm 패키지 문서 참조
+
+`@simplysm/*` 패키지 사용 시, 해당 패키지의 README.md를 먼저 읽어 API와 사용법을 파악한다.
+- monorepo 내부: `packages/{패키지명}/README.md`
+- 외부 프로젝트: `node_modules/@simplysm/{패키지명}/README.md`

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

@@ -0,0 +1,133 @@
+---
+name: sd-audit
+description: 코드베이스를 점검하여 개선 사항을 도출하고, 승인된 결과를 문서로 저장. 사용자가 코드베이스의 문제점이나 개선점 검토를 요청할 때 사용
+argument-hint: "<점검 대상 또는 범위>"
+---
+
+# sd-audit: 코드 점검
+
+코드베이스를 점검하여, 승인된 개선 사항을 audit.md로 저장한다.
+
+## 1. 입력 파싱
+
+`$ARGUMENTS`에서 점검 대상 텍스트를 추출한다.
+- `$ARGUMENTS`가 비어있으면 현재 대화 맥락에서 점검 대상을 파악한다. 대화 맥락도 없으면 AskUserQuestion으로 점검 대상을 요청한다
+- 점검 대상에서 topic을 영문 kebab-case로 변환한다 (예: "ORM 마이그레이션" → `orm-migration`, "사용자 인증" → `user-auth`)
+- 특수문자(`#`, `/`, `\`, `(`, `)`, `.` 등)는 제거하거나 `-`로 치환한다 (예: "DB 연동 (v2.0)" → `db-connection-v2-0`)
+- 이미 kebab-case이면 그대로 사용한다
+
+## 2. 코드베이스 탐색
+
+점검 대상과 관련된 코드의 위치를 수집한다. 코드 품질이나 개선 여부에 대한 판단은 수행하지 않는다.
+- Agent tool (subagent_type: Explore)을 활용하여 관련 파일, 패키지, 의존성의 위치를 탐색한다
+- 필요에 따라 Glob, Grep 등을 직접 사용할 수도 있다
+- 탐색 결과로 관련 파일 경로, 패키지 구조, 의존 관계를 파악한다
+
+## 3. 코드 점검
+
+탐색 결과를 바탕으로 메인 에이전트가 직접 코드를 Read하여 점검하고, 개선 사항을 건으로 도출한다.
+- 최대 5건으로 제한하고, 가장 영향이 큰 것을 우선한다
+- 발견한 건이 없으면 "점검 결과 발견된 개선 사항이 없습니다."를 출력하고 문서 저장 없이 종료한다
+
+**건 결과 구조:**
+
+각 건을 다음 형식으로 정리한다:
+
+```
+### 건 1: {건 제목}
+
+**해야 할 이유 (방안들)**
+
+방안 A: {방안 제목}
+- 설명: {상세 설명}
+- 점수: {N}/10
+
+방안 B: {방안 제목}
+- 설명: {상세 설명}
+- 점수: {N}/10
+
+**반론**
+- 설명: {상세 설명}
+- 점수: {N}/10 (높을수록 반론이 강함)
+
+```
+
+- 각 건의 "해야 할 이유"에는 1개 이상의 방안이 포함된다 (방안이 여러 개이면 대안적 접근법을 의미)
+- 각 건은 반드시 "해야 할 이유 (방안들)"와 "반론"을 모두 포함한다 (해당 없으면 점수 0/10으로 표기)
+- 0/10은 해당 이유가 전혀 존재하지 않는 경우에만 사용하며, 약한 이유라도 있으면 최소 1점 이상을 부여한다
+- 각 건은 독립적으로 방안 선택 또는 거부를 판단할 수 있는 단위여야 한다
+
+## 4. 점검 결과 표시 및 선택
+
+도출된 건들에 대해 하나씩 다음 프로세스를 반복한다.
+
+1. 해당 건의 점검 결과를 **자세한 설명을 텍스트로 먼저 출력**한다
+   - 건 제목
+   - 각 방안의 상세 설명 + 점수를 명확히 표시
+   - 반론의 상세 설명 + 점수를 명확히 표시
+   - 방안 간 및 반론과의 트레이드오프를 포함
+2. **자동 결정 조건**에 해당하면 결정 결과를 텍스트로 출력하고 다음 건으로 넘어간다
+3. 자동 결정 조건에 해당하지 않으면 `AskUserQuestion`을 **1개만** 호출하여 선택을 요청한다
+   - 선택지: 각 방안 + "거부" (예: "방안 A" / "방안 B" / "거부")
+   - 한 번에 하나의 건에 대해서만 질문 (한꺼번에 여러 건을 묻지 않음)
+4. 답변을 반영한 뒤 다음 건으로 넘어간다
+
+**자동 결정 조건 (묻지 않는 경우):**
+
+모든 점수(각 방안 점수 + 반론 점수)를 동등하게 비교한다:
+
+- 모든 점수가 0인 경우 → 비실질적 건으로 간주하여 건너뛴다
+- 반론 점수가 모든 방안 점수보다 높으면 (단 1점이라도) → 무조건 자동 거부 (사용자에게 묻지 않음)
+  - 예: 방안A 5점, 방안B 3점, 반론 6점 → 반론(6) > 방안A(5) 이므로 무조건 자동 거부
+- 최고 점수가 나머지 모든 점수의 2배 이상이면 → 최고 점수 항목으로 자동 결정 (최고 ≥ 각 나머지 × 2)
+  - 최고가 방안이면 → 해당 방안 자동 채택
+  - 최고가 반론이면 → 자동 거부
+  - 최고 점수가 동점이면 → 자동 결정 불가 → 사용자에게 질문
+  - 예: 방안A 8점, 방안B 3점, 반론 3점 → 8 ≥ 3×2, 8 ≥ 3×2 이므로 방안A 자동 채택
+  - 예: 방안A 4점, 방안B 2점, 반론 9점 → 9 ≥ 4×2, 9 ≥ 2×2 이므로 자동 거부
+  - 예: 방안A 6점, 방안B 5점, 반론 3점 → 6 ≥ 5×2? 아니오(6 < 10) → 자동 결정 불가 → 사용자에게 질문
+
+## 5. 결과 문서 저장
+
+승인된 건들을 audit.md로 저장한다.
+
+**파일 경로:**
+- 디렉토리: `.tasks/{yyMMddHHmmss}_{topic}/`
+  - `yyMMddHHmmss`는 현재 시간 (Bash `date +%y%m%d%H%M%S`로 생성)
+  - `{topic}`은 1단계에서 변환한 kebab-case topic
+- 파일명: `audit.md`
+- 디렉토리가 없으면 먼저 생성한다
+
+**audit.md 구조:**
+
+```markdown
+# 점검 결과: {topic 설명}
+
+## 개요
+
+{점검 대상의 목적과 배경}
+
+## 현재 상태
+
+{코드베이스 분석 결과 - 관련 기존 코드/패키지, 현재 구현 방식, 관련 의존성}
+
+## 요구사항
+
+### R1. {승인된 건 제목}: {채택된 방안 제목}
+
+{채택된 방안의 내용을 요구사항으로 정리}
+
+### R2. {승인된 건 제목}: {채택된 방안 제목}
+
+{채택된 방안의 내용을 요구사항으로 정리}
+```
+
+- 승인된 건만 R번호를 부여하여 요구사항으로 기록한다
+- 거부된 건은 audit.md에 포함하지 않는다
+
+## 6. 완료 안내
+
+문서 작성이 완료되면 다음을 출력한다:
+- 완성된 문서의 파일 경로
+- 사용자에게 직접 문서를 확인할 것을 권장
+- 다음 단계 안내: "다음 단계로 `/sd-plan`을 실행하세요."

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

@@ -1,73 +1,135 @@
 ---
 name: sd-check
-description: Used when requesting "check", "sd-check", "typecheck+lint+test", "full check", etc.
+description: check 명령어로 코드 품질 검사를 실행하고 에러를 자동 수정. 사용자가 코드 품질 검사 및 자동 수정을 요청할 때 사용
+argument-hint: "[targets..]"
 ---
 
-# SD Check — Automated Check and Error Fix Loop
+# sd-check: 코드 품질 검사 및 자동 수정
 
-Detects the package manager, runs the check script, reviews the results, and if there are code errors, invokes sd-debug to analyze the root cause, applies fixes, and re-runs the check. This loop repeats until all errors are resolved.
+`check` 명령어를 실행하고, 발견된 에러를 분석하여 자동 수정한다. 수정 후 전체 check를 재실행하여 수렴시킨다.
 
-ARGUMENTS: Target paths (optional, multiple allowed). If not specified, determined from the conversation context. If no specific target exists or "all" is specified, run without targets.
+## 1. 인자 파싱
 
----
+`$ARGUMENTS`에서 targets를 파싱한다.
+
+- `targets`는 공백으로 구분된 경로 또는 패키지 목록 (예: `packages/core-common packages/solid`)
+- targets가 비어있으면 인자 없이 명령어를 실행한다 (프로젝트 기본 동작에 위임)
+- targets의 kebab-case 형태를 topic으로 사용한다 (예: `packages/core-common` → `check-core-common`). targets가 비어있으면 topic은 `check`
+
+## 2. 전제조건 검사
+
+### check 스크립트 확인
 
-## Step 1: Preparation (PM Detection + Script Verification + Target Resolution)
+프로젝트 루트의 package.json을 Read하여 `scripts`에 `check`이 있는지 확인한다.
 
-1. **PM Detection**: Determine the package manager from the lock file in the project root.
-   - `pnpm-lock.yaml` exists → `pnpm`
-   - `yarn.lock` exists → `yarn`
-   - `package-lock.json` exists → `npm`
-   - None found → `npm` (default)
-2. **Script Verification**: Check whether `scripts.check` exists in `package.json`. If not, inform the user with `"The check script is not defined in package.json."` and **stop**.
-3. **Target Resolution**: Determine targets in the following priority order.
-   1. Targets explicitly specified in ARGUMENTS
-   2. Inferred from the current conversation context (e.g., user is working on a specific package)
-   3. If neither applies or "all" is specified → run without targets (full check)
+- **없으면**: "package.json에 `check` 스크립트가 없습니다. `check` 스크립트를 추가하세요."를 출력하고 **종료**한다
+- **있으면**: 계속 진행한다
 
-## Step 2: Run Check
+### 패키지 매니저 탐지
 
-1. `mkdir -p .tmp/check` (Bash)
-2. Run the following command via Bash:
-   ```
-   TS=$(date +%y%m%d%H%M%S); $PM check [targets...] > .tmp/check/${TS}.txt 2>&1; echo "EXIT_CODE:$?" >> .tmp/check/${TS}.txt
-   ```
-   - `$PM` = the package manager detected in Step 1
-   - `$TS` = timestamp variable (e.g., `260312143025`)
-   - Include targets in the command if present; omit otherwise
-3. Read the result file (`.tmp/check/${TS}.txt`) using the Read tool.
+프로젝트 루트의 lock 파일로 패키지 매니저를 판단한다:
 
-## Step 3: Analyze Results
+- `pnpm-lock.yaml` 존재 → `pnpm`
+- `yarn.lock` 존재 → `yarn`
+- `package-lock.json` 존재 → `npm`
+- 모두 없으면 → `npm` (기본값)
 
-Read the result file content and classify it into one of the following three categories:
+## 3. 보조 명령어 탐지
 
-- **Success**: All checks passed without errors → proceed to **Step 5 (Completion)**
-- **Environment Error**: The issue is an environment/infrastructure problem rather than a code problem (e.g., missing dependencies, out of memory, command not found, network issues, etc.) → show the error details to the user and **stop immediately**. Do not attempt code fixes.
-- **Code Error**: The issue is a source code problem such as type errors, lint violations, or test failures → proceed to **Step 4**
+프로젝트 루트의 CLAUDE.md와 package.json에서 다음 보조 명령어를 탐지한다. **없어도 오류가 아니다** — check만으로 동작 가능하다.
 
-> The classification above should be determined by reading and interpreting the result content freely, not by hardcoded pattern matching.
+### 탐지 대상
 
-**Iteration Limit**: If the current iteration count exceeds 5, report the remaining errors to the user, inform them with `"Errors remain after 5 iterations. Please review the remaining errors."`, and **stop**.
+| 명령어 | CLAUDE.md 키워드 | package.json scripts 키워드 |
+|--------|-----------------|---------------------------|
+| typecheck | typecheck, 타입 검사, tsc | `typecheck`, `type-check`, `tsc` |
+| lint | lint, 린트 검사 | `lint` |
+| lint:fix | lint:fix, lint --fix, 린트 수정 | `lint:fix`, 또는 lint 스크립트에 `--fix` 추가 |
+| test | test, vitest, jest, 단위 테스트 | `test`, `vitest`, `jest` |
 
-## Step 4: Error Analysis and Fix (Using sd-debug)
+### targets 지원 판단
 
-Invoke `sd-debug` via the Skill tool. Pass the following content as args:
+- CLAUDE.md에서 해당 명령어 설명에 `[targets..]`, `[패키지]`, `[경로]` 등의 인자 형식이 기술되어 있으면 targets를 지원하는 것으로 판단한다
+- package.json에서만 탐지된 명령어는 targets 미지원으로 간주한다
 
+### 탐지 결과 표시
+
+```
+## 탐지된 명령어
+
+| 명령어 | 상태 | targets 지원 |
+|--------|------|-------------|
+| check | ✅ {명령어} | {Yes/No} |
+| typecheck | {명령어 또는 ⏭️ 미탐지} | {Yes/No} |
+| lint | {명령어 또는 ⏭️ 미탐지} | {Yes/No} |
+| lint:fix | {명령어 또는 ⏭️ 미탐지} | {Yes/No} |
+| test | {명령어 또는 ⏭️ 미탐지} | {Yes/No} |
 ```
-Analyze the code errors from the check results below.
-**Important workflow instructions:**
-1. Perform Steps 1-2 thoroughly — gather problem information and conduct in-depth codebase analysis to identify the root cause. Do NOT skip or rush these steps.
-2. Output the diagnostic report from Step 3, but skip the user confirmation (do not call AskUserQuestion).
-3. Skip Steps 4-5 (do not invoke sd-plan).
-4. Based on the analysis results and diagnostic report, apply fixes directly.
-
-<Include the error content from the check result file here>
+
+## 4. check 실행 및 로그 저장
+
+1. `.tasks/{yyMMddHHmmss}_{topic}/` 디렉토리를 생성한다 (`yyMMddHHmmss`는 Bash `date +%y%m%d%H%M%S`)
+2. `{PM} check {targets}`를 Bash로 실행하고, stdout+stderr를 `check.log`에 저장한다
+3. 로그 파일을 Read하여 에러를 분석한다
+
+**명령어 실행 자체 실패 처리:** `command not found`, 타임아웃 등 코드 에러가 아닌 환경 문제로 명령어가 실패하면, 에러 메시지를 사용자에게 보고하고 종료한다.
+
+## 5. 에러 분석 및 자율 수정
+
+에러가 없으면 → 7절(완료 안내)로 진행한다.
+
+에러가 있으면 → 에러를 분석하고 코드를 수정한다 (6절의 수정 원칙 필수 준수). 수정 과정에서 **탐지된 보조 명령어를 자율적으로 활용**한다.
+
+### 활용 예시 (강제가 아닌 가이드)
+
+상황에 맞게 판단한다. 다음은 예시일 뿐이며, 반드시 이 순서를 따를 필요는 없다:
+
+- **lint 에러** → lint:fix가 탐지되었으면 먼저 실행해보고, lint로 남은 에러를 확인한다
+- **typecheck 에러** → 코드 수정 후 typecheck만 재실행하여 부분 검증한다
+- **test 에러** → 코드 수정 후 test만 재실행하여 부분 검증한다
+- **보조 명령어 미탐지** → 코드만 수정하고 전체 check에서 확인한다
+
+### 수정 후 재실행
+
+수정한 것이 있으면 → 4절로 돌아가 **새 타임스탬프로** 전체 check를 재실행한다 (최대 5회).
+수정한 것이 없으면 (더 이상 수정 불가) → 남은 에러를 기록하고 7절(완료 안내)로 진행한다.
+
+## 6. 수정 원칙 — 편법/우회방법 절대 금지
+
+sd-check는 에러를 자동 수정하므로, "빨리 에러를 없애려는" 편법 유혹이 가장 큰 스킬이다. 반드시 **"왜 이 에러가 발생하는가?"를 근원까지 추적**하여 원인 자체를 제거해야 한다.
+
+### 절대 하지 말 것
+
+- `@ts-ignore`, `@ts-expect-error` 추가로 타입 에러 무시
+- `eslint-disable`, `eslint-disable-next-line` 추가로 lint 에러 무시
+- `try-catch`로 에러를 삼켜서 테스트 통과시키기
+- `as any`, `as unknown as T` 등 타입 단언으로 타입 에러 회피
+- 테스트 기대값을 실제 결과에 맞춰 변경 (테스트 의도를 훼손)
+- 테스트 케이스를 삭제하거나 `.skip` 처리
+- 조건문/플래그 변수를 추가하여 문제 경로를 우회
+
+### 올바른 수정 방향
+
+- 타입 에러 → 타입 정의, 인터페이스, 함수 시그니처를 올바르게 수정
+- lint 에러 → 코딩 규칙에 맞게 코드 구조를 변경
+- 테스트 실패 → 구현 코드의 로직을 수정하여 기대 동작을 달성
+- CLAUDE.md에 코딩룰이 있으면 반드시 준수
+
+## 7. 완료 안내
+
+결과를 요약하여 출력한다:
+
 ```
+## sd-check 결과
+
+- check 실행: N회
+- 최종 상태: ✅ 전체 통과 / ⚠️ 미해결 에러 있음
 
-After sd-debug completes → return to **Step 2** (re-run check with a new txt file)
+### 수정된 파일
+- {파일 경로}: {변경 내용 요약}
 
-## Step 5: Completion Report
+### 미해결 에러 (있는 경우)
+- {에러 내용}
+```
 
-When all checks pass, output the following:
-- Total number of iterations
-- Summary of fixes made in each iteration
-- Format: `"Check complete: all checks passed after {N} iteration(s)."` + bullet list of fix details
+커밋 안내: "커밋하지 않습니다. 필요 시 `/sd-commit`을 실행하세요."