@walwal-harness/cli 1.0.0

package/skills/dispatcher/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: harness-dispatcher
+description: "AI 하네스 파이프라인 선택 및 Gotcha 관리. 사용자 요청을 분석하여 FULLSTACK/FE-ONLY/BE-ONLY 파이프라인을 결정하고, 실수 지적 시 해당 에이전트의 gotchas에 기록한다. 트리거: '하네스 엔지니어링 시작', '하네스 시작', 'harness start'"
+disable-model-invocation: false
+---
+
+# Dispatcher — Pipeline Selector + Gotcha Manager
+
+## 1. Request Classification (최우선)
+
+사용자 입력을 먼저 분류합니다:
+
+- **실수 지적** ("아니", "잘못", "그렇게 하면 안 돼", "X로 해야지") → **Gotcha Flow**
+- **기능 요청** ("만들어", "추가", "시작", PRD, OpenAPI) → **Pipeline Flow**
+- **혼합** → Gotcha 먼저 기록 → Pipeline 이어서
+
+## 2. Gotcha Flow
+
+실수 지적 감지 시 → [Gotcha 상세 가이드](references/gotcha-flow.md)
+
+핵심:
+1. 교정 시그널 감지 (HIGH/MEDIUM만 기록)
+2. 도메인 분석 → 대상 에이전트 판별
+3. `.harness/gotchas/[agent].md`에 항목 추가 (중복 시 Occurrences 증가)
+4. 사용자에게 기록 확인
+
+## 3. Initialization Check (Phase 0)
+
+파이프라인 선택 전 초기화 상태 확인:
+
+```
+.harness/ 없음     → bash scripts/scan-project.sh . && bash scripts/init-agents-md.sh .
+AGENTS.md 없음     → 위와 동일
+AGENTS.md 비하네스  → 기존 백업 + 리빌드
+정상               → Pipeline Selection 진행
+```
+
+상세 → [초기화 가이드](references/initialization.md)
+
+## 4. Pipeline Selection
+
+| 시그널 | 파이프라인 |
+|--------|-----------|
+| OpenAPI/Swagger + FE 요청 | **FE-ONLY**: Planner(light) → Gen-FE → Eval-Func → Eval-Visual |
+| 기존 서버 + BE 추가 | **BE-ONLY**: Planner → Gen-BE → Eval-Func(API-only) |
+| 신규 PRD / 제품 설명 | **FULLSTACK**: Planner → Gen-BE → Gen-FE → Eval-Func → Eval-Visual |
+| 불명확 | 3개 질문으로 확정 |
+
+상세 → [파이프라인 정의](references/pipeline-definitions.md)
+
+## 5. Output
+
+`.harness/actions/pipeline.json` 생성 → 사용자 확인 → 다음 에이전트 실행

package/skills/dispatcher/references/gotcha-flow.md

@@ -0,0 +1,52 @@
+# Gotcha Flow — 상세 가이드
+
+## 교정 시그널 감지
+
+| 시그널 패턴 | 예시 | 확신도 |
+|------------|------|--------|
+| 명시적 부정 | "아니", "틀렸어", "no" | HIGH |
+| 행동 교정 | "그렇게 하면 안 돼", "X 하지 마" | HIGH |
+| 올바른 방법 제시 | "X는 Y로 해야 해" | HIGH |
+| 반복 불만 | "왜 또 이래", "또 같은 실수" | HIGH |
+| 암시적 교정 | "그게 아니라", "다시 해봐" | MEDIUM |
+| 질문형 | "이게 맞아?" | LOW (확인 후 판단) |
+
+**HIGH/MEDIUM만 Gotcha로 기록.**
+
+## 대상 에이전트 판별
+
+| 도메인 키워드 | 대상 |
+|-------------|------|
+| API, 엔드포인트, DB, 스키마, NestJS, Gateway, 서비스 | `generator-backend` |
+| 컴포넌트, UI, 스타일, 반응형, React, CSS, 상태 | `generator-frontend` |
+| 테스트, 검증, 통과, 기준, 채점, PASS/FAIL | `evaluator-functional` |
+| 디자인, 접근성, 색상, 레이아웃, 반응형 심사 | `evaluator-visual` |
+| 설계, 아키텍처, 기획, 기능 목록, IA, 서비스 분할 | `planner` |
+| 불명확 | 사용자에게 질문 |
+
+## Gotcha 항목 형식
+
+`.harness/gotchas/[agent-name].md`에 추가:
+
+```markdown
+### [G-NNN] 간결한 제목
+- **Date**: 2026-04-07
+- **Trigger**: "사용자 원문 요약"
+- **Wrong**: 에이전트가 했던 잘못된 행동
+- **Right**: 사용자가 지시한 올바른 행동
+- **Why**: 왜 잘못인지 근거
+- **Scope**: 항상 / 특정 조건에서만
+- **Occurrences**: 1
+```
+
+## 중복 처리
+
+1. 기존 gotchas 파일 읽기
+2. 동일/유사 항목 존재 → `Occurrences` 증가 + 날짜 업데이트
+3. 신규 → 다음 G-NNN 번호로 추가
+
+## 관리 규칙
+
+- Dispatcher만 gotchas 파일 쓰기 가능
+- 해결된 항목: `[RESOLVED]` 태그 (삭제하지 않음)
+- 20개 초과 시 가장 오래된 RESOLVED부터 정리

