@simplysm/sd-claude 14.0.56 → 14.0.57

package/claude/references/sd-simplysm-v14/sd-claude/assets.md

@@ -36,19 +36,17 @@ claude/
 | `sd-check/`           | sd-check           | typecheck/lint/test 실행 및 에러 해결              |
 | `sd-claude-docs/`     | sd-claude-docs     | CLAUDE.md + usage 문서 동시 생성                   |
 | `sd-commit/`          | sd-commit          | 전체 변경사항에 대한 단일 커밋 생성                |
-| `sd-debug/`           | sd-debug           | 버그 근본 원인 분석 및 해결책 제안                 |
+| `sd-debug/`           | sd-debug           | 버그 근본 원인 분석(ACH) 및 보고                   |
 | `sd-deliverable/`     | sd-deliverable     | 매뉴얼/SIT 문서 생성                               |
 | `sd-dev/`             | sd-dev             | 통합 개발 오케스트레이터 (요구명세 → TDD → 리뷰)   |
 | `sd-doc-extract/`     | sd-doc-extract     | 문서 파일 텍스트/이미지 추출 (Python)              |
 | `sd-inner-clarify/`   | sd-inner-clarify   | (내부 전용) 명확성 분류·근거 탐색·명확화 질문      |
-| `sd-inner-debug/`     | sd-inner-debug     | (내부 전용) 근본 원인 분석(ACH) 로직               |
-| `sd-inner-review/`    | sd-inner-review    | (내부 전용) 코드 리뷰 분석 로직                    |
 | `sd-issue/`           | sd-issue           | GitHub 이슈 생성                                   |
 | `sd-outlook/`         | sd-outlook         | Outlook 메일 검색/다운로드 (Python)                |
 | `sd-plan/`            | sd-plan            | 요구명세/구현계획 작성                             |
 | `sd-prompt/`          | sd-prompt          | 스킬/프롬프트 파일 작성/개선                       |
 | `sd-refactor/`        | sd-refactor        | 리팩토링 분석 리포트 생성                          |
-| `sd-review/`          | sd-review          | 코드 리뷰 리포트 생성                              |
+| `sd-review/`          | sd-review          | 코드 리뷰 및 수정 개발 연결                        |
 | `sd-tdd/`             | sd-tdd             | TDD 개발                                           |
 | `sd-use/`             | sd-use             | 자연어 → sd-\* 스킬 라우팅                         |
 | `sd-wbs/`             | sd-wbs             | WBS Feature 분해                                   |

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

@@ -21,6 +21,35 @@
   - 명시적 요청없이 코드/문서등을 바로 수정하지 말것
 - 사용자가 직접 확인해야할 사항이 있으면, 계속 진행하지 말고 멈추고 사용자에게 직접 확인 결과를 요청할 것.
 
