pdca

PDCA Skill (gaegulzip Project Override)

Unified Skill for managing PDCA cycle with agent-integrated workflow. Each PDCA phase automatically invokes the appropriate project agents from bkit.config.json. Phase 상세 절차는 phases/ 디렉토리의 개별 파일 참조.

Config Reference

Read bkit.config.json to determine:

• context.defaultLanguage → 모든 출력(문서, 상태 메시지, 에이전트 응답)에 이 언어 사용
• pdca.planDocPaths → document output paths
• pdca.designDocPaths → document output paths
• pdca.analyzeDocPaths → analysis document output paths
• pdca.reportDocPaths → report document output paths
• platforms.{platform}.agents → agent mapping per phase
• pdca.statusFile → .pdca-status.json path
• pdca.matchRateThreshold → 90 (default)
• pdca.maxIterations → 5 (default)

Language Rule

All output MUST be in the language specified by bkit.config.json → context.defaultLanguage. When calling agents via Task tool, always append to the prompt: \nIMPORTANT: Respond and write all documents in {defaultLanguage}. Code, paths, and technical terms stay in English.

⚠️ Intent-Only Document Rule (Plan & Design 문서 필수 원칙)

Plan/Design 문서는 "무엇을(WHAT)"과 "왜(WHY)"만 작성한다. "어떻게(HOW)" 즉 구현은 절대 작성하지 않는다.

이 원칙을 위반하는 예시:

• ❌ 파일명/경로 지정: src/services/authService.ts에 구현
• ❌ 코드 구조 지시: useEffect로 상태를 관리하고 Redux store에 저장
• ❌ 함수 시그니처: async function validateToken(token: string): Promise<boolean>
• ❌ DB 쿼리 작성: SELECT * FROM users WHERE email = ?
• ❌ 특정 라이브러리 사용법: zod.object({ email: z.string().email() })로 검증

이 원칙을 지키는 예시:

• ✅ 사용자 행동 정의: 사용자는 이메일과 비밀번호로 로그인할 수 있다
• ✅ 비즈니스 규칙: 비밀번호는 최소 8자, 영문+숫자+특수문자 포함
• ✅ 데이터 요구사항: 사용자 프로필에는 닉네임, 프로필 이미지, 가입일이 포함된다
• ✅ API 계약 (Design): POST /auth/login → 요청: { email, password }, 응답: { token, user }
• ✅ 제약조건: 토큰 만료 시간은 24시간

이유: 구현은 Do 단계의 개발자 에이전트가 결정한다. 설계 문서에 구현을 쓰면 에이전트 자율성을 제한하고, 코드 변경 시 문서 부패를 유발한다.

모든 Plan/Design phase 에이전트 프롬프트에 이 원칙을 포함시킬 것.

Product Naming Convention

{product}는 앱 이름을 그대로 사용합니다:

• wowa — 메인 앱
• admin — 어드민 대시보드
• talmosang — 탈모상 AI 두피 분석

경로 예: docs/wowa/auth/user-story.md, docs/admin/dashboard/web-brief.md

Fullstack frontendType 제약

frontendType은 단일 값만 허용합니다 ("mobile" 또는 "web"). Mobile + Web 동시 개발이 필요한 경우, 별도 PDCA 사이클로 분리합니다:

• 예: wowa feature = fullstack (frontendType: mobile), admin feature = fullstack (frontendType: web)

Status Tracking

.pdca-status.json stores platform and phase per feature:

{
  "features": {
    "{feature}": {
      "phase": "research | plan | design | do | analyze | iterate | completed | archived",
      "platform": "server | mobile | web | fullstack",
      "frontendType": "mobile | web",
      "startedAt": "ISO timestamp",
      "documents": {}
    }
  }
}

IMPORTANT:

• platform is determined during Plan phase by CTO and reused in all subsequent phases.
• frontendType is set when platform is fullstack to distinguish Mobile vs Web frontend agents.

Arguments

Phase Details

각 phase 실행 시 해당 파일을 Read하여 상세 절차를 따릅니다.

status (Status Check)

1. Read .pdca-status.json
2. Display: feature, phase, platform, matchRate, documents
3. Visualize progress

📊 PDCA Status
─────────────────────────────
Feature: {feature}
Platform: {platform}
Phase: {phase}
Match Rate: {matchRate}%
─────────────────────────────
[Research] ✅ → [Plan] ✅ → [Design] ✅ → [Do] 🔄 → [Check] ⏳ → [Act] ⏳

next (Next Phase)

Agent Integration Summary (All Bidirectional)

↔ = 양방향 (피드백 경로 있음), ──→ = 단방향 (최종 출력) 참조: .claude/guide/agent-communication-protocol.md — 전 phase 양방향 통신 프로토콜

Research: clarify (user) ──→ research-director (research.md + Decision Points)
                                       │
                                       ↓ CTO 통합 평가 (아키텍처 + 복잡도)
                                       │
                              BLOCK ↔ clarify 재호출 (max 2회)
                              CONCERN → AskUserQuestion
                                       │
                                       ↓ Decision Points → PO에게 전달
Plan:    PO (user-story.md) ↔ CTO (⓪-pre 타당성 스캔)
              │                        │ BLOCK → PO 재호출 (max 2회)
              │                        ↓ PASS/WARN
         interactive-review (사용자 승인) ──→ CTO (⓪ 플랫폼 라우팅)
                                                   │
                                       Scope Mismatch ↔ PO 보완 + 사용자 재승인
                                                   ↓ platform & frontendType stored
Design:  ┌── Server: tech-lead (server-brief)
         ├── Mobile: ui-ux-designer ↔ tech-lead (Design Pushback 루프, max 2회)
         │           └── frontend-design (Skill) 포함
         └── Web:    ui-ux-designer ↔ tech-lead (Design Pushback 루프, max 2회)
                     └── frontend-design (Skill) 포함
              │      Fullstack = Server + frontend (by frontendType)
              │      + API Contract 양방향 검증 (server tech-lead ↔ CTO ↔ frontend tech-lead)
              │
Do:      CTO (work-plan) ──→ developers (node/flutter/react)
              │                    ↔ BLOCKED:QUESTIONS → CTO 라우팅 → 답변자 → 재개
              │              OR: Ralph Loop (단일 에이전트 자율 반복)
              │
Analyze: gap-detector ↔ CTO (review)
              │
Iterate: pdca-iterator (if < 90%)  OR: Ralph Loop (FINDINGS 자율 수정)
              │
Report:  report-generator ──→ CHANGELOG
              │
Verify:  independent-reviewer (optional)

Bidirectional Communication Reference

전 phase의 양방향 통신 프로토콜 상세는 아래 문서를 참조합니다:

• 통신 프로토콜: .claude/guide/agent-communication-protocol.md
• phase별 상세: phases/{phase}.md

CTO Involvement (5 Points)