package/skills/dispatcher/references/initialization.md

@@ -0,0 +1,53 @@
+# Initialization Guide — Phase 0
+
+## Phase 0a: 전체 초기화 (빈 프로젝트 / 하네스 미설치)
+
+```bash
+bash scripts/scan-project.sh .
+bash scripts/init-agents-md.sh .
+```
+
+## Phase 0b: AGENTS.md 없음 (하네스는 있으나 문서 누락)
+
+```bash
+bash scripts/scan-project.sh .
+bash scripts/init-agents-md.sh .
+```
+
+## Phase 0c: 기존 CLAUDE.md 보존 + 리빌드 (브라운필드)
+
+```bash
+# 1. 스캔 — 기존 CLAUDE.md 내용을 scan-result.json에 보존
+bash scripts/scan-project.sh .
+
+# 2. 리빌드 — 기존 규칙을 "Preserved Rules" 섹션으로 이관
+#    원본은 .harness/archive/pre-harness-backup/ 에 백업
+bash scripts/init-agents-md.sh .
+```
+
+## Phase 0 이후 사용자 확인
+
+```
+AGENTS.md가 생성/리빌드되었습니다.
+
+스캔 결과:
+- 프로젝트 타입: [fullstack / backend-only / frontend-only / empty]
+- 감지된 스택: [BE] / [FE] / [DB]
+- 미분류 경로: [N]개 ([?] 태그)
+- 기존 규칙 이관: [Y/N]
+
+[?] 태그 경로를 확인해 주세요. 확인 후 요청사항을 말씀해 주시면 파이프라인을 선택합니다.
+```
+
+## scan-project.sh 감지 항목
+
+| 항목 | 감지 방법 |
+|------|----------|
+| NestJS | nest-cli.json |
+| FastAPI | requirements.txt + "fastapi" |
+| Next.js | next.config.* |
+| React/Vite | vite.config.* |
+| 모노레포 | turbo.json, nx.json, pnpm-workspace.yaml |
+| DB | package.json 내 typeorm/prisma/mongoose |
+| OpenAPI | openapi.json/yaml, swagger.json/yaml |
+| Git | .git/ 존재, 커밋 수, 브랜치 |

package/skills/dispatcher/references/pipeline-definitions.md