+# 질문 vs 수정 분리
+
+- 질문형 요청("이게 왜 이래?", "어떻게 동작해?", "맞아?")은 분석·설명으로 처리한다. 사용자가 명시적으로 "수정해줘", "고쳐줘", "바꿔줘"라고 요청하지 않으면 코드/문서 수정으로 전환하지 않는다.
+- "A를 B로 바꿔" 같은 명시적 변경 지시가 있을 때만 즉시 수정한다.
+- 해결 방식이 열린 요청(예: "이거 어떻게 해결하지?", "리팩토링 방안 좀")은 수정 대상·방향·검증 계획을 먼저 설명하고 사용자 승인을 받은 뒤 수정한다.
+
+# 사용자 편의성 우선
+
+**CRITICAL: 구현 복잡도·코드 양·리팩토링 부담보다 사용자 편의성을 우선한다.**
+
+- 구현 복잡도와 사용자 편의성이 충돌하면 편의성을 택한다.
+- 복잡도가 크게 증가해도 편의성 이득이 분명하면 채택한다.
+- '구현이 어렵다'는 이유로 편의성 다운그레이드 금지.
+- 선택지 평가 시 '사용자 편의성' 축을 반드시 포함하고 가중치를 둔다.
+
+# 사용성 보존
+
+**CRITICAL: 버그 수정·규칙 준수·타입/lint 오류 해결 작업은 사용성 변경 요청이 아니다.**
+
+- 사용자 흐름, 화면 동작, 문구, 기본값, 옵션 의미, 공개 API 동작은 보존한다.
+- 작업 중 사용성 문제를 발견해도 같이 고치지 말고, 별도 이슈로 보고만 한다.
+- 사용성 변경이 불가피하면 변경되는 사용성, 대안, 영향을 사전 설명하고 사용자 응답을 대기한다.
+
+# 구현 방식 결정 분리
+
+- 사용자가 목표·방향·통합 여부를 확정해도 구현 방식은 별도 결정사항이다.
+- 구현 방식 후보가 2개 이상이거나 새 개념(내부 모드/플래그/래퍼/호환 계층/파일 삭제·이동/호출 흐름 변경) 도입이 필요하면 `.claude/rules/sd-options.md`의 형식으로 선택지를 제시하고 응답을 대기한다.
+- 회피용 우회 구조(재귀, 순환 의존, 호환성 문제 등)가 발견되면 먼저 사용자에게 보고하고, 그 다음 sd-options 형식으로 질문한다.
+
 # Playwright
 
 - 사용자가 접속주소를 알려주지 않았다면, 반드시 사용자에게 접속주소를 요청할것. (서버 강제 실행 금지)

package/claude/rules/sd-options.md

@@ -6,36 +6,25 @@
 
 - "이 정도 질문은 과하다", "단순 확인이니 생략"은 위반이다
 - 단일 경로만 합리적이라 느껴질 때도, "수행 안 함"을 포함한 선택지 구조로 제시한다
-- 가벼운 사안은 경량 모드로 오버헤드를 낮추되, 선택지 구조와 `AskUserQuestion` 호출은 생략 불가
 
 ## 공통 규칙
 
-- 결정 대상 명시: 선택지 전에 한 줄로 `결정 대상: {파일경로:라인}` 출력 (예: `결정 대상: packages/foo.ts:45`)
+- 질문 대기열 우선: 사용자 답변이 필요한 항목이 있으면 질문 대기열에 등록한다. 사용자 답변으로 새 질문이 생기면 후속 프로세스를 시작하지 말고 질문 대기열에 추가한다.
+- 결정 대상 명시: 각 선택지 묶음 전에 `결정 대상 {번호}/{전체}: {파일경로:라인}` 출력. 단일 결정사항이면 `결정 대상: {파일경로:라인}` 출력.
 - 하나의 선택지를 추천하고 사유 한 줄 요약
-- 복수 결정사항: 한 응답에 한 건만. 다음 건은 새 응답에서. 남은 건수 표시 (예: "1/3건 완료")
+- 복수 질문: 질문은 한 번에 하나씩 제시한다. 각 질문마다 사용자 답변을 받은 뒤 다음 질문을 제시한다.
+- 답변 누적: 앞선 질문의 답변은 저장된 결정으로 취급한다. 다음 질문을 하거나 전체 답변 수집을 완료하기 전까지, 앞선 답변에 따른 수정·실행·해결 프로세스를 시작하지 않는다.
+- 실행 시작 조건: 질문 대기열이 비고 모든 필수 질문의 답변을 받은 뒤에만 수정·실행·검증 등 후속 프로세스를 시작한다.
+- 누락 답변 처리: 사용자가 현재 질문에 답하지 않으면 같은 질문을 다시 묻는다. 누락 항목을 임의 추천안으로 처리하지 않는다.
+- 추가 질문 처리: 답변 수집 중 또는 작업 중 새로 물어봐야 할 항목이 발견되면 질문 대기열에 추가하고, 다시 한 번에 하나씩 질문한다.
+- 질문 정렬: 발견된 질문은 발생 출처(Step/Feature 번호/대상 식별자) 단위로 묶음 분류한다. 한 묶음을 모두 소진한 뒤 다음 묶음으로 넘어가며, 진행 중 묶음 내에서 발견된 새 질문은 해당 묶음 끝에 추가한다. 묶음 간 순서는 의존성·상위→하위 순으로 한다.
 - 도구 호출 의무: 선택지 출력 후 즉시 `AskUserQuestion` tool을 호출하여 응답을 종료한다. 텍스트로 "진행할까요?" 묻고 응답 대기하면 위반.
   - `AskUserQuestion`이 deferred tool로 표시되어 있으면 먼저 `ToolSearch query="select:AskUserQuestion"`로 스키마를 로드한 뒤 호출한다.
