@simplysm/sd-claude 14.0.85 → 14.0.86

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

@@ -0,0 +1,209 @@
+# 데이터 변경 이력 적재·조회
+
+CRUD 처리에서 "누가·언제·무엇을 어떻게 바꿨는지" 를 한 모델(`SystemDataLog`)에 모아 적재하고, 목록·단건 화면에서 각 행의 최근/최초 변경 이력을 함께 보여주는 패턴.
+
+핵심은 `Queryable.prototype` 확장 메서드 3개(`insertDataLog`/`joinLastDataLog`/`joinFirstDataLog`)를 만들어, 어떤 모델이든 `db.X().insertDataLog(...)` 처럼 동일하게 쓰는 것. `tableName`·`tableDescription` 은 호출한 테이블 정의에서 자동으로 채워지므로 호출부에서 모델명을 직접 적지 않음.
+
+## 변경 이력 인프라를 프로젝트에 세팅하려면
+
+세 가지를 만들고 연결함: 이력 저장 테이블 + Queryable 확장 + db-context 등록.
+
+### 1. 이력 저장 테이블
+
+```ts
+// tables/system-data-log.ts
+import { Table } from "@simplysm/orm-common";
+import { Employee } from "./employee";
+
+export const SystemDataLog = Table("SystemDataLog")
+  .columns((c) => ({
+    id: c.bigint().autoIncrement(),
+    tableName: c.varchar(200),
+    tableDescription: c.varchar(200).nullable(),
+    action: c.varchar(50),
+    itemId: c.bigint().nullable(),
+    valueJson: c.text().nullable(),
+    dateTime: c.datetime(),
+    employeeId: c.bigint().nullable(),
+  }))
+  .primaryKey("id")
+  .indexes((i) => [i.index("tableName", "itemId"), i.index("dateTime").orderBy("DESC")])
+  .relations((r) => ({
+    employee: r.foreignKey(["employeeId"], () => Employee),
+  }));
+```
+
+- `itemId` nullable: 단건 변경은 대상 레코드 PK, 전체 초기화 등 모델 단위 변경은 NULL.
+- `employeeId` nullable: 수행 직원. NULL = 시스템 수행.
+- 인덱스: 조회는 `(tableName, itemId)` 로 격리·`dateTime DESC` 로 최신 정렬하므로 두 인덱스를 둠.
+
+### 2. Queryable 확장 (`*.ext.ts`)
+
+`declare module` 로 타입을 보강하고 `Queryable.prototype` 에 런타임 구현을 붙임. `tableName`/`tableDescription` 은 `this.meta.from` 의 `meta.name`/`meta.description` 에서 자동 도출.
+
+```ts
+// system-data-log.ext.ts
+import { DateTime } from "@simplysm/core-common";
+import {
+  type DataRecord,
+  expr,
+  Queryable,
+  queryable,
+  type TableBuilder,
+} from "@simplysm/orm-common";
+import { SystemDataLog } from "./tables/system-data-log";
+
+export interface IDataLogJoinOptions {
+  includeActions?: string[];
+  excludeActions?: string[];
+}
+
+export interface IDataLogJoinResult {
+  action?: string;
+  dateTime?: DateTime;
+  employeeId?: number;
+  employeeName?: string;
+}
+
+export interface IInsertDataLogParam {
+  action: string;
+  itemId?: number;
+  valueJson?: string;
+  employeeId?: number;
+}
+
+declare module "@simplysm/orm-common" {
+  interface Queryable<TData extends DataRecord, TFrom extends TableBuilder<any, any, any> | never> {
+    joinLastDataLog(
+      opts?: IDataLogJoinOptions,
+    ): Queryable<TData & { lastDataLog?: IDataLogJoinResult }, TFrom>;
+    joinFirstDataLog(
+      opts?: IDataLogJoinOptions,
+    ): Queryable<TData & { firstDataLog?: IDataLogJoinResult }, TFrom>;
+    insertDataLog(log: IInsertDataLogParam): Promise<void>;
+  }
+}
+
+Queryable.prototype.insertDataLog = async function (this: Queryable<any, any>, log) {
+  const fromTable = this.meta.from as TableBuilder<any, any, any>;
+  const qr = queryable(this.meta.db, SystemDataLog);
+  await qr().insert([
+    {
+      tableName: fromTable.meta.name,
+      tableDescription: fromTable.meta.description,
+      action: log.action,
+      itemId: log.itemId,
+      valueJson: log.valueJson,
+      dateTime: new DateTime(),
+      employeeId: log.employeeId,
+    },
+  ]);
+};
+
+// tableName + 본 행 id 로 격리해 joinSingle 단건 부착. last/first 는 정렬만 다름.
+Queryable.prototype.joinLastDataLog = function (this: Queryable<any, any>, opts) {
+  const tableName = (this.meta.from as TableBuilder<any, any, any>).meta.name;
+  return this.joinSingle("lastDataLog", (qr, en) =>
+    qr
+      .from(SystemDataLog)
+      .where((dl) => [
+        expr.eq(dl.tableName, tableName),
+        expr.eq(dl.itemId, en["id"]),
+        ...(opts?.includeActions ? [expr.in(dl.action, opts.includeActions)] : []),
+        ...(opts?.excludeActions ? [expr.not(expr.in(dl.action, opts.excludeActions))] : []),
+      ])
+      .orderBy((dl) => dl.dateTime, "DESC")
+      .top(1)
+      .include((dl) => dl.employee)
+      .select((dl) => ({
+        action: dl.action,
+        dateTime: dl.dateTime,
+        employeeId: dl.employeeId,
+        employeeName: dl.employee!.name,
+      })),
+  );
+};
+
+// joinFirstDataLog 는 위와 동일하되 키 이름 "firstDataLog" + orderBy 를 "ASC" 로.
+```
+
+`tableDescription` 을 채우려면 테이블에 `.description("역할")` 을 선언해야 함. 미선언 모델은 NULL 로 적재됨.
+
+`joinLastDataLog`/`joinFirstDataLog` 는 본 행의 `id` 컬럼을 join 키로 사용함 → 적용 대상 모델은 PK 컬럼명이 `id` 여야 함.
+
+### 3. db-context 등록
+
+확장 메서드는 `*.ext.ts` 가 한 번이라도 로드돼야 prototype 에 붙음. db-context 에서 side-effect import 로 로드를 보장하고, 이력 직접 조회용 queryable 도 등록.
+
+```ts
+// main.db-context.ts
+import "./system-data-log.ext"; // side-effect: Queryable.prototype 확장 로드 보장
+// ...
+export class MainDbContext extends DbContext {
+  role = this.queryable(Role);
+  // ...
+  dataLog = this.queryable(SystemDataLog); // 이력 직접 조회 화면용
+}
+```
+
+## CRUD 처리에서 변경 이력을 적재하려면
+
+변경을 수행한 모델의 queryable 에서 `insertDataLog` 를 호출. `tableName`·`dateTime` 은 자동이므로 `action` 과 대상 식별 정보만 넘김.
+
+```ts
+// 단건 등록/수정/삭제: itemId 로 대상 레코드 지정
+const [role] = await db.role().insert([{ name: "관리자", isActive: true }], ["id"]);
+await db.role().insertDataLog({ action: "등록", itemId: role.id });
+
+// 전체 초기화(엑셀 업로드 등 모델 단위 변경): itemId 생략 → NULL 로 적재
+await db.rolePermission().insertDataLog({ action: "초기화" });
+
+// 수행 직원·변경 값 스냅샷까지 남기기
+await db.role().insertDataLog({
+  action: "수정",
+  itemId: role.id,
+  employeeId: ctx.employeeId,
+  valueJson: JSON.stringify(changed),
+});
+```
+
+`action` 문자열(`등록`/`수정`/`삭제`/`복구`/`초기화` 등)은 프로젝트 규약으로 통일. 조회 시 `includeActions`/`excludeActions` 가 이 문자열로 필터함.
+
+## 목록·단건에 최근/최초 변경 이력을 함께 표시하려면
+
+본 쿼리 체인에 `joinLastDataLog()`/`joinFirstDataLog()` 를 끼우면 각 행에 `lastDataLog`/`firstDataLog` 단건이 부착됨(없으면 `undefined`). 수행 직원명까지 한 쿼리로 조인됨.
+
+```ts
+const rows = await db
+  .role()
+  .where((p) => [expr.eq(p.id, role.id)])
+  .joinLastDataLog()   // 최신 변경 1건 → 행.lastDataLog
+  .joinFirstDataLog()  // 최초 변경 1건 → 행.firstDataLog
+  .execute();
+
+rows[0].lastDataLog?.action;       // "삭제"
+rows[0].lastDataLog?.dateTime;     // DateTime
+rows[0].lastDataLog?.employeeName; // "홍길동" (employee 조인 결과)
+rows[0].firstDataLog?.action;      // "등록"
+```
+
+`tableName` + 행 `id` 로 격리되므로 다른 모델의 같은 `itemId` 이력은 섞이지 않음. "최종 수정자/일시", "최초 등록자/일시" 컬럼은 별도 컬럼을 두지 말고 이 조인 결과로 표시.
+
+## 표시 대상 변경 유형을 한정·제외하려면
+
+`includeActions`/`excludeActions` 로 어떤 `action` 만 최근/최초로 칠지 조절.
+
+```ts
+// "등록"·"수정"만 대상 → "삭제" 가 최신이어도 제외하고 "수정" 이 lastDataLog
+.joinLastDataLog({ includeActions: ["등록", "수정"] })
+
+// "삭제" 만 빼고 최신 → "최종 수정 일시" 컬럼에 적합
+.joinLastDataLog({ excludeActions: ["삭제"] })
+```
+
+## 지킬 것
+
+- 모델 변경을 적재할 땐 변경을 수행한 그 모델의 queryable 에서 `insertDataLog` 호출. `db.dataLog().insert(...)` 로 `tableName` 을 손으로 적지 않음(자동 도출이 깨짐).
+- "최종 수정자/일시"·"최초 등록자/일시" 는 대상 테이블에 별도 컬럼을 추가하지 말고 `joinLastDataLog`/`joinFirstDataLog` 조인으로 표시.
+- 적재와 본 데이터 변경은 같은 트랜잭션 안에서 수행 — 이력만 남고 데이터가 롤백되거나 그 반대가 되지 않게 함.
+- `action` 문자열은 프로젝트 단위로 고정된 집합을 쓰고, 조회 측 `includeActions`/`excludeActions` 와 철자를 일치시킴.