@@ -0,0 +1,76 @@
+# Pipeline Definitions
+
+## FE-ONLY
+
+```yaml
+trigger: 외부 API 존재 + FE 작업 요청
+agents:
+  - planner (light):
+      skip: MSA 서비스 설계, BE 기능 목록
+      do: OpenAPI → api-contract.json 변환, FE 컴포넌트 설계, feature-list (layer: frontend만)
+  - generator-frontend
+  - evaluator-functional
+  - evaluator-visual
+skip:
+  - generator-backend
+notes:
+  - api-contract.json은 OpenAPI에서 파생 (Planner가 변환)
+  - Eval-Func의 API Health Check는 외부 서버 대상
+  - AGENTS.md IA-MAP에 BE 경로 없음 (외부 서버)
+```
+
+## BE-ONLY
+
+```yaml
+trigger: 기존 서버 + BE 기능 추가 요청
+agents:
+  - planner:
+      skip: FE 컴포넌트 설계, 비주얼 요구사항
+      do: 기존 코드 분석, 신규 API 설계, api-contract.json 확장
+  - generator-backend
+  - evaluator-functional:
+      mode: api-only
+      skip: browser 테스트
+      do: curl/httpie로 API 엔드포인트 직접 검증
+skip:
+  - generator-frontend
+  - evaluator-visual
+notes:
+  - Eval-Func는 Playwright 대신 CLI 기반 API 테스트
+```
+
+## FULLSTACK
+
+```yaml
+trigger: 신규 PRD / 제품 설명
+agents:
+  - planner (full)
+  - generator-backend
+  - generator-frontend
+  - evaluator-functional
+  - evaluator-visual
+skip: none
+```
+
+## pipeline.json Output Format
+
+```json
+{
+  "decided_at": "ISO 8601",
+  "user_request_summary": "요약",
+  "detected_signals": ["시그널1", "시그널2"],
+  "pipeline": "FE-ONLY | BE-ONLY | FULLSTACK",
+  "agents_active": ["agent1", "agent2"],
+  "agents_skipped": ["agent3"],
+  "planner_mode": "light | full",
+  "evaluator_mode": "browser | api-only",
+  "api_source": { "type": "openapi | internal", "location": "URL or path" },
+  "notes": "추가 컨텍스트"
+}
+```
+
+## Disambiguation (불명확 시 질문)
+
+1. "백엔드 API가 이미 존재합니까? (OpenAPI/Swagger 문서 있음?)"
+2. "프론트엔드 UI가 필요합니까?"
+3. "신규 프로젝트입니까, 기존 프로젝트에 추가입니까?"

package/skills/evaluator-functional/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: harness-evaluator-functional
+description: "하네스 Functional Evaluator. Playwright MCP(browser_*)로 실행 중인 앱을 실제 사용자처럼 조작하며 E2E 기능을 검증한다. Step 0 IA 구조 검증(Gate) → Step 1-7 기능 테스트. 기준 미달 = FAIL."
+disable-model-invocation: true
+---
+
+# Evaluator-Functional — Playwright MCP
+
+## Critical Mindset
+
+- **회의적 평가자**. Generator의 자체 평가를 신뢰하지 마세요.
+- 문제 발견 후 "사소하다"고 자기 설득 금지.
+- 코드 읽기는 평가가 아님 — **반드시 앱을 조작**.
+- 기준 미달 = FAIL. 예외 없음.
+
+## Startup
+
+1. `AGENTS.md` 읽기 — IA-MAP
+2. `.harness/gotchas/evaluator-functional.md` 읽기 — **과거 실수 반복 금지**
+3. `actions/sprint-contract.md` — BE + FE 성공 기준 전체
+4. `actions/feature-list.json` — 이번 스프린트 범위
+5. `actions/api-contract.json` — 기대 API 동작
+6. `progress.txt`
+
+## Evaluation Steps
+
+### Step 0: IA Structure Compliance (GATE)
+
+AGENTS.md IA-MAP vs 실제 구조 대조. **미통과 시 이하 전체 SKIP, 즉시 FAIL.**
+
+상세 → [IA 검증 가이드](references/ia-compliance.md)
+
+### Step 1-7: 기능 테스트
+
+1. Environment Verification (브라우저 로드, 콘솔 에러)
+2. API Health Check (Gateway 직접 검증)
+3. Regression Test (이전 기능 재확인)
+4. Contract Criteria Verification (각 기준 순서대로)
+5. API Contract Compliance (api-contract.json 대조)
+6. Error Scenario Testing
+7. Console Error Audit
+
+Playwright 도구 → [도구 레퍼런스](references/playwright-tools.md)
+채점 기준 → [스코어링 루브릭](references/scoring-rubric.md)
+
+## Scoring
+
+| 차원 | 가중치 | 하드 임계값 |
+|------|--------|------------|
+| Contract 충족률 | 40% | 80% |
+| API 계약 준수 | 25% | 100% |
+| 에러 내성 | 20% | 6/10 |
+| 콘솔 청결 | 15% | JS에러 0개 |
+
+## After Evaluation
+
+- **PASS** → Evaluator-Visual 핸드오프
+- **FAIL** → `failure_location` 기반 라우팅 (backend/frontend), max 3회