+  - `AskUserQuestion`의 선택지(`options`)는 평균 점수 내림차순으로 정렬하여 전달한다. 동점이면 추천안을 우선 배치한다.
 
-## 티어 선택
-
-사안의 무게에 따라 경량 모드와 전체 모드 중 하나를 선택한다.
-
-### 경량 모드 — 적용 대상 중 가벼운 결정
-
-조건: 영향 범위가 단일 파일·수 줄 이내이고, 각 선택지의 차이가 한눈에 명확할 때.
+## 선택지 제시 형식
 
 필수 항목:
-- 결정 대상 한 줄
-- 2~4개 선택지 + "수행 안 함"
-- 각 선택지: 한 줄 요약 + 한 줄 트레이드오프 + 10점 만점 단일 점수
-- 추천 한 줄
-- `AskUserQuestion` 호출
-
-### 전체 모드 — 적용 대상 중 무거운 결정
-
-조건: 설계·아키텍처·공개 API·규칙/설정 파일·복수 파일 영향·되돌리기 어려운 변경.
-
-필수 항목 (공통 규칙 + 아래):
 
 - 근거 제시
   - 현재 상태 인용: 파일경로:라인번호 필수. 코드블록 사용 시에도 경로:라인 병기
@@ -46,4 +35,12 @@
 - 축별 점수
   - 맥락에 맞는 관점(축) 3개 이상 선정
   - 축별 점수를 반드시 노출한 뒤 평균을 10점 만점으로 병기 (최종 점수만 쓰는 것 금지)
-
+  - 표기 형식: 단일 매트릭스 표 1개로 표시한다. 행 = 선택지(평균 내림차순), 열 = 평가축 + 평균. 선택지마다 별도 표 작성 금지.
+  - 예시:
+    ```
+    | 선택지 | 일관성 | 단순성 | 워크플로 보존 | 평균 |
+    |---|---|---|---|---|
+    | A. xxx | 10 | 10 | 7 | **9.0** |
+    | B. yyy | 6 | 7 | 9 | **7.3** |
+    | C. 수행 안 함 | 2 | 10 | 5 | **5.7** |
+    ```

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

