@simplysm/sd-claude 14.0.100 → 14.0.102

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

@@ -4,20 +4,24 @@ Claude 에이전트가 코드 작성·설계·변경 시 따라야 할 행동
 
 ## 인터페이스 설계 시
 
-- 산출물에서 사용자가 접하는 면(공개 API·props·옵션·UI·출력 등)의 단순함이 내부 구현 단순함보다 우선:
-  - 복잡도는 내부에서 처리.
-  - 내부 처리 불가능할 경우 사용자에게 보고 후 사용자 결정에 따름.
-- 내부 구현 난이도를 회피하려고 사용자 요구를 완화·근사화하는 것 금지:
-  - 난이도는 내부에서 처리.
-  - 내부 처리 불가능할 경우 사용자에게 보고 후 사용자 결정에 따름.
-- 명시된 정의 자체를 임의로 단순화하여 처리 금지:
-  - 정확한 구현 부담이 크면 단순화안을 사용자에게 보고 후 사용자 합의에 따름.
+사용자가 접하는 면(공개 API·props·옵션·UI·출력)은 단순하고 정의에 충실하게 유지. 그 대가로 내부 구현이 복잡해지는 것은 당연히 떠안음 — 사용자 직관이 구현 편의보다 우선.
+
+- 사용자 면의 단순함이 내부 구현의 단순함보다 우선. 사용자가 직관적으로 쓰게 하려면 구현이 복잡해져야 하며, 이는 회피 대상이 아니라 당연한 일.
+- **구현이 복잡하다·부담된다는 사실은 기능을 빼거나, 사용자 요구를 완화·근사화하거나, 명시된 정의를 임의로 단순화하거나, 우회하자고 제안할 근거가 될 수 없음.** 구현 복잡도에 대한 불안을 결정 근거로 쓰지 않음.
+- "어렵다" 와 "불가능하다" 를 구분 — 어려우면 그냥 구현. 정말 불가능할 때만 그 사실을 중립적으로 보고("X 때문에 불가, 원인 Y")하고, 단순화·축소 여부는 사용자가 결정. "안 하자·우회하자" 식 추천 금지.
+    - 나쁜 예: "구현이 복잡해지니 이 기능은 빼거나 A 방식으로 우회하는 게 어떨까요?"
+    - 좋은 예: 복잡해도 정의대로 구현. 진짜 불가능하면 원인만 사실 보고.
+- 공유·공개 코드(라이브러리 컴포넌트·공개 API)의 설계·변경 시 **선언된 모든 입력·모드를 1급으로 다룸.** 현재 소비처의 사용 양상(특정 입력을 늘 같은 값으로 호출하는 등)을 설계 근거나 기본 가정으로 삼지 않음 — 소비처가 어떻게 쓸지는 알 수 없음.
+    - 나쁜 예: "소비 화면이 전부 `inlineEdit=false` 니 비인라인이 기본형" 이라며 한 모드 위주로 설계·판단.
+    - 좋은 예: `inlineEdit` 의 true·false 를 동등하게 놓고 각 모드 동작을 모두 정의.
+- 인터페이스를 쪼개거나 재구성할 때, **각 표면 요소를 그것이 수행하는 목적·액션에 귀속**시키는 일은 도출이지 사용자 결정이 아님. 목적에서 답이 정해지면 선택지로 만들어 묻지 말고 직접 귀속해 확정. (단순화·기능축소 불가 원칙과 같은 맥락)
+    - 나쁜 예: 삭제 버튼을 어느 권한에 걸지 "A안/B안" 으로 사용자에게 질문.
+    - 좋은 예: 삭제 버튼은 delete 액션이므로 delete 권한에 귀속 — 도출해 확정.
 
 ## 불필요한 래핑·추상화 금지
 
-API·함수가 단순 입력(리터럴·기본값·직접 인자)을 그대로 받으면 그대로 전달. "타입 안전"·"방어" 등을 명분으로 래핑·변환·간접층을 덧대지 말 것.
+API·함수가 단순 입력(리터럴·기본값·직접 인자)을 그대로 받으면 그대로 전달. "타입 안전"·"방어" 등을 명분으로 래핑·변환·간접층을 덧대지 말 것 — 호출부 가독성을 해치고, 읽는 사람이 타입에 문제가 있나 의심하게 만듦.
 
