POC-First 개발 워크플로우

JikiME-ADK의 Greenfield 기능 개발을 위한 단계별 접근법입니다.

개요

POC-First는 새로운 기능을 처음부터 만들 때 사용하는 구조화된 워크플로우입니다. 테스트를 먼저 작성하는(TDD) 대신, 먼저 동작하게 만들고 체계적으로 개선합니다.

사용 시점

상황	워크플로우	이유
새로운 기능 개발	POC-First	보존할 기존 동작이 없음
새 API 엔드포인트	POC-First	Greenfield 구현
새 UI 컴포넌트	POC-First	먼저 만들고, 나중에 테스트
기존 코드 리팩토링	DDD	동작 보존 필수
버그 수정	TDD	회귀 테스트 우선
레거시 마이그레이션	DDD	변경 전 특성화 필수

5단계 구조

┌─────────────────────────────────────────────────────────────┐
│                  POC-First 워크플로우                         │
│                                                             │
│  Phase 1        Phase 2        Phase 3        Phase 4       │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌─────────┐  │
│  │ 동작하게 │──▶│ 리팩토링 │──▶│ 테스팅   │──▶│ 품질    │  │
│  │  만들기  │   │          │   │          │   │  검증   │  │
│  │ (50-60%) │   │ (15-20%) │   │ (15-20%) │   │(10-15%) │  │
│  └──────────┘   └──────────┘   └──────────┘   └─────────┘  │
│       │                                            │        │
│       │              Phase 5                       │        │
│       │         ┌──────────────┐                   │        │
│       └────────▶│ PR 라이프사이클│◀──────────────────┘        │
│                 └──────────────┘                            │
└─────────────────────────────────────────────────────────────┘

Phase 1: 동작하게 만들기 (50-60%)

목표: 핵심 기능을 end-to-end로 동작시키기

동작하게 만드는 것에만 집중
하드코딩 허용
엣지 케이스, 에러 처리 생략
섣부른 최적화 금지
console.log 자유롭게 사용

완료 조건: Happy path가 동작. 이해관계자에게 데모 가능.

Phase 2: 리팩토링 (15-20%)

목표: 동작을 변경하지 않고 코드 정리

하드코딩 값을 상수/설정으로 추출
큰 파일 분리 (400줄 초과 시)
네이밍 컨벤션 적용
디버그 구문 제거
적절한 타입 추가

완료 조건: 코드가 깔끔하고, 잘 정리되어 있으며, 여전히 동작.

Phase 3: 테스팅 (15-20%)

목표: 포괄적인 테스트 커버리지 확보

비즈니스 로직 단위 테스트 (80%+ 커버리지)
API 엔드포인트 통합 테스트
핵심 사용자 플로우 E2E 테스트
엣지 케이스 및 에러 시나리오 커버리지

완료 조건: 테스트 스위트 통과, 커버리지 80% 이상.

Phase 4: 품질 검증 (10-15%)

목표: 프로덕션 수준의 품질 확보

린트 에러, 타입 에러 제로
보안 감사 통과
성능 기준 충족
문서 작성 완료

품질 게이트 체크리스트:

[ ] 빌드 통과 (에러 제로)
[ ] 전체 테스트 통과, 커버리지 >= 80%
[ ] 린트 클린 (에러/경고 제로)
[ ] 타입 체크 클린
[ ] 크리티컬/하이 보안 취약점 없음
[ ] 주요 함수 문서화

Phase 5: PR 라이프사이클

목표: PR 생성 및 머지

PR 라이프사이클 자동화 워크플로우를 사용하여 자동화.

의도 분류 (Intent Classification)

시작 전 워크플로우가 자동으로 의도를 분류합니다:

새로운 코드인가? (기존 동작 없음)
  ├── 예 → POC-First 워크플로우
  └── 아니오 → 기존 코드를 수정하는가?
        ├── 예 → DDD 워크플로우 (ANALYZE-PRESERVE-IMPROVE)
        └── 회귀 테스트 필요? → TDD 워크플로우 (RED-GREEN-REFACTOR)

단계 전환 규칙

단계 건너뛰기 불가: Phase 1 → 2 → 3 → 4 → 5 (엄격한 순서)
단계 게이트 필수: 각 단계는 [VERIFY] 체크포인트로 종료
회귀 금지: 이전 단계의 검증이 여전히 통과해야 함
사용자 확인: Phase 1 완료 시 사용자 확인 필요

사용법

슬래시 커맨드

bash

# 전체 POC 워크플로우
/jikime:poc "JWT 사용자 인증 시스템"

# 특정 단계부터 시작
/jikime:poc "인증 시스템" --phase 3

# PR 단계 생략
/jikime:poc "인증 시스템" --skip-pr

스킬로 사용

다른 커맨드나 에이전트에서 스킬로 로드:

Skill("jikime-workflow-poc")

태스크 포맷 연동

POC 워크플로우 내 모든 태스크는 구조화된 태스크 포맷의 Do/Files/Done when/Verify/Commit 5필드와 [VERIFY] 품질 체크포인트를 사용합니다.

다른 워크플로우와 비교

측면	POC-First	TDD	DDD
시작점	동작하는 코드	실패하는 테스트	기존 동작 분석
테스트 시점	Phase 3 (동작 후)	구현 전	수정 전
적합한 경우	새로운 기능	명확한 스펙의 새 함수	기존 코드 리팩토링
리스크	기술 부채 (단계로 완화)	과도한 테스팅	과도한 분석
데모까지 속도	가장 빠름	보통	가장 느림

POC-First 개발 워크플로우 ​

개요 ​

사용 시점 ​

5단계 구조 ​

Phase 1: 동작하게 만들기 (50-60%) ​

Phase 2: 리팩토링 (15-20%) ​

Phase 3: 테스팅 (15-20%) ​

Phase 4: 품질 검증 (10-15%) ​

Phase 5: PR 라이프사이클 ​

의도 분류 (Intent Classification) ​

단계 전환 규칙 ​

사용법 ​

슬래시 커맨드 ​

스킬로 사용 ​

태스크 포맷 연동 ​

다른 워크플로우와 비교 ​

관련 문서 ​