kjh2064/KArtSell.Aegis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add WBS Execution Procedures (Comprehensive Framework)

Browse Source 
## 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 <noreply@anthropic.com>
This commit is contained in:
김재현
2026-08-04 00:22:04 +09:00
parent e9f72e60cc
commit ca2aeaeebb
1 changed files with 559 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CURRENT/WBS_EXECUTION_PROCEDURES.md
+559
View File
@@ -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 메시지 형식
**필수 요소:**
```
<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