@@ -0,0 +1,35 @@
+# 사용자 응답 형식 (Claude Code 채팅 출력 전용)
+
+적용 범위: 사용자에게 출력되는 채팅 응답에만 적용한다.
+파일 작성(.md/.ts/.json/매뉴얼/README/SIT/Spec/Plan 등 모든 산출물)에는 적용하지 않는다.
+파일 작성 시에는 해당 파일이 렌더링될 환경(GitHub/Web/Word 등)의 일반 마크다운 관례를 따른다.
+
+## 구조
+
+- 결론 우선: 답변 첫 줄에 결론을 둔다. 근거·세부는 그 아래에 배치.
+- 헤더로 분리: 응답이 3개 이상 논점/단계로 구성되면 `##`/`###` 헤더로 섹션을 나눈다. 짧은 답변(1~2단락)에는 헤더 금지. 헤더는 색상 강조보다 "섹션 분리" 용도다.
+- 가로선 분리: 큰 논리 블록(예: 결론 → 분석 → 변경안 → 결정 요청) 사이에 유니코드 가로선 `────────────────────────────────────────` (U+2500 반복, 40자 권장)을 삽입. markdown `---` HR은 Claude Code 터미널에서 가로선으로 렌더링되지 않으므로 사용 금지.
+- 불릿 우선: 항목이 2개 이상이거나 병렬 구조면 산문 대신 불릿 리스트 사용. 3줄 이상 텍스트가 이어지면 빈 줄 또는 리스트로 끊는다.
+- 표 활용: 대비·비교·다축 평가는 표(table)로 정돈. 정렬·가시성 우수.
+- 코드블록 활용: 명령어 1줄 이상, 코드 인용, 파일 내용 발췌, 변경 전후 본문은 fenced code block으로 분리.
+
+## 색상 활용 (Claude Code 터미널 기준)
+
+- 직접 색 지정은 불가능하다. 자동으로 색이 입혀지는 markdown 요소를 의도적으로 사용한다.
+- 강조 위계는 GUI 마크다운과 다르다: 인라인 코드(녹색, 강함) > 헤더(굵음만, 약함) > `**bold**`(효과 0).
+- 키워드 강조는 인라인 코드(`\``)를 사용. 사용자 환경에서 유일한 강한 색상 강조 수단.
+- 정/부 대비, 변경 전후, 권장/금지 대비는 ` ```diff ` 블록으로 표현 (`+` 녹색, `-` 빨강). `!`는 강조 효과가 약하므로 사용 자제.
+- 인용·주의·권고는 blockquote(`>`)로 분리 (세로선 + 이탤릭체로 시각 구분).
+
+## 인라인 표기
+
+- 백틱 표기: 파일경로·명령어·심볼·식별자·기호는 인라인 코드(`\``)로 감싼다. 파일 위치는 `path/file.ts:42` 형식.
+- 표기 통일: 같은 키워드를 따옴표("...")와 백틱(`...`)으로 이중 표기 금지. 한 가지 표기로만 사용.
+- `**bold**` 사용 금지: 색상 효과 0이고 한글 모노스페이스에선 굵기 차이도 인지 어렵다. 결정적 키워드 강조는 인라인 코드로 처리.
+- 이모지 금지: 사용자가 명시 요청한 경우만 사용.
+
+## 어조
+
+- 한 문장 한 정보: 한 문장에 여러 정보를 담지 않는다. 부연은 다음 문장으로 분리.
+- 사족 금지: "좋은 질문입니다", "알겠습니다", "~할 수도 있을 것 같습니다" 같은 완충/사과/감탄 표현 제거. 단정적 어조 사용.
+- 응답 길이 매칭: 단순 확인 질문엔 1~3줄, 분석/설계 질문엔 필요한 만큼. 짧은 답에 헤더·가로선·표를 억지로 넣지 않는다.

package/claude/settings.json

