KArtSell.Aegis/docs/CURRENT/WBS_EXECUTION_PROCEDURES.md

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

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

---

📋 목차

1. WBS 작업 흐름 (Workflow)
2. Step 1: 작업 계획 (Planning)
3. Step 2: 작업 실행 (Execution)
4. Step 3: 증거 수집 (Evidence Collection)
5. Step 4: WBS 추적 업데이트 (Tracking Update)
6. Step 5: Commit & 메모리 기록 (Commit & Memory)
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 작업 계획 기록

로컬 메모 파일 생성:

## 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 테스트 검증

필수 확인:

# 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 상태 검증

# 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 업데이트

수행:

# 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

---
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 인덱스 업데이트

추가:

- [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

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

# 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: 추적 업데이트

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