# WBS 실행 절차 가이드 (WBS Execution Procedures)

**Governance:** AGENTS.md v16.0 + CLAUDE.md  
**Purpose:** 누락 없이 절차적으로 WBS 작업을 추적하고 완료하기 위한 하네스  
**Effective Date:** 2026-08-04

---

## 📋 목차

1. [WBS 작업 흐름 (Workflow)](#wbs-작업-흐름)
2. [Step 1: 작업 계획 (Planning)](#step-1-작업-계획)
3. [Step 2: 작업 실행 (Execution)](#step-2-작업-실행)
4. [Step 3: 증거 수집 (Evidence Collection)](#step-3-증거-수집)
5. [Step 4: WBS 추적 업데이트 (Tracking Update)](#step-4-wbs-추적-업데이트)
6. [Step 5: Commit & 메모리 기록 (Commit & Memory)](#step-5-commit--메모리-기록)
7. [완료 기준 (Definition of Done)](#완료-기준)
8. [검증 체크리스트 (Verification Checklist)](#검증-체크리스트)

---

## WBS 작업 흐름

```
┌─────────────────────────────────────────────────────┐
│ Step 1: 작업 계획                                    │
│ - WBS_MASTER.csv에서 다음 항목 선택                 │
│ - 의존성 확인 (Dependency)                          │
│ - 완료 기준 정의 (Acceptance_Evidence)              │
└────────────────┬────────────────────────────────────┘
                 │
┌─────────────────v────────────────────────────────────┐
│ Step 2: 작업 실행                                    │
│ - 코드 작성/테스트/빌드                             │
│ - 176/176 테스트 PASS 확인                          │
│ - git status 검증 (clean or staged)                 │
└────────────────┬────────────────────────────────────┘
                 │
┌─────────────────v────────────────────────────────────┐
│ Step 3: 증거 수집                                    │
│ - 산출물 위치 기록 (Artifact)                       │
│ - 수용 기준 검증 (Acceptance_Evidence)              │
│ - 부족한 증거 식별                                   │
└────────────────┬────────────────────────────────────┘
                 │
┌─────────────────v────────────────────────────────────┐
│ Step 4: WBS 추적 업데이트                           │
│ - WBS_PROGRESS_TRACKER.csv 업데이트                │
│  └─ Status, Completion_Date, Evidence_Link, Notes  │
└────────────────┬────────────────────────────────────┘
                 │
┌─────────────────v────────────────────────────────────┐
│ Step 5: Commit & 메모리 기록                        │
│ - git commit (WBS_ID 포함)                         │
│ - 메모리 파일 업데이트                             │
│ - MEMORY.md 인덱스 갱신                             │
└─────────────────────────────────────────────────────┘
```

---

## Step 1: 작업 계획

### 1.1 WBS 항목 선택

**조건:**
- [ ] WBS_MASTER.csv에서 `Status = PLANNED` 항목 찾기
- [ ] `Dependency` 컬럼 확인 (의존 항목이 모두 완료되었는가?)
- [ ] `Gate` 확인 (현재 Gate 레벨 이상인가?)

**예시:**
```
WBS_ID: AEG-VS-00-04
Task: Vertical Slice API/Application/SQL 구현
Dependency: AEG-VS-00-03 (완료됨 ✅)
Gate: G0 (현재 Gate 레벨 ✅)
Status: ✅ 선택 가능
```

### 1.2 완료 기준 정의

**WBS_MASTER.csv의 다음 컬럼을 읽고 이해:**

| 컬럼 | 예시 | 용도 |
|------|------|------|
| **Acceptance_Evidence** | "인증·권한·멱등·트랜잭션·ProblemDetails·낙관적 동시성·correlation이 수용기준과 일치" | 완료 조건 |
| **Artifact** | "HEALTH-01; Endpoint/Validator/Application/Dapper/Outbox" | 산출물 목록 |
| **Test_ID** | "T-ARCH-001" | 테스트 케이스 |

### 1.3 작업 계획 기록

**로컬 메모 파일 생성:**
```markdown
## WBS_ID: AEG-VS-00-04
- **Task:** Vertical Slice API/Application/SQL 구현
- **Slice:** PlatformBootstrap (Host/BuildingBlocks)
- **Acceptance_Evidence:** 인증·권한·멱등·트랜잭션·correlation 검증
- **Artifacts:** 
  - src/KArtSell.Host/Features/...
  - tests/KArtSell.*.Tests/...
- **Target Gate:** G0 (Host startup)
- **Status:** IN_PROGRESS
- **Start Date:** 2026-08-04
```

---

## Step 2: 작업 실행

### 2.1 코드 작성 및 테스트

**AGENTS.md v16.0 "Work Decision Checklist" 13가지 기준 적용:**

- [ ] **SOLID:** 단일 책임 확인
- [ ] **Complexity:** 순환 복잡도 ≤ 10
- [ ] **Audit:** Evidence/Revision 추적
- [ ] **Necessity:** 근거 있는 변경인가?
- [ ] **Normalization:** Write 3NF, Read projection
- [ ] **Simplicity:** 위→아래 가독성
- [ ] **Pattern:** 수직 슬라이스 표준
- [ ] **Guardrails:** Source/Assumption/Decision 기록
- [ ] **Traceability:** Artifact 보존
- [ ] **Safety:** Idempotent, rollback-safe
- [ ] **Maturity:** Contract/Schema/Test first
- [ ] **Right Way:** 정공법 (shortcut 없음)
- [ ] **Debt:** Tech debt 등록

### 2.2 테스트 검증

**필수 확인:**

```bash
# 1. 전체 테스트 실행
dotnet test KArtSell.sln -c Release

# 2. 결과 확인
✅ 176/176 tests PASS (또는 실제 숫자)

# 3. Frontend 테스트
cd frontend
pnpm test
✅ 모든 tests PASS

# 4. Build 확인
dotnet build KArtSell.sln -c Release
✅ Build Success (0 errors, 0 warnings)
```

### 2.3 Git 상태 검증

```bash
# 1. 상태 확인
git status
✅ On branch main
✅ All changes staged or working tree clean

# 2. 변경사항 확인
git diff --cached
✅ 의도된 파일만 변경됨

# 3. 커밋 이력 확인
git log --oneline -5
✅ 마지막 커밋이 명확한 메시지를 가짐
```

---

## Step 3: 증거 수집

### 3.1 산출물 확인

**WBS_MASTER.csv의 "Artifact" 컬럼에서 산출물 위치 확인:**

| Artifact | 경로 | 상태 |
|----------|------|------|
| HEALTH-01 | src/KArtSell.Host/Features/Health/HealthEndpoint.cs | ✅ 있음 |
| T-ARCH-001 | tests/KArtSell.ArchitectureTests/... | ✅ 있음 |
| MIG-0000 | src/KArtSell.DbMigrator/0000_Bootstrap.sql | ✅ 있음 |

### 3.2 수용 기준 검증

**"Acceptance_Evidence"의 각 항목을 체크:**

```
Acceptance_Evidence: "인증·권한·멱등·트랜잭션·ProblemDetails·낙관적 동시성·correlation이 수용기준과 일치"

검증:
☐ 인증: X-KArtSell-User 헤더 처리 ✅ (DevelopmentHeaderAuthenticationHandler)
☐ 권한: Role-based authorization ✅ (X-KArtSell-Role)
☐ 멱등: IdempotencyKey 사용 ✅ (Command에 포함)
☐ 트랜잭션: DB transaction 경계 명확 ✅ (Handler에서 처리)
☐ ProblemDetails: HTTP error response ✅ (FastEndpoints)
☐ 낙관적 동시성: ETag/version 검증 ✅ (Entity에 포함)
☐ Correlation: CorrelationId 전파 ✅ (Serilog)
```

### 3.3 부족한 증거 식별

**누락 확인:**

```
예: WBS_ID AEG-VS-00-06 (Vue feature 구현)
- Acceptance_Evidence: "loading/empty/partial/stale/warn/error/401/403/409/expired/readonly와 접근성·권한 경계가 검증됨"
- 현황: 아직 구현 안 됨 ❌
- 상태: PLANNED (구현 전까지 유지)
- 메모: "Blocked: Requires frontend implementation. Depends on AEG-VS-00-04 completion."
```

---

## Step 4: WBS 추적 업데이트

### 4.1 WBS_PROGRESS_TRACKER.csv 업데이트

**수행:**

```bash
# 1. 파일 열기
nano docs/CURRENT/CATALOGS/WBS_PROGRESS_TRACKER.csv
# 또는 Excel/Google Sheets

# 2. 다음 컬럼 업데이트:
WBS_ID          → (변경 없음)
Status          → COMPLETED / IN_PROGRESS / BLOCKED / RUNNING
Completion_Date → YYYY-MM-DD 또는 TBD
Evidence_Link   → 산출물 경로 (src/..., docs/..., commit hash)
Owner           → 담당자
Notes           → 완료 상황 / 차단 사유 / 진행 상황

# 3. 예시:
AEG-VS-00-04,S0,VS-00,Vertical Slice API/Application/SQL 구현,COMPLETED,2026-08-04,POST /api/shadow-runs (Job 976),BE Lead,"Endpoint: /api/shadow-runs. Handler: ShadowRunCommandHandler. Tests: 176/176 PASS."
```

### 4.2 상태 정의

| Status | 의미 | 다음 액션 |
|--------|------|----------|
| **PLANNED** | 아직 시작 안 됨 | 의존성 확인 후 실행 시작 |
| **IN_PROGRESS** | 작업 중 | 증거 수집 후 COMPLETED로 전환 |
| **COMPLETED** | 완료, 증거 확보 | WBS_MASTER.csv도 업데이트 고려 |
| **BLOCKED** | 의존성 미충족 | 차단 사유 기록, 의존 항목 추적 |
| **RUNNING** | 장시간 자동 진행 | Job/workflow ID 기록, 완료 예상일 메모 |

### 4.3 Evidence_Link 형식

```
# 코드 경로
src/KArtSell.Host/Features/ShadowRuns/Endpoint.cs

# 커밋 해시
commit f573a1e

# API 엔드포인트
POST /api/shadow-runs (HTTP 202)

# Job ID
Job 976 (Hangfire)

# 테스트 통과
176/176 tests PASS

# 로그 증거
docs/operational-runbook.md (Section: Scenario 3 Job Stuck)
```

---

## Step 5: Commit & 메모리 기록

### 5.1 Commit 메시지 형식

**필수 요소:**
```
<type>: <subject> (WBS_ID 포함)

## Summary
- ✅ <완료 항목 1>
- ✅ <완료 항목 2>
- ⏳ <진행 중 항목>

## AGENTS.md v16.0 Compliance
- ✅ <적용된 기준 1>
- ✅ <적용된 기준 2>

## Evidence
- Artifacts: <산출물 경로>
- Tests: 176/176 PASS
- Gates Verified: <Gate 번호>

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
```

**예시:**
```
feat: Implement AEG-VS-00-04 Vertical Slice API (Shadow Run)

## Summary
- ✅ Shadow Run API endpoint (/api/shadow-runs)
- ✅ Handler + Policy + Dapper SQL
- ✅ Idempotent job creation (Job 976)

## AGENTS.md v16.0 Compliance
- ✅ SOLID (single responsibility: ShadowRunCommandHandler)
- ✅ Complexity (cyclomatic ≤ 10)
- ✅ Audit (CorrelationId + Evidence tracking)
- ✅ Safety (idempotent, rollback-safe)

## Evidence
- Artifacts: src/KArtSell.Host/Features/ShadowRuns/
- Tests: 176/176 PASS (40 unit + 95 integration + 40 frontend + 1 E2E)
- Gates Verified: Gate 1-4 (HTTP 202, Job 976 queued)

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
```

### 5.2 메모리 파일 생성

**새 메모리 파일:** `session_2026_08_04_wbs_update_aeg_vs_00_04.md`

```markdown
---
name: wbs_completion_aeg_vs_00_04
description: ✅ COMPLETED: AEG-VS-00-04 Vertical Slice API (Shadow Run API endpoint, 176/176 tests, Job 976)
metadata:
  type: project
---

# WBS Completion: AEG-VS-00-04

**WBS_ID:** AEG-VS-00-04  
**Slice:** PlatformBootstrap (VS-00)  
**Task:** Vertical Slice API/Application/SQL 구현  
**Status:** ✅ COMPLETED  
**Date:** 2026-08-04  

## Acceptance Evidence

- ✅ **인증:** DevelopmentHeaderAuthenticationHandler (X-KArtSell-User)
- ✅ **권한:** Role-based (X-KArtSell-Role: Admin)
- ✅ **멱등:** IdempotencyKey in ShadowRunCommand
- ✅ **트랜잭션:** DB transaction (Handler boundary)
- ✅ **ProblemDetails:** FastEndpoints HTTP error handling
- ✅ **낙관적 동시성:** ETag/version in response
- ✅ **Correlation:** CorrelationId tracking (Serilog)

## Artifacts

- `src/KArtSell.Host/Features/ShadowRuns/`
  - Endpoint.cs (Route: POST /api/shadow-runs)
  - Handler.cs (ShadowRunCommandHandler)
  - Command.cs (ShadowRunCommand)
  - Policy.cs (Business logic)
  - Dapper SQL (Append-only event log)

## Evidence Link

- **API:** POST /api/shadow-runs → HTTP 202 Accepted
- **Job:** Job 976 created (Hangfire)
- **Tests:** 176/176 PASS
- **Commit:** f573a1e
- **Gate:** Gate 1-4 ✅

## Dependencies

- ✅ Completed: AEG-VS-00-03 (Domain implementation)
- ✅ Completed: AEG-X-004 (DbUp migrations)
- ⏳ Next: AEG-VS-00-05 (Event/Job/Inbox implementation)
```

### 5.3 MEMORY.md 인덱스 업데이트

**추가:**
```markdown
- [WBS Completion: AEG-VS-00-04](wbs_completion_aeg_vs_00_04.md) — ✅ Vertical Slice API (Shadow Run), 176/176 tests, Job 976, Gates 1-4 verified
```

---

## 완료 기준

### Definition of Done (DoD)

작업을 "완료"로 마킹하기 전에 다음을 모두 확인:

**Code Quality:**
- [ ] 176/176 tests PASS (또는 기존 통과 테스트 수 이상)
- [ ] `git status` clean (모든 변경이 staged/committed)
- [ ] AGENTS.md v16.0 13가지 기준 적용
- [ ] 코드 리뷰 검토 (self-review 최소)

**Artifact & Evidence:**
- [ ] WBS_MASTER.csv의 "Artifact" 모두 생성됨
- [ ] "Acceptance_Evidence" 모든 항목 검증됨
- [ ] 산출물 경로를 WBS_PROGRESS_TRACKER.csv에 기록

**Git & Memory:**
- [ ] `git commit` with WBS_ID 포함
- [ ] Commit 메시지에 AGENTS.md 기준 명시
- [ ] 메모리 파일 생성 (session_YYYYMMDD_wbs_*.md)
- [ ] MEMORY.md 인덱스 업데이트

**Traceability:**
- [ ] Evidence_Link: 산출물/테스트/Job ID 기록
- [ ] Status: WBS_PROGRESS_TRACKER.csv 업데이트
- [ ] Notes: 완료 상황 / 차단 사유 / 다음 단계

---

## 검증 체크리스트

### Pre-Completion Verification

작업 완료 전 다음 체크리스트를 실행:

```bash
# 1. Tests
$ dotnet test KArtSell.sln -c Release
✅ All tests PASS (expected count?)

# 2. Build
$ dotnet build KArtSell.sln -c Release
✅ 0 errors, 0 warnings

# 3. Git Status
$ git status
✅ On branch main, working tree clean (or staged changes only)

# 4. Commit Message
$ git log --oneline -1
✅ WBS_ID + AGENTS.md criteria mentioned

# 5. WBS Tracker
$ grep "AEG-VS-00-04" docs/CURRENT/CATALOGS/WBS_PROGRESS_TRACKER.csv
✅ Status: COMPLETED, Completion_Date: YYYYMMDD, Evidence_Link populated

# 6. Memory File
$ ls -la docs/memories/session_*_wbs_*.md
✅ Latest session memory exists

# 7. MEMORY.md Index
$ grep "WBS Completion" C:\Users\kjh20\.claude\projects\D--JobRoomz-KArtSell-Aegis\memory\MEMORY.md
✅ Latest WBS completion indexed
```

### Post-Completion Review

완료 후 다음을 검토:

- [ ] **Dependency Chain:** 다음 PLANNED 항목이 이제 시작 가능한가?
- [ ] **Gate Progression:** 현재 Gate 다음 레벨로 진행 가능한가?
- [ ] **No Gaps:** Acceptance_Evidence에서 누락된 항목이 있는가?
- [ ] **Traceability:** Evidence_Link를 따라가면 산출물을 찾을 수 있는가?

---

## 예시: 완전한 WBS 작업 흐름

### Scenario: AEG-VS-00-04 완료

**Step 1: 계획**
```
- WBS_ID: AEG-VS-00-04
- Status: PLANNED → IN_PROGRESS
- Dependency: AEG-VS-00-03 (✅ 완료됨)
- Task: "Vertical Slice API/Application/SQL 구현"
```

**Step 2: 실행**
```
- POST /api/shadow-runs endpoint 작성
- ShadowRunCommandHandler 구현
- 176/176 tests PASS 달성
```

**Step 3: 증거**
```
- Artifacts: src/KArtSell.Host/Features/ShadowRuns/
- Acceptance: 인증·권한·멱등·트랜잭션 모두 ✅
- Evidence: HTTP 202, Job 976, commit f573a1e
```

**Step 4: 추적 업데이트**
```csv
AEG-VS-00-04,S0,VS-00,Vertical Slice API/Application/SQL 구현,COMPLETED,2026-08-04,POST /api/shadow-runs (Job 976),BE Lead,"Endpoint verified, 176/176 PASS"
```

**Step 5: Commit**
```
git commit -m "feat: Implement AEG-VS-00-04 Vertical Slice API (WBS)

- ✅ POST /api/shadow-runs endpoint
- ✅ AGENTS.md v16.0 compliance (SOLID, Audit, Safety)
- ✅ 176/176 tests PASS
- ✅ Job 976 (Shadow Run) created

Evidence: HTTP 202, commit f573a1e, Gate 1-4 verified

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>"
```

**Step 5-2: 메모리**
```
Create: session_2026_08_04_wbs_aeg_vs_00_04.md
Update: MEMORY.md index
```

---

## FAQ

### Q1: 언제 BLOCKED로 마킹하나요?
**A:** Dependency가 미충족일 때
```
예: AEG-VS-07-01 (ManageClientIPS)
Dependency: AEG-X-001 (NOT completed)
Status: BLOCKED
Notes: "Depends on AEG-X-001 (Governance) completion"
```

### Q2: RUNNING 상태는?
**A:** 장시간 자동화 작업 (Job/workflow)
```
예: PHASE-1-SHADOW-RUN
Completion_Date: TBD-50-90-days
Status: RUNNING
Evidence: Job 976 (Hangfire), expected completion ~2026-10-23
```

### Q3: 부분 완료는?
**A:** IN_PROGRESS로 유지, 차단 사유 기록
```
예: AEG-VS-00-06 (Vue feature)
Status: PLANNED (구현 시작 안 함)
또는
Status: IN_PROGRESS, Notes: "FE implementation 50% complete, blocked by design review"
```

### Q4: 의존성이 여러 개면?
**A:** 모두 COMPLETED여야 시작 가능
```
AEG-VS-09-01 (BuildEvidenceSnapshot)
Dependency: VS-03, VS-04, VS-05, VS-06 (모두 완료 필요)
Status: BLOCKED
```

---

## 참고 문서

- **AGENTS.md v16.0:** Decision Criteria, Traceability (기준 #9)
- **CLAUDE.md:** WBS Optimization Principle, PRODUCTION_READINESS
- **WBS_MASTER.csv:** 전체 작업 정의 (170+ 항목)
- **WBS_PROGRESS_TRACKER.csv:** 진행률 추적 (Source of Truth)

---

**버전:** 1.0  
**적용일:** 2026-08-04  
**관리:** AGENTS.md v16.0 Governance