package/claude/references/sd-simplysm14/manuals/event.md

@@ -0,0 +1,135 @@
+# 서비스 이벤트 매뉴얼
+
+클라이언트끼리(또는 서버 → 클라이언트로) 실시간 알림을 주고받으려 할 때 참조. 예: 한 사용자가 주문 상태를 바꾸면 같은 화면을 보는 다른 사용자에게 즉시 반영.
+
+`@simplysm/service-common` 의 `defineEvent` 로 이벤트를 정의하고, `ServiceClient`(`@simplysm/service-client`) 또는 서버 `ServiceContext` 로 발생·구독함. WebSocket 위에서 동작하므로 연결된 클라이언트에만 전달됨.
+
+흐름:
+
+```
+[발생측]  client.emitEvent(EventDef, selector, data)   ← 클라이언트 (가장 흔함)
+          ctx.server.emitEvent(EventDef, selector, data)  ← 서버
+              │
+              ▼  서버가 selector 로 대상 구독을 추려 라우팅
+[구독측]  client.getEvent(EventDef).addListener(info, cb) 로 등록한 콜백 실행
+```
+
+- **구독(리스너 등록)은 클라이언트에만 있음**. 서버는 발생만 가능(구독 불가).
+- **발생은 클라이언트·서버 양쪽 가능**. 화면 동작에서 비롯되는 변경 알림이 대부분이라 클라이언트 발생이 더 흔함.
+
+## 이벤트를 정의하려면
+
+`defineEvent<TInfo, TData>(eventName)` 로 정의해 **공통 패키지(`@<workspace>/common`)에서 export**. 발생측·구독측이 같은 정의 객체를 값으로 import 하므로, 서버·클라이언트 양쪽에서 import 가능한 공통 패키지에 둠.
+
+```ts
+// @<workspace>/common 의 events.ts
+import { defineEvent } from "@simplysm/service-common";
+
+export const OrderStatusChangedEvent = defineEvent<
+  { warehouseId: number }, // TInfo: 구독·필터 기준 메타데이터
+  { orderId: number; status: string } // TData: 전달 페이로드
+>("OrderStatusChanged");
+```
+
+- 두 제네릭의 의미:
+  - `TInfo` — 구독자가 "무엇을 구독하는지" 식별하는 메타데이터. 발생측이 이 값으로 대상을 골라냄.
+  - `TData` — 이벤트가 실어 나르는 페이로드.
+- 인자 `eventName` 은 라우팅 키. 같은 이름이면 같은 이벤트로 취급되므로 앱 내에서 고유하게.
+- **이름·타입의 단일 소스는 이 정의 객체**. 발생·구독 호출 시 정의 객체를 그대로 첫 인자로 넘기면 이름과 타입이 자동 추론됨 — 문자열 이름이나 `<typeof X>` 를 따로 적지 않음.
+
+## 클라이언트에서 이벤트를 구독하려면
+
+`client.getEvent(EventDef)` 로 프록시를 얻어 `addListener(info, cb)` 를 호출. 반환된 키는 해제에 사용하므로 보관.
+
+```ts
+const event = client.getEvent(OrderStatusChangedEvent);
+
+const listenerKey = await event.addListener(
+  { warehouseId: 7 }, // info: 이 구독이 받을 범위
+  async (data) => {
+    // data 는 { orderId, status } 로 타입 추론됨
+    await this.reload();
+  },
+);
+```
+
+- `info` 는 정의의 `TInfo` 타입. 발생측의 selector 가 이 값을 보고 전달 여부를 결정(아래 "특정 구독자에게만").
+- 콜백의 `data` 는 정의의 `TData` 로 타입이 잡힘.
+- `addListener` 는 연결이 끊긴 상태에서 호출하면 throw(`서버에 연결되지 않았습니다.`). 부트스트랩의 `connectAsync()` 이후에 등록.
+- AppServiceProvider 에서 이벤트 프록시를 getter 로 노출하는 패턴은 [client-service.md](./client-service.md) 참조.
+
+## 구독을 해제하려면
+
+등록 때 받은 키로 `removeListener` 호출. 화면 컴포넌트면 파기 시점에 해제.
+
+```ts
+await client.removeListener(listenerKey);
+```
+
+- 키 없이 일괄 해제하는 API 는 없음. 등록 시 받은 키를 화면·프로바이더 상태로 들고 있다가 해제.
+
+## 클라이언트에서 이벤트를 발생시키려면
+
+화면 동작으로 생긴 변경을 다른 클라이언트에 알리는 가장 흔한 경우. `client.emitEvent(EventDef, infoSelector, data)` 호출. 프록시의 `.emit()` 도 동일.
+
+```ts
+// 7번 창고를 구독 중인 클라이언트에게만 전달
+await client.emitEvent(
+  OrderStatusChangedEvent,
+  (info) => info.warehouseId === 7,
+  { orderId: 1024, status: "shipped" },
+);
+
+// 프록시 형태
+await client.getEvent(OrderStatusChangedEvent).emit(
+  (info) => info.warehouseId === 7,
+  { orderId: 1024, status: "shipped" },
+);
+```
+
+- `infoSelector` 는 각 구독의 `info` 를 받아 전달 대상인지 판정하는 함수.
+- 자기 자신이 같은 이벤트를 구독 중이고 selector 에 걸리면 자신의 콜백도 실행됨.
+
+## 서버에서 이벤트를 발생시키려면
+
+서버 측 처리(예: 외부 시스템 연동 결과 반영)에서 알릴 때. 서비스 메서드의 `ctx.server` 로 발생.
+
+```ts
+export const OrderService = defineService("Order", (ctx) => ({
+  ship: async (orderId: number) => {
+    // ... 처리 ...
+    await ctx.server.emitEvent(
+      OrderStatusChangedEvent,
+      (info) => info.warehouseId === 7,
+      { orderId, status: "shipped" },
+    );
+  },
+}));
+```
+
+- 발생 시그니처는 클라이언트와 동일(`emitEvent(EventDef, infoSelector, data)`).
+- `defineService` / `ServiceContext` 의 전반은 서버 패키지 작성 시 참조.
+
+## 특정 구독자에게만 전달하려면
+
+이벤트는 구독자의 `info` 와 발생측의 `infoSelector` 매칭으로 대상을 좁힘. 같은 이벤트라도 selector 가 `true` 를 돌려준 구독만 콜백을 받음.
+
+```ts
+// 구독: 자신이 보는 창고를 info 로 등록
+await event.addListener({ warehouseId: 7 }, cb7);
+await event.addListener({ warehouseId: 9 }, cb9);
+
+// 발생: warehouseId === 7 인 구독만 전달 → cb7 만 실행, cb9 는 무시
+await client.emitEvent(OrderStatusChangedEvent, (info) => info.warehouseId === 7, data);
+```
+
+- 전체에게 보내려면 `() => true` 를 selector 로.
+- selector 가 어떤 구독에도 걸리지 않으면 아무 콜백도 실행되지 않음(전송 자체가 생략됨).
+
+## 지킬 것
+
+- 이벤트 정의는 공통 패키지에 두고 정의 객체를 그대로 발생·구독에 넘김. 발생·구독 호출부에 이벤트 이름 문자열이나 `<typeof X>` 제네릭을 중복으로 적지 않음.
+- 구독은 클라이언트에서만. 서버는 발생 전용이며 `addListener` 가 없음 — 서버가 다른 서버 동작을 기다려야 한다면 이벤트가 아닌 다른 수단을 사용.
+- `addListener` 로 받은 키는 반드시 보관하고 화면·프로바이더 파기 시 `removeListener` 로 해제. 미해제 리스너는 재연결 때마다 누적됨.
+- 재연결 시 등록된 리스너는 자동으로 재구독되므로, 연결 복구를 감지해 수동으로 다시 `addListener` 하지 않음.
+- 전달은 그 시점에 연결된 클라이언트에만 일어남. 오프라인 클라이언트를 위한 보관·재전송은 없으므로, 놓치면 안 되는 상태는 이벤트가 아니라 조회(재로딩)로 확정.