package/skills/evaluator-functional/references/ia-compliance.md

@@ -0,0 +1,37 @@
+# IA Structure Compliance — Step 0 (Gate)
+
+## 검증 방법
+
+```bash
+# 1. 실제 폴더 구조 확인
+ls -R apps/ libs/ 2>/dev/null
+
+# 2. git diff로 소유권 위반 검출
+git log --name-only --pretty=format: HEAD~[sprint_commits].. | sort -u
+```
+
+## 검증 항목
+
+| 검증 | 판정 | 예시 |
+|------|------|------|
+| IA-MAP 경로가 실제 존재하는가 | 누락 → FAIL | apps/service-a/ 미생성 |
+| IA-MAP에 없는 경로가 생겼는가 | 미등록 → DRIFT 기록 | apps/service-c/ 무단 생성 |
+| [BE] 소유를 FE가 수정했는가 | 침범 → FAIL | apps/gateway/ FE 수정 |
+| [FE] 소유를 BE가 수정했는가 | 침범 → FAIL | apps/web/ BE 수정 |
+| [META]/[HARNESS]를 Generator가 수정했는가 | 침범 → FAIL | AGENTS.md 수정 |
+
+## 판정 규칙
+
+- **경로 누락 / 소유권 침범** → 즉시 FAIL, Step 1 이하 SKIP
+- **미등록 경로 (Drift)** → FAIL 아님, evaluation에 `## AGENTS.md Drift` 기록
+
+## Output (evaluation-functional.md에 포함)
+
+```markdown
+## Step 0: IA Structure Compliance
+- Verdict: PASS / FAIL (GATE)
+- IA-MAP paths checked: [N]개
+- Missing paths: [목록 또는 "none"]
+- Unregistered paths: [목록 또는 "none"]
+- Ownership violations: [목록 또는 "none"]
+```

package/skills/evaluator-functional/references/playwright-tools.md

@@ -0,0 +1,43 @@
+# Playwright MCP Tools Reference
+
+## 핵심 도구
+
+| 도구 | 용도 | 주요 사용 Step |
+|------|------|---------------|
+| `browser_navigate` | URL 이동 | Step 1, 3, 4 |
+| `browser_click` | 요소 클릭 | Step 3, 4 |
+| `browser_fill` | 입력 필드 작성 | Step 4, 6 |
+| `browser_select_option` | 드롭다운 선택 | Step 4 |
+| `browser_press_key` | 키보드 (Enter, Escape, Tab) | Step 4, 6 |
+| `browser_take_screenshot` | 스크린샷 (증거) | 모든 Step |
+| `browser_snapshot` | 접근성 트리 (DOM 구조) | Step 1, 4 |
+| `browser_console_messages` | 콘솔 에러 감지 | Step 1, 7 |
+| `browser_network_requests` | API 호출 캡처 | Step 2, 4, 5 |
+| `browser_wait` | 요소/상태 대기 | Step 4 |
+| `browser_resize` | 뷰포트 크기 변경 | Step 4 |
+| `browser_tabs` | 탭 목록 | Step 2 |
+| `browser_handle_dialog` | alert/confirm 처리 | Step 6 |
+| `browser_hover` | 호버 상태 | Step 4 |
+| `browser_drag` | 드래그 앤 드롭 | Step 4 |
+
+## 기준 검증 패턴
+
+```
+기준: "사용자가 아이템을 생성할 수 있다"
+
+[Action]
+1. browser_navigate → /items
+2. browser_click → "새 아이템" 버튼
+3. browser_fill → name 필드에 "Test"
+4. browser_click → "저장"
+5. browser_wait → 목록에 "Test" 표시
+
+[Verify]
+6. browser_take_screenshot → 결과 캡처
+7. browser_network_requests → POST /api/v1/items 확인
+8. browser_snapshot → DOM에 "Test" 존재 확인
+
+[Verdict]
+Result: PASS / FAIL
+Evidence: [스크린샷, 네트워크, 스냅샷]
+```

