poc-forge 0.1.0

AI-native pipeline: idea -> Claude Code-ready docs

PoC Forge

아이디어 → 문서 → 리뷰 → 승인 → Claude Code 자동 개발

PoC를 빠르게 만들고 싶은 개발자와 PM을 위한 AI-native 문서 생성 + 에이전트 개발 파이프라인.
설계 문서가 정확하고 빠짐없어야 에이전트 개발 시 수정이 적다 — 이 원칙을 데이터로 검증합니다.

파일럿 실험 결과: CC Ready Score ≥ 60인 문서의 Claude Code AEQ는 평균 0.867,
미달 문서는 0.000 — 30배 이상 차이 (Pearson r = 0.937, n=10)

---

핵심 플로우 (v4)

Idea Input  (mode: new_project | feature_addition)
    ↓
[Phase 0A] Intake Enrichment  → IdeaDoc JSON (entities · deps · constraints)
[Phase 0B] Architecture Pattern Detection  (8 patterns, Haiku 1-shot)
    ↓  [feature_addition only]
[FA-0] Codebase Ingestion  (CLAUDE.md paste or Git URL)
[FA-1] Delta Analysis  → ADD / MODIFY / CONFLICT report
    ↓
[Phase 1-0] Assumption Map  ← identify-assumptions-new 방법론 내장 (8 리스크)
[Phase 1a]  Domain Model    ← 패턴별 섹션 자동 주입
[Phase 1b]  API Contract    ← 패턴별 섹션 자동 주입
    ↓
[Phase 2 ‖] Task List (WWA 포맷) · PRD · Test Strategy  (병렬 3개)
              ↑ wwas 방법론 내장    ↑ test-scenarios 방법론 내장
    ↓
[Phase 3]   Cross-doc 자가 검증 + 수정 루프  (≤3회)
    ↓
[Phase 4 ‖] 6개 리뷰 에이전트  (병렬)
    · Arch · Security · PM/Biz · Test Strategy · CC Readiness · Regression
    ↓
[Phase 5]   CC Repair Loop  ── score ≥ 80이면 즉시 통과
    while score < 80 AND iteration ≤ 3:
        repair(all issues, HIGH 우선)
        re-run all reviewers
        score 재계산
    ──▶ 3회 후에도 미달이면 경고 표시 (승인은 가능)
    ↓
[Phase 6]   Human Approve Gate
    ├── Approve  ──▶ Phase 7
    └── Reject   ──▶ 파이프라인 종료  (재시작하려면 새 아이디어 제출)
    ↓
[Phase 7]   Agent-Friendly 변환
    · CLAUDE.md  · tasks.json (why 필드)  · CONSTRAINTS.md
    · delta_patch.md  [feature_addition only]
    ↓
[Phase 8]   Claude Code 실행  (task-by-task · SSE 스트리밍)
    ↓
실시간 Progress 대시보드  (SSE — phase · cc_score · doc_ready · task_done)

외부 플러그인 불필요: pm-skills 방법론과 CC Repair Loop은 파이프라인에 완전 내장. 사용자는 API 키 + uv tool install poc-forge 만으로 동일한 품질을 얻습니다.

---

CC Ready — 핵심 차별점

기존 AI 코딩 도구(Lovable, Bolt, Replit)와의 결정적 차이는 코드를 쓰기 전에 설계를 검증하는 것입니다.

"이 문서만 보고 Claude Code가 한 번의 질문 없이 구현 + 테스트까지 완료할 수 있는가?"

CC Ready Score는 11개 기준 × 가중치로 0–100점 정량화됩니다.

기준	가중치
task_unambiguous — 모호한 표현 없음	20%
acceptance_criteria — 검증 가능 + WHY 필드	20%
api_spec_complete — method/path/request/response	15%
db_schema_complete — 타입/제약/인덱스	15%
dependencies_explicit — task 간 의존성	10%
env_vars_documented	8%
file_structure_defined	5%
atomic_tasks	5%
no_vague_instructions + Out-of-scope 미침범	2%

---

pm-skills 통합 (v3)

phuryn/pm-skills에서 선별한 3개 스킬이 파이프라인에 내장됩니다.

identify-assumptions-new → Stage 0 Assumption Map

Teresa Torres의 8개 리스크 카테고리 분석.
Out-of-scope 목록이 CONSTRAINTS.md의 MUST NOT 룰로 자동 변환됩니다.

wwas → Task List 포맷 강제

모든 task에 WHY 필드 필수 — 실험에서 acceptance_criteria 플래그 감소에 직접 기여.

### T001: 사용자 인증 엔드포인트
**Why:** 모든 API 접근 보호 — Viability 리스크 완화의 핵심
**What:** POST /auth/login, JWT HS256 24h TTL
**Acceptance Criteria:**
- [ ] 유효한 credentials → 200 + {token, expires_at}
- [ ] 잘못된 password → 401 + {"error": "invalid_credentials"}

test-scenarios → Test Strategy 구조화

Test Objective + Starting Conditions + Test Steps + Expected Outcomes 포맷 강제.
Assumption Map의 가장 위험한 가정에 대한 검증 시나리오 자동 포함.

---

배포 형태

형태	진입점	상태
통합 서버	poc-forge (uv tool install, 프론트+백 단일 포트)	✅ 지원
CLI	forge "idea" (서버 없이 헤드리스 실행)	✅ 지원
Self-hosted	FastAPI + Docker Compose	✅ 지원
Web SaaS	https://poc-forge.dev	계획
VS Code Extension	Marketplace	계획

---

구조