package/claude/sd-system-prompt.md

@@ -11,8 +11,12 @@
 - `/<skill-name>` (예: `/commit`) 은 사용자가 사용자 호출 가능 스킬을 부르는 단축어. 실행되면 전체 프롬프트로 확장됨. 이를 실행하려면 Skill 도구 사용.
 - Skill 도구는 사용자 호출 가능 스킬 섹션에 나열된 스킬에만 사용. 추측하거나 내장 CLI 명령에 사용하지 말 것.
 - Agent 도구(서브에이전트 호출)는 단계지침상 명시되어 있거나, 사용자가 명시적으로 지시한 경우에만 사용. 그 외에는 Grep·Read·Glob 등 기본 도구로 직접 처리.
-- 도구 호출이 에러를 반환하면 멈추고 에러 메시지부터 원인을 규명. 원인 규명 전에 같은 목적을 수단만 바꿔 재시도하지 말 것.
-- Read, Grep, Read, Glob 등의 도구로 수행할 일을 PowerShell 도구로 수행하지 말것.
+- 도구 호출이 에러를 반환하면 멈추고 에러 메시지부터 원인을 규명. 다음은 원인 규명 전에 하면 안 되는 회피 행위:
+    - 같은 목적을 수단만 바꿔 재시도 — 금지.
+    - 그 호출을 건너뛰기·결과를 '무해·무관'으로 단정해 넘기기 — 금지.
+    - 미검증 추측(예: '샌드박스가 막음')을 원인으로 단정 — 금지.
+  - 원인 규명을 마친 뒤에 건너뛸지·보고할지·재시도할지 판단.
+- **IMPORTANT**: Read, Grep, Read, Glob 등의 도구로 수행할 일을 PowerShell 도구로 수행하지 말것. 
 
 # 행동 규칙
 
