@simplysm/sd-claude 14.0.88 → 14.0.89

package/claude/skills/sd-spec/references/spec-authoring.md

@@ -0,0 +1,519 @@
+# spec.md 문서작성 매뉴얼
+
+`spec.md` 의 골격·섹션 구조·각 섹션 작성법·포함 내용 규정. 작업 절차(신규 작성·수정·합의 등)는 범위 밖 — 문서 형식·내용만 다룸 (절차는 SKILL.md).
+
+형식 모범: `example-spec.md` (WMS 예시 1건).
+
+## spec.md 형식
+
+### 섹션 구조
+
+spec.md 의 § 별 섹션 이름과 분류:
+
+| §   | 섹션             | 분류                         |
+| --- | ---------------- | ---------------------------- |
+| §1  | 개요             | 분석 명세                    |
+| §2  | 업무 프로세스    | 분석 분할/명세               |
+| §3  | 기타 요구사항    | 분석 분할/명세               |
+| §4  | 화면             | 설계 분할/명세               |
+| §5  | 자동 처리        | 설계 분할/명세               |
+| §6  | 공통·기반 기능   | 설계 분할/명세               |
+| §7  | 공통 정의        | 자연 도출                    |
+| §8  | 도메인 모델      | 자연 도출                    |
+| §9  | 외부 인터페이스  | 자연 도출                    |
+| §10 | 본문 외 확정 사항 | 메타 (결정이 발생할 때마다 누적) |
+
+### 마커
+
+#### 헤더 마커 (섹션 상태)
+
+섹션 헤더에 부착하는 마커:
+
+| 마커                                   | 의미                                                                                                                                                |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| (마커 없음)                            | 미확정. 사용자가 아직 검증하지 않은 섹션 — 신규 작성된 초안이거나 보류 중. 보류 사유·재분석 방법은 본문에 직접 기술. 근거 없는 항목은 인라인 `[OPEN]`.   |
+| `[확정: YYYY-MM-DD]`                   | 섹션 확정 (사용자 검토 완료). 본문에 인라인 `[OPEN]` 이 있어도 무방.                                                                                  |
+| `[확정: YYYY-MM-DD, 구현: YYYY-MM-DD]` | §4/§5/§6 에만 적용. `[확정]` 에 `구현: 날짜` 를 콤마로 결합. 구현·시연 검증 통과 시 부착. 본문이 변경되면 `, 구현: …` 부분만 제거 (구버전 구현 무효화). |
+
+대괄호 쌍 연이은 표기(`[확정: …][구현: …]`) 는 마크다운이 reference-style 링크로 해석함 → 단일 대괄호 안에 콤마로 결합하는 형식 사용.
+
+#### 본문 인라인 마커
+
+본문 안에서 사용하는 인라인 마커:
+
+| 마커     | 의미                                      |
+| -------- | ----------------------------------------- |
+| `[OPEN]` | 정보 부족·근거 없는 항목. 향후 확정 필요. |
+
+- 임의로 채우거나 누락하지 말고 `[OPEN]` 으로 표기.
+- 근거가 부족한 항목 (As-Is 만 근거인 항목 등) 은 근거 없음으로 보고 `[OPEN]` 으로 표기.
+- 헤더 `[확정]` + 본문 `[OPEN]` 조합은 OPEN 을 인정한 상태로 섹션을 확정. 이후에는 OPEN 항목만 처리.
+
+### 본문 내 참조 (이름 기반)
+
+본문 내에서 다른 섹션을 참조할 때 § 번호 대신 `[카테고리.이름]` 형식 사용. 다단 표기 가능. § 번호는 분석 중 자주 바뀌므로 이름 기반 표기가 더 안정적.
+
+예:
+- `[모델.재고]`·`[모델.박스.수량]`·`[모델.박스.품목.코드]`.
+- `[화면.재고 확인]`·`[프로세스.입고]`·`[기타.과거 재고 조회]`.
+- `[자동 처리.재고 스냅샷]`·`[기반.DataLog 기록]`·`[외부인터페이스.ERP 입고 통보]`·`[공통 정의.Location 라벨]`.
+
+**관련 섹션 한 줄**: §2~§9 본문에 `관련 섹션: [카테고리.이름], ...` 형식의 한 줄로 참조·의존 섹션을 콤마로 나열 (카테고리 제한 없음).
+
+### sub-section 헤더 레벨
+
+§별 sub-section 의 spec.md 본문 표기 룰 — 평문 (헤더 없이 라벨·한 줄·bullet 직접) / h4 마크다운 헤더 (`####`).
+
+| §  | 평문 sub-section (형식)                                       | h4 sub-section                                                       |
+| -- | ------------------------------------------------------------- | -------------------------------------------------------------------- |
+| §2 | BPMN (mermaid fence) · 흐름 설명 bullet · 관련 섹션 (한 줄)   | (없음)                                                               |
+| §4 | 헤더 인덱스 (한 줄씩) · 기능 개요 (라벨 + bullet)             | 와이어프레임 · 항목 · 동작 · 시각 규칙 · 도메인 규칙·로직 · 자유 추가 |
+| §5 | 목적 (라벨 + 한 줄) · 트리거 (라벨 + 본문) · 관련 섹션 (한 줄) | 처리 · 예외 처리 · 자유 추가                                         |
+| §6 | 목적 · 트리거·적용 범위 (해당) · 관련 섹션 · 참조 매뉴얼 (기본 기능) | (없음 — bespoke 만 본문 자유 서술, 필요 시 h4 자유 추가) |
+| §9 | 기본 정보 (라벨 bullet 3) · 관련 섹션 (한 줄)                 | 자료 매핑 · 예외 처리                                                |
+
+본 문서 내의 `#### 처리`·`#### 자료 매핑` 등의 표기는 작성법 설명용 sub-section 분류 표기. 실제 spec.md 본문에서의 표기는 위 표의 룰 따름.
+
+## §1 개요
+
+### §1.1 핵심 목적
+
+- 한 줄 동사형의 큰 단위로 작성.
+- 핵심 도메인 간 사이클·관계를 표현.
+- §2.x 의 동사구 항목 나열 금지 (해당 표현은 §1.2 의 역할).
+
+### §1.2 주요 목표
+
+- 단위: 최종 사용자의 업무 흐름 1건 (화면·기능 단위가 아님).
+- 표현: 한 줄 동사구. 최종 사용자 도메인 어휘 사용.
+- §2 업무 프로세스 헤더와 1:1 매핑되는 것이 일반적.
+- §2.x 본문의 핵심 항목은 한 줄에 모두 담아야 하며, 임의 축약·누락 금지.
+
+### §1.3 최종 사용자/이해관계자
+
+- 실제 담당자의 이름 사용 금지.
+- 역할로 일반화하여 표현.
+
+### §1.4 환경/장치
+
+구성도와 장치 목록은 목적이 별개이므로 각각 독립적으로 작성.
+
+- **ASCII 구성도**: 현장 물리 구성 시각화 — 이해당사자 간 그림 맞추기.
+  - 포함 대상: 솔루션 노드 (서버·DB·클라이언트) + 노드 간 연결선 + 물리 위치 그룹 (IDC·사무실·창고) + 자동 연동되는 외부 시스템.
+  - 제외 대상: Actor, 외부 관계자 (인적·조직), 수동 채널 (메일·종이), 구체 제품명 (MySQL)·통신 프로토콜 (HTTPS), 장치 사양 (OS·해상도).
+- **장치 목록**: 솔루션이 대상으로 하는 장치·환경 스펙 — 서버·DB·클라이언트 등. OS·버전·제품명·모델·해상도·하드웨어.
+  - 명시한 스펙에 맞게 개발하며, 그 외 스펙 환경에서의 동작은 책임 범위 외.
+
+## §2 업무 프로세스
+
+### 분할 단위 = BPMN end-to-end process
+
+§2.x 1건 = BPMN end-to-end process 1건 (= Value Stream L1). start event ~ end event 의 풀 사이클. 사이클 내부의 handoff (역할 전환·시간 지연·외부 채널·동일인의 다른 시점) 도 포함 — BPMN swim lane 또는 노드 분기로 표현. **handoff 는 §2.x 분리 사유가 아님**.
+
+- **start event** (BPMN 시작 트리거):
+  - Message — 외부 actor 의 메시지·자료가 도착 (구매처 발주·고객 주문·거래처 EDI).
+  - Timer — 시간이 도래 (세무 신고일·정산 마감일).
+  - Signal — 외부 조건 신호.
+- **end event** (BPMN 종결 outcome):
+  - 외부 가치 전달 또는 외부 자료 송신 (출하 완료·세금 제출·EDI 송신).
+- **분리 기준 = pivotal event**:
+  1. start event 가 별개 (입고 start ↔ 출고 start).
+  2. end event 가 별개.
+  3. 도메인 어휘 자체의 전환점 (DDD 경계).
+
+### 헤더 명칭
+
+- 외부 관계자 평면 기반의 도메인 업무 동사구 사용.
+- 시스템·문서·메뉴·양식의 명칭을 그대로 사용 금지.
+  - ❌ `발주서 변경 요청` (발주서 = 시스템 문서).
+  - ✅ `구매처 발주 변경 요청`.
+
+### 본문 구조
+
+sub-section 헤더 레벨은 `## spec.md 형식` 의 "sub-section 헤더 레벨" 표 참조.
+
+**평문 sub-section** (§2.x 헤더 바로 아래에 위→아래 순서로 작성):
+
+- **BPMN** (mermaid fence):
+  - 사용자에게 보여줄 때는 ASCII, 확정 후 mermaid 형식으로 저장.
+  - 노드 = 최종 사용자 액션 또는 시스템 핵심 트랜잭션 (1행 동사구). 줄바꿈 `<br/>` 사용 금지.
+  - Actor·장치·매체 (PDA·PC·종이) 는 액션 컨텍스트로 노드 안에 명시 허용 (예: `창고 작업자: PDA 박스 바코드 스캔`). OS·해상도·API·DB 등 시스템 내부 디테일은 제외.
+  - 외부 채널 송신 (메일·파일 다운로드) 과 외부 응답 수신 (다음 사이클 자료 도착) 도 노드로 표현. 처리 노드는 사각 (`T[...]`), 이벤트 노드는 둥근 (`E([...])`).
+  - 분기는 사용자의 의사결정 분기만 표현.
+- **흐름 설명 bullet** (BPMN 아래, 관련 섹션 위에 자유롭게 나열):
+  - 노드 동사구만으로는 표현되지 않는 룰·조건·계산식·외부 약속·자료 출처 인용 등을 한 줄씩 기재.
+  - §4/§5/§6 본문 작성 시 이 bullet 들을 근거로 매핑하여 누락 방지.
+  - 단, §4/§5/§6 자체의 디테일 (필드·UI·파일 확장자) 과 §7/§8/§9 의 정형 명세는 여기에 작성 금지 — 각 § 본문에서는 이름으로만 참조.
+- **관련 섹션** (`관련 섹션: [카테고리.이름], ...` 형식의 한 줄): "본문 내 참조" 절의 룰 따름.
+
+### 안티패턴 (구조)
+
+- ❌ 같은 사이클의 A→B→C 단계별로 담당자·산출물이 다르다는 이유로 §2.A·§2.B·§2.C 로 쪼개는 행위.
+- ❌ 메뉴 그룹·기존 화면 폴더·코드 As-Is 구조를 기준으로 묶거나 쪼개는 행위.
+
+## §3 기타 요구사항
+
+### 분할 단위 = Cockburn sea level use case
+
+- Cockburn 의 정의: "primary actor go away happy after having done this in a single sitting?".
+- 행위자가 1회 작업으로 끝내고 만족하여 떠나는 단일 user goal.
+- 사이클·handoff·지연이 없음.
+- 정형 분해 (화면 / 자동 처리 / 공통·기반 기능) 를 동반하는, 사용자의 직접 요구.
+- 시스템 전반 자동 룰 (예: "모든 데이터 수정 시 변경 이력 기록") 과 프레임워크 운영 기반 (앱 구조·접근 권한·부트스트랩 등) 도 §3 에 포함 — 그에 대한 설계는 §6 공통·기반 기능에서 수행.
+
+### 본문 구조
+
+- 요구 의도 (한 줄 또는 한 문단).
+- 관련 섹션 한 줄 ("본문 내 참조" 절 룰 따름).
+- 구현 디테일은 §4 화면 / §5 자동 처리 / §6 공통·기반 기능 본문에 작성.
+
+## §4 화면
+
+**모범** (와이어 패턴별 — example-spec.md 의 가장 가까운 화면 패턴 라인을 형식 모범으로 직접 참조):
+- 시트 화면: example-spec.md §4.1·§4.3.
+- 폼 모달: §4.2·§4.4.
+- PDA: §4.5.
+- 분석 시트: §4.6.
+
+### 화면 목록 표 (§4 첫머리)
+
+5컬럼 구조: `§ | 분류 | 화면 | 유형 | 장치`.
+
+- 분류: 도메인 묶음·메뉴 그룹의 자유 명칭 (예: `기준정보`·`입고`·`재고`).
+- 유형: 마스터 / 트랜잭션 / 조회 중 택1.
+- 장치: PC / PDA / 기타 중 택1.
+- 화면이 추가·제거되면 표도 함께 갱신. 같은 분류끼리 인접 배치.
+
+### 화면 정의 (§4.x 표준 구조)
+
+화면 헤더에 (장치) 표기를 유지: `### N.N 화면명 (PC) [확정: 날짜]` 또는 `(PDA)`.
+
+sub-section 헤더 레벨은 `## spec.md 형식` 의 "sub-section 헤더 레벨" 표 참조.
+
+**평문 sub-section** (§4.x 헤더 바로 아래에 위→아래 순서로 작성):
+
+- **헤더 인덱스** (한 줄씩 작성):
+  - `Actor: <역할>` — §2 BPMN 의 swim lane 또는 §3 의 사용자 직접 요구에서 자연 도출.
+  - `관련 섹션:` "본문 내 참조" 절 룰 따름 — 모달 호출·시트 영역 재활용 등 화면 간 의존 포함.
+- **기능 개요**: `기능 개요:` 라벨 다음에 bullet 로 화면 기능을 설명.
+
+**h4 sub-section** (평문 아래, 고정 순서, 위→아래):
+
+#### 와이어프레임 (텍스트)
+
+**형식 일탈 금지**: ASCII 박스 (┌─┐ │ └┘) ·영역 추상화 표기 (`<필터>`·`<시트>`·`<폼>` 등) ·액션 버튼 텍스트 표기를 임의로 변형 금지. example-spec.md 의 가장 가까운 화면 패턴 라인 (시트 §4.1·§4.3 / 폼 §4.2·§4.4 / PDA §4.5 / 분석 시트 §4.6) 을 직접 참조.
+
+**원칙**: 영역 배치·구획만 표현. 디테일 (필드·시트 컬럼·실제 값·아이콘 placeholder·fixed 경계·비활성 행 등 시각 표현) 은 와이어에 두지 않음 — 항목 표·동작 절·도메인 규칙 절이 단일 출처.
+
+- 데이터 영역: 영역 타입 + 짧은 라벨로 추상화 — `<필터>`·`<폼>`·`<시트>`·`<목록>`·`<PO 목록>`·`<라인 시트 - 작성영역>` 등. 영역 종류가 한눈에 잡히지 않으면 라벨을 보강.
+- 액션 버튼: 텍스트를 유지 (`[조회]`·`[저장]`·`[등록]`) — 버튼 위치 자체가 와이어가 전달하는 정보. 아이콘만 있는 버튼도 텍스트로 표기.
+- 영역 (좌/우 분할·탭·상단 command 바·시트 상단 버튼바) 으로 나뉠 경우 박스 라인으로 구획.
+- 상태 (작성중·확정 등) 에 따라 영역 구획이 크게 달라지면 상태별로 분리. 제목 형식: `와이어프레임 (<상태명>):` (예: `와이어프레임 (확정 전):`).
+
+#### 항목
+
+데이터 항목만 작성 (필터·시트 컬럼·입력 폼·상세 폼). 액션 버튼은 "동작" 절에 작성.
+
+- **표 제목 = 와이어의 영역 라벨과 동일 명칭** 을 굵게 표기 — 와이어의 `<필터>` → `**필터**`, `<품목 목록 시트>` → `**품목 목록 시트**`, `<스캔 입력 폼>` → `**스캔 입력 폼**`.
+- 한 영역에 종류가 다른 표가 여러 개 있을 경우 종류를 부기 — `**<영역 라벨> — <필터|시트 컬럼|입력 폼>**` (예: `**헤더 목록 — 필터**`, `**BOA 시트 — 시트 컬럼**`).
+- 시트 화면의 기본 구성: 상단 command 바의 `<필터>` + 시트 영역 (시트 컬럼) 총 2 그룹.
+
+**표 형식** — 도메인 매핑은 별도 컬럼으로 (필터는 시트 컬럼과 중복되므로 도메인 매핑 컬럼 없음):
+- 입력 폼: `항목 | 종류 | 필수 | 도메인 매핑 | 비고`.
+- 시트 컬럼: `컬럼 | 종류 | 필수 | 도메인 매핑 | 비고`.
+- 필터: `항목 | 종류 | 필수 | 비고`.
+
+- 필수 컬럼: 의미가 없는 경우 (조회 시트 컬럼 등) 는 `-`.
+- 도메인 매핑: `[모델.X.Y]` 형식 (양식 매핑과 일관). 매핑이 없는 항목 (선택 체크박스 등) 은 `-`.
+- 비고: 표시 내용 (이름과 도메인만으로 자명하지 않을 때 어떤 값이 표시되는지) / 편집 방법 (편집 가능 항목 — 예: 클릭 시 모달, 인라인 편집) / 기타 자유 설명.
+
+**시트 컬럼 그룹핑** (해당 시): 컬럼들이 도메인적으로 묶일 경우 표 안에 그룹 표시.
+- 그룹 헤더 행을 1줄 (`**그룹명**` 표시, 다른 셀은 빈 칸).
+- 자식 컬럼은 `└ ` 들여쓰기 prefix 부착.
+- 표의 컬럼 수는 유지.
+
+#### 동작
+
+bullet 을 `- <트리거>: 처리 내용` 형식으로 작성.
+
+- 트리거 예시: `` `[버튼]` 클릭 ``, `박스 바코드 스캔`, `Enter 키`.
+- 처리 내용: 동사구 + 대상 (예: `[화면.X] 을 모달로 띄움`, `검색 필터 조건으로 목록 갱신`).
+
+#### 시각 규칙 (해당 시)
+
+행 단위·조건부 시각 표현 (비활성 행 취소선·상태별 강조 색·아이콘 등) 을 작성. 컬럼 단위 표현은 항목 표의 비고에 작성하므로 여기에는 작성하지 않음.
+
+#### 도메인 규칙·로직 (해당 시)
+
+표준 sub-section 으로 담기지 않는, 화면 고유의 도메인 요구를 작성. 자유 명칭의 절을 필요한 만큼 추가. 누락 없이 적는 것이 핵심.
+
+**자유 추가 sub-section** (`#### 도메인 규칙·로직` 아래, 화면별 필요 시 h4 자유 추가):
+
+- **양식 입출력** (예: `#### 업로드 양식`·`#### 다운로드 양식`) — 양식별로 별도 sub-section 작성.
+  - 단순 양식: 내부에 단순 표 — 컬럼은 `파일 컬럼` + `도메인 모델 ([모델.X.Y])` + `변환·규칙 (해당 시)`. §7.x 에 명세된 양식이면 컬럼명을 일치시키고, 일회성 양식이면 sub-section 내부에서 직접 명세.
+  - 복잡 양식 (다중 시트·구조 분할): 내부의 sub-단위 (시트 등) 는 h5 (`##### <시트>` 등) 로 작성.
+- **기타 화면 고유 정보** — sub-section 이름은 자유. 표준 sub-section 으로 담기지 않는 화면 고유 정보의 누락 방지 목적.
+
+### 마스터 화면 표준
+
+화면 목록 표에서 유형이 "마스터" 인 §4.x 에 적용. 화면 정의 sub-header (와이어프레임·항목·동작) 와 함께 작성.
+
+- ID 컬럼은 편집 버튼 (`[E N]`) 으로 표현.
+- 첫 컬럼은 선택 체크박스 (`[ ]`).
+- 시트 상단 버튼바: `[등록] [선택 삭제] [선택 복구] [엑셀 업로드] [엑셀 다운로드]`.
+- ID 정렬은 역방향 (내림차순).
+
+### 상단 command 바
+
+화면 정의 sub-header 의 와이어프레임·동작과 함께 작성. 페이지 제목 바로 아래, 시트·폼 영역 위에 배치. 페이지 전체 또는 현재 레코드 단위의 액션 바.
+
+- 좌측: 필터 입력 + 조회 (list 화면) / 진입 컨텍스트 표시 (detail 화면).
+- 우측: 페이지 단위·레코드 단위 액션 (있는 경우에만).
+- 좌·우 사이에 ` │ ` 세로 구분선.
+
+**우측 버튼 그룹 순서** (좌→우):
+1. 기본 CRUD (저장 / 삭제 / 복구).
+2. 워크플로 상태 전환 (확정 / 취소 / 승인 / 반려).
+3. 유틸리티 (원본 다운로드 / 프린트 / PDF).
+
+list 화면과 detail 화면 모두 동일. 새 버튼은 해당 그룹의 끝에 추가. 시트 상단 버튼바도 동일한 그룹 순서를 따름 (마스터 화면 표준은 그 구체 인스턴스).
+
+### 모달 처리
+
+호출하는 쪽 §4.x 의 동작 sub-header 와 호출되는 쪽 §4.x 양쪽 모두에 적용.
+
+- 모달 화면도 별도의 §4.x. 호출하는 쪽의 동작에 "→ [화면.X] 을 모달로 띄움" 을 명시.
+- 화면명에 "(모달)" 등의 사용 맥락 표기 금지 — 같은 화면이 다른 곳에서는 다른 방식으로 호출될 수 있음.
+- 화면의 일부 영역 (시트·탭) 이 다른 화면에서 모달로 재활용되는 경우, 별도 §4.x 로 분리하지 않음. 대신 그 화면의 동작 절 끝에 "영역별로 모달 호출 시 제약" (편집 가능 여부 / 선택 전용 / multiselect) 을 한 줄씩 명시. 호출하는 쪽의 동작은 "→ [화면.X] 의 <영역> 을 모달로 띄움" 으로 표기.
+
+## §5 자동 처리
+
+### 정의
+
+스케줄러 또는 이벤트 트리거로 동작하는 시스템 백그라운드 처리. 표준 프로토콜·채널을 통한 외부 자료 수집·적재 (메일 폴링 + 첨부 적재, FTP 자료 수집 등) 도 §5 에 포함 — 시스템별 협상이 필요 없는 표준 인터페이싱은 §9 가 아님.
+
+§6 공통·기반 기능과의 차이: §5 = 스케줄·이벤트로 명시적인 트리거가 있음. §6 = 명시적 트리거가 없는 것 (부수효과로 발동되거나 전역에 상시 구성되는 것).
+
+### 본문 구조
+
+sub-section 헤더 레벨은 `## spec.md 형식` 의 "sub-section 헤더 레벨" 표 참조.
+
+**평문 sub-section** (§5.x 헤더 바로 아래에 "라벨 + 본문" 형식으로 작성):
+
+- `목적:` 도메인 목적을 한 줄로.
+- `트리거:` 스케줄·이벤트 명시.
+- `관련 섹션:` "본문 내 참조" 절 룰 따름.
+
+**h4 sub-section** (평문 아래에 고정 순서로 위→아래 작성):
+
+#### 처리
+
+처리 단계 작성.
+
+#### 예외 처리
+
+실패 케이스별 위험·대처·재시도 한계 작성.
+
+**자유 추가 sub-section** (`#### 예외 처리` 아래에, §5.x 별로 필요 시 h4 자유 추가):
+
+- **양식 입출력** (예: `#### 읽기 양식`·`#### 쓰기 양식`) — §4 의 "양식 입출력" sub-section 룰과 동일. 방향은 읽기·쓰기. 일회성 양식이면 sub-section 안에서 직접 명세.
+- **기타 자동 처리 고유 정보** — sub-section 이름은 자유.
+
+## §6 공통·기반 기능
+
+화면(§4)도 명시적 트리거 자동 처리(§5)도 아닌, 시스템을 떠받치는 공통·기반 개발 단위 전부 (캐치올). §4·§5 에 속하지 않는 개발 entry 는 전부 여기로 모임 — 갈 곳 없는 항목을 §7(공통 정의) 등 명세 섹션으로 올리지 말 것.
+
+포괄 대상 (두 성격이 한 섹션에 섞임. 항목을 어느 한쪽으로 미리 분류하지 않음 — 애매하거나 두 성격을 겸하는 항목도 그대로 수용):
+- 부수효과로 발동되는 동작 — DataLog 기록·권한 체크·캐시 무효화·알림 발송·감사 로그.
+- 전역에 상시 구성되는 정적 골격 — 앱 구조(메뉴·권한·모듈)·로깅 정책·부트스트랩 초기화.
+
+### 정의
+
+§4 화면·§5 자동 처리에 속하지 않는 모든 개발 단위. §3 기타 요구사항의 시스템 전반 자동 룰을 설계 차원에서 풀이하는 것도 포함. 부수효과로 발동되는 동작과 전역 상시 골격을 모두 포괄하되, 두 성격이 한 항목에 섞일 수 있으므로 미리 가르지 않음.
+
+§5 자동 처리와의 차이: §5 = 스케줄·이벤트로 명시적 트리거 (예: 매일 자정·메일 도착). §6 = 명시적 트리거가 없는 것 — 부수효과로 발동되거나 전역에 상시 존재.
+
+### 본문 구조
+
+§6 은 항목 성격이 제각각인 캐치올이라 §4/§5 같은 고정 sub-section 구조가 없음. 항목은 두 갈래로 작성:
+
+- **프레임워크 기본 기능** (앱 구조·로깅·부트스트랩·데이터 변경 이력 등 — 매뉴얼이 존재) → 매뉴얼 참조 stub. 평문 라벨 + `참조 매뉴얼:` 한 줄. 처리·구성·예외 detail 은 매뉴얼로 위임하고 spec 에 적지 않음.
+- **bespoke** (앱 고유 부수효과 — 매뉴얼 없음) → 평문 라벨 + 본문 한두 줄 자유 서술.
+
+sub-section 헤더 레벨은 `## spec.md 형식` 의 "sub-section 헤더 레벨" 표 참조.
+
+**평문 sub-section** (§6.x 헤더 바로 아래에 "라벨 + 본문" 형식, 위→아래):
+
+- `목적:` 도메인 목적 (필수).
+- `트리거·적용 범위:` (해당 시) 어떤 동작의 부수로 발동되는지 / 어디에 상시 적용되는지 + 적용 시점. (예: "모든 엔티티 update 시 / 전체", "앱 부팅 시 / 전체 클라이언트").
+- `관련 섹션:` "본문 내 참조" 절 룰 따름.
+- `참조 매뉴얼:` (프레임워크 기본 기능인 경우) 구현 매뉴얼 파일명 (`.claude/references/sd-simplysm14/manuals/` 기준). 이 줄이 있으면 처리·구성·예외 detail 은 적지 않음.
+
+**본문** (bespoke 항목만, 평문 아래에 작성):
+
+- 설계 내용을 한두 줄로 자유 서술 — 설계 고도까지만 (구현 디테일은 제외).
+- 처리 절차·모델 매핑·예외 처리 같은 고정 sub-section 은 두지 않음. 양식·매핑 등 정말 필요한 정보만 h4 자유 추가 (이름 자유).
+
+## §7 공통 정의
+
+새로운 도메인 어휘·시스템 규격을 발견하면 작성.
+
+### §7.1 용어 사전 (고정)
+
+도메인 어휘·약어·시스템 내 의미를 정의.
+
+### §7.2~ 기타 공통 규격
+
+시스템 전반 규격 (바코드 형식·라벨·공통 정책 등) 작성.
+
+특정 §2/§3 본문 단계에서 자연스럽게 포함되는 규칙 (업로드 자료 컬럼 매핑·자료 해석 규칙 등) 은 §7 에 두지 않음 → 사용처 본문에 둠.
+
+### 외부 자료 명세
+
+§7 의 외부 자료 = **시스템 외부에서 정의되어 도메인 모델로 자명하지 않은** 자료 (예: 외부 시스템 송신 파일, 거래처 표준 양식, 정해진 외부 규격). 도메인 모델의 자체 엑셀 업로드·다운로드 양식은 §7 가 아님 — §8 도메인 모델 + §4/§5/§6 의 양식 매핑으로 자명.
+
+자료별로 표가 필수. 외부 자료의 모든 컬럼·필드를 1행 1정의로 작성 (자료 자체의 객관 명세).
+
+**자료-레벨 메타** (송신 측·자료 라이프사이클·갱신 주기·식별 키 구조 등 자료 *전체* 에 적용되는 객관 명세):
+- 근거가 있을 때만 컬럼 표 위에 자유 작성 (불릿·단락·`라벨: 값` 형식 모두 허용).
+- 컬럼 표 안에 욱여넣지 않음.
+
+**컬럼 표**:
+- 외부 자료가 여러 개 (`SAP.XML`·`D1.CSV` 등) 이면 자료별로 별도의 표 작성.
+- 컬럼 구성은 자료 성격에 따라 초안 제시 후 확정. 예: `컬럼명/식별자 | 필수/선택 | 설명/규칙`.
+- 모든 컬럼에 대한 행을 유지.
+- "설명/규칙" 류 컬럼에는 **그 컬럼이 무엇인지** (데이터 정의: 형식·값 범위·의미·제약) 만 작성. **용도** (어디에 어떻게 쓰이는지) 는 작성 금지 — 용도·매핑은 사용처 (§4/§5/§6 의 양식 매핑) 에서 작성.
+- 각 셀 값은 근거로 채택 가능한 자료가 있을 때만 작성. 추정·임의 작성 금지.
+- "원본 따름"·"전체 명세는 X.xlsx 참조" 등 외부 참조로 본문 정의를 대체 금지.
+
+## §8 도메인 모델
+
+새로운 엔티티를 발견하면 작성.
+
+섹션 구조: `필드:` 표 + `키/제약:` 불릿.
+
+### 필드 표
+
+컬럼 구성: `필드 | 타입 | 필수 | 비고`.
+
+- 비고에는 **그 필드가 무엇인지** (데이터 정의: 형식·값 범위·의미·제약·예시) 만 작성. **용도·출처·외부 양식·외부 시스템과의 매핑** 은 작성 금지 — §4/§5/§6 의 양식 매핑·모델 매핑 / §9 의 자료 매핑에서 작성.
+
+### 키/제약 불릿
+
+- **식별 키**: 모든 엔티티에 `ID` 필드 (숫자, 자동 부여) 를 명시.
+- **비즈니스 키** (코드 등): 별도로 명시. 수정 가능 (PK 가 아님).
+- **활성/비활성 boolean** = 소프트 삭제 플래그. 마스터에는 완전 삭제가 없음. UI 의 "삭제/복구" 액션과 매핑됨 → §7.1 용어 사전에 한 줄로 명문화.
+
+## §9 외부 인터페이스
+
+외부 시스템 호출을 발견하면 작성.
+
+### 정의
+
+§9 = 상대 시스템 고유의 인터페이스 약속 (시스템마다 자료 매핑·방식이 달라 협상이 필요한 것).
+
+- 포함 예시: 상대 ERP·거래처가 자체 정의한 API·EDI 규격, 외부 시스템의 webhook 페이로드.
+- 제외 예시: 표준 프로토콜·채널 (메일 SMTP·IMAP·Exchange·Graph, FTP, 표준 OAuth 등). 시스템별 협상이 없음 → §5 자동 처리에서 트리거·처리·양식 매핑으로 처리.
+
+### 디테일 범위
+
+도메인 약속 레벨까지만 작성. 구체 endpoint URL·HTTP method·query 파라미터·인증 흐름 단계 (grant_type·scope·token endpoint 등) ·SDK 메소드명 등 구현 디테일은 제외. (§2 BPMN·§4 와이어·§8 도메인 모델과 동일한 원칙).
+
+### 본문 구조
+
+sub-section 헤더 레벨은 `## spec.md 형식` 의 "sub-section 헤더 레벨" 표 참조.
+
+**평문 sub-section** (§9.x 헤더 바로 아래에 위→아래 순서로 작성):
+
+- **기본 정보** (라벨 bullet 3건):
+  - `상대 시스템: <시스템명>`.
+  - `방향: <방향 표기>`.
+  - `전송 방식: <방식>`.
+- **관련 섹션** (`관련 섹션: [카테고리.이름], ...` 형식의 한 줄): "본문 내 참조" 절 룰 따름. 호출자 등 참조·의존 섹션 포함.
+
+**h4 sub-section** (평문 아래에 고정 순서로 위→아래 작성):
+
+#### 자료 매핑
+
+표 형식 — 상대 시스템의 필드 ↔ 본 시스템의 출처.
+
+#### 예외 처리
+
+실패 케이스별 위험·대처·재시도 한계 작성.
+
+## §10 본문 외 확정 사항
+
+§1~§9 의 어느 곳에도 자연스럽게 들어가지 않는 결정·메모를 누적. §1~§9 의 적절한 자리에 넣을 수 있는 결정은 §10 에 두지 않음 (누락 도피처가 아님).
+
+### 형식
+
+각 항목의 구조:
+
+- **헤더 1줄** (필수): `- YYYY-MM-DD: <결정 한 줄>`.
+  - 분석 제외 시: `- YYYY-MM-DD [제외]: <결정 한 줄>`.
+- **자식 bullet**: 형식 자유 (개수·내용 모두 자유).
+  - **결정 근거 1개 이상 필수**.
+  - 자유 항목 예시: 자료 위치·영향 범위·대화 발췌·메모·관련 § 등.
+  - 분석 제외 시 추가 필수 항목: `후속 처리`·`자료 위치`.
+
+### 포괄 결정 종류
+
+매번 분류하지 않음 — 자연 흐름대로 누적. 분석 제외 신호가 있을 때만 `[제외]` 마커 부착.
+
+- **미래 결정**: 해당 단계에 도달하기 전에 미리 내린 결정 (예: "추후 §4.5 작성 시 X 항목 포함").
+- **구현 영역 결정**: spec 본문에 들어가지 않는 구현 측 결정 (예: 라이브러리 선택).
+- **부정 결정**: "X 안 함" 부정 명시 — 반복 질문 방지용.
+- **분석 제외**: 본 spec 에서 다루지 않는 항목 — 다른 spec·운영 잔손 등 외부 후속 처리 대상.
+
+### 예시
+
+```
+- 2026-05-22: 월간 마감 자동화 — 안 함
+  - 근거: 회계팀 수동 처리 선호
+  - 자료 위치: 회의록_3.md L120-135
+  - 영향: §5 자동 처리 후보에서 제외
+
+- 2026-05-22: 구현 시 결제 라이브러리 X 사용
+  - 근거: 사용자 명시 (PG사 계약 호환)
+
+- 2026-05-22 [제외]: 다국어 지원
+  - 근거: 현재 단계 아님
+  - 후속 처리: 다른 spec 신규
+  - 자료 위치: 회의록_3.md L80-95
+```
+
+## spec.md 골격
+
+spec.md 를 신규 생성할 때 사용하는 골격. `{name}` 은 시스템명.
+
+```markdown
+# {name} 요구 분석서
+
+## 1. 개요
+
+### 1.1 핵심 목적
+
+### 1.2 주요 목표
+
+### 1.3 최종 사용자/이해관계자
+
+### 1.4 환경/장치
+
+## 2. 업무 프로세스
+
+## 3. 기타 요구사항
+
+## 4. 화면
+
+## 5. 자동 처리
+
+## 6. 공통·기반 기능
+
+## 7. 공통 정의
+
+## 8. 도메인 모델
+
+## 9. 외부 인터페이스
+
+## 10. 본문 외 확정 사항
+```