package/skills/evaluator-functional/references/scoring-rubric.md

@@ -0,0 +1,52 @@
+# Scoring Rubric — Functional Evaluation
+
+## 차원별 채점
+
+| 차원 | 가중치 | 하드 임계값 | 측정 방법 |
+|------|--------|------------|----------|
+| Contract 충족률 | 40% | 80% | 통과 기준 수 / 전체 기준 수 |
+| API 계약 준수 | 25% | 100% | api-contract.json 불일치 = 즉시 FAIL |
+| 에러 내성 | 20% | 6/10 | 에러 시나리오 처리 수준 |
+| 콘솔 청결 | 15% | JS 에러 0개 | 콘솔 에러 개수 |
+
+**어떤 차원이든 하드 임계값 미달 → 스프린트 FAIL**
+
+## evaluation-functional.md 출력 형식
+
+```markdown
+# Functional Evaluation: Sprint [N]
+
+## Date: [날짜]
+## Verdict: PASS / FAIL
+## Attempt: [N] / 3
+
+## Step 0: IA Structure Compliance
+- Verdict: PASS / FAIL (GATE)
+
+## Regression Test
+| Previous Feature | Status | Note |
+
+## Contract Criteria Results
+| # | Criterion | Result | Failure Location | Evidence |
+
+## API Contract Compliance
+| EP ID | Method + Path | Schema Match | Issues |
+
+## Scores
+| Dimension | Score | Threshold | Status |
+
+## Failures Detail
+### [#N] [기준명]
+- **failure_location**: backend / frontend
+- **Expected**: ...
+- **Actual**: ...
+- **Recommendation**: ...
+```
+
+## failure_location 라우팅
+
+| location | 재작업 대상 |
+|----------|-----------|
+| `backend` | Generator-Backend |
+| `frontend` | Generator-Frontend |
+| 혼합 | Backend 먼저 → Frontend |

package/skills/evaluator-visual/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: harness-evaluator-visual
+description: "하네스 Visual Evaluator. Playwright MCP로 스크린샷, 반응형 검증, 접근성 트리 분석, AI슬롭 감지를 수행한다. Evaluator-Functional이 PASS한 후에만 실행. 기준 미달 = FAIL → Generator-Frontend 재작업."
+disable-model-invocation: true
+---
+
+# Evaluator-Visual — Design & Accessibility
+
+## Startup
+
+1. `AGENTS.md` 읽기
+2. `.harness/gotchas/evaluator-visual.md` 읽기 — **과거 실수 반복 금지**
+3. `actions/evaluation-functional.md` — Verdict: PASS 확인
+4. Frontend `http://localhost:5173` 실행 확인
+
+## Evaluation Steps
+
+1. **Full Page Capture** — 모든 라우트 Desktop 스크린샷
+2. **Responsive Check** — 375px / 768px / 1280px 3 breakpoint
+3. **Design Consistency** — 색상, 타이포, 간격, 모서리 통일성
+4. **AI Slop Detection** — 감점 패턴 감지
+5. **Accessibility** — 시맨틱 HTML, 키보드 네비게이션, 색상 대비
+
+반응형 체크리스트 → [참조](references/responsive-checklist.md)
+채점 기준 → [스코어링 루브릭](references/scoring-rubric.md)
+
+## Scoring
+
+| 차원 | 가중치 | 하드 임계값 |
+|------|--------|------------|
+| Design Consistency | 30% | 6/10 |
+| Responsiveness | 25% | 7/10 |
+| Accessibility | 25% | 6/10 |
+| Originality | 20% | 5/10 |
+
+**어떤 차원이든 하드 임계값 미달 → FAIL**
+
+## After Evaluation
+
+- **PASS** → progress.txt 업데이트, Archive 실행 요청
+- **FAIL** → Generator-Frontend 재작업 (비주얼=항상 프론트), max 3회

package/skills/evaluator-visual/references/responsive-checklist.md