@@ -139,17 +143,12 @@ X 함수에 캐시 도입 검토 중. 기존 의존성 확인 결과 lru-cache
 - 나쁜 예: 30줄 제안 "맞나요?" → 한 줄만 "아님" → 그 줄만 고쳐 나머지 확정으로 진행.
 - 좋은 예: → 정정 반영해 전체 다시 제시 → "이렇게 수정함, 맞나요?".
 
-## 다단계 지침 진행 시
-
-지침상 여러 단계가 정의되어 있고, 단계 진행에 대한 사용자 확인을 받으라는 명시가 없는 경우 → 단계 산출물 보고 후 자동으로 다음 단계 진행. 단계 사이에 "다음 단계 진행할까요?"·"계속할까요?" 류 트리거 위임 질문 생성 금지.
-
-- "지침" = 스킬·룰·사용자 발언으로 부여된 다단계 절차 일체.
-- "사용자 확인 명시" = 지침 본문에 단계 게이트("단계 산출 후 확인"·"각 단계마다 합의" 등) 가 적혀 있는 경우.
-- 명시 있는 지점에서만 확인 질문. 그 외 단계 전환은 자동.
-
 ## 문제 발생 시
 
-**적용 조건**: [사용자 발언 의도 파악](#사용자-발언-의도-파악) 의 "의문·요청 (원인·방법·가능성)" 또는 "문제 기술·현상 보고" 의도로 분류된 경우.
+**적용 조건**: 다음 중 하나.
+
+- [사용자 발언 의도 파악](#사용자-발언-의도-파악) 의 "의문·요청 (원인·방법·가능성)" 또는 "문제 기술·현상 보고" 의도로 분류된 경우.
+- 에이전트가 실행 중 마주친 실패 — 도구 에러, 테스트·빌드·lint·typecheck·check 실패, 예상과 다른 런타임 결과 등. 수단만 바꾼 재시도 전에 본 워크플로 적용 (시스템 섹션의 "도구 호출이 에러를 반환하면 멈추고..." 항목과 연동).
 
 **근본 원인 우선**:
 
@@ -199,7 +198,7 @@ X 함수에 캐시 도입 검토 중. 기존 의존성 확인 결과 lru-cache
 | ---------------------------- | ----------------------------------------- | ---------------------------- | ------------------------------------------- |
 | 명령·승인                    | "고쳐줘", "응 그렇게", "적용해"           | "해줘", "응", "ㅇㅇ", "진행" | 도구 호출 (실행)                            |
 | 의문·요청 (원인·방법·가능성) | "왜 ~?", "어떻게 ~안될까?", "~방법 있어?" | "왜", "어떻게", "?"          | [문제 발생 시](#문제-발생-시) 워크플로 따름 |
-| 제안·아이디어                | "X 하면 어때?", "Y 가 좋을듯"             | "어때", "좋을듯", "할까?"    | 텍스트 응답 (검토·대안 제시) → 합의 후 실행 |
+| 제안·아이디어                | "X 하면 어때?", "Y 가 좋을듯", "X 할 생각을 해", "X 검토해봐" | "어때", "좋을듯", "할까?", "생각을 해", "검토해봐", "고려해" | 텍스트 응답 (검토·대안 제시) → 합의 후 실행 |
 | 문제 기술·현상 보고          | "이거 안돼", "버그 있어"                  | "안돼", "버그"               | [문제 발생 시](#문제-발생-시) 워크플로 따름 |
 | 위치·맥락 정보 단독          | "X 파일에..", "Y 섹션쪽에.."              | "X에", "Y쪽에"               | 의도 확인 질문 또는 다음 발언 대기          |
 
@@ -224,11 +223,14 @@ X 함수에 캐시 도입 검토 중. 기존 의존성 확인 결과 lru-cache
 ### 어휘·태도
 
 - 한국어 원어민 수준으로 자연스럽게 응답.
-- 통용 표현 우선. LLM이 자체 조합한 신조어·합성어 사용 금지 — 사람들이 흔히 쓰는 단어로.
+- 통용 표현 우선. 단, 구어·속어·비속어는 통용되더라도 금지 (예: "퉁치다"→"대신하다"). LLM이 자체 조합한 신조어·합성어도 금지 — 글에서 흔히 쓰는 단어로.
 - 직설적이고 솔직하게 응답. 형식어·완곡어·균형형 응답 금지.
 - 결론·답·핵심 먼저, 근거·맥락·세부는 그 다음 (두괄식).
     - 나쁜 예: "X 는 ~한 특성이 있어 ~합니다. 따라서 추천."
     - 좋은 예: "X 추천. 이유: ~한 특성이 있어 ~함."
+- 교정·치환된 값은 결과값만 적음. 폐기된 이전 값이나 그 부정형(`~아님`·`~말고`)은 그 부정 자체가 독자에게 필요한 정보(알려진 함정·금지 사항 등)일 때만 적음. 대화에서 받은 교정 대비를 산출물 본문으로 옮기지 말 것.
+    - 나쁜 예: "B" 로 교정받음 → 문서에 "B (A 아님)" 기재.
+    - 좋은 예: "B" 로 교정받음 → 문서에 "B" 만 기재.
 - 의견 요청 시 권장/비권장 명시. "어느 쪽도 가능" 식 회피 금지.
 - 불확실은 얼버무리지 말고 명시.
     - 나쁜 예: "아마 X일 것 같습니다"
@@ -261,8 +263,7 @@ X 함수에 캐시 도입 검토 중. 기존 의존성 확인 결과 lru-cache
 
 다이어그램, 구성도, 와이어프레임 등.
 
-- 이모지(✏ ☐ ❌ ⭐ ♥ 등) 금지: 렌더러별 1칸·2칸 변동되어 정렬이 깨짐.
-- 그 외 폭 안정 문자 허용.
+- 폭: 한글 등 전각 문자는 2칸, 그 외(영문·숫자·ASCII 기호·이모지)는 1칸. 이 폭으로 정렬.
 
 ## LLM용 문서 (CLAUDE.md, Skill, Rule 등) 작성 시
 
@@ -272,6 +273,19 @@ X 함수에 캐시 도입 검토 중. 기존 의존성 확인 결과 lru-cache
 - 표준 용어로 통할 내용을 풀어쓰지 말 것.
 - 예시는 LLM 패턴 식별에 필요한 만큼 활용 (좋은/나쁜 예시 쌍 권장). 흔한 도메인(예: 재고관리)으로.
 
+**최소 분량**:
+
+- 의도 전달에 필요한 최소 분량으로 작성. 한두 줄로 끝나는 지침에 정의·안티패턴·완료기준 등 부속 블록을 덧붙이지 말 것.
+- 부속 블록은 그게 없으면 LLM이 실제로 오작동하는 경우에만 추가.
+
+**근거 없는 서술 금지** (IMPORTANT):
+
+- LLM 문서에 적는 모든 서술(규칙·사실·동작 설명·설정값 등)은 [결정 근거](#결정-근거)에 기반. 미검증 사항을 단정형으로 적지 말 것.
+- 적기 전 근거 확보 우선: 코드·공식 문서·기존 패턴 직접 확인 → 확보되면 그대로 서술.
+- 확보 불가 → 사용자에게 확인 후 서술. 확인 절차 없이 추측을 사실처럼 적는 것 금지.
+- 나쁜 예: 동작 미확인 상태로 "X 옵션은 Y 로 동작함" 단정 서술.
+- 좋은 예: 코드·문서로 확인 후 서술, 또는 "추정(근거 미확인: <항목>)" 으로 불확실성 명시.
+
 **Convention 확정 금지**:
 
 - 사용자 피드백을 글자 그대로 문서화하지 말 것.

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

@@ -1,11 +1,11 @@
 ---
 name: sd-impl
-description: spec.md 의 단위(§4.x 화면 / §5.x 자동 처리 / §6.x 횡단 처리) 1개를 현재 코드베이스 상태와 비교해 차이만큼 풀 구현(테스트·시연 포함). Use when "화면 풀 구현", "데모를 실 구현으로", "화면 실가동", "자동 처리 풀 구현", "횡단 처리 풀 구현" 을 요청할 때.
+description: spec.md 의 단위(§4.x 화면 / §5.x 자동 처리 / §6.x 공통·기반 기능) 1개를 현재 코드베이스 상태와 비교해 차이만큼 풀 구현(테스트·시연 포함). Use when "화면 풀 구현", "데모를 실 구현으로", "화면 실가동", "자동 처리 풀 구현", "공통·기반 기능 풀 구현" 을 요청할 때.
 ---
 
 # sd-impl
 
-spec.md 단위(§4.x 화면 / §5.x 자동 처리 / §6.x 횡단 처리) 1개를 현재 코드베이스 상태와 비교해 빠지거나 어긋난 부분만큼 풀 구현. 데모 골격이 있으면 보존. 끝에 사용자 시연으로 회귀 점검.
+spec.md 단위(§4.x 화면 / §5.x 자동 처리 / §6.x 공통·기반 기능) 1개를 현재 코드베이스 상태와 비교해 빠지거나 어긋난 부분만큼 풀 구현. 데모 골격이 있으면 보존. 끝에 사용자 시연으로 회귀 점검.
 
 호출 시나리오 2종 — 동일 워크플로:
 
@@ -17,6 +17,7 @@ spec.md 단위(§4.x 화면 / §5.x 자동 처리 / §6.x 횡단 처리) 1개를
 워크플로 전 단계 적용:
 
 - **임의 채움 금지**: spec 본문에 명시가 없거나 모호한 분기를 발견하면 즉시 멈추고 사용자에게 질문. 자체 판단으로 채우지 않음.
+- **YAGNI**: spec 에 없는 기능·옵션·추상화·방어코드 추가 금지. 필요해질 때까지 만들지 않음 (작성 시점부터 적용).
 - **사용자 보고 어휘**: 사용자에게 보고하는 본문에 코드 식별자(변수명·SQL 함수명·타입 키워드 등) 노출 금지. 도메인 어휘로 풀어 보고.
 
 ## 워크플로
@@ -24,9 +25,9 @@ spec.md 단위(§4.x 화면 / §5.x 자동 처리 / §6.x 횡단 처리) 1개를
 ### 1단계: 입력 확보
 
 - 대상 spec.md 경로.
-- 구현할 단위 식별자 — `§4.x` (화면) / `§5.x` (자동 처리) / `§6.x` (횡단 처리).
+- 구현할 단위 식별자 — `§4.x` (화면) / `§5.x` (자동 처리) / `§6.x` (공통·기반 기능).
 
-없으면 묻기. spec.md 에서 식별자 매칭이 안 되면 §4 화면 목록 표 / §5 자동 처리 / §6 횡단 처리 헤더 목록에서 후보를 제시 후 확정.
+없으면 묻기. spec.md 에서 식별자 매칭이 안 되면 §4 화면 목록 표 / §5 자동 처리 / §6 공통·기반 기능 헤더 목록에서 후보를 제시 후 확정.
 
 ### 2단계: 외부 입력 점검
 
@@ -64,11 +65,11 @@ spec 본문 수정이 필요한 경우(인라인 `[OPEN]` 해소·헤더 `[OPEN]
 
 **4계층**:
 
-| 계층        | §4.x (화면)   | §5.x (자동 처리)        | §6.x (횡단 처리)               |
+| 계층        | §4.x (화면)   | §5.x (자동 처리)        | §6.x (공통·기반 기능)          |
 | ----------- | ------------- | ----------------------- | ------------------------------ |
 | 도메인 모델 | 엔티티·필드   | 동일                    | 동일                           |
 | 데이터 접근 | 쿼리·서비스   | 동일                    | 동일                           |
-| 본체        | 화면 컴포넌트 | 자동 처리 로직 + 트리거 | 횡단 처리 로직 + 부수효과 후크 |
+| 본체        | 화면 컴포넌트 | 자동 처리 로직 + 트리거 | 부수효과 후크 또는 설정·부트스트랩 구성 |
 | 테스트      | 단위 테스트   | 동일                    | 동일                           |
 
 **기준 단위 선정** (같은 종류 §4.x↔§4.x, §5.x↔§5.x, §6.x↔§6.x 안에서):
@@ -138,11 +139,17 @@ spec 본문 수정이 필요한 경우(인라인 `[OPEN]` 해소·헤더 `[OPEN]
 | 테스트 가능        | 도메인 로직·계산·변환·서버 함수·데이터 접근   | RED → GREEN → REFACTOR |
 | 테스트 불가·비효율 | UI 시각·인터랙션·외부 서비스 실호출·환경 의존 | 구현 → REFACTOR        |
 
+**테스트 단위 = spec 이 요구한 산출 단위. 내부 구현을 쪼개지 말 것**:
+
+- 위 "테스트 가능" 분류는 그 처리가 **spec 이 독립 산출물로 요구한 단위**(공개 함수·API·계약)일 때 적용 — 그 경우 그 단위를 그대로 테스트.
+- 요구사항이 "동작"(화면·자동 처리·공통·기반 기능·초기화 등)이고 변환·매핑·계산이 그 동작의 **내부 구현 조각**일 뿐이면, 동작 전체를 테스트 단위로 봄. 동작이 통째로 테스트 가능하면 그 단위로, 아니면(외부 I/O·환경 의존) "테스트 불가·비효율" 로 분류.
+- **내부 구현 조각을 테스트하려고 별도 함수·파일·인터페이스로 분리·추상화하지 말 것.** spec 이 그 조각을 산출물로 요구하지 않았다면, 테스트는 그 조각을 떼낼 이유가 되지 못함.
+
 **사이클 단계 정의**:
 
 - **RED**: 테스트만 작성 → 러너 실행 → 실패 확인. **구현 파일은 손대지 않음.**
 - **GREEN**: 테스트를 통과하는 **최소** 구현 → 러너 통과 확인.
-- **REFACTOR**: 중복·가독성·기존 패턴 정합 정리 → 러너 통과 유지. 정리할 것이 없으면 스킵.
+- **REFACTOR**: 중복·가독성·기존 패턴 정합 정리 → 러너 통과 유지.
 
 작업 사이클 중 spec 미정의·모호 분기를 만나면 2단계로 회귀.
 
@@ -225,8 +232,6 @@ subagent 출력을 받은 후 분류별로 처리:
 
 ### 7단계: 코드 정리
 
-spec 에 없는 기능·옵션·추상화 추가 금지 (YAGNI 원칙: 필요해질 때까지 만들지 않음).
-
 - **횡단 중복**: 작업 사이클 사이에 흩어진 동일 로직 합치기.
 - **계층별 정합 점검**: 3-B 의 기준 단위 + 보강 출처 파일을 다시 Read 하여 4계층별로 실제 작성분과 비교. 한 계층이라도 채택 패턴과 어긋나면(임의 변형·새 발명) 수정.
   - 도메인 모델: 필드·타입·제약·네이밍 패턴 일치.
@@ -249,7 +254,7 @@ spec 에 없는 기능·옵션·추상화 추가 금지 (YAGNI 원칙: 필요해
 - 기능 개요·동작의 사용자 흐름을 1회씩 수행.
 - 화면 항목·와이어프레임 위치와 실제 렌더 결과를 비교.
 - §5.x (자동 처리) 는 트리거 발생 → 결과 확인.
-- §6.x (횡단 처리) 는 부수효과 트리거 동작 발동 → 결과·기록 확인.
+- §6.x (공통·기반 기능): 부수효과 동작은 트리거 발동 → 결과·기록 확인, 상시 구성은 앱 부팅 후 구성 반영 확인.
 
 회귀 발견 시 5단계로 회귀 → 수정 → 재시연.
 

package/claude/skills/sd-impl/evals/fixtures/case-a-new-screen/.specs/260513120000_warehouse/spec.md

@@ -75,7 +75,7 @@ Actor: 창고 작업자
 
 ## 5. 자동 처리
 
-## 6. 횡단 처리
+## 6. 공통·기반 기능
 
 ## 7. 공통 정의
 

package/claude/skills/sd-impl/evals/fixtures/case-b-update-with-demo/.specs/260513120000_warehouse/spec.md

@@ -75,7 +75,7 @@ Actor: 창고 작업자
 
 ## 5. 자동 처리
 
-## 6. 횡단 처리
+## 6. 공통·기반 기능
 
 ## 7. 공통 정의
 

package/claude/skills/sd-impl/evals/fixtures/case-c-new-cross/.specs/260513120000_warehouse/spec.md

@@ -38,13 +38,13 @@
 
 모든 도메인 모델 변경분을 변경 로그에 기록. 감사·복구 목적.
 
-관련 섹션: [횡단 처리.데이터 변경 로그]
+관련 섹션: [기반.데이터 변경 로그]
 
 ## 4. 화면
 
 ## 5. 자동 처리
 
-## 6. 횡단 처리
+## 6. 공통·기반 기능
 
 ### 6.1 데이터 변경 로그 [확정: 2026-05-20]
 

package/claude/skills/sd-impl/evals/fixtures/case-d-spec-modify/.specs/260513120000_warehouse/spec.md

@@ -75,7 +75,7 @@ Actor: 창고 작업자
 
 ## 5. 자동 처리
 
-## 6. 횡단 처리
+## 6. 공통·기반 기능
 
 ## 7. 공통 정의
 

package/claude/skills/sd-impl/evals/golden.jsonl

@@ -1,4 +1,4 @@
 {"id": "case-a-new-screen", "input": ".specs/260513120000_warehouse/spec.md §4.1 화면 풀 구현해줘. eval 환경 단축 모드: 단위 테스트 핵심 1건만, 6단계 subagent 대조·7단계 코드 정리·REFACTOR·dev 시연 스킵.", "rubric": ["fixture 의 spec.md 파일이 워크스페이스에 보존되었는가", "워크스페이스 spec.md 의 §4.1 헤더에 [확정: YYYY-MM-DD, 구현: YYYY-MM-DD] 형식 마커가 부착되었는가", "워크스페이스에 §4.1 화면 본체에 해당하는 코드 파일이 1개 이상 생성되었는가 (예: 박스 등록 화면 컴포넌트)", "assistant 응답에 spec 분해 표가 마크다운 표 형식(파이프 구분, 헤더 행 포함)으로 출력되었는가"], "fixture": "case-a-new-screen"}
 {"id": "case-b-update-with-demo", "input": ".specs/260513120000_warehouse/spec.md §4.1 데모를 실 구현으로 전환해줘. eval 환경 단축 모드: 단위 테스트 핵심 1건만, 6단계 subagent 대조·7단계 코드 정리·REFACTOR·dev 시연 스킵.", "rubric": ["fixture 의 데모 골격 파일(packages/app/src/screens/box-register/box-register.view.ts)이 워크스페이스에 보존되었는가 (삭제되지 않았는가)", "워크스페이스 spec.md 의 §4.1 헤더에 [확정: YYYY-MM-DD, 구현: YYYY-MM-DD] 형식 마커가 부착되었는가", "워크스페이스에 데모 골격 외의 코드 파일(데이터 접근 또는 단위 테스트 계층)이 1개 이상 추가되었는가", "assistant 응답에 spec 분해 표가 마크다운 표 형식(파이프 구분, 헤더 행 포함)으로 출력되었는가"], "fixture": "case-b-update-with-demo"}
-{"id": "case-c-new-cross", "input": ".specs/260513120000_warehouse/spec.md §6.1 횡단 처리 풀 구현해줘. eval 환경 단축 모드: 단위 테스트 핵심 1건만, 6단계 subagent 대조·7단계 코드 정리·REFACTOR·dev 시연 스킵.", "rubric": ["워크스페이스에 §6.1 횡단 처리 본체(부수효과 후크 또는 처리 로직)에 해당하는 코드 파일이 1개 이상 생성되었는가", "워크스페이스 spec.md 의 §6.1 헤더에 [확정: YYYY-MM-DD, 구현: YYYY-MM-DD] 형식 마커가 부착되었는가", "assistant 응답에 spec 분해 표가 마크다운 표 형식(파이프 구분, 헤더 행 포함)으로 출력되었는가"], "fixture": "case-c-new-cross"}
+{"id": "case-c-new-cross", "input": ".specs/260513120000_warehouse/spec.md §6.1 공통·기반 기능 풀 구현해줘. eval 환경 단축 모드: 단위 테스트 핵심 1건만, 6단계 subagent 대조·7단계 코드 정리·REFACTOR·dev 시연 스킵.", "rubric": ["워크스페이스에 §6.1 공통·기반 기능 본체(부수효과 후크 또는 처리 로직)에 해당하는 코드 파일이 1개 이상 생성되었는가", "워크스페이스 spec.md 의 §6.1 헤더에 [확정: YYYY-MM-DD, 구현: YYYY-MM-DD] 형식 마커가 부착되었는가", "assistant 응답에 spec 분해 표가 마크다운 표 형식(파이프 구분, 헤더 행 포함)으로 출력되었는가"], "fixture": "case-c-new-cross"}
 {"id": "case-d-spec-modify", "input": ".specs/260513120000_warehouse/spec.md §4.1 화면 풀 구현해줘. §8.1 의 인라인 [OPEN] 마커는 만나는 즉시 결정해서 spec.md 를 직접 수정하고 진행해줘. eval 환경 단축 모드: 단위 테스트 핵심 1건만, 6단계 subagent 대조·7단계 코드 정리·REFACTOR·dev 시연 스킵.", "rubric": ["fixture spec.md 안의 인라인 [OPEN] 마커가 워크스페이스 spec.md 의 §8.1 본문에서 제거 또는 결정 내용으로 치환되었는가 ('[OPEN]' 문자열이 §8.1 본문에 더 이상 존재하지 않는가)", "워크스페이스 spec.md 의 §4.1 헤더에 [확정: YYYY-MM-DD, 구현: YYYY-MM-DD] 형식 마커가 부착되었는가", "events 에 sd-spec 룰 자료(.claude/skills/sd-spec/SKILL.md 또는 동등 자료) 읽기 흔적(Read·Bash cat 등 동등 명령)이 1회 이상 있는가", "워크스페이스에 §4.1 화면 본체에 해당하는 코드 파일이 1개 이상 생성되었는가"], "fixture": "case-d-spec-modify"}

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

@@ -0,0 +1,51 @@
+---
+name: sd-manual
+description: `.claude/references/sd-simplysm14/manuals/` 에 주제 단위 목적 기반 개발 매뉴얼(how-to)을 작성·갱신. Use when 라이브러리·프레임워크 사용법을 "~하려면 ~한다" 식 매뉴얼로 새로 쓰거나 코드 변경을 반영해 갱신할 때.
+---
+
+# sd-manual
+
+독자(주로 코드 작업 중인 에이전트)가 어떤 작업을 하려 할 때 그 작업을 올바르게 수행하는 방법을 빠르게 얻도록, 주제 단위 목적 기반 매뉴얼을 작성·갱신.
+
+좋은 매뉴얼의 두 본질 축:
+
+- **축1 — 작업 목적 단위로 조직**: 독자는 "내가 무엇을 하려는지" 로 찾음. 매뉴얼은 "~하려면 ~한다" 구성이어야 하며, 구현 내부 동작을 설명 단위로 삼지 않음.
+- **축2 — 방법이 실제 동작과 일치**: 적은 방법이 코드의 실제 결과와 맞아야 함. 검증 기준은 **독자가 관찰하는 최종 결과**(화면·실제 동작)이며, 함수 내부 반환값이 아님.
+
+## 산출물
+
+- `.claude/references/sd-simplysm14/manuals/<주제>.md` — 매뉴얼 본문.
+- `.claude/references/sd-simplysm14/README.md` 의 매뉴얼 인덱스 표 — 트리거 + 링크 1행.
+
+## 워크플로
+
+### 1. 대상·범위 확정
+
+- 매뉴얼 주제와 대상 코드 범위 파악.
+- 신규 작성인지, 기존 매뉴얼 갱신인지 판별. 갱신이면 기존 파일을 먼저 읽어 현재 구조를 파악.
+- 독자가 이 매뉴얼로 하려는 **작업들**(use case)을 식별.
+
+### 2. 작업 목적 분해 → 목차
+
+- 1단계에서 식별한 작업들을 목차로 변환. 각 섹션 = 하나의 작업 목적("~하려면 ~한다").
+- 함수·옵션을 나열하는 레퍼런스 구조나, 내부 동작을 설명하는 구조로 만들지 않음(축1).
+
+### 3. 수행법 조사 + 결과 추적
+
+- 각 작업의 수행법을 대상 코드를 직접 읽어 근거 위에 확정.
+- 그 방법이 독자가 관찰하는 **최종 결과**(화면·실제 동작)로 이어지는지 끝까지 추적해 확인. 함수 반환값만 보고 결과를 단정하지 않음(축2).
+- 갱신이면 코드 변경분이 어떤 작업 목적에 해당하는지 짚어 반영 위치를 정함.
+
+### 4. 작성 + 인덱스 등재
+
+- 기존 `manuals/*.md` 의 톤·구조를 답습: 목적 설명 → 작성법 + 코드 예시 → 지킬 것.
+- 신규: README 매뉴얼 인덱스 표에 트리거 + 링크 1행 추가.
+- 갱신: 기존 매뉴얼 파일과 인덱스 행을 보존한 채 변경분만 반영. 합의 없이 무관한 부분을 고치지 않음.
+
+### 5. 자가 검증 게이트
+
+출력 전 자문:
+
+- 각 섹션이 작업 목적("~하려면") 단위인가, 구현 동작 설명이 아닌가?
+- 각 서술이 독자가 관찰하는 최종 결과와 일치하는가(함수 반환값이 아니라)?
+- 기존 매뉴얼의 톤·구조와 일관되는가?