package/claude/workflows/sd-docs.js

@@ -0,0 +1,84 @@
+export const meta = {
+  name: 'sd-docs',
+  description: '@simplysm/* 라이브러리 패키지 API 문서를 코드 기준으로 풀 재작성하고 상위 README 패키지 인덱스를 갱신',
+  phases: [
+    { title: '발견', detail: 'packages/*/package.json 에서 라이브러리 패키지 목록 수집' },
+    { title: '문서화', detail: '라이브러리 패키지 1개당 agent 1개 팬아웃, sd-docs.rules.md 규칙대로 apis/<패키지>/ 산출' },
+    { title: '인덱스 취합', detail: '전 패키지 결과로 상위 README 패키지 인덱스 섹션 1회 갱신' },
+  ],
+}
+
+// 경로는 모두 워크스페이스 루트(cwd) 상대 — 소비 프로젝트에 배포돼도 동작.
+const DOC_RULES = '.claude/workflows/sd-docs.rules.md'
+const APIS_DIR = '.claude/references/sd-simplysm14/apis'
+const ROOT_README = '.claude/references/sd-simplysm14/README.md'
+
+const PKG_SCHEMA = {
+  type: 'object',
+  properties: {
+    packages: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          shortName: { type: 'string', description: '@simplysm/ 접두사를 제외한 짧은 이름' },
+          dir: { type: 'string', description: '패키지 디렉토리 경로' },
+        },
+        required: ['shortName', 'dir'],
+      },
+    },
+  },
+  required: ['packages'],
+}
+
+const DOC_SCHEMA = {
+  type: 'object',
+  properties: {
+    shortName: { type: 'string' },
+    mode: { type: 'string', enum: ['신규', '갱신'] },
+    writtenFiles: { type: 'array', items: { type: 'string' } },
+    deletedFiles: { type: 'array', items: { type: 'string' } },
+    triggerSummary: { type: 'string', description: '상위 README 인덱스에 옮겨 적을 패키지 한 줄 트리거 요약' },
+  },
+  required: ['shortName', 'mode', 'writtenFiles', 'deletedFiles', 'triggerSummary'],
+}
+
+phase('발견')
+const discovery = await agent(
+  `현재 워크스페이스의 packages/*/package.json 을 모두 확인해 문서화 대상 패키지 목록을 반환해.\n` +
+  `- 대상 = package.json 에 "private": true 가 없고, 동시에 src/index.ts 가 존재하는 라이브러리 패키지. 둘 중 하나라도 어긋나면 제외(예: src/index.ts 가 없는 scripts/bin 전용 패키지는 라이브러리 API 가 없으므로 제외).\n` +
+  `- 각 항목: shortName(name 필드에서 @simplysm/ 접두사를 제외한 짧은 이름), dir(워크스페이스 루트 기준 패키지 디렉토리 경로. 예: packages/excel).`,
+  { phase: '발견', schema: PKG_SCHEMA }
+)
+const pkgs = discovery.packages
+log(`라이브러리 패키지 ${pkgs.length}개 발견: ${pkgs.map(p => p.shortName).join(', ')}`)
+
+phase('문서화')
+const results = (await parallel(pkgs.map(p => () =>
+  agent(
+    `@simplysm/${p.shortName} 패키지의 API 문서를 풀 재작성한다. 반드시 ${DOC_RULES} 를 먼저 읽고 그 작성 규칙(입력 분석·사용 트리거 군 분류·산출 단위 판정·풀 재작성 모드·README/분할 형식·식별자 풀이 의무·작성 원칙)을 그대로 따른다.\n\n` +
+    `진실 근거: ${p.dir}/src/index.ts 의 export 와 그 정의 파일(타입+본문)·JSDoc, 그리고 tests/ 중 이 패키지를 import 해 검증하는 테스트 코드뿐. 외부 자료·과거 git 기록·다른 패키지의 사용처 참조 금지.\n\n` +
+    `산출 자리: ${APIS_DIR}/${p.shortName}/ — README.md 1장 필수, 큰 군만 <군명>.md 로 분할. 풀 재작성 모드이므로 기존 파일은 참고하지 말고 처음부터 작성. 코드에서 사라진 군의 분할 파일은 삭제.\n` +
+    `상위 README(${ROOT_README})는 절대 건드리지 말 것 — 인덱스는 별도 단계에서 처리.\n\n` +
+    `완료 후 ${DOC_RULES} "8. 구조화 결과 반환" 형식으로 결과 반환.`,
+    { label: `docs:${p.shortName}`, phase: '문서화', schema: DOC_SCHEMA }
+  )
+))).filter(Boolean)
+
+phase('인덱스 취합')
+const sorted = results.slice().sort((a, b) => (a.shortName < b.shortName ? -1 : a.shortName > b.shortName ? 1 : 0))
+const indexLines = sorted.map(r =>
+  `- **${r.shortName}** — ${r.triggerSummary} 자세히: [apis/${r.shortName}/README.md](./apis/${r.shortName}/README.md)`
+)
+await agent(
+  `${ROOT_README} 의 "## 패키지 인덱스" 섹션 본문(항목 리스트)만 아래 내용으로 교체한다.\n` +
+  `- 건드리지 않음: 섹션 머리(## 패키지 인덱스), 다른 모든 섹션, 파일 상단/하단 텍스트.\n` +
+  `- 항목 리스트는 이미 패키지명 알파벳순으로 정렬되어 있으니 순서 그대로 사용.\n\n` +
+  `교체할 항목 리스트:\n${indexLines.join('\n')}`,
+  { phase: '인덱스 취합' }
+)
+
+return {
+  count: results.length,
+  written: sorted.map(r => ({ shortName: r.shortName, mode: r.mode, writtenFiles: r.writtenFiles, deletedFiles: r.deletedFiles })),
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/sd-claude",
-  "version": "14.0.88",
+  "version": "14.0.89",
   "description": "심플리즘 패키지 - Claude Code 셋업",
   "author": "심플리즘",
   "license": "Apache-2.0",

package/claude/references/sd-simplysm14/apis/orm-common/query-builder.md

@@ -1,29 +0,0 @@
-# @simplysm/orm-common — QueryBuilder (dialect SQL 렌더러)
-
-`QueryDef` AST 를 각 DBMS SQL 문자열로 변환하는 클래스군. executor 구현체(`@simplysm/orm-node` 등)가 사용하며, 일반 쿼리 작성에선 직접 다루지 않는다.
-
-## 팩토리
-
-- `createQueryBuilder(dialect: Dialect): QueryBuilderBase` — dialect 에 맞는 QueryBuilder 인스턴스 생성. `dialect` 가 `"mysql"|"mssql"|"postgresql"` 중 하나에 따라 아래 구현체 반환.
-
-```typescript
-const builder = createQueryBuilder("mysql");
-const { sql } = builder.build(queryDef);
-```
-
-## QueryBuilder 클래스
-
-- `abstract class QueryBuilderBase` — QueryDef → SQL 추상 기반.
-  - `build(def: QueryDef): QueryBuildResult` — `def.type` 과 동일 이름 메서드로 동적 dispatch 하여 SQL 렌더. 알 수 없는 타입이면 throw. dialect 공통 로직만 구현하고 차이나는 부분은 abstract(하위 클래스 구현).
-- `class MysqlQueryBuilder extends QueryBuilderBase` — MySQL 렌더러.
-- `class MssqlQueryBuilder extends QueryBuilderBase` — MSSQL 렌더러(TOP, IDENTITY_INSERT, OUTPUT 등).
-- `class PostgresqlQueryBuilder extends QueryBuilderBase` — PostgreSQL 렌더러.
-
-## ExprRenderer 클래스
-
-`QueryBuilder` 내부에서 `Expr`/`WhereExpr` AST 를 SQL 식 문자열로 렌더.
-
-- `abstract class ExprRendererBase` — 표현식 렌더 추상 기반. `render(expr)`/`renderWhere(wheres)` 를 dispatch, dialect 차이(함수명·NULL 안전 비교·날짜 함수 등)는 abstract.
-- `class MysqlExprRenderer extends ExprRendererBase` — MySQL 표현식 렌더러(`<=>` 등).
-- `class MssqlExprRenderer extends ExprRendererBase` — MSSQL 표현식 렌더러.
-- `class PostgresqlExprRenderer extends ExprRendererBase` — PostgreSQL 표현식 렌더러.