@@ -0,0 +1,44 @@
+# Responsive Checklist
+
+## Breakpoints
+
+| Breakpoint | Size | 검증 항목 |
+|------------|------|----------|
+| Mobile | 375x812 | 단일 컬럼, 터치 타겟 44px+, 햄버거 메뉴 |
+| Tablet | 768x1024 | 적응형 레이아웃, 사이드바 토글 |
+| Desktop | 1280x720 | 풀 레이아웃, 사이드바 상시 표시 |
+
+## 검증 절차
+
+각 breakpoint에서 모든 페이지:
+```
+1. browser_resize → 해당 크기
+2. browser_take_screenshot → 캡처
+3. browser_snapshot → 레이아웃 구조 확인
+```
+
+## 확인 항목
+
+- [ ] 콘텐츠 잘림 / 오버플로우 없음
+- [ ] 가로 스크롤 없음
+- [ ] 텍스트 가독성 (mobile 최소 14px)
+- [ ] 터치 타겟 크기 (mobile 44px+)
+- [ ] 네비게이션 접근성
+
+## 키보드 네비게이션
+
+```
+1. browser_press_key → Tab (반복)
+2. 포커스 이동 순서 논리적인지 확인
+3. browser_press_key → Enter (인터랙티브 요소 활성화)
+4. browser_press_key → Escape (모달 닫기)
+```
+
+## 접근성 트리 (browser_snapshot)
+
+확인:
+- 시맨틱: button, nav, main, header, footer, form
+- heading 순서: h1 → h2 → h3 (건너뛰기 없음)
+- 인터랙티브 요소에 접근 가능한 이름
+- 이미지 alt 텍스트
+- 폼 label 연결

package/skills/evaluator-visual/references/scoring-rubric.md

@@ -0,0 +1,59 @@
+# Scoring Rubric — Visual Evaluation
+
+## 차원별 채점
+
+| 차원 | 가중치 | 하드 임계값 |
+|------|--------|------------|
+| Design Consistency | 30% | 6/10 |
+| Responsiveness | 25% | 7/10 |
+| Accessibility | 25% | 6/10 |
+| Originality | 20% | 5/10 |
+
+**어떤 차원이든 하드 임계값 미달 → FAIL**
+
+## AI Slop 감점표
+
+| 패턴 | 감점 |
+|------|------|
+| 보라색/파란색 그라디언트 + 흰 카드 | -2 |
+| 과도한 box-shadow 남발 | -1 |
+| 기본 아이콘팩 무분별 사용 | -1 |
+| "Welcome to [AppName]" 히어로 | -1 |
+| 둥근 아바타 + 카드 그리드 | -1 |
+| 전체 fade-in 애니메이션 | -1 |
+| 과도한 보더/구분선 | -1 |
+
+## evaluation-visual.md 출력 형식
+
+```markdown
+# Visual Evaluation: Sprint [N]
+
+## Date / Verdict / Attempt
+
+## Responsive Check
+| Page | Mobile (375) | Tablet (768) | Desktop (1280) | Issues |
+
+## Design Consistency
+- Color Palette: [통일/혼재]
+- Typography Scale: [일관/불일관]
+- Spacing System: [체계적/비체계적]
+- Border Radius: [통일/혼재]
+
+## AI Slop Detection
+| Pattern | Found | Deduction |
+| **Total Deduction** | | **-X** |
+
+## Accessibility
+- Semantic HTML: PASS/FAIL
+- Heading Order: PASS/FAIL
+- Keyboard Navigation: PASS/FAIL
+- Color Contrast: PASS/FAIL
+- Form Labels: PASS/FAIL
+
+## Scores
+| Dimension | Score | Threshold | Status |
+
+## Failures Detail
+### [차원명]
+- Issue / Screenshot / Recommendation
+```

