sd-impl

sd-impl

spec.md 단위(§4.x 화면 / §5.x 자동 처리 / §6.x 공통·기반 기능) 1개를 현재 코드베이스 상태와 비교해 빠지거나 어긋난 부분만큼 풀 구현. 데모 골격이 있으면 보존. 끝에 사용자 시연으로 회귀 점검.

호출 시나리오 2종 — 동일 워크플로:

• 신규: spec 단위가 코드베이스에 아직 없음 — 처음 구현.
• 갱신: spec 단위가 이미 구현되어 있고 spec 변경분에 맞춰 수정.

본질 (횡단 룰)

워크플로 전 단계 적용:

• 임의 채움 금지: spec 본문에 명시가 없거나 모호한 분기를 발견하면 즉시 멈추고 사용자에게 질문. 자체 판단으로 채우지 않음.
• YAGNI: spec 에 없는 기능·옵션·추상화·방어코드 추가 금지. 필요해질 때까지 만들지 않음 (작성 시점부터 적용).
• 사용자 보고 어휘: 사용자에게 보고하는 본문에 코드 식별자(변수명·SQL 함수명·타입 키워드 등) 노출 금지. 도메인 어휘로 풀어 보고.

워크플로

1단계: 입력 확보

• 대상 spec.md 경로.
• 구현할 단위 식별자 — §4.x (화면) / §5.x (자동 처리) / §6.x (공통·기반 기능).

없으면 묻기. spec.md 에서 식별자 매칭이 안 되면 §4 화면 목록 표 / §5 자동 처리 / §6 공통·기반 기능 헤더 목록에서 후보를 제시 후 확정.

입력 spec.md 읽기 범위: 경로·식별자 확보 후 ① 구현 대상 단위(§4.x/§5.x/§6.x) 본문 → ② 그 본문이 이름 기반 참조([화면.X]·[모델.X]·[공통 정의.X] 등)로 가리키는 § 를 재귀적으로(참조의 참조까지) → ③ §10 본문 외 확정 사항 전체 를 Read. spec.md 는 다른 세션이 누적한 결정의 영속 산출물이라 안 읽은 영역의 결정·제약을 추측으로 덮어쓰면 안 되며, 그 결정·제약은 전역이면 §10·단위 한정이면 그 단위의 진행방법 NOTE 나 인라인 [OPEN] 에 모이도록 sd-spec 형식이 규정함. grep·부분 읽기로 대상 § 만 보고 §10·참조 § 를 빠뜨리지 않음.

2단계: 외부 입력 점검

작업 대상 §4.x/§5.x/§6.x 와 작업 대상이 참조하는 §5/§6/§7/§8/§9 항목을 점검:

• 섹션 [OPEN] (초안 부재): 섹션 본문이 재분석 포인터일 뿐 초안이 없음 → "spec 수정 절차" 적용.
• 본문 인라인 [OPEN]: 결정 근거가 있으면 결정. 없으면 1건씩 질문 → 답변 후 "spec 수정 절차" 적용.
• 사용자 제공 예정 자료: spec 본문에 사용자 회신 대기로 적힌 자료. 사용자 회신 후 진행.
• 묵시적 모호: 명시 마커는 없지만 spec 본문이 분기·정의·정의식·경계 케이스를 다루지 않는 부분. 4단계 분해 중 발견 가능성 높음. 발견 시 본 단계로 회귀.

spec 수정 절차

spec 본문 수정이 필요한 경우(인라인 [OPEN] 해소·섹션 [OPEN] 해소·구조 변경·6단계 (b)(c) 분류 처리 등) 메인 LLM 이 직접 처리:

1. sd-spec SKILL.md Read — 룰 인지: 부분 수정 인라인 경로·신뢰도 표기·형식 준수(§ 작성법 Read)·이름 기반 참조 cascade.
2. sd-spec "부분 수정 (인라인)" 경로로 Edit — 정밀 반영(도메인 답이 이미 확정된 인라인 [OPEN]·6단계 결정 반영)은 바로 Edit, 초안·판단 필요분(섹션 [OPEN] 초안·구조 변경·모순 정정)은 진단·초안 제시 → 합의 후 Edit. 수정분은 사후 보고.
3. 의존 추적 — sd-spec "§4~6 [구현] 마커 제거" 절의 의존 식별 규칙으로 수정된 § 를 의존으로 가진 §4.x/§5.x/§6.x 를 전수 추적. 본 작업 단위 자신은 제외 (작업 중).
4. 마커 제거 — 추적된 §4.x/§5.x/§6.x 헤더의 [구현] 마커 제거 (이전 구현 무효화). 합의 절차도 같은 절 따름.

본 작업 단위(§4.x/§5.x/§6.x 자신)의 헤더에는 9단계에서 [구현] 마커를 부착.

3단계: 보조 자료 수집 (있다면 활용)

부재로 워크플로를 멈추지 않음. framework 별 세부 지침은 본 SKILL.md 본문에 명시하지 않음 — 코드베이스 매뉴얼·기준 단위·테스트 환경이 발견되면 따르고, 부재 시 framework 자체 표준(Angular CLI 기본 구조·esbuild 기본 옵션 등)으로 채워도 됨. 도메인 결정·분기·계산식 등 spec 결정 사항은 본질 "임의 채움 금지" 적용.

A. 라이브러리·개발 매뉴얼