@@ -1,4 +1,6 @@
 {
+  "transcriptView": "verbose",
+  "outputStyle": "Explanatory",
   "hooks": {
     "PreToolUse": [
       {

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

@@ -9,7 +9,7 @@ description: typecheck, lint, test를 실행하고 에러 발생시 사용자
 
 ### 에러 분석 및 수정
 
-에러 분석: `/sd-inner-debug` 스킬을 호출한다.
+에러 분석: `/sd-debug`의 ACH 분석 규칙을 적용한다. 아래 에러 처리 범위와 에스컬레이션 규칙을 우선한다.
 
 #### 에러 처리 범위
 
@@ -27,7 +27,7 @@ description: typecheck, lint, test를 실행하고 에러 발생시 사용자
 **CRITICAL: 아래 2가지 경우에만 사용자에게 보고/선택지 제시한다. 그 외 사유로는 절대(NEVER) 보고·질문·선택지 제시 금지.**
 
 화이트리스트 (이 2가지가 전부):
-1. **동일/유사 에러 2회 반복**: 1회차에 `/sd-inner-debug`로 근본 원인 분석 및 수정 시도 → 2회차 재발 시 중단하고 분석·시도 내역 보고.
+1. **동일/유사 에러 2회 반복**: 1회차에 `/sd-debug`의 ACH 분석 규칙으로 근본 원인 분석 및 수정 시도 → 2회차 재발 시 중단하고 분석·시도 내역 보고.
 2. **원인 특정 불가**: 추측으로 수정 시도 금지, 즉시 보고.
 
 **금지 사항 (자주하는 환각)**:
@@ -104,7 +104,34 @@ typecheck 명령어를 실행한다. (`출력 캡처 규칙`에 따라 파일로
 테스트 명령어를 실행한다. (`출력 캡처 규칙`에 따라 파일로 리다이렉트)
 
 - 에러 발생 시: `에러 분석 및 수정`에 따라, 테스트 실패의 원인을 분석하고 코드를 수정한다.
-- 코드 수정후, 테스트 변경이 누락되었을 수 있음. 의도파악을 위해서 history확인이 필요할 수 있다.
+
+### 코드 수정 후 테스트 실패 처리
+
+**CRITICAL: 이 대화세션에서 코드 수정이 있었고 이후 테스트가 실패하면, 실패 원인을 "코드 버그"로 단정하기 전에 반드시(MUST) 테스트 변경 누락 가능성을 먼저 검토한다.**
+
+코드 수정 후 테스트 실패를 처리할 때는 아래 순서를 지킨다:
+
+1. 현재 세션에서 수정한 코드 diff와 테스트 실패 내용을 대조한다.
+2. 실패한 테스트, fixture, expected/golden 파일이 수정된 동작을 검증하는지 확인한다.
+3. 관련 테스트 변경이 없거나 expected/golden만 낡아 보이면, 사용자 요청·현재 대화 history·현재 diff를 근거로 의도된 동작인지 판단한다.
+4. 대화 history만으로 의도가 불명확하면 관련 파일의 git history를 확인한다.
+5. 실패 원인을 아래 중 하나로 1차 분류한다:
+   - **구현 버그**: 코드가 사용자 요청 또는 기존 계약을 어긴 경우 코드 수정.
+   - **테스트 변경 누락**: 코드 동작이 사용자 요청에 맞고 테스트만 예전 동작을 기대하는 경우 테스트, fixture, expected/golden 수정.
+   - **테스트 데이터 갱신 누락**: snapshot/expected/golden 출력만 달라진 경우 변경 의도 확인 후 해당 테스트 데이터 수정.
+   - **무관한 기존 실패**: `에러 처리 범위`에 따라 조용히 스킵.
+   - **원인 특정 불가**: 에스컬레이션 규칙에 따라 즉시 보고.
+6. 1차 분류 결과와 근거 전체를 `/sd-inner-clarify`로 전달하여 분류와 처리 방향의 명확성을 판정한다. sd-check가 자체 판단으로 명확한 항목을 제외하고 보내지 않는다.
+7. `/sd-inner-clarify`가 분류와 처리 방향을 명확하다고 판정하면 즉시 처리한다:
+   - **구현 버그가 명확함**: 코드 수정.
+   - **테스트 변경 누락이 명확함**: 테스트, fixture, expected/golden 수정.
+   - **테스트 데이터 갱신 누락이 명확함**: snapshot/expected/golden 수정.
+   - **무관한 기존 실패가 명확함**: `에러 처리 범위`에 따라 조용히 스킵.
+8. `/sd-inner-clarify`가 1%라도 불확실하다고 판정하면 처리하지 않는다. 사용자에게 분류 근거와 처리 방향을 확인받고 승인된 처리만 실행한다.
+
+**NEVER: 테스트를 통과시키기 위해 현재 세션의 의도된 코드 변경을 예전 동작으로 되돌리지 않는다.** 코드 롤백성 수정은 실패 원인이 구현 버그로 확정된 경우에만 허용한다. "테스트가 기존 값을 기대한다"는 사실만으로 구현 버그를 확정할 수 없다.
+
+**ALWAYS: 코드 수정으로 공개 동작, 렌더링 결과, SQL/DDL 출력, 직렬화 결과, 에러 메시지, fixture 구조가 바뀌었으면 관련 테스트와 expected/golden 파일 갱신 여부를 확인한다.** 테스트 변경 누락이 확인되면 코드가 아니라 테스트 산출물을 수정한다.
 
 ## Step 5: 반복 혹은 완료
 

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

@@ -1,7 +1,7 @@
 ---
 name: sd-claude-docs
 description: 프로젝트 분석을 통해 CLAUDE.md(개발자용)와 README.md/docs(소비자용) 문서를 동시 생성하는 스킬. "init", "CLAUDE.md 생성", "README 생성", "LLM 문서 만들어줘", "패키지 문서 생성" 등을 요청할 때 사용한다.
-effort: low
+model: haiku
 ---
 
 # sd-claude-docs: CLAUDE.md + README.md/docs 통합 생성
@@ -95,7 +95,7 @@ version: "14.0.51" → 메이저 버전: 14 → {문서 루트}: .claude/referen
 
 ### 1-4. `.claude/rules/` 스캔
 
-디렉토리가 존재하면 모든 `.md` 파일을 읽어 이미 다루고 있는 주제를 목록화한다. 해당 주제는 **CLAUDE.md에서 제외**한다 — 파일 간 규칙 중복은 LLM이 고유 지침 대신 중복 컨텍스트를 처리하게 되어 지침의 효과를 약화시킨다.
+디렉토리가 존재하면 `.claude/rules/*.md`에 매칭되는 룰 본문 파일을 읽어 이미 다루고 있는 주제를 목록화한다. 단, `*.eval.md` 파일은 룰의 Eval 시나리오이므로 제외한다. 해당 주제의 상세 규칙 본문은 **CLAUDE.md에서 제외**한다 — 파일 간 규칙 중복은 LLM이 고유 지침 대신 중복 컨텍스트를 처리하게 되어 지침의 효과를 약화시킨다.
 
 ### 1-5. 프로젝트 유형 감지
 
@@ -124,7 +124,7 @@ subagent가 개별 파일을 하나씩 Read하는 대신 병합 파일 1회 Read
 
 ```bash
 TS=$(date +%y%m%d%H%M%S)
-bash .claude/skills/sd-claude-docs/merge-source.sh {패키지경로} ./.tmp/docs/$TS/{패키지명}-source.txt
+python .claude/skills/sd-claude-docs/merge-source.py {패키지경로} ./.tmp/docs/$TS/{패키지명}-source.txt
 ```
 
 ### 3-2. subagent 병렬 실행
@@ -164,18 +164,37 @@ Step 2의 "Step 4 수행" 열이 "수행"인 경우에만 진행한다.
 
 ### 4-1. 콘텐츠 구성
 
-Step 1 결과와 Step 3의 각 패키지 CLAUDE.md를 조합하여 루트 CLAUDE.md를 생성한다. `.claude/rules/`에서 이미 다루는 주제(1-4에서 감지)는 **제외**한다. 패키지 CLAUDE.md에 기술된 상세(아키텍처, 패턴 등)는 루트에 중복하지 않고, 아키텍처 섹션에서 패키지 간 의존 관계와 역할 요약만 포함한다.
+루트 CLAUDE.md는 Claude가 이 저장소에서 작업하기 전에 읽고 따르는 **작업 지침서**로 작성한다. 프로젝트 소개서, 기술 스택 요약서, 아키텍처 설명서처럼 작성하지 않는다.
+
+Step 1 결과와 Step 3의 각 패키지 CLAUDE.md를 조합하여 루트 CLAUDE.md를 생성한다. `.claude/rules/`에서 이미 다루는 주제(1-4에서 감지)의 상세 규칙 본문은 **제외**한다. 패키지 CLAUDE.md에 기술된 상세(패키지 내부 구조, 패턴, API 사용법 등)는 루트에 중복하지 않는다. 루트에는 작업자가 어느 패키지와 어떤 문서를 먼저 봐야 하는지 판단할 수 있는 수준의 라우팅 정보만 둔다.
+
+#### 작성 원칙
+
+- **작업자가 바로 행동할 수 있게 작성한다**: "무엇을 읽고 → 어디를 수정하고 → 어떤 명령으로 검증하는가"를 중심으로 쓴다.
+- **설명보다 지침을 우선한다**: 기술 스택·아키텍처·패키지 역할은 작업 판단에 필요한 만큼만 짧게 쓴다.
+- **중복을 피한다**: `.claude/rules/*.md`, 패키지 CLAUDE.md, 소비자 README/docs에 이미 있는 상세 내용은 링크하거나 한 줄로 라우팅한다.
+- **금지와 대안을 함께 쓴다**: 금지 명령어·금지 API·금지 패턴을 쓰는 경우 허용되는 명령어·API·패턴을 같은 항목에 적는다.
+- **명령어는 실제 스크립트 기준으로 쓴다**: 일반적인 `npm run script -- --flag` 습관을 추측으로 적용하지 않는다. `package.json` 스크립트가 `pnpm sd-cli <command>`처럼 커스텀 CLI를 감싸면 `--target` 같은 옵션은 중간 `--` 없이 작성한다.
 
 #### 포함할 섹션
 
-- **프로젝트 정보**: 루트 `package.json`의 `name`/`description`, 패키지 매니저
-- **모노레포 구조**: 워크스페이스 경로 나열, 각 패키지 10단어 이내 요약
-- **기술 스택**: 주요 프레임워크·번들러·테스트 도구 (최대 10개)
-- **명령어**: 1-2의 스크립트를 카테고리별 bash 코드 블록으로 포매팅, 인라인 주석 추가
-- **아키텍처**: 패키지 간 의존 관계 및 역할 요약
-- **코딩 규칙**: 1-3에서 선별한 규칙을 불릿 리스트로 포매팅
+- **작업 언어**: 사용자 응답 언어, 저장소 문서 언어, 공개 소비자 문서 작성 관점
+- **저장소 구조와 수정 경계**: 워크스페이스 경로, 루트/패키지/테스트/문서 산출물의 책임 경계
+- **패키지 라우팅**: 사용자 요청 유형별로 먼저 볼 패키지·테스트·문서 경로를 표로 정리
+- **명령어**: 1-2의 스크립트를 작업 유형별 bash 코드 블록으로 포매팅, 각 명령을 언제 쓰는지 인라인 주석 추가
+- **코딩 규칙**: 1-3에서 선별한 규칙 중 작업 중 실수하기 쉬운 전역 금지·필수 규칙을 불릿 리스트로 포매팅
+- **테스트와 검증 기준**: 변경 유형별 최소 검증 명령, 통합 테스트 전제 조건, 실행하지 못한 경우 보고 기준
+- **주의할 변경사항**: lockfile, 생성물, 공개 API, 설정 파일처럼 파급이 큰 파일을 언제 함께 갱신해야 하는지 기술
+
+실질적 내용이 없는 섹션은 생략한다. 필요 시 위 외 섹션도 추가한다 (예: 네이티브 앱 실행, 브라우저 검증).
+
+#### 제외할 내용
 
-실질적 내용이 없는 섹션은 생략한다. 필요 시 위 외 섹션도 추가한다 (예: 통합 테스트).
+- 프로젝트 홍보 문구, 긴 개요, 기술 스택 나열만을 위한 섹션
+- 패키지 내부 디렉토리별 상세 설명 — 패키지 CLAUDE.md에 둔다
+- 공개 API 사용법, 예제, anti-pattern — 소비자 README/docs에 둔다
+- `.claude/rules/*.md`에 이미 있는 상세 규칙 본문
+- 작업 판단에 쓰이지 않는 의존 관계 다이어그램
 
 ### 4-2. 병합
 
@@ -188,38 +207,52 @@ Step 1 결과와 Step 3의 각 패키지 CLAUDE.md를 조합하여 루트 CLAUDE
 ````markdown
 # Simplysm
 
-pnpm 모노레포. 패키지 경로: `packages/*`, 테스트: `tests/*`
+pnpm 기반 TypeScript ESM 모노레포. 이 파일은 Claude가 작업 전에 읽는 저장소 작업 지침이다.
 
-## 명령어
+## 작업 언어
 
-### 개발
+- 사용자 안내와 작업 요약은 한국어로 작성한다.
+- 공개 소비자 문서는 패키지를 사용하는 LLM이 바로 코드를 작성할 수 있는 작업 라우터 형태로 작성한다.
 
-```bash
-pnpm dev [targets..]                     # 서버 패키지를 개발 모드로 실행
-pnpm watch [targets..]                   # 라이브러리 패키지를 watch 빌드
-```
+## 저장소 구조와 수정 경계
 
-### 코드 품질
+- 워크스페이스는 `packages/*`, `tests/*`이다.
+- 공개 패키지 코드를 수정하면 해당 패키지의 소비자 문서도 함께 확인한다.
+- 루트 설정, lockfile, 생성물은 관련 변경이 있을 때만 수정한다.
 
-```bash
-pnpm check [targets..]                   # 전체 검사
-pnpm typecheck [targets..]               # TypeScript 타입 체크
-```
+## 패키지 라우팅
 
-## 아키텍처
+| 요청 유형 | 먼저 볼 위치 | 함께 확인할 위치 |
+|-----------|--------------|------------------|
+| Angular UI | `packages/angular` | `{문서 루트}/angular/README.md` |
+| 서비스 서버 | `packages/service-server` | `tests/service` |
+| ORM | `packages/orm-common`, `packages/orm-node` | `tests/orm` |
 
-의존 방향: 위 → 아래. `core-common`은 내부 의존성 없는 리프 패키지이다.
+## 명령어
 
-```
-UI:       angular (Angular)
-서비스:   service-server / service-client / service-common
-코어:     core-common (중립) / core-browser / core-node
+```bash
+pnpm check [--target <pkg>]              # 패키지 변경 후 타입체크와 lint 실행
+pnpm typecheck [--target <pkg>]          # 타입 오류만 확인
+pnpm lint [--target <pkg>]               # lint 오류만 확인
+vitest run <path>                        # 변경 범위에 맞는 테스트 실행
 ```
 
 ## 코딩 규칙
 
 - `import type` 필수 (`verbatimModuleSyntax`), `#private` 금지 → `private` 키워드 사용
 - `console.*` 금지, `Buffer` 금지 → `Uint8Array`
+
+## 테스트와 검증 기준
+
+- 타입·lint 영향이 있는 변경은 `pnpm check [--target <pkg>]`로 검증한다.
+- 런타임 로직 변경은 관련 `vitest run <path>`를 함께 실행한다.
+- 실행하지 못한 검증은 최종 응답에 이유와 남은 위험을 적는다.
+
+## 주의할 변경사항
+
+- 공개 API를 바꾸면 소비자 문서와 API 인덱스를 함께 갱신한다.
+- 의존성 변경이 있을 때만 lockfile을 갱신한다.
+- 생성물은 생성 명령을 실행한 경우에만 갱신한다.
 ````
 
 ## Step 5: 결과 보고

package/claude/skills/sd-claude-docs/merge-source.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def collect_source_files(package_path: Path) -> list[Path]:
+    files: list[Path] = []
+
+    src_dir = package_path / "src"
+    if src_dir.is_dir():
+        files.extend(path for path in src_dir.rglob("*.ts") if path.is_file())
+
+    scss_dir = package_path / "scss"
+    if scss_dir.is_dir():
+        files.extend(path for path in scss_dir.rglob("*.scss") if path.is_file())
+
+    return sorted(files, key=lambda path: path.as_posix())
+
+
+def write_merged_source(files: list[Path], output_path: Path) -> None:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with output_path.open("w", encoding="utf-8", newline="\n") as output:
+        for file_path in files:
+            output.write(f"=== {file_path.as_posix()} ===\n")
+            text = file_path.read_text(encoding="utf-8")
+            output.write(text)
+            if not text.endswith("\n"):
+                output.write("\n")
+            output.write("\n")
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 3:
+        print("Usage: merge-source.py <package-path> <output-file>", file=sys.stderr)
+        return 1
+
+    package_path = Path(argv[1])
+    output_path = Path(argv[2])
+    write_merged_source(collect_source_files(package_path), output_path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))