-- 입력 타입이 단순 값을 허용하는데 래퍼로 감싸는 것 금지 — 호출부 가독성을 해치고, 읽는 사람이 타입에 문제가 있나 의심하게 만듦.
 - 래핑·변환은 타입이 래퍼만 받는 등 실제로 요구되는 자리에서만 사용.
 
 - 나쁜 예: 입력 타입이 `string | Wrapper<string>` 인데 항상 `wrap("재고", ...)` 로 감싸 전달.
@@ -34,22 +38,21 @@ API·함수가 단순 입력(리터럴·기본값·직접 인자)을 그대로
 - 나쁜 예: 제품 분류(빈 값 가능)를 `category ?? ""` 로 받아 미분류와 빈 분류를 같은 것으로 취급.
 - 좋은 예: 받는 타입을 `category?: string` 로 정의해 미분류(undefined)를 끝까지 유지.
 
-## 변경 전 기존 패턴 조사
+## 변경·분석 전 기존 패턴·매뉴얼 조사
 
-변경 전, 변경 영역의 기존 코드 패턴과 개발 매뉴얼을 먼저 조사.
+변경·분석 전, 대상 영역의 기존 코드 패턴과 개발 매뉴얼을 먼저 조사.
 
-- `@simplysm/*` 14.x 패키지 변경 시 → `.claude/references/sd-simplysm14/README.md` 참조.
+- `@simplysm/*` 14.x 심볼(provider·함수·컴포넌트 등)을 쓰거나·바꾸거나·동작을 해석할 때 → `.claude/references/sd-simplysm14/README.md` 의 트리거 표로 해당 매뉴얼을 먼저 확인.
+- `@simplysm/*` 동작이 불확실하면 추측·우회·미확인(보류)로 넘어가기 전에 그 매뉴얼부터 확인 — 매뉴얼로 풀리는 것을 미확인으로 남기지 않음.
 
 ## 라이브러리 우회 금지
 
-- 의존 라이브러리 동작에 이상이 있을 때 → 우회 코드 작성 전에 라이브러리 측 원인부터 먼저 조사.
-  - 라이브러리 버그·누락으로 판단될 시 → 사용자에게 보고 후 수정 방법 혹은 이슈 발행 제안.
-- 우회 코드 작성 금지:
-  - 불가피할 경우 사용자에게 보고 후 사용자 결정에 따름.
+- 의존 라이브러리 동작에 이상이 있으면, 우회 코드를 짜기 전에 라이브러리 측 원인부터 조사. 버그·누락으로 판단되면 사용자에게 보고 후 수정 방법 또는 이슈 발행을 제안.
+- 우회 코드는 작성하지 않음. 불가피하면 사용자에게 보고 후 그 결정에 따름.
 
 ## 에러 처리 시 throw 원칙
 
-문제 발생 시 throw:
+코드에서 예외·오류 상황을 만나면 throw:
 
 - silent skip 금지 — 예외를 잡은 후 대안 없이 진행하면 후속 프로세스가 결손된 채 동작함.
 - **자동 복구** (예: 의존성 미설치 → 설치·재시도 = 완전한 동작 회복) 는 silent skip 아님.
@@ -73,8 +76,11 @@ API·함수가 단순 입력(리터럴·기본값·직접 인자)을 그대로
 
 사용자에게 노출되는 알림(로그·토스트·다이얼로그 등)의 심각도 분류 기준:
 
-- `error` (danger): 문제 발생. 예외를 잡았는지·무시했는지·재시도했는지 여부와 무관하게 "문제가 일어난 사실" 이면 전부 해당.
-- `warn`: 문제는 아니지만 사용자가 인지해야 할 중요한 알림.
-- `info`: 알면 좋은 일반 알림.
-- `success`: 정상 완료 알림.
+| 심각도          | 분류 기준                                                                                              |
+| --------------- | ----------------------------------------------------------------------------------------------------- |
+| `error`(danger) | 문제 발생. 예외를 잡았는지·무시했는지·재시도했는지 여부와 무관하게 "문제가 일어난 사실" 이면 전부 해당. |
+| `warn`          | 문제는 아니지만 사용자가 인지해야 할 중요한 알림.                                                      |
+| `info`          | 알면 좋은 일반 알림.                                                                                   |
+| `success`       | 정상 완료 알림.                                                                                        |
+
 - 안티패턴: 중단 없이 복구가 되었다는 이유로 `error` 대신 `warn` 을 선택 — 분류 기준 오용.