• @simplysm/* — SessionStart 가 주입한 활성 references 경로의 README.md 참조 후 "개발 매뉴얼" 진입.
• 그 외 framework — 코드베이스 안의 동등 위치 문서 참조.

B. 기준 단위 + 계층별 보강

풀 구현은 다층 흐름이 한 줄로 가야 일관성이 유지됨. 기존 단위 1개를 통째로 따라가는 방식이 아니라, 기준 단위 1개를 잡고 비어있거나 부적합한 계층만 다른 단위에서 보강.

4계층:

계층	§4.x (화면)	§5.x (자동 처리)	§6.x (공통·기반 기능)
도메인 모델	엔티티·필드	동일	동일
데이터 접근	쿼리·서비스	동일	동일
본체	화면 컴포넌트	자동 처리 로직 + 트리거	부수효과 후크 또는 설정·부트스트랩 구성
테스트	단위 테스트	동일	동일

기준 단위 선정 (같은 종류 §4.x↔§4.x, §5.x↔§5.x, §6.x↔§6.x 안에서):

1. 도메인이 인접한 풀구현 단위 후보 탐색 (인접 도메인 정의는 sd-spec §4 화면 목록 분류·코드베이스 구조 등에서 자유 도출).
2. 후보가 1개 → 자동 채택. 2개 이상 → 후보 목록 제시 후 사용자에게 1회 질문. 0개 → 같은 종류 전 범위로 확장 후 동일 규칙 적용.
3. 전 범위에도 0개 → 기준 단위 없이 매뉴얼(A) + framework 자체 표준.

계층별 보강: 기준 단위의 4계층 각각을 다음과 같이 평가:

평가	의미	처리
비어있음	해당 계층 파일이 기준 단위에 없음	같은 종류 다른 단위에서 그 계층 패턴 차용
부적합	있지만 spec 요구와 어긋남	같은 종류 다른 단위에서 그 계층 패턴 차용
적합	그대로 따름	변경 없이 사용

비어있음·부적합 계층은 같은 종류의 서로 다른 단위 2개 이상에서 동일하게 나타난 패턴을 자동 채택. 단위 1개에서만 쓰인 변종은 배제. 여러 패턴이 갈리면 사용자에게 1회 질문.

읽기: 기준 단위의 적합 계층 파일 + 보강 출처 파일을 모두 읽기. 5단계 작성 시 채택 패턴 기준이자 7단계 drift 점검의 입력.

C. 테스트 환경

단위 테스트 프로젝트 구분·실행 명령·mocking 패턴·dev 서버 실행 명령을 파악. 부재 시 framework 자체 표준으로 조합.

4단계: spec 분해 표

대상 §4.x/§5.x/§6.x 와 참조 §5/§6/§7/§8/§9 본문을 항목 단위까지 분해하여 표 작성. 표는 assistant 응답으로 출력 (이후 5·6단계의 입력). 일치 항목은 손대지 않음(차이만 작업).

예시 (재고관리 도메인, 박스 입고 화면 §4.1 일부):

항목 ID	spec 인용	현재 코드 상태	판정	매핑 파일	의존
1	§4.1 항목 "박스 바코드" (필수·문자열·24자)	없음	없음	packages/app/src/screens/incoming/box-form.view.ts	-
2	§4.1 동작 "스캔: 바코드 검증·박스 등록"	있음 (검증 누락)	불일치	(동일)	1

항목 분해 단위:

• 도메인 모델: 필드 1개당 1줄 (타입·제약·기본값).
• 계산식: 정의식 1개당 1줄 (좌변·우변·참조).
• 상태값·분기: 케이스 1개당 1줄 (조건·결과).
• UI 항목: 컬럼·필드·버튼 1개당 1줄.
• 동작·자동 처리: 트리거·결과 단위 1줄.

컬럼:

• 항목 ID: 1, 2 ... (이후 의존 컬럼 참조용. 형식 자유).
• spec 인용: spec.md § 위치 + 본문 문구.
• 현재 코드 상태: 코드베이스 조사 결과 사실. 신규 호출 = "없음", 갱신 호출 = "있음(어떻게)". 조사는 워킹트리 파일을 Read·Grep·Glob 로만 수행. 갱신 호출도 동일.
• 판정: 없음 / 불일치 / 일치.
• 매핑 파일: 이 항목이 작성·갱신될 파일 경로.
• 의존: 다른 항목 ID.

분해 중 spec 본문이 정의·정의식·분기·경계 케이스를 다루지 않거나 모순되는 부분을 발견 → 2단계로 회귀("spec 수정 절차" 적용).

표 작성 완료 후 5단계 진입.

5단계: 작업 사이클

표의 (없음·불일치) 판정 항목만 의존 순서로 진행 (차이만 작업). 일치 항목은 손대지 않음.

데모 골격 보존: 작업 대상 매핑 파일이 데모 골격(sd-demo 산출물)이면 골격 구조를 유지하며 차이만 보강.

각 항목 시작 시 테스트 작성 가능 여부를 판정 (3-C 의 테스트 환경 이용):

분류	적용 대상	사이클
테스트 가능	도메인 로직·계산·변환·서버 함수·데이터 접근	RED → GREEN → REFACTOR
테스트 불가·비효율	UI 시각·인터랙션·외부 서비스 실호출·환경 의존	구현 → REFACTOR

테스트 단위 = spec 이 요구한 산출 단위. 내부 구현을 쪼개지 말 것:

• 위 "테스트 가능" 분류는 그 처리가 spec 이 독립 산출물로 요구한 단위(공개 함수·API·계약)일 때 적용 — 그 경우 그 단위를 그대로 테스트.
• 요구사항이 "동작"(화면·자동 처리·공통·기반 기능·초기화 등)이고 변환·매핑·계산이 그 동작의 내부 구현 조각일 뿐이면, 동작 전체를 테스트 단위로 봄. 동작이 통째로 테스트 가능하면 그 단위로, 아니면(외부 I/O·환경 의존) "테스트 불가·비효율" 로 분류.
• 내부 구현 조각을 테스트하려고 별도 함수·파일·인터페이스로 분리·추상화하지 말 것. spec 이 그 조각을 산출물로 요구하지 않았다면, 테스트는 그 조각을 떼낼 이유가 되지 못함.

사이클 단계 정의:

• RED: 테스트만 작성 → 러너 실행 → 실패 확인. 구현 파일은 손대지 않음.
• GREEN: 테스트를 통과하는 최소 구현 → 러너 통과 확인.
• REFACTOR: 중복·가독성·3-B 채택 패턴·3-A 매뉴얼 정합 정리(채택 패턴·매뉴얼에서 벗어나는 임의 변형 금지) → 러너 통과 유지.

작업 사이클 중 spec 미정의·모호 분기를 만나면 2단계로 회귀.

6단계: spec 대조 (subagent 위탁)

5단계의 모든 항목 완료 후, 별도 subagent 에 위탁해 spec ↔ 현재 코드 전체를 독립 대조. 같은 LLM 의 자체 검증에서 발생하는 표면적 확인 편향을 제거하는 목적.

대조는 작업 단위 전체를 대상으로 함. 신규·갱신 호출 무관, "이번 변경분만" 식 스코프 제한 없음.

subagent 호출

• 도구: Agent.
• subagent_type: general-purpose (추론·도메인 어휘 풀어 보고 필요해 read-only 에이전트 사용 안 함).
• description: sd-impl spec 대조.
• prompt: 아래 입력 패키지 (그대로 복사 후 <…> 부분만 채움).

sd-impl 의 spec ↔ 코드 독립 대조를 수행해줘.

**대상**:
- spec.md 경로: <절대경로>
- 단위 식별자: <§4.x / §5.x / §6.x>

**참조 자료**:

(1) 4단계 spec 분해 표 (인라인):

| 항목 ID | spec 인용 | 현재 코드 상태 | 판정 | 매핑 파일 | 의존 |
| ------- | --------- | -------------- | ---- | --------- | ---- |
| ...     | ...       | ...            | ...  | ...       | ...  |

(2) 현재 구현 파일 목록 (절대경로):
- <file1>
- <file2>
- ...

**작업**:

1. spec.md 의 §<단위> 본문 + 참조 §5/§6/§7/§8/§9 항목을 다시 읽기.
2. 현재 구현 파일을 모두 읽기.
3. spec ↔ 코드를 항목 단위로 1:1 대조 (단위 전체 대상. "이번 변경분만" 식 스코프 제한 없음).
4. 차이 발견 시 아래 3분류로 보고:

   - (a) **코드 위반**: spec 명확한데 코드가 빠뜨림·다름.
   - (b) **spec 내부 모순**: §A 정의 vs §B 정의 충돌. (양쪽 인용 명시)
   - (c) **spec 미정의 + 코드 임의 채움**: spec 본문에 정의·분기·경계 케이스 명시 없는데 코드가 채움.

5. 보고 형식 (각 차이 1건마다):

   ### 차이 N: <도메인 어휘로 표현된 한줄 요약>
   - 분류: (a) / (b) / (c)
   - spec 위치: §X.x line Y
   - spec 인용: "..."
   - 코드 위치: <file:line>
   - 코드 동작: <도메인 어휘로>
   - 비고: (b) 면 모순 상대 인용 함께

6. 차이 0건이면 `차이 없음, 검증 통과` 1줄만 응답.

**제약**:

- 보고 본문에 코드 식별자(변수명·SQL 함수명·타입 키워드 등) 노출 금지. 모두 도메인 어휘로 풀어 쓸 것.
- "코드가 spec 위반" 으로 단정 금지. 3분류 중 어디에 해당하는지 명시.
- spec 본문에 인용할 수 있는 문구가 없으면 (b)(c) 후보로 처리.

**산출**: 위 3분류 보고 목록 또는 `차이 없음, 검증 통과`.

결과 처리

subagent 출력을 받은 후 분류별로 처리:

• (a) 코드 위반: 5단계 사이클로 재진입하여 코드 수정.
• (b) spec 내부 모순: 사용자에게 1건씩 보고 (모순 양쪽 인용 + 어느 쪽이 합리적인지 의견) → 처리 방향 묻기 (spec 수정 / 코드 정정) → spec 수정 시 2단계 "spec 수정 절차" 적용.
• (c) spec 미정의 + 코드 임의 채움: 사용자에게 1건씩 질문 → 결정 수령 → 2단계 "spec 수정 절차" 로 인라인 결정 반영 → 5단계 사이클 재진입.

(b)(c) 모두 한꺼번에 묶음 보고 금지. 1건씩 합의.

처리 완료 후 6단계 재실행 (재대조). 차이 0건 확인 후 7단계 진입.

7단계: 코드 정리

• 횡단 중복: 작업 사이클 사이에 흩어진 동일 로직 합치기.
• 계층별 drift 점검: 다항목 작업 누적으로 5단계의 3-B 채택 패턴에서 이탈한 계층이 있는지 4계층 전체를 횡단 점검. 이탈분만 채택 패턴으로 수정 (개별 항목 정합은 5단계에서 선반영).
  • 도메인 모델: 필드·타입·제약·네이밍 패턴 일치.
  • 데이터 접근: 함수 시그니처·쿼리 패턴·에러 처리 일치.
  • 본체: 컴포넌트·트리거·처리 단계·핸들러·의존성 패턴 일치.
  • 테스트: 러너·assertion·mock 패턴 일치.
• 불필요한 코드: 미사용 import·변수·주석, 요구가 없는 옵션·추상화 제거. 작업 결과로 어디서도 참조되지 않는 파일도 포함 (검사 범위는 전체 워크스페이스). 단 파일 단위 삭제는 후보 목록을 사용자에게 보고 → 확정분만 삭제 (dynamic import·마이그레이션·문서 자산 등 보존 대상은 사용자가 제외 지시).
• 매뉴얼 권위 규약 (횡단): 3-A 매뉴얼 규약 중 여러 항목·계층에 걸쳐 작성 후에만 드러나는 위반만 점검·수정 (개별 항목 준수는 5단계에서 선반영).

정리 후 단위 테스트 재실행하여 회귀 없음을 확인.

8단계: 시연 검증

시연 스킵 조건: 대상 단위에 세션 시작 시점부터 이미 [구현] 마커가 있었고(이전 시연 완료) + 이번 세션이 코드 파일을 하나도 생성·수정하지 않음(5단계 편집 0건 + 6단계 (a) 코드 위반 0건) → 본 단계 스킵 후 9단계 진입. 마커가 없던 단위(첫 검증)는 코드 변경이 없어도 시연 수행.

사용자에게 요청: "dev 서버를 실행하고 접속 주소를 알려달라."

사용자가 띄워 주소를 회신할 때까지 대기. 사용자가 본 단계의 스킵을 지시하거나 시연 불가 환경이 명시되면 본 단계 스킵 후 9단계 진입.

주소 회신 후 playwright-cli 로 §4.x/§5.x/§6.x 동작 시나리오를 직접 시연:

• 기능 개요·동작의 사용자 흐름을 1회씩 수행.
• 화면 항목·와이어프레임 위치와 실제 렌더 결과를 비교.
• §5.x (자동 처리) 는 트리거 발생 → 결과 확인.
• §6.x (공통·기반 기능): 부수효과 동작은 트리거 발동 → 결과·기록 확인, 상시 구성은 앱 부팅 후 구성 반영 확인.

회귀 발견 시 5단계로 회귀 → 수정 → 재시연.

9단계: 완료 보고

• 대상 spec.md 의 해당 §4.x / §5.x / §6.x 헤더(제목 + (장치) 표기 뒤)에 [구현] 마커를 부착. 이미 [구현] 이 있으면 그대로 둠 (날짜·[확정] 부착 안 함).
• 만들거나 갱신한 파일 목록 보고 (마커를 부착한 spec.md 포함).
• 본 세션에서 2단계·6단계 "spec 수정 절차" 로 의존 §4.x/§5.x/§6.x 마커가 제거된 항목이 있으면 영향 단위 목록 보고 (재구현 필요 알림). 없으면 생략.
• 시연에서 사용자 확인이 끝나면 종료.