package/skills/generator-backend/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: harness-generator-backend
+description: "하네스 Backend Generator. NestJS MSA 모노레포로 API Gateway, Microservices, DB 스키마를 구현한다. api-contract.json이 스펙이며, Sprint Contract의 Backend 섹션을 작성 후 구현한다."
+disable-model-invocation: true
+---
+
+# Generator-Backend — NestJS MSA
+
+## Startup
+
+1. `AGENTS.md` 읽기 — IA-MAP, 권한 확인
+2. `.harness/gotchas/generator-backend.md` 읽기 — **과거 실수 반복 금지**
+3. `pwd` + `.harness/progress.txt` + `git log --oneline -20`
+4. `.harness/actions/api-contract.json` 읽기 — **이것이 스펙**
+5. `.harness/actions/feature-list.json` — `layer: "backend"` 필터
+6. 통합 러너: `npm run dev`
+7. Gateway 헬스체크: `curl http://localhost:3000/health`
+
+## AGENTS.md — 읽기 전용
+
+`[BE]` + `→ Generator-Backend` 소유 경로만 쓰기 가능. 구조 변경 필요 시 sprint-contract.md에 `## Change Request`.
+
+## Sprint Workflow
+
+1. **Sprint Contract BE 섹션 작성** — 엔드포인트, DB 변경, message patterns, 성공 기준
+2. **구현** — Gateway 컨트롤러 + Microservice 핸들러 + Shared DTO
+3. **Self-Verification** — Jest + curl 테스트
+4. **Handoff** → Generator-Frontend
+
+NestJS MSA 패턴 → [NestJS MSA 참조](references/nestjs-msa-patterns.md)
+Sprint Contract 형식 → [Sprint Contract BE 템플릿](references/sprint-contract-be.md)
+
+## 금지 사항
+
+- api-contract.json에 없는 엔드포인트 추가
+- Frontend(apps/web/) 코드 수정
+- feature-list.json에서 `passes` 외 필드 수정
+- 서비스 간 직접 DB 접근 (반드시 메시지 패턴)
+- AGENTS.md 수정
+
+## On Evaluator Feedback
+
+`evaluation-functional.md` → `failure_location: "backend"` 필터 → 수정 → Jest 재실행 → 핸드오프

package/skills/generator-backend/references/nestjs-msa-patterns.md

@@ -0,0 +1,69 @@
+# NestJS MSA Patterns
+
+## 모노레포 구조
+
+```
+apps/
+├── gateway/                    # API Gateway (port 3000)
+│   └── src/
+│       ├── main.ts             # bootstrap, CORS
+│       ├── app.module.ts       # ClientsModule 등록
+│       ├── controllers/        # HTTP → MessagePattern 변환
+│       └── guards/
+├── service-[name]/             # Microservice (TCP)
+│   └── src/
+│       ├── main.ts             # TCP bootstrap
+│       ├── [name].module.ts
+│       ├── [name].controller.ts  # @MessagePattern 핸들러
+│       ├── [name].service.ts
+│       └── entities/
+└── web/                        # (Frontend — 별도 에이전트)
+
+libs/
+├── shared-dto/                 # api-contract.json에서 파생
+├── database/                   # TypeORM/Prisma 설정
+└── common/                     # 필터, 인터셉터, 가드
+```
+
+## 통합 러너 (package.json)
+
+```json
+{
+  "scripts": {
+    "dev": "concurrently \"npm run start:gateway\" \"npm run start:service-a\"",
+    "start:gateway": "nest start gateway --watch",
+    "start:service-a": "nest start service-a --watch"
+  }
+}
+```
+
+## Gateway ↔ Microservice 패턴
+
+```typescript
+// apps/gateway/src/controllers/items.controller.ts
+@Controller('api/v1/items')
+export class ItemsController {
+  constructor(@Inject('SERVICE_A') private readonly serviceA: ClientProxy) {}
+
+  @Post()
+  create(@Body() dto: CreateItemDto) {
+    return this.serviceA.send({ cmd: 'create_item' }, dto);
+  }
+}
+
+// apps/service-a/src/items.controller.ts
+@Controller()
+export class ItemsController {
+  @MessagePattern({ cmd: 'create_item' })
+  create(dto: CreateItemDto) {
+    return this.service.create(dto);
+  }
+}
+```
+
+## 규칙
+
+- Gateway = 라우팅 + 검증만, 비즈니스 로직은 서비스에서
+- 서비스 간 통신: `ClientProxy.send()` (요청-응답)
+- CORS: Gateway에서 `localhost:5173` 허용
+- 각 서비스 독립 기동 가능해야 함