PAI Zero — Plugin AI for ProjectZero

AI 개발을 "설계-실행-검증-평가-환경" 5단계로 구조화하는 빌드 오케스트레이터

사용자 시나리오

A. 처음 설치하고 나서

npm install -g pai-zero
pai                                 # ← 환영 화면 + 다음 단계 안내 자동 출력

B. 새 프로젝트 시작 (모드 3단계 선택)

pai init my-app
# ? 어떤 수준의 프로젝트인가요?
#   🧪 prototype    빠른 검증 (아이디어·UI 목업·컨셉 시연)
#   🔬 poc          PoC 웹개발 (동작 데모·기본 기능 구현)
#   🏭 production   운영 서비스 (테스트·QA·배포·모니터링)

선택에 따른 플러그인 매트릭스:

| 플러그인 | prototype | poc | production | |---|:-:|:-:|:-:| | github | ✓ | ✓ | ✓ | | openspec | ✓ | ✓ | ✓ | | roboco | ✓ | ✓ | ✓ | | omc | — | ✓ | ✓ | | vercel | — | opt | opt | | gstack | — | — | ✓ | | harness | — | — | ✓ | | supabase | — | — | opt |

C. 기존 PAI 프로젝트에서 재실행

pai init                            # 또는 pai status
# 현재 모드: prototype
# ? 어떤 작업을 할까요?
#   📊 AI 개발 준비도 평가       (pai grade — 6카테고리 점수)
#   ➕ 플러그인 추가·모드 승격   (pai add — prototype → poc → production)
#   🩺 환경 점검                (pai check — Node/Git/Claude/OMC)

D. 모드 승격

pai add
# 현재 모드: prototype
# 다음 단계: poc
# 승격 시 추가되는 플러그인: omc, vercel
# ? poc 수준으로 승격하시겠어요? (y/N)

E. CI 품질 게이트

pai grade --fail-under 70 --output report.md
# 70점 미만이면 exit 1 — GitHub Actions에서 PR 블록 가능

v0.11 변경 사항 (Breaking)

• OMC 설치 방식 전환: 기존 npx -y github:Yeachan-Heo/oh-my-claudecode install 호출을 제거하고, Claude Code 네이티브 플러그인 마켓플레이스에 등록하는 방식으로 바꿨습니다.
  • PAI는 ~/.claude/settings.json에 extraKnownMarketplaces.omc와 enabledPlugins["oh-my-claudecode@omc"]만 안전 병합합니다. 실제 설치는 Claude Code 기동 시 자동으로 수행됩니다.
  • 이점: 공급망 안전성↑, 버전 고정 가능, 사내망/Windows 호환성↑, 제거 단순화.
  • 등록 실패 시 사용자에게 수동 명령 /plugin install SoInKyu/oh-my-claudecode 안내만 제공합니다 (npx 폴백 없음).
• 명령어 이름 정리(예정): pai env setup → add, doctor → check, evaluate → grade, validate → test, pipeline → run, /pai install → /pai add. v0.12에서 alias 도입, v0.13에서 구 명령어 제거 예정.

빠른 시작

npx pai-zero init          # 프로젝트 초기화
npx pai-zero grade         # 품질 평가 (구: evaluate)
npx pai-zero run           # 전체 파이프라인 실행 (구: pipeline)

설치 후에는 pai init, pai grade 등 짧은 명령어도 사용 가능합니다.

파이프라인 5단계

Environment → Design → Execution → Validation → Evaluation
(환경 구성)   (설계)    (AI 코드생성)  (테스트/검증)  (품질 평가)

| 단계 | 명령어 | 설명 | |------|--------|------| | Environment | pai init / pai add | 프로젝트 분석, 인터뷰, 설정 생성 | | Design | pai design init / pai design validate | OpenSpec PRD + OMC 관리 | | Execution | Claude Code에서 직접 수행 | OMC 기반 AI 코드 생성 | | Validation | pai test | gstack 테스트 + harness 검증 | | Evaluation | pai grade | 6카테고리 가중 점수 (vibe-ready) |

명령어 (v0.11+)

npx pai init                        # 초기화 (신규/기존 자동 감지)
npx pai add                         # 플러그인 추가 (Mockup → Production)
npx pai check                       # 환경 점검 (Node/Git/Claude Code/OMC)
npx pai status                      # 프로젝트 상태
npx pai help                        # 명령어 안내
npx pai design init                 # PRD/OMC 템플릿 생성
npx pai design validate             # PRD 완성도 검증
npx pai test                        # 테스트 / 하네스 검증
npx pai grade                       # AI 품질 평가
npx pai grade --fail-under 70       # CI 모드 (점수 미달 시 exit 1)
npx pai grade --verbose             # 상세 findings 출력
npx pai run                         # 전체 5단계 파이프라인 실행
npx pai run --from validation       # 특정 단계부터 실행

구 명령어 호환 (v0.13 까지 유지, 경고 1회 출력)

| 구 | 신 | |---|---| | pai env setup, pai install | pai add | | pai env doctor | pai check | | pai env status | pai status | | pai validate | pai test | | pai evaluate | pai grade | | pai pipeline | pai run |

품질 평가 (6카테고리)

| 카테고리 | 분류 | 가중치 | |---------|------|--------| | 테스트 커버리지 | 필수 | 20% | | CI/CD | 필수 | 20% | | 훅 기반 검증 | 필수 | 20% | | 리포지토리 구조 | 선택 | 13.3% | | 문서화 수준 | 선택 | 13.3% | | 하네스 엔지니어링 | 선택 | 13.4% |

등급: A(90+), B(80+), C(70+), D(50+), F(<50) 페널티: 필수 카테고리 F등급 시 전체 등급 최대 C로 제한

init 완료 후 구조

my-project/
├── docs/
│   ├── openspec.md          ← PRD 작성 시작!
│   └── vibe-coding/         ← 5단계 프로세스 템플릿
├── src/
├── tests/
├── .pai/
│   ├── config.json          ← PAI 설정
│   ├── omc.md               ← 도메인 객체 모델
│   ├── gstack.json          ← QA 설정 (Production)
│   └── harness.json         ← 검증 설정 (Production)
├── CLAUDE.md                ← AI 컨텍스트
├── .claude/settings.json    ← AI 에이전트 설정
├── vercel.json              ← 배포 설정
└── .env.local               ← 환경변수

Claude Code 플러그인

.claude/skills/pai/SKILL.md가 Claude Code에 자동으로 로드되어 /pai 슬래시 커맨드를 사용할 수 있습니다.

Agent SDK (Optional)

@anthropic-ai/claude-agent-sdk를 설치하면 AI 인터뷰 및 LLM 기반 분석이 활성화됩니다. 미설치 시 정적 분석 모드로 동작합니다.

npm install @anthropic-ai/claude-agent-sdk

기여 / 문의

• GitHub: https://github.com/SoInKyu/pai