poc-forge/
├── backend/
│   ├── main.py                   # FastAPI app + SSE /stream endpoint
│   ├── core/orchestrator.py      # 전체 파이프라인 실행기
│   ├── agents/
│   │   ├── doc_agents.py         # Stage 0-3 (v3: pm-skills 통합)
│   │   ├── review_agents.py      # 5개 리뷰어 (v3: WHY check 추가)
│   │   └── converter.py          # CLAUDE.md · tasks.json · CONSTRAINTS.md
│   ├── routers/__init__.py       # intake · generate · review · approve · convert · execute
│   └── models/
│       ├── session.py            # 세션 상태 + asyncio approval gate
│       └── metrics.py            # CCReadyScorer · ExecutionMetrics · AEQ Score
├── experiment/
│   ├── run_10_ideas_local.py     # CC Ready × AEQ 상관관계 실험
│   └── results.json              # 파일럿 결과 (r=0.937)
├── docs/
│   ├── CLAUDE.md.template
│   ├── tasks.schema.json
│   └── CONSTRAINTS.md.template
├── docker-compose.yml
└── README.md

---

빠른 시작

통합 서버 (권장)

uv tool install poc-forge

poc-forge          # 첫 실행 시 LLM 설정 위자드 → http://localhost:3000 자동 오픈

브라우저에서 아이디어 제출 → 문서 생성 → 리뷰 → Approve → 프로젝트 경로 지정 → Claude Code 자동 실행.

poc-forge --port 8080            # 포트 변경
poc-forge --no-browser           # 브라우저 자동 오픈 비활성화
poc-forge setup                  # LLM 설정 재실행

LLM 설정 위자드 (poc-forge setup) 에서 선택:

Provider	필요 정보
Anthropic API	ANTHROPIC_API_KEY
LiteLLM 프록시	LITELLM_API_BASE + LITELLM_API_KEY
Claude Code 구독	API 키 불필요

설정은 ~/.poc-forge/config.toml에 저장됩니다.

---

CLI (서버 없이 헤드리스 실행)

forge "idea"                                        # 기본 (new_project 모드)
forge "idea" --preset web-saas                      # 프리셋: generic|web-saas|cli|smart-contract|mobile
forge "idea" --lang ko                              # 한국어 문서 생성
forge "idea" --auto-approve                         # 승인 게이트 건너뛰기
forge "idea" --output-dir ./docs                    # 출력 경로 지정
forge "idea" -f idea.md                             # 파일에서 아이디어 읽기

# Feature Addition 모드 (기존 코드베이스에 기능 추가)
forge "Slack 알림 추가" --mode feature_addition --codebase ./CLAUDE.md

---

소스에서 설치 (개발용)

git clone https://github.com/tokamak-network/poc-forge
cd poc-forge

uv sync

# 프론트엔드 빌드 (선택, 통합 서버 모드 시 필요)
cd frontend && npx next build && cp -r out ../backend/_static

poc-forge --reload   # 자동 리로드 활성화

---

Web API (REST 직접 호출)

poc-forge    # 서버 실행 후

# 아이디어 제출
curl -X POST http://localhost:3000/api/intake/ \
  -H "Content-Type: application/json" \
  -d '{"idea": "온라인 강의 플랫폼", "preset": "web-saas"}'

# 실시간 진행 확인
curl -N http://localhost:3000/api/sessions/{id}/stream

# 문서 확인
curl http://localhost:3000/api/generate/{id}/docs | jq 'keys'
# ["assumption_map", "domain_model", "api_contract", "task_list", "prd", "test_strategy"]

# CC Ready Score 확인 후 승인
curl http://localhost:3000/api/review/{id}/report
curl -X POST http://localhost:3000/api/approve/{id} -d '{"approved": true}'

# 프로젝트 경로 설정 후 Claude Code 실행
curl -X POST http://localhost:3000/api/execute/{id}/setup \
  -d '{"project_path": "~/projects/my-app"}'
curl -X POST http://localhost:3000/api/execute/{id}

---

실험 데이터 (파일럿, n=10)

Pearson r(CC Ready, AEQ) = 0.937

임계값 분석:
  CC ≥ 60 → AEQ 평균 0.867 (n=8)
  CC <  60 → AEQ 평균 0.000 (n=2)
  Delta:   +0.867 (30배 차이)

가장 자주 걸리는 기준:
  6x acceptance_criteria  (WHY 필드 누락 포함)
  5x api_spec_complete
  5x db_schema_complete

실험 재현: python experiment/run_10_ideas_local.py

---

개발 로드맵

• Core API (FastAPI + SSE)
• Stage 0–3 문서 생성 파이프라인 (순차 + 자가검증)
• 5 Review Agents + CC Ready Scorer
• Human Approval Gate
• Agent-Friendly Converter
• pm-skills 통합 (identify-assumptions-new · wwas · test-scenarios)
• CC Ready × AEQ 상관관계 실험 프레임워크
• CLI (forge "idea" — 서버리스, typer + rich)
• Feature Addition 모드 (기존 코드베이스 + 신규 기능 → delta_patch.md)
• Web UI (Progress Dashboard + Assumption Map + Approve Gate)
• 통합 바이너리 (poc-forge — 프론트+백 단일 포트, 설정 위자드, 브라우저 자동 오픈)
• Claude Code 실행 대시보드 (프로젝트 경로 설정 → task-by-task 실행 진행)
• VS Code Extension
• Preset 시스템 (web-saas · cli · smart-contract · mobile)
• n=50 실험으로 통계적 유의성 확보

---

기여

PR 환영합니다. 새 리뷰 에이전트, Preset 추가, 실제 Claude Code 실행 데이터 제출이 특히 도움됩니다.

---

라이선스

MIT