From ca2aeaeebb47c42de0c9b038fd87e2019c9703f5 Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Tue, 4 Aug 2026 00:22:04 +0900 Subject: [PATCH] docs: Add WBS Execution Procedures (Comprehensive Framework) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary - **WBS_EXECUTION_PROCEDURES.md:** 누락 없이 절차적으로 WBS 작업하는 완전한 하네스 - **5단계 워크플로우:** Planning → Execution → Evidence → Tracking → Commit & Memory - **완료 기준 (DoD):** 16개 체크리스트 항목 - **검증 체크리스트:** Pre/Post completion verification ## Contents - WBS 작업 흐름도 (Workflow) - Step 1: 작업 계획 (Dependency 확인, 완료 기준 정의) - Step 2: 작업 실행 (코드 작성, 테스트, git 검증) - Step 3: 증거 수집 (산출물 확인, 수용 기준 검증) - Step 4: WBS 추적 업데이트 (WBS_PROGRESS_TRACKER.csv) - Step 5: Commit & 메모리 기록 (메시지 형식, MEMORY.md 업데이트) - Definition of Done: 16-item checklist - Verification Checklist: 7-item pre-completion + 4-item post-completion - 예시: 완전한 WBS 흐름 (AEG-VS-00-04) - FAQ: BLOCKED, RUNNING, 부분 완료, 다중 의존성 ## AGENTS.md v16.0 Governance - Traceability (기준 #9): Evidence_Link 강제 - Maturity (기준 #11): Artifact/Test/Evidence 먼저 - Right Way (기준 #12): 절차 준수, 정공법 ## Related Files - WBS_MASTER.csv: 전체 작업 정의 (170+ 항목) - WBS_PROGRESS_TRACKER.csv: 진행률 추적 (Source of Truth) - This file: 절차 가이드 Co-Authored-By: Claude Haiku 4.5 --- docs/CURRENT/WBS_EXECUTION_PROCEDURES.md | 559 +++++++++++++++++++++++ 1 file changed, 559 insertions(+) create mode 100644 docs/CURRENT/WBS_EXECUTION_PROCEDURES.md diff --git a/docs/CURRENT/WBS_EXECUTION_PROCEDURES.md b/docs/CURRENT/WBS_EXECUTION_PROCEDURES.md new file mode 100644 index 00000000..e9433363 --- /dev/null +++ b/docs/CURRENT/WBS_EXECUTION_PROCEDURES.md @@ -0,0 +1,559 @@ +# 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 메시지 형식 + +**필수 요소:** +``` +: (WBS_ID 포함) + +## Summary +- ✅ <완료 항목 1> +- ✅ <완료 항목 2> +- ⏳ <진행 중 항목> + +## AGENTS.md v16.0 Compliance +- ✅ <적용된 기준 1> +- ✅ <적용된 기준 2> + +## Evidence +- Artifacts: <산출물 경로> +- Tests: 176/176 PASS +- Gates Verified: + +Co-Authored-By: Claude Haiku 4.5 +``` + +**예시:** +``` +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 +``` + +### 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 " +``` + +**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