@simplysm/sd-claude 14.0.94 → 14.0.95

package/claude/references/sd-simplysm14/manuals/client-crud.md

@@ -50,6 +50,10 @@
 
 `<sd-sheet-column>` 은 `<sd-crud-list>` 의 직속 자식으로 두면 내부 시트로 자동 투영됨.
 
+### 와이어프레임이 표준 버튼 위치와 충돌하면
+
+`(create)/(delete)/(restore)` 표준 출력이 와이어프레임에 명시된 버튼 위치를 가린다면, 표준 출력 사용을 포기하고 `#toolTpl` 등 슬롯 안에 `sd-button` 으로 직접 배치. 시각 요소 배치는 와이어프레임이 1순위 ([client-component.md "시각 요소 배치 기준"](./client-component.md)).
+
 ### viewType 별 동작
 
 - **`'page'`** — 라우팅 진입 단위. 상단에 저장 버튼.
@@ -110,7 +114,7 @@ async onEdit(item: IItem, event: Event): Promise<void> {
 ```html
 <ng-template #toolTpl>
   <sd-button [size]="'sm'" [theme]="'link-success'" (click)="onDownloadExcelButtonClick()">
-    <ng-icon [svg]="tablerFileExcel" />
+    <ng-icon [svg]="tablerUpload" />
     엑셀 다운로드
   </sd-button>
 </ng-template>
@@ -149,9 +153,106 @@ async onDownloadExcelButtonClick(): Promise<void> {
 - 조회는 목록과 같은 `_search` 를 페이징 인자만 꺼서 재사용 — 보이는 페이지가 아니라 결과 전체를 받음.
 - 파일명은 `<화면제목>_<yyMMdd>.xlsx`. 화면 제목은 `injectViewTitleSignal()`.
 - 양식 컬럼 = 화면 표시 컬럼 + `삭제`(참/거짓) + `수정일시`·`수정자`([data-log.md](./data-log.md) 의 표시 규약). 참조 마스터는 명칭으로 출력.
-- 비밀번호 등 평문으로 못 꺼내는 값은 양식에서 제외.
+- 같은 `_excelWrapper`(zod 스키마) 를 아래 업로드 레시피와 **공유**함 — `write` 가 다운로드, `read` 가 업로드.
 - `ExcelWrapper`/`downloadBlob` 자체 사용법은 [apis/excel/README.md](../apis/excel/README.md) · [apis/core-browser/README.md](../apis/core-browser/README.md).
 
+### 엑셀 업로드로 일괄 등록·수정하려면
+
+다운로드와 **같은 `_excelWrapper`(zod 스키마) 를 공유**해 역방향으로 읽음. `#toolTpl` 의 다운로드 버튼 옆에 업로드 버튼을 `edit` 권한으로 게이팅해 두고, `openFileDialog` → `_excelWrapper.read` → 정합성 검증 → `save` 일괄 저장. 아래 예시는 참조 마스터(예: 역할) 컬럼을 포함한 목록 기준.
+
+```html
+<ng-template #toolTpl>
+  @if (perms().includes("edit")) {
+    <sd-button [size]="'sm'" [theme]="'link-success'" (click)="onUploadExcelButtonClick()">
+      <ng-icon [svg]="tablerUpload" />
+      엑셀 업로드
+    </sd-button>
+  }
+  <!-- 위 '엑셀 다운로드' 버튼과 같은 #toolTpl 안에 둠 -->
+</ng-template>
+```
+
+```ts
+async onUploadExcelButtonClick(): Promise<void> {
+  if (this.busyCount() > 0) return;
+  if (!this.perms().includes("edit")) return;
+
+  const files = await openFileDialog({ accept: ".xlsx" });
+  if (files == null) return; // 취소
+
+  this.busyCount.update((v) => v + 1);
+  await this._sdToast.try(async () => {
+    // 파생 컬럼(수정일시·수정자)은 업로드에서 제외하고 파싱.
+    const records = await this._excelWrapper.read(files[0], 0, {
+      excludes: ["lastModifiedAt", "lastModifiedBy"],
+    });
+    if (records.length === 0) throw new Error("업로드할 데이터가 없습니다.");
+
+    // 다건일 때만 에러 메시지에 항목명을 붙임(단건이면 평문).
+    const label = (itemName: string): string =>
+      records.length > 1 ? `직원 '${itemName}': ` : "";
+
+    // 참조 마스터: 명칭 → ID 역변환(활성 기준). 매칭 안 되는 명칭은 throw.
+    const roleIdByName = new Map(this.sharedRoles.items().map((r) => [r.name, r.id] as const));
+    const inputs = records.map((rec) => {
+      let roleId: number | undefined;
+      const roleName = rec.roleName?.trim();
+      if (roleName != null && roleName !== "") {
+        roleId = roleIdByName.get(roleName);
+        if (roleId == null) throw new Error(`${label(rec.name)}존재하지 않는 역할입니다. (${roleName})`);
+      }
+      return { id: rec.id, name: rec.name, roleId, isDeleted: rec.isDeleted };
+    });
+
+    // ID↔이름 정합성 — id 있는 행은 DB의 (id, name) 과 대조. id 없으면 신규.
+    const ids = inputs.flatMap((x) => (x.id != null ? [x.id] : []));
+    const dbRows =
+      ids.length === 0
+        ? []
+        : await this._appOrm.connectWithoutTransAsync((db) =>
+            db
+              .employee()
+              .where((c) => [expr.in(c.id, ids)])
+              .select((c) => ({ id: c.id, name: c.name }))
+              .execute(),
+          );
+    const dbNameById = new Map(dbRows.map((r) => [r.id, r.name] as const));
+
+    // 기존 이름(비즈니스키)이 바뀌면 엑셀 행 어긋남(정렬 사고) 의심 → 변경 건수를 입력받아 확인.
+    let nameChangedCount = 0;
+    for (const x of inputs) {
+      if (x.id == null) continue;
+      const dbName = dbNameById.get(x.id);
+      if (dbName == null) throw new Error(`${label(x.name)}ID ${x.id} 에 해당하는 직원이 없습니다.`);
+      if (dbName !== x.name.trim()) nameChangedCount++;
+    }
+    if (nameChangedCount >= 1) {
+      const answer = prompt(
+        `기존 항목 ${nameChangedCount}건의 이름이 변경됩니다.\n계속하려면 ${nameChangedCount} 을(를) 입력하세요.`,
+      );
+      if (answer == null || answer.trim() !== String(nameChangedCount)) return;
+    }
+
+    const results = await this._appService.employee.save(inputs); // 일괄 저장(트랜잭션)
+    await this._appSharedData.emitAsync(
+      "직원",
+      results.map((r) => r.id),
+    );
+    this._sdToast.success(`${results.length}건이 반영되었습니다.`);
+    await this._refresh();
+  });
+  this.busyCount.update((v) => v - 1);
+}
+```
+
+- 다운로드와 같은 `_excelWrapper` 를 그대로 재사용 — `read(file, sheetIndex, { excludes })` 가 역방향. `excludes` 로 파생 컬럼(수정일시·수정자)을 파싱에서 뺌.
+- 빈 파일(0건)은 throw — 정상 처리하지 않음.
+- 참조 마스터(역할 등)는 **명칭 → ID 역변환**. 매칭 안 되는 명칭은 throw — 일부만 건너뛰지 않음(다중 작업 원자성).
+- `id` 유무로 신규/수정 분기. `id` 있는 행은 DB의 `(id, name)` 과 대조해 존재·정합성 확인(없으면 throw).
+- 기존 이름(비즈니스키) 변경은 엑셀 행이 밀린 사고일 수 있어, 변경 건수를 직접 입력받아 확인 후 진행.
+- 저장은 `save(inputs)` 한 번으로 일괄 — 한 건이라도 실패하면 전체 롤백(트랜잭션 원자성).
+- 업로드 버튼은 `edit` 권한일 때만 노출. import 추가: `openFileDialog`(`@simplysm/core-browser`) · `tablerUpload`(`@ng-icons/tabler-icons`).
+
 ### 특정 행의 선택·삭제를 막으려면
 
 `[getItemSelectableFn]` 로 행별 선택 가능 여부를 반환. 문자열을 반환하면 그 사유가 안내되고 해당 행은 선택(→삭제) 불가. 개별 선택·전체 선택 모든 경로에 적용됨.
@@ -167,6 +268,26 @@ getItemSelectableFn = (item: IItem): boolean | string =>
 - `true` = 선택 가능, `string` = 선택 불가 + 사유. 선택 자체가 막히므로 핸들러에 같은 가드를 또 두지 않아도 됨.
 - 단건 상세에는 선택 개념이 없으므로, 같은 제약을 삭제 버튼을 조건부로 숨겨 적용(`@if (!isSelf() && perms().includes("edit")) { ...삭제 버튼... }`).
 
+### 시트 정렬을 서버 정렬로 반영하려면
+
+`[(sorts)]="sortingDefs"` 로 받은 정렬 조건을 `_search` 쿼리에 반영. 시트 컬럼 `key` 가 select 별칭과 일치하므로, 컬럼별 분기 없이 `obj.getChainValue` 로 `key` 를 컬럼으로 풀어 `orderBy` 에 전달.
+
+```ts
+// 화면 사용자가 지정한 정렬을 우선순위대로 적용
+for (const sort of this.sortingDefs()) {
+  qr2 = qr2.orderBy((c) => obj.getChainValue(c, sort.key) as any, sort.desc ? "DESC" : "ASC");
+}
+// 이 화면의 기본 정렬 — 여기를 고쳐 화면별 기본값을 바꿈
+if (!this.sortingDefs().some((s) => s.key === "id")) {
+  qr2 = qr2.orderBy((c) => c.id, "DESC");
+}
+```
+
+- 아래 `if` 블록이 그 화면의 기본 정렬을 정하는 자리. 예시는 `id DESC` — 다른 기본 정렬이 필요하면 `orderBy` 의 컬럼·방향과 `s.key` 를 같은 키로 함께 바꿈.
+- 화면 사용자가 시트 헤더로 정렬하면 그 정렬이 1순위로 적용되고, 기본 정렬은 맨 뒤에 깔림.
+- 컬럼마다 `if (sort.key === "X") orderBy((c) => c.X, ...)` 식 분기 금지 — `sort.key` 가 select 별칭과 일치하므로 한 줄로 처리.
+- `obj` 는 `@simplysm/core-common`, `SortingDef` 는 `@simplysm/angular`.
+
 ## `sd-crud-detail`
 
 단일 레코드 편집 화면의 표준 골격. 다음 기능을 일괄 제공: 폼 래핑, CTRL+S 단축키 저장, 저장 버튼, 모달의 "확인" 버튼 자동 처리.
@@ -209,7 +330,9 @@ getItemSelectableFn = (item: IItem): boolean | string =>
 
 ### 삭제 (onDelete)
 
-`confirm` → soft delete(`isDeleted=true`) → 이력 적재 → 공유 데이터 통지 → 목록은 refresh / 단건은 close.
+`confirm` → soft delete(`isDeleted=true`) → 이력 적재 → 공유 데이터 통지 → 목록(list)은 `_refresh()` / 단건(detail)은 `submitted.emit(true)`.
+
+**벌크 삭제 (list)**:
 
 ```ts
 async onDelete(targets: IItem[]): Promise<void> {
@@ -236,6 +359,30 @@ async onDelete(targets: IItem[]): Promise<void> {
 }
 ```
 
+**단건 삭제 (detail)**: `sd-crud-detail` 표준 호출에는 `(delete)` output 이 없으므로, 삭제 버튼을 `#commandTpl` 슬롯에 두고 `(click)="onDelete()"` 로 배선. 목록의 `_refresh()` 대신 `submitted.emit(true)` 로 부모(list) 에 통지.
+
+```ts
+async onDelete(): Promise<void> {
+  if (this.busyCount() > 0) return;
+  if (!this.canEdit()) return;
+  if (!confirm("삭제하시겠습니까?")) return;
+
+  const id = this.dataId();
+  const employeeId = this._appAuth.authInfo()?.employeeId;
+  this.busyCount.update((v) => v + 1);
+  await this._sdToast.try(async () => {
+    await this._appOrm.connectAsync(async (db) => {
+      await db.role().where((c) => [expr.eq(c.id, id)]).update(() => ({ isDeleted: true }));
+      await db.role().insertDataLog({ action: "삭제", itemId: id, employeeId });
+    });
+    await this._appSharedData.emitAsync("역할", [id]);
+    this._sdToast.success("삭제되었습니다.");
+    this.submitted.emit(true);
+  });
+  this.busyCount.update((v) => v - 1);
+}
+```
+
 ### 복구 (onRestore)
 
 복구는 `confirm` 없이 진행하되, **활성 유니크 컬럼(명칭·코드)이 있으면 복구로 활성 중복이 생기지 않는지 재검증**해야 함(삭제된 동안 같은 값의 활성 레코드가 생겼을 수 있음). 검증 위치가 단건/벌크에서 다름. 활성 유니크 정책 자체는 [orm.md](./orm.md) 의 유니크 전략.
@@ -288,4 +435,4 @@ for (const id of ids) {
 - 삭제·복구·이력 적재는 한 `connectAsync` 트랜잭션 안에서 수행 — 데이터만 바뀌고 이력이 빠지거나 그 반대가 되지 않게 함.
 - 벌크 복구는 하나라도 충돌하면 전체 롤백(원자성). 충돌분만 빼고 나머지를 복구하지 않음.
 - 활성 유니크 검증은 복구 경로에서 빠뜨리지 않음 — 단건은 선검증, 벌크는 후검증. 활성 유니크가 없는 모델이면 생략 가능.
-- 단건은 삭제 후 닫고(close), 복구 후엔 닫지 않고 refresh — 복구 직후 상세를 계속 보도록.
+- 단건(detail)은 삭제 후 [client-component.md "detail 데이터 흐름"](./client-component.md) 의 계약대로 `submitted.emit(true)` 로 부모에 통지(modal 컨텍스트에선 모달 호스트가 그 위에 `close` 로 닫음 — `emit` 의 대체 아님). 복구 후엔 닫지 않고 refresh — 복구 직후 상세를 계속 보도록.

package/claude/references/sd-simplysm14/manuals/client-demo.md

@@ -4,24 +4,11 @@
 
 ## 화면 정의 섹션(4번 섹션) 의 화면 유형별 파일 역할
 
-| 화면 유형 패턴                                           | 파일 역할                                                                                       |
-| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| 마스터(체크박스·`[E N]`·5버튼바) / 시트 단일             | `<domain>.list.ts`                                                                              |
-| 단건 입력 폼                                             | `<domain>.detail.ts`                                                                            |
-| 좌 목록 + 우 단건                                        | `<domain>.view.ts` + `.list.ts` + `.detail.ts`                                                  |
-| 좌 헤더 목록 + 우(헤더 정보 + 라인 시트) 마스터-라인     | `<domain>.view.ts` + `.list.ts` + `.detail.ts` — 우 라인 영역은 `.detail.ts` (헤더 단건 + 라인) |
-| 모달 전용 비-CRUD 화면 (도구·검색·설정 등)               | `<domain>.modal.ts`                                                                             |
-| 프린트 양식                                              | `<domain>.print-template.ts`                                                                    |
-
-`<domain>` 은 화면명을 dash-case 영문으로 음역한 슬러그. 같은 도메인 폴더에 같은 역할의 파일이 2개 이상이면 `<domain>-<갈래>.<역할>.ts` 형식 사용.
-
-동작 섹션의 `→ [화면.X] 을 모달로 띄움` 표기는 표시 방식일 뿐 파일 역할이 아님. 화면.X 가 단건 편집이면 `.detail.ts` 를 `showAsync` 로 띄우고(= 위 "단건 입력 폼" 행), 모달 전용 비-CRUD UI 일 때만 `.modal.ts`. 판별 기준은 [client-component.md "detail 과 modal 구분"](./client-component.md) 참조.
+화면 유형 → 파일 구성 매핑(`<domain>` 슬러그·모달 표기 해석 포함) 은 [client-component.md "파일명·역할·위치"](./client-component.md) 의 "화면 정의 → 파일 구성" 을 따름. 데모도 같은 매핑으로 파일을 구성.
 
 ## 와이어프레임 기준
 
-화면 정의 섹션(4번 섹션) 의 와이어프레임이 모든 시각 요소(버튼·필터·시트·탭·검색) 의 **존재·영역·순서** 결정의 1순위. 표준 슬롯이나 기본 UI(사용자 인터페이스) 와 충돌하면 와이어프레임에 맞춰 슬롯을 비우거나 컴포넌트를 교체. 줄 수·픽셀 좌표는 기준이 아님 (폼 inline 자동 wrap 등의 표현 한계 때문).
-
-`sd-crud-list` 의 표준 출력(`(create)/(delete)/(restore)`) 이 와이어프레임에 명시된 버튼 위치를 가린다면 표준 출력 사용을 포기하고 슬롯 안에 `sd-button` 으로 직접 배치.
+시각 요소(버튼·필터·시트·탭·검색) 의 존재·영역·순서는 와이어프레임이 1순위 ([client-component.md "시각 요소 배치 기준"](./client-component.md)). `sd-crud-list` 표준 출력과 충돌할 때의 처리는 [client-crud.md "와이어프레임이 표준 버튼 위치와 충돌하면"](./client-crud.md). 데모도 와이어프레임을 따라 구성.
 
 ## 항목표의 `종류` 컬럼을 입력 컨트롤로 매핑
 
@@ -73,7 +60,7 @@ if (!result) return;
 
 영역 한정 호출(`→ [화면.Y] 의 <영역> — 선택 전용` 등) 은 모달의 입력 시그널(`selectMode` 등) 로 전달. spec 마커 매핑: "선택 전용"·multiselect 는 `selectMode`(`single`/`multi`) 로, "편집 가능 여부" 는 `readonly` 로 따로 전달. "선택 전용" 은 선택 목적을 뜻할 뿐 편집을 막지 않으므로(readonly 아님), 편집까지 차단하려면 `readonly=true` 를 함께 줄 것.
 
-단건 편집을 모달로 띄우는 경우 피호출 화면은 `.detail.ts`(`<sd-crud-detail>` 루트, `viewType='modal'` 자동 주입)이며 모달 표시용 별도 `.modal.ts` 를 만들지 않음. 모달 전용 비-CRUD 화면(`.modal.ts`)은 `sd-crud-detail` 대신 `sd-busy-container` 등으로 자체 구성. 어느 경우든 임의 `close` output 규약을 만들지 말 것 — `_sdModal.showAsync` 의 페이로드 반환 규약만 사용.
+단건 편집을 모달로 띄우는 경우 피호출 화면은 `.detail.ts`(`<sd-crud-detail>` 루트, `viewType='modal'` 자동 주입)이며 모달 표시용 별도 `.modal.ts` 를 만들지 않음. 모달 전용 비-CRUD 화면(`.modal.ts`)은 `sd-crud-detail` 대신 `sd-busy-container` 등으로 자체 구성.
 
 **동반 모달**: 동작 섹션에 `→ [화면.Y] 을 모달로 띄움` 으로 등장하는 모든 모달은 같은 호출에서 함께 생성. 이미 존재하면 재사용.
 
@@ -84,7 +71,7 @@ if (!result) return;
 ```html
 <ng-template #toolTpl>
   <sd-button [size]="'sm'" [theme]="'link-success'" (click)="onExcelUploadClick()">
-    <ng-icon [svg]="tablerFileExcel" /> 엑셀 업로드
+    <ng-icon [svg]="tablerUpload" /> 엑셀 업로드
   </sd-button>
   <sd-button [size]="'sm'" [theme]="'link-success'" (click)="onExcelDownloadClick()">
     <ng-icon [svg]="tablerDownload" /> 엑셀 다운로드
@@ -115,4 +102,4 @@ list 와 detail 의 합성 view 에서 항목 미선택 빈 상태는 [client-co
 
 ## 라우팅·메뉴 따라가기
 
-기존 화면 1개의 라우팅·메뉴 등록 위치·방식을 그대로 따름. 라우트 경로는 화면명을 dash-case 영문으로 음역한 슬러그 사용 (프로젝트의 기존 슬러그 규칙이 일관되어 있다면 그 규칙을 따름). 메뉴 라벨은 spec 의 화면명을 그대로 사용.
+라우팅·메뉴 등록 관례(기존 화면 본뜨기·`title`=화면명·`code`=음역 슬러그) 는 [client-app-structure.md "2. 메뉴 추가"](./client-app-structure.md) 를 따름. 데모도 같은 방식으로 등록.

package/claude/references/sd-simplysm14/manuals/client-shared-data.md

@@ -184,7 +184,10 @@ sharedProducts = useSharedSignal("품목");
 
   @let _selectedRole = selectedRole();
   @if (_selectedRole == null) {
-    <div class="flex-fill p-xxl">역할을 선택하세요.</div>
+    <div class="flex-fill tx-theme-gray-default p-xxl" style="font-size: 48px; line-height: 1.5em">
+      <ng-icon [svg]="tablerArrowLeft" />
+      역할을 선택하세요.
+    </div>
   } @else {
     <app-role-permission-detail class="flex-fill" [roleId]="_selectedRole.id" />
   }
@@ -209,7 +212,7 @@ constructor() {
 - 두 이탈 경로를 모두 막음:
   - `[canChangeFn]="checkCanLeave"` — 좌측에서 **다른 항목으로 전환**하기 전 확인.
   - `setupCanDeactivate(checkCanLeave)` — **페이지(라우팅) 이탈** 전 확인.
-- 선택 전(`selectedItem == null`)에는 안내 문구를 두고 상세를 띄우지 않음.
+- 선택 전(`selectedItem == null`)에는 미선택 빈 상태를 둠 — 아이콘 + 안내 문구 구조와 `NgIcon` 등록은 [client-component.md](./client-component.md) 의 'list + detail 합성' 빈 상태 규약을 따름.
 
 ## 지킬 것
 

package/claude/references/sd-simplysm14/manuals/data-log.md

@@ -133,7 +133,7 @@ Queryable.prototype.joinLastDataLog = function (this: Queryable<any, any>, opts)
 
 ### 3. db-context 등록
 
-확장 메서드는 `*.ext.ts` 가 한 번이라도 로드돼야 prototype 에 붙음. db-context 에서 side-effect import 로 로드를 보장하고, 이력 직접 조회용 queryable 도 등록.
+확장 메서드는 `*.ext.ts` 가 한 번이라도 로드돼야 prototype 에 붙음. `*.ext.ts` 가 진입점 import 그래프에 포함되면 로드 보장됨 — 표준 구조에선 `index.ts` 의 배럴 재export(`export * from "./db-main/system-data-log.ext"`)가 이를 충족. 배럴을 거치지 않고 db-context 를 직접 import 하는 경로가 따로 있으면 그 db-context 에 side-effect import 추가. 이력 직접 조회용 queryable 도 db-context 에 등록.
 
 ```ts
 // main.db-context.ts

package/claude/sd-system-prompt.md

@@ -49,6 +49,13 @@ Claude 에이전트가 반드시 지켜야 할 행동 지침.
 
 **요청 받은 스코프만 처리. 요청되지 않은 개선·확장 금지** (코드·문서·분석·대화 등 모든 작업).
 
+**합의·패턴에 없는 구현 선택은 임의로 정하지 않음**: 합의된 범위가 규정하지 않는 모든 선택(색상·테마·아이콘·문구·메시지 포맷·헬퍼 도입·기존 코드나 계약의 변형 등 구현 세부 포함)은 동일 맥락(같은 파일·같은 레이어)의 [기존 코드 패턴](#결정-근거)을 따름. 따를 패턴이 없으면 사용자에게 묻기. 임의 결정 금지.
+
+- "사소한 구현 디테일"·"기술적으로 필요"는 면제 사유가 아님 — 합의·패턴에 근거가 없으면 그 선택 자체가 물어야 할 결정임.
+- 합의에서 건드리지 않기로 한 코드·계약(스키마·시그니처 등)을 바꿔야 할 필요가 생기면, 우회·변형으로 조용히 해결하지 말고 그 필요성을 사용자에게 보고 후 결정 수령.
+- 나쁜 예: 같은 화면의 다운로드 버튼이 success 인데 업로드 버튼 색을 근거 없이 primary 로 정함.
+- 좋은 예: 같은 화면 기존 버튼 테마를 따라 맞춤. 맞출 패턴이 없으면 질문.
+
 ## 사용자 질의 시
 
 에이전트가 사용자에게 묻는 모든 행위 (결정·의견·정보 확인 등)에 적용. 사용자에게 묻고 답을 받아 [결정 근거](#결정-근거)로 확정.

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

@@ -1,43 +1,158 @@
 ---
 name: sd-debug
-description: 버그·실패·예외의 원인을 다관점으로 발굴하고 가설별 검증·해결책·적대검증을 거쳐 검증된 해결책을 제안하는 멀티에이전트 디버깅. Use when 버그·예외·실패의 근본 원인 분석과 해결책이 필요할 때.
+description: 버그·실패·예외의 원인을 다관점으로 발굴하고 가설별 검증·해결책·적대검증을 거쳐 검증된 해결책을 제안하는 멀티에이전트 디버깅. Use when 사용자가 sd-debug 스킬을 직접 지정해 호출할 때만 사용 (자동 트리거 금지).
 ---
 
 # sd-debug
 
-디버깅 요청 시 멀티에이전트 워크플로(`workflow.js`)에 원인 발굴·검증·적대검증을 위임하고, 그 결과를 메인 루프가 사용자에게 제시·결정 처리.
+디버깅 요청 시 메인 루프가 직접 오케스트레이션. 관점을 직접 도출한 뒤, 문제 규모에 따라 관점별 가설 발굴과 가설별 검증·해결책·적대검증을 서브에이전트(Agent 도구)로 펼치거나 직접 수행하고, 검증된 해결책을 병합·우선순위화·결정 처리. Workflow 도구는 쓰지 않음 — 효과를 문제 규모에 비례시켜 고정 비용을 피함.
+
+## 디버깅 원칙 (전 단계 공통)
+
+발굴·검증·적대검증 서브에이전트에 항상 주입하고, 메인 루프가 직접 수행할 때도 동일하게 적용:
+
+- 모든 판정은 실제 코드/설정을 Read 하여 확인. 근거 없는 추측·일반론 금지(추측은 '가설'로만 등록, 사실로 단정 금지).
+- 현재 워킹트리만 기준. git log/diff/show/blame 등 과거 조회 금지. `.back/` 및 `.gitignore` 등재 경로(node_modules·dist·.tmp 등) 읽지 말 것.
+- 결측(null/undefined)은 결측대로 다룰 것. 빈 값을 추측으로 채우지 말 것.
+- 입력 정보가 부족하면 Grep/Glob/Read 로 코드베이스를 직접 조사해 보강.
 
 ## 절차
 
-1. **문제 확정** — 증상·기대동작·관찰결과를 확정.
-   - 대화 중 오류를 논의하다 진입했으면, 그때까지의 맥락(증상·에러·스택·시도·관찰)을 요약해 문제 설명으로 합성.
-   - 에러 메시지·스택·재현조건·관련 코드 경로·환경은 있으면 함께 모음(선택).
-   - 문제 설명조차 불명확하면 사용자에게 묻기.
+### 1. 문제 확정
+
+증상·기대동작·관찰결과를 확정.
+
+- 대화 중 오류를 논의하다 진입했으면, 그때까지의 맥락(증상·에러·스택·시도·관찰)을 요약해 문제 설명으로 합성.
+- 에러 메시지·스택·재현조건·관련 코드 경로·환경은 있으면 함께 모음(선택).
+- 문제 설명조차 불명확하면 사용자에게 묻기.
+
+### 2. 의심 관점 도출 (메인 루프 직접)
+
+증상을 보고, 원인을 찾을 때 서로 겹치지 않는 '의심 관점(범주)'을 도출:
+
+- 증상 성격에 맞춰 동적으로 고름. 예시 범주: 동시성·타이밍, 데이터·결측, 타입·계약, 로직·경계조건, 외부의존·환경·설정, 상태·생명주기. (예시일 뿐 — 증상에 맞게 가감)
+- 각 관점에 key·title·focus(이 관점이 의심하는 구체 지점) 부여.
+- 보통 3~6개. 증상을 좁게 가리키면 적게, 막연하면 넓게.
+
+### 3. 규모 판단 → 펼침 여부 결정
+
+- **가설 발굴**: 관점이 여러 개이고 코드베이스 조사 범위가 넓으면 → 관점마다 Agent 펼침(각 Agent 는 자기 관점만 보므로 사각지대가 줄고 재현율이 오름). 관점이 적고 조사 범위가 좁으면 메인 루프가 직접 발굴.
+- **검증·적대검증**: 검증자가 가설을 발굴자와 무관하게 코드로 재확인하는 독립성이 핵심. **가설이 1건이라도 검증·적대검증은 독립 Agent 로 수행함이 기본**. 가설이 다수면 가설마다 Agent 병렬.
+- 서브에이전트 다수를 펼칠 때는 **한 메시지에 Agent 호출을 여러 개** 넣어 동시 실행. agentType 은 general-purpose (전수 Read·판정 필요).
+
+### 4. 가설 발굴
+
+(Agent 펼침 또는 직접) 관점별로 원인 가설을 발굴하고, 어떤 관점에도 매이지 않는 자유탐색 가설도 1벌 추가(사각지대 안전망).
+
+관점별 Agent 프롬프트:
+
+```
+문제: <문제 설명>
+[디버깅 원칙 주입]
+
+너의 일: 오직 '<title>' 관점에서만 원인 가설을 발굴하라. 이 관점의 의심 지점: <focus>
+- 코드베이스를 Grep/Glob/Read 로 직접 조사해 이 관점에 해당하는 원인 후보를 빠짐없이 뽑을 것(재현율 우선).
+- 다른 관점의 원인은 무시(중복은 이후 정리).
+- 각 가설에 title·cause·perspective('<title>')·evidenceExpected(맞다면 보일 근거)·refuteSignal(틀렸다면 보일 반증) 채움.
+- 이 관점에서 원인이 안 보이면 비울 것(억지 생성 금지).
+```
+
+자유탐색 Agent 는 위에서 `perspective='free'`, 정해진 관점 목록에 잘 안 들어가는 원인일수록 가치가 크다는 지시로 1벌.
+
+### 5. 가설 중복제거 (메인 루프 직접)
+
+발굴된 가설을 의미 기준으로 병합:
+
+- '같은 근본 원인'을 가리키는 가설끼리만 하나로 합침(표현만 다른 중복 제거). 근본 원인이 다르면 절대 합치지 말 것 — 서로 다른 원인을 뭉개면 검증에서 통째 탈락함.
+- 병합 시 evidenceExpected·refuteSignal 은 합쳐 보존, perspective 는 합쳐진 관점들 표기.
+- 개수를 인위적으로 줄이지 말 것(재현율 우선). 진짜 중복만 제거.
+
+### 6. 검증 + 해결책 도출
+
+각 가설을 (독립 Agent 가 기본) 코드를 Read 해 검증하고, 통과 시 같은 근거 위에서 해결책까지 도출. Agent 프롬프트:
+
+```
+문제: <문제 설명>
+[디버깅 원칙 주입]
+
+너의 일: 아래 원인 가설을 실제 코드를 Read 해 검증하고(관대 기준), 통과하면 같은 코드 근거 위에서 해결책까지 도출하라.
+
+1) 검증(verdict):
+- confirmed: 코드에서 근거를 확인함.
+- uncertain: 근거가 부분적·애매하지만 코드에서 일부라도 뒷받침됨 — 통과시킴(이후 적대검증이 거른다).
+- rejected: 코드로 보아 '명백히 틀린' 경우, 또는 코드에서 근거가 전혀 확인되지 않고 반증신호가 우세한 경우. 단 일부라도 뒷받침되면 기각하지 말고 uncertain('근거 전무'만 기각해 누락 방지).
+- reason 에 확인한 코드 위치·내용 인용. 통과면 refinedCause 에 구체화된 원인 기술.
+
+2) 해결책(rejected 가 아닐 때만):
+- 확인한 코드 근거 위에서, 근본 원인을 가장 직접적으로 제거하는 정도가 높은 순으로 최대 2개, 서로 접근이 다르게.
+- 각 후보에 approach·mechanism(원인을 어떻게 제거하나)·changeScope(수정 범위) 채움.
+- 과도한 설계(over-engineering)·증상만 가리는 임시방편은 피할 것.
+- rejected 면 solutions 를 비울 것.
+
+가설:
+- 제목: <title>
+- 원인: <cause>
+- 관점: <perspective>
+- 예상 근거: <evidenceExpected>
+- 반증 신호: <refuteSignal>
+```
+
+`rejected` 가설은 dropped 로 분리(보고용). `confirmed`/`uncertain` 은 통과로 다음 단계.
+
+### 7. 적대검증
+
+통과 가설의 각 해결책을 (독립 Agent 가 기본) 4관점에서 적대적으로 공격. 해결책마다 Agent 1개. 프롬프트:
+
+```
+문제: <문제 설명>
+[디버깅 원칙 주입]
+
+너의 일: 아래 (원인 가설 + 해결책) 쌍을 다음 4개 관점 각각에서 적대적으로 공격하라. 기본 입장은 '이 해결책은 결함이 있다'로 두고 약점을 찾을 것. 각 관점을 서로 끌려가지 말고 독립 판정해 관점마다 1개 항목으로 반환.
+
+관점:
+- 인과: 해결책이 이 가설의 원인을 실제로 제거하는가. 원인-증상 인과가 성립하는가.
+- 회귀·부작용: 해결책이 새 버그·룰 위반·엣지케이스(결측 null/undefined·동시성/트랜잭션·soft delete 동명 레코드·권한 분기·타입/스키마 제약)를 유발하는가.
+- 증거 정합: 가설의 근거가 실제 코드/스택과 일치하는가. 오인·과장은 없는가.
+- 대안 원인: 이 가설 말고 다른 원인이 진짜일 가능성은 없는가.
+
+각 관점 판정:
+- pass=false 로 둘 결함을 찾으면 reason 에 코드 근거와 함께 적고, 치명적(회귀 유발·인과 불성립 등)이면 critical=true. 교정안 있으면 revisedNote 에.
+- 그 관점에서 결함이 없으면 pass=true, critical=false, revisedNote="".
+
+원인 가설: <title> — <refinedCause 또는 cause>
+해결책: <approach> / <mechanism> (수정 범위: <changeScope>)
+```
+
+**fail-fast**: 펼친 Agent 중 하나라도 실패(에러)하면 부분 결과로 진행 금지. 실패 사실을 알린 뒤 해당 Agent 만 재실행해 보완. 전건 정상이어야 전 가설·전 해결책 검증 완료로 간주.
+
+### 8. 해결책 판정 (메인 루프 집계)
+
+각 해결책의 4관점 결과를 다음 규칙으로 판정:
+
+- **veto**: 어느 한 관점이라도 `critical=true && pass=false` 면 기각(치명결함 1표면 탈락).
+- **passed**: veto 가 없고, `pass=true` 가 과반(passVotes > total/2)이면 통과(채택 후보).
+- **risks**: `pass=false` 인 관점의 reason 모음(잔존 리스크).
+- **revisions**: 비어있지 않은 revisedNote 모음(교정안).
+- `votes` = `passVotes/total` 로 통과 강도 표기.
+
+### 9. 병합·우선순위화 (메인 루프)
+
+- 같은 근본 원인의 가설이 중복되면 병합.
+- 각 가설의 해결책 중 `passed=true` 인 것을 채택하되 revisions(교정)를 반영하고 risks 는 잔존 리스크로 보존.
+- (검증 confidence: confirmed>uncertain) + (적대검증 통과 강도 votes) + (원인-증상 직접성)으로 우선순위 정렬.
 
-2. **워크플로 실행** — Workflow 도구로 이 스킬의 `workflow.js` 실행:
-   - `Workflow({ scriptPath: ".claude/skills/sd-debug/workflow.js", args: <문제 설명> })`.
-   - `args` 는 1단계의 문제 설명(자연어 문자열 또는 `{ problem, error, repro, paths, env }` 객체).
-   - 관점 도출·가설 발굴·검증·해결책 탐색·적대검증·병합은 워크플로가 자율 수행.
+### 10. 결과 렌더
 
-3. **병합·우선순위화** — 반환값 `survived[]` 를 메인이 직접 정리:
-   - 같은 근본 원인의 가설이 중복되면 병합.
-   - 각 가설의 해결책 중 `passed: true` 인 것을 채택하되 `revisions`(교정)를 반영하고 `risks` 는 잔존 리스크로 보존.
-   - (검증 confidence: confirmed>uncertain) + (적대검증 통과 강도 `votes`) + (원인-증상 직접성)으로 우선순위 정렬.
+행동 규칙 "문제 발생 시" 의 3블록으로 제시:
 
-4. **결과 렌더** — 행동 규칙 "문제 발생 시" 의 3블록으로 제시:
-   - 원인 가설: `survived[].hypothesis`·`cause` (+ `dropped[]` 로 기각된 가설과 사유).
-   - 검증: 각 항목의 `verdict`·`verifyReason` (uncertain 은 "근거 약함" 으로 표시).
-   - 해결책: 채택한 해결책(교정 반영) + 잔존 리스크.
+- **원인 가설**: 통과 가설의 hypothesis·cause (+ dropped 로 기각된 가설과 사유).
+- **검증**: 각 항목의 verdict·verifyReason (uncertain 은 "근거 약함" 으로 표시).
+- **해결책**: 채택한 해결책(교정 반영) + 잔존 리스크.
 
-5. **결정 진행** — 채택 해결책 후보가 1건 이상이면 행동 규칙 "사용자 질의 시" 의 결정 진행 모드로 전환(우선순위 순). 사용자가 고른 해결책만 실제 수정에 착수.
+### 11. 결정 진행
 
-6. **미해결 보고** — `summary.noSolution` 이면(검증된 해결책 0건) `survived[]` 의 가설·탈락 사유와 `dropped[]` 를 제시해 다음 수동 디버깅의 출발점으로 삼게 함.
+채택 해결책 후보가 1건 이상이면 행동 규칙 "사용자 질의 시" 의 결정 진행 모드로 전환(우선순위 순). 사용자가 고른 해결책만 실제 수정에 착수.
 
-## 워크플로 반환 구조
+### 12. 미해결 보고
 
-- `survived[]`: `{ hypothesis, cause, perspective, verdict, verifyReason, solutions }` — 검증 통과 가설.
-  - `solutions[]`: `{ approach, mechanism, changeScope, passed, vetoed, votes, risks, revisions }` — `passed: true` 가 채택 후보.
-- `dropped[]`: `{ hypothesis, cause, reason }` — 검증에서 기각된 가설과 사유.
-- `summary`: 집계(가설 수·confirmed/uncertain·dropped·solutionsPassed·noSolution).
-- `perspectives`: 사용한 의심 관점 목록.
-- `problem`: 입력 문제 요약.
+검증된 해결책이 0건이면 통과 가설의 가설·탈락 사유와 dropped 를 제시해 다음 수동 디버깅의 출발점으로 삼게 함.