Run any Skill in Manus with one click

Get Started

develop

개발 단계 AI 협업 — 백엔드·프론트엔드·AI엔지니어·QA가 API 계약 기반 병렬 개발 수행

Run Skill in Manus

Overview

개발 단계 AI 협업 — 백엔드·프론트엔드·AI엔지니어·QA가 API 계약 기반 병렬 개발 수행

Install command

npx skills add https://github.com/unicorn-plugins/npd --skill develop

Copy and paste this command into Claude Code to install the skill

Source

unicorn-plugins/npd

Stars20

Forks0

UpdatedMay 20, 2026 at 02:43

SKILL.md

readonly

Develop

[NPD Develop 활성화]

목표

백엔드개발자·프론트엔드개발자·AI엔지니어·QA가 협업하여 API 계약(OpenAPI 명세) 기반 병렬 개발 전략으로 개발을 수행함.

Phase 1: 환경 구성 (백엔드/프론트엔드/AI/백킹서비스 병렬 초기화)
Phase 2: API 계약 기반 병렬 개발 (BE API + FE Mock + AI 서비스 동시 진행)
Phase 3: 통합 연동 (Mock→실제 API 전환, BE↔AI 연동)
Phase 4: 종합 테스트 및 QA

활성화 조건

사용자가 /npd:develop 호출 시 또는 "개발 시작", "개발해줘", "구현 시작" 키워드 감지 시.

주의사항: 중간 단계부터 시작할 때도 사전 설정 수집 및 진행 모드를 설정하는 Phase 0은 항상 수행해야 합니다.

선행 조건

/npd:create 완료 (프로젝트 디렉토리 및 AGENTS.md 존재)
/npd:design 완료 (docs/design/ 산출물 존재)

작업 환경 변수 로드

AGENTS.md 파일에서 ## 환경변수 섹션의 환경변수 로딩. 로딩 실패 시 사용자에게 /npd:create를 먼저 수행하라고 안내하고 종료.

AI 개발 키트

설계→개발 경계에서 1회 컴파일되는 개발 입력 세트. Phase 1 / Step 1에서 생성되며 이후 모든 Step의 유일한 입력이다.

구성 요소	경로	원본	역할
통합 맥락	`docs/develop/dev-plan.md`	전체 설계 산출물 분석 결과	전체 그림 + 아키텍처 결정사항
백엔드 계약	`docs/design/api/*.yaml`	이미 존재 (변환 불요)	API 엔드포인트·스키마 정의
DB 계약	`docs/design/database/*.md`	이미 존재 (변환 불요)	테이블·인덱스·관계 정의
패키지 구조	`docs/design/class/package-structure.md`	이미 존재 (변환 불요)	서비스별 패키지 레이아웃
프론트엔드 계약	`docs/plan/.../prototype/*.html+css`	이미 존재 (변환 불요)	UI 레이아웃·스타일 정의
행위 계약	`test/design-contract/*.spec.ts`	시퀀스 설계서에서 변환	alt/else 분기 → it() 테스트 케이스 (참고 자료, 실행 불요)

원칙: Phase 1 / Step 1 (AI 개발 키트 컴파일) 이후의 에이전트는 docs/design/sequence/, docs/design/class/*.puml 등 원본 설계 문서를 직접 읽지 않는다. 필요한 정보는 모두 AI 개발 키트에 포함되어 있다. 원본이 필요한 경우는 키트에 누락이 있는 것이므로 Phase 1 / Step 1을 보완한다. 단, Phase 1 / Step 1 (AI 개발 키트 컴파일)은 변환 단계이므로 원본 설계 문서 읽기가 필수이다. 이 단계에서만 원본을 읽어 키트로 변환한다.

환경 변수 명세 의무: AI 개발 키트의 docs/develop/dev-plan.md는 설계서에서 식별된 모든 외부 의존성(메시지 브로커·DB·LLM·외부 API·시크릿)에 대해 환경 변수 이름과 용도를 명시한 표를 포함해야 한다. 이 표가 비어 있으면 Phase 1 / Step 1을 완료로 보지 않는다. 이후 Phase 2/3에서 신규 환경 변수가 도입될 때마다 같은 표에 추가하고 .env.example에 키 템플릿을 등록한다.

에이전트 호출 규칙

에이전트	FQN
architect	`npd:architect:architect`
backend-developer	`npd:backend-developer:backend-developer`
frontend-developer	`npd:frontend-developer:frontend-developer`
ai-engineer	`npd:ai-engineer:ai-engineer`
qa-engineer	`npd:qa-engineer:qa-engineer`
product-owner	`npd:product-owner:product-owner`
service-planner	`npd:service-planner:service-planner`

프롬프트 조립

{NPD_PLUGIN_DIR}/resources/guides/combine-prompt.md에 따라 AGENT.md + agentcard.yaml + tools.yaml 합치기
Agent(subagent_type=FQN, model=tier_mapping 결과, prompt=조립된 프롬프트) 호출
tier → 모델 매핑은 {NPD_PLUGIN_DIR}/gateway/runtime-mapping.yaml 참조

서브 에이전트 호출

워크플로우 단계에 Agent: {agent-name}이 명시된 경우, 메인 에이전트는 해당 단계를 직접 수행하지 않고, {NPD_PLUGIN_DIR}/resources/guides/call-subagent.md에 따라 서브 에이젼트 호출

공통 참조 리소스

모든 Step에서 아래 표준을 준수:

개발주석표준: {NPD_PLUGIN_DIR}/resources/references/standard_comment.md
테스트코드표준: {NPD_PLUGIN_DIR}/resources/references/standard_testcode.md
패키지구조표준: {NPD_PLUGIN_DIR}/resources/references/standard_package_structure.md
병렬 처리 전략: {NPD_PLUGIN_DIR}/resources/guides/design/common-principles.md

가이드 문서 조건 분기 프로토콜

가이드 문서(.md) 내  조건 지시문 처리. 지원 변수 (PLATFORM, FRONTEND_PORT, MOCK, TEST_MODE)는 AGENTS.md > ### develop > 지원 변수 에 저장·조회한다. 상세: {NPD_PLUGIN_DIR}/resources/guides/develop/conditional-branching-protocol.md ← 필수 로드

진행상황 업데이트 및 재개

{PROJECT_DIR}/AGENTS.md에 각 Phase의 Step 완료 시 저장. 최종 완료 시 Done으로 표기.

## 워크플로우 진행상황
### develop
- 진행 모드: {선택값}
- 개발 범위: {선택된 Phase 목록} (Phase 0 / Step 1에서 기록)
- 마지막 완료 Phase/Step: Phase 1/Step 0
- 지원 변수:
  - PLATFORM: {REACT|VUE|FLUTTER} (Phase 1 / Step 4 시작 시 결정)
  - FRONTEND_PORT: {3000} (PLATFORM 결정 직후)
  - MOCK: {SINGLE} (Phase 1 / Step 3 완료 후)
  - TEST_MODE: {AUTO|MANUAL} (Phase 0 / Step 5)
- 기술스택:
  - Java: {버전}
  - Spring Boot: {버전}
  - 빌드 도구: {Gradle/Maven}
  - Node.js: {버전}
  - 프론트엔드: {React/Vue/Flutter}
  - Python: {버전}
  - AI 프레임워크: {FastAPI}

{PROJECT_DIR}/AGENTS.md의 ## 워크플로우 진행상황 > ### develop에 진행상황 정보가 있는 경우 마지막 완료 Step 이후부터 자동 재개. 기술스택은 Phase 1 / Step 1 (AI 개발 키트 컴파일) 수립 시 dev-plan.md의 ### 10-5. 기술스택 정보에서 추출하여 기록. 지원 변수는 ## 가이드 문서 조건 분기 프로토콜의 결정 시점에 따라 단계별로 채워지며, 이후 가이드 실행 시 해당 값을 우선 조회한다.

워크플로우

개요

Phase 0: 사전 설정·진행 모드 선택 (개발 범위 + 크리덴셜 + 테스트 모드 + 진행 모드)
   ↓
Phase 1: 환경 구성 (AI 개발 키트 + 백엔드/백킹/FE/AI/실행 프로파일)
   ↓
Phase 2: API 계약 기반 병렬 개발 (BE API + FE Mock + AI)
   ↓
Phase 3: 통합 연동 (FE 실제 API + BE↔AI + API 테스트)
   ↓
Phase 4: 종합 테스트 및 QA (브라우저 테스트 + 제품 검증 + Final Report)
   ↓
Phase 5: 개발 완료

Phase 0: 사전 설정·진행 모드 선택

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/phase0-presetup.md ← 필수 로드
TASK: 위 GUIDE의 6개 Step 절차에 따라 사용자 입력을 사전 수집
EXPECTED OUTCOME:
- AGENTS.md > ### develop 섹션에 진행 모드·개발 범위·지원 변수(TEST_MODE) 기록
- {PROJECT_DIR}/.env에 크리덴셜 (또는 .env.example에 키 등록)

Step 1. 개발 범위 결정

HighLevel 아키텍처 14.1 개발 단계에서 구현 범위를 사용자에게 선택받음.

Step 2. OAuth2 크리덴셜 확인 (조건부)

설계서의 인증 방식이 OAuth2/하이브리드인 경우 Provider 크리덴셜 수집.

Step 3. Gemini API Key 확인

프론트엔드 이미지 생성용 GEMINI_API_KEY 수집.

Step 4. AI 서비스 크리덴셜 확인 (조건부)

ai-service-design.md 존재 시 LLM/Tool/RAG 크리덴셜 수집.

Step 5. 테스트 모드 선택

브라우저 테스트 모드(자동/수동) 선택 → AGENTS.md 지원 변수 > TEST_MODE에 저장.

Step 6. 진행 모드 선택

단계별 승인/자동 진행 선택. 단계별 승인 시 ASK_USER 형식 정의됨. (중요) 자동 진행 시 사용자에게 진행에 필요한 정보를 한꺼번에 요청. AskUserQuestion 사용하지 않고 대화창으로 질문

Phase 1: 환경 구성

Step 1. AI 개발 키트 컴파일 → Agent: architect (주도) + backend-developer + frontend-developer + ai-engineer (병렬 검증)

Step 1은 두 단계로 구성된다:

Step 1-1. 종합 개발 계획 수립

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/dev-plan.md
INPUT: Phase 0 / Step 1에서 선택된 개발 단계(Phase) 범위
TASK: 3개 에이전트 분담 작성 → architect 통합 리뷰
EXPECTED OUTCOME: docs/develop/dev-plan.md

Step 1-2. 행위 계약 테스트 생성

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/design-contract-compile.md
INPUT:
- docs/develop/dev-plan.md (Step 1-1 산출물)
- docs/design/sequence/inner/*.puml (내부 시퀀스)
- docs/design/sequence/outer/*.puml (외부 시퀀스)
- docs/design/api/*.yaml (API 명세)
TASK:
1. dev-plan.md를 통합 맥락 문서로 확장 (아키텍처 결정사항, 서비스 간 의존관계 시각화 추가)
2. 시퀀스 설계서의 alt/else 분기를 test spec의 describe/it 구조로 1:1 변환
3. API 명세의 요청/응답 스키마를 assertion으로 변환
EXPECTED OUTCOME (AI 개발 키트):
- docs/develop/dev-plan.md (확장된 통합 맥락)
- test/design-contract/*.spec.ts (행위 계약 참고 자료 — 백엔드 구현 시 분기 누락 방지용, 실행 불요)
SKIP 조건 결정: AI 서비스 설계서 미존재 시, AI 관련 test spec 생성 건너뜀
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

이후 모든 Step의 입력:

docs/develop/dev-plan.md (통합 맥락)

docs/design/api/*.yaml (백엔드 계약)

docs/design/database/*-schema.psql 또는 docs/design/database/*.md (DB 계약)

docs/design/class/package-structure.md (패키지 구조)

docs/plan/.../prototype/*.html+css (프론트엔드 계약)

test/design-contract/*.spec.ts (행위 계약 참고 자료)

Step 2. 백엔드 환경 구성 → Agent: backend-developer

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/backend-env-setup.md
TASK: Gradle Wrapper 생성 + 멀티모듈 build.gradle 구성 + 공통 모듈 개발
EXPECTED OUTCOME: gradlew, gradlew.bat, gradle/wrapper/, settings.gradle, build.gradle(루트), {service-name}/build.gradle(서비스별), {service-name}/src/main/resources/application.yml(서비스별), common/src/main/java/.../common/
주의: application.yml의 환경변수는 placeholder만 작성 (환경변수 키는 Step 3의 .env.example 템플릿에 정의되며, 실제 값은 {PROJECT_DIR}/.env에서 통일)
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Step 3. 백킹서비스 + Mock 서버 로컬 구성 → Agent: backend-developer

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/backing-service-setup.md
TASK: 데이터설계서 기반 프로젝트 루트 단일 docker-compose.yml 작성 → DB(PostgreSQL/MySQL/MariaDB/MongoDB)/Cache/MQ + Prism Mock 서버 구성. 기본 제품(PostgreSQL) 외 선택 시 카테고리 가이드 참조
EXPECTED OUTCOME: ./docker-compose.yml, ./.env.example, docs/develop/backing-service-result.md
docker-compose 서비스 구성:
- 기본 서비스 (항상 기동): DB, Cache, MQ(설계서 명시 시만)
- mock 프로파일: Prism Mock 서버 (docker compose --profile mock up)
- ai 프로파일: AI 서비스 컨테이너 (docker compose --profile ai up, AI 서비스 존재 시만)
사용자 선택: 사용자가 선택한 백킹서비스 환경에 따라 분기
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Step 4. 프론트엔드 프로젝트 초기화 → Agent: frontend-developer

GUIDE (플랫폼별 선택):
- REACT: {NPD_PLUGIN_DIR}/resources/guides/develop/frontend-env-setup-react.md
- VUE: {NPD_PLUGIN_DIR}/resources/guides/develop/frontend-env-setup-vue.md
- FLUTTER: {NPD_PLUGIN_DIR}/resources/guides/develop/frontend-env-setup-flutter.md
TASK: 기술스택 결정 → 프로젝트 생성 → 기반 시스템(스타일/라우팅/상태관리) 구축 → Prism Mock 서버 연동 준비
EXPECTED OUTCOME: frontend/ 프로젝트 골격, tools/generate-runtime-env.sh (프로젝트 서비스 구성에 맞게 동적 생성됨), npm run dev 실행 확인
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Step 5. AI 서비스 프로젝트 초기화 → Agent: ai-engineer

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/ai-service-env-setup.md
TASK: Python/FastAPI 프로젝트 생성 → 의존성 설치 → 기본 구조 설정 → docker-compose ai 프로파일에 등록
EXPECTED OUTCOME: ai-service/ 프로젝트 골격, uvicorn 실행 확인
SKIP 조건: Phase 1 / Step 1에서 AI SKIP으로 결정된 경우 건너뜀
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Phase 1 / Step 2 ~ Step 5는 병렬 실행: 4개 에이전트가 동시에 작업. Step 2와 Step 3의 환경변수 정합성은 placeholder 방식으로 해결 (각자 독립 작성, 값은 {PROJECT_DIR}/.env에서 통일. .env.example은 키 템플릿)

Step 6. 실행 프로파일 작성 → Agent: backend-developer

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/run-profile.md
TASK: 백킹서비스 연결 정보(Phase 1 / Step 3) + application.yml(Phase 1 / Step 2) 기반 실행 프로파일 작성
EXPECTED OUTCOME: {service-name}/.run/{service-name}.run.xml (서비스별)
선행 조건: Phase 1 / Step 2, Step 3 완료 필수 (Phase 2 진입 전 게이트)
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Phase 2: API 계약 기반 병렬 개발

Step 1. 백엔드 API 구현 → Agent: backend-developer

참고: Phase 0 / Step 2에서 OAuth2 크리덴셜을 사전 수집하였다. '나중에 설정'을 선택한 경우: 본 Step 에이전트에 "OAuth2 크리덴셜 미설정, 코드 구현만 진행하고 통합 테스트는 생략" 지시를 포함한다. Phase 3 진입 전에 {PROJECT_DIR}/.env 파일에서 다시 확인한다.

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/backend-api-dev.md
INPUT:
- docs/develop/dev-plan.md (통합 맥락 — 서비스 목록, 의존관계, 개발 순서)
- docs/design/api/{service-name}-api.yaml (API 계약)
- docs/design/database/{service-name}.md (DB 계약)
- docs/design/class/package-structure.md (패키지 구조)
- test/design-contract/{service-name}/*.spec.ts (행위 계약 참고 자료)
TASK:
- API 설계서 + 행위 계약 참고 자료 기반 컨트롤러·서비스·레포지토리 구현 + 단위 테스트
- Sprint 분할 제거: 서비스 1개를 하나의 작업 단위로 완결. 의존관계 기반 순서만 유지
- 서비스 구현 시: test/design-contract/{service-name}/*.spec.ts의 it() 케이스를 참고하여 alt/else 분기 누락 방지 (테스트 실행 불요)
EXPECTED OUTCOME: {service-name}/src/main/java/.../{service-name}/(API 구현 코드), {service-name}/src/test/java/.../{service-name}/(단위 테스트 코드)
병렬: 서비스 간 의존성 분석 후 독립 서비스는 병렬 구현 (서브에이전트 활용)
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Step 2. 프론트엔드 Prism Mock 기반 개발 → Agent: frontend-developer

참고: Phase 0 / Step 3에서 Gemini API Key를 사전 수집하였다. '나중에 설정'을 선택한 경우: 본 Step 에이전트에 "Gemini API Key 미설정, 이미지 생성 불가 — 이미지가 필요한 곳은 CSS/SVG 기반 대체 구현" 지시를 포함한다.

GUIDE (플랫폼별 선택):
- REACT: {NPD_PLUGIN_DIR}/resources/guides/develop/frontend-dev-react.md
- VUE: {NPD_PLUGIN_DIR}/resources/guides/develop/frontend-dev-vue.md
- FLUTTER: {NPD_PLUGIN_DIR}/resources/guides/develop/frontend-dev-flutter.md
TASK: docker-compose의 Prism Mock 서버 활용 → 페이지별 구현
EXPECTED OUTCOME: frontend/src/components/, frontend/src/layouts/, frontend/src/services/api/, frontend/src/hooks/, frontend/src/pages/
Prism 실행: docker compose --profile mock up (Phase 1 / Step 3에서 구성)
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Step 3. AI 서비스 구현 → Agent: ai-engineer

SKIP 조건: Phase 1 / Step 1에서 AI SKIP으로 결정된 경우 건너뜀

참고: Phase 0 / Step 4에서 AI 서비스 크리덴셜을 사전 수집하였다. '나중에 설정'을 선택한 경우: 본 Step 에이전트에 "LLM 크리덴셜 미설정, 코드 구현만 진행하고 실제 LLM 호출 테스트는 생략" 지시를 포함한다. Phase 3 진입 전에 {PROJECT_DIR}/.env 파일에서 다시 확인한다.

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/ai-service-dev.md
TASK: AI 서비스 설계서 기반 엔드포인트 구현, 프롬프트 작성, LLM 연동
EXPECTED OUTCOME: {service-name}/models/, {service-name}/clients/, {service-name}/prompts/, {service-name}/services/, {service-name}/routers/, {service-name}/tests/
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Phase 2 / Step 1 ~ Step 3은 병렬 실행: 백엔드는 실제 API 구현, 프론트엔드는 Prism Mock으로 독립 개발, AI는 별도 서비스로 독립 개발

Phase 3: 통합 연동

Step 1. 프론트엔드 실제 API 연동 → Agent: frontend-developer

PREV_ACTION: Phase 3 진입 전에 반드시 아래 수행
- 프로토타입 화면과 개발 화면 매핑
- Playwright MCP로 웹브라우저로 개발된 화면의 첫 화면 오픈
- 각 개발된 화면을 클릭하여 프로토타입과 비교하여 UI/UX 일치 여부 확인 (개발 화면이 프로토타입과 다를 경우, 프론트엔드 개발자에게 피드백하여 수정 요청)
- 모든 개발된 화면이 프로토타입과 일치할 때까지 반복 수행
GUIDE (플랫폼별 선택):
- REACT: {NPD_PLUGIN_DIR}/resources/guides/develop/frontend-integration-react.md
- VUE: {NPD_PLUGIN_DIR}/resources/guides/develop/frontend-integration-vue.md
- FLUTTER: {NPD_PLUGIN_DIR}/resources/guides/develop/frontend-integration-flutter.md
TASK: Prism Mock → 실제 백엔드 API 전환, E2E 동작 확인
EXPECTED OUTCOME: frontend/public/runtime-env.js, frontend/src/services/api/client.ts, frontend/src/services/api/authService.ts, frontend/src/store/authStore.ts, frontend/(실제 API 연동 완료)
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Step 2. 백엔드 ↔ AI 서비스 연동 → Agent: backend-developer + ai-engineer

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/backend-ai-integration.md
TASK: 백엔드에서 AI 서비스 호출 코드 구현, Circuit Breaker/Fallback 설정
EXPECTED OUTCOME: .../client/AiServiceClient.java(인터페이스), .../client/AiServiceClientImpl.java(HTTP 클라이언트), {service-name}/src/main/resources/application.yml(resilience4j 섹션), .../client/AiServiceClientTest.java(통합 테스트)
SKIP 조건: Phase 1 / Step 1에서 AI SKIP으로 결정된 경우 건너뜀
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Phase 3 / Step 1, Step 2는 병렬 실행 가능 (단, Step 1은 Phase 2 / Step 1 완료 필요, Step 2는 Phase 2 / Step 1 + Step 3 완료 필요)

Step 3. API 테스트 → Agent: qa-engineer

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/test-api.md
TASK: 가이드에 따라 백엔드·AI 서비스의 전체 API를 curl로 호출하여 정상 동작을 검증
1. 빌드 사전 확인 (./gradlew clean build 성공)
2. Controller 레이어에서 API 목록 정리
3. 샘플 데이터 작성 (seed.sql, JSON fixture)
4. 백킹서비스 + 백엔드 서비스 기동
5. 각 API를 curl로 호출하여 응답 확인
6. 실패 시 원인 분석 → 코드 수정 → 재테스트
EXPECTED OUTCOME:
- docs/develop/api-test-result.md (API 테스트 결과)
- {service}/src/test/resources/data/ (SQL seed, JSON fixture)
선행 조건: Phase 3 / Step 1, Step 2 완료 필수
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Phase 4: 종합 테스트 및 QA

Step 1. 브라우저 테스트

선행 조건: Phase 3 / Step 3 (API 테스트) 전체 PASS 필수

Step 1-1. 테스트 모드 적용

Phase 0 / Step 5에서 사전 수집된 테스트 모드를 적용한다.

자동 진행 모드 (Phase 0 / Step 6) → 테스트 모드를 **"자동 테스트"**로 강제 설정 (Phase 0 / Step 5 선택과 무관)
단계별 승인 모드 (Phase 0 / Step 6) → Phase 0 / Step 5에서 선택한 테스트 모드 적용

결정된 테스트 모드를 AGENTS.md의 ### develop > 지원 변수 섹션에 TEST_MODE: {AUTO|MANUAL} 로 기록한다.

Step 1-2. 자동 테스트 모드 수행 → Agent: qa-engineer + (수정 시) backend-developer, frontend-developer, ai-engineer

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/test-browser-auto.md ← 필수 로드
수행 조건: TEST_MODE = AUTO인 경우만
TASK: 위 GUIDE의 1-2a~1-2d sub-flow + 체크포인트(.temp/phase4-step1-checkpoint.json) + 재테스트 루프(최대 3회) 수행
EXPECTED OUTCOME:
- docs/develop/test/e2etest-{N}.md
- e2e/tests/scenarios.spec.ts
- .temp/iter-{N}/tc-*.png (Step 2 입력)
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Step 1-3. 수동 테스트 모드 수행 → Agent: backend-developer, frontend-developer, ai-engineer (이슈 수정 시)

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/test-browser-manual.md ← 필수 로드
수행 조건: TEST_MODE = MANUAL인 경우만
TASK: 위 GUIDE의 1-3a~1-3c 대화형 sub-flow 수행. AskUserQuestion 사용 금지
EXPECTED OUTCOME: 사용자 보고 이슈 반영된 코드 + Step 3 (Final Report) 입력용 대화 이력
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Step 2. 제품 검증

선행 조건: Phase 4 / Step 1 완료

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/product-verify.md ← 필수 로드
TASK: 위 GUIDE의 모드별 sub-flow 수행
- TEST_MODE = AUTO → Step 2-1 자동 모드 (5단계: 2-1a~2-1e, 체크포인트 .temp/phase4-step2-checkpoint.json, 개선 루프 최대 2회. PO/SP 재검증이 회귀 영향을 통합 검증하므로 별도 회귀 TC 재실행은 수행하지 않음)
- TEST_MODE = MANUAL → Step 2-2 수동 모드 (2-2a~2-2b 대화형, AskUserQuestion 사용 금지)
EXPECTED OUTCOME:
- 자동: docs/develop/test/verify-po-{N}.md, verify-sp-{N}.md, .temp/iter-{N+1}/
- 수동: 개선된 코드 + 대화 이력
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Step 3. Final Report 작성

선행 조건: Phase 4 / Step 2 완료

입력:
- 자동 모드: docs/develop/test/e2etest-*.md, verify-po-*.md, verify-sp-*.md
- 수동 모드: Phase 4 / Step 1~2 대화에서 보고된 이슈 + 수정·개선 내역 + 사용자 최종 판정
TASK: 전체 테스트 과정 요약 + 최종 결과 + 잔여 이슈/개선사항 정리
EXPECTED OUTCOME: docs/develop/test/final-report.md
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

Phase 5: 개발 완료

Step 1. 개발 완료

GUIDE: {NPD_PLUGIN_DIR}/resources/guides/develop/dev-complete.md ← 필수 로드
TASK: 위 GUIDE의 6단계 절차 수행
1. 서비스 중지 (백엔드/프론트/백킹/AI)
2. 실행 도구 복사 (tools/run-backend.py, tools/run-frontend.py)
3. README.md 생성 (참조: readme-generation.md)
4. 축하 메시지 출력
5. 실행 가이드 템플릿 출력
6. 다음 단계 안내 (/npd:deploy)
EXPECTED OUTCOME: tools/run-backend.py, tools/run-frontend.py, {PROJECT_DIR}/README.md
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트

MUST 규칙

#	규칙
1	`<!--ASK_USER-->` 발견 시 AskUserQuestion 도구를 호출할 것 (텍스트 출력 금지)
2	*Phase 1 / Step 1 (AI 개발 키트 컴파일) 이후의 에이전트는 `docs/design/sequence/`, `docs/design/class/.puml` 등 원본 설계 문서를 직접 읽지 않을 것** (AI 개발 키트만 사용. 원본이 필요한 경우 키트에 누락이 있는 것이므로 Phase 1 / Step 1을 보완)
3	외부 가이드(`{NPD_PLUGIN_DIR}/resources/guides/develop/.md`)가 명시된 Step은 해당 가이드를 반드시 Read로 로드한 뒤* 절차를 수행할 것. SKILL.md 본문의 요약만 보고 직접 수행하면 스킬 미준수로 간주
4	Phase 2 완결 원칙: Phase 2/Step 1~3의 산출물은 그 단계 안에서 실제 동작이 완성되어야 한다. "Phase 3에서 실제 연동", "추후 구현" 같은 미루기 주석·스텁을 금지한다. 외부 의존성(메시지 브로커·DB·LLM·외부 API) 사용이 설계서에 명시된 경우, 그 단계에서 실제 클라이언트 코드와 통합 테스트까지 완료한다
5	하드코딩 금지 정책: 모든 산출물 코드에서 (a) 시크릿/API Key, (b) 가격·환율 등 비즈니스 상수, (c) URL·포트, (d) 도메인 데이터 샘플(`MOCK_`, `SAMPLE_`, `FAKE_*` 등 명명 상수)이 코드 리터럴로 박혀 있으면 안 된다. 모두 환경변수·설정파일·시드 SQL·실제 API 응답 중 하나로 외부화한다
6	스텁 검출 게이트: 각 Phase 완료 시 자동 검출을 실행한다. (a) `grep -rn "MOCK_\|SAMPLE_\|FAKE_" frontend/`, (b) `grep -rn "TODO\|FIXME\|HACK" .`, (c) `grep -rn "log.info.*\[EVENT\]" .` 결과가 0건이어야 다음 Phase로 진입한다. 의도적 잔존이 필요한 경우 같은 줄에 `// ALLOW: 사유` 또는 `<!-- ALLOW: 사유 -->` 주석으로 사유를 명시한다

완료 조건

검증 프로토콜

산출물 파일 존재 확인 (개발 계획서, 백엔드 코드, 프론트엔드 코드, AI 코드, 실행 프로파일)
Phase 3 / Step 3 (API 테스트) 전체 PASS (curl 기반 전 엔드포인트 검증)
Phase 4 / Step 1 (브라우저 테스트) 전체 PASS (Playwright Test Suite 기반 유저 시나리오 + GAP 패턴 검증)
Phase 4 / Step 2 (제품 검증) PO/SP 완료 (Critical/Major 0건 + 회귀 의심 0건 — PO/SP 재검증 4종 범위)
Phase 4 / Step 1·2 루프 제한 준수 (Step 1 재테스트 ≤ 3회, Step 2 개선 ≤ 2회)
Phase 4 / Step 3 (Final Report) 생성 확인 (docs/develop/test/final-report.md)

상태 정리

완료 시 임시 상태 파일 정리. 산출물은 유지.

인수 라우팅

ARGUMENTS가 전달된 경우, 아래 매핑 테이블에서 키워드를 매칭하여 특정 Step으로 직접 점프한다. 이 로직은 재개 로직보다 우선 적용된다.

인수 키워드	시작 Step	선행 조건 확인
`브라우저테스트`, `브라우저 테스트`, `phase4-step1`, `step5`	Phase 4 / Step 1	`docs/develop/api-test-result.md` 존재
`제품검증`, `제품 검증`, `phase4-step2`, `step6`	Phase 4 / Step 2	`.temp/phase4-step1-checkpoint.json`의 status가 `completed`

처리 절차

ARGUMENTS에서 매핑 테이블의 키워드를 매칭한다 (부분 일치 허용)
매칭 시: a. AGENTS.md의 ### develop 섹션에서 변수를 복원한다 (진행 모드, 개발 범위, 지원 변수(TEST_MODE 등), 기술스택) b. 테스트 모드 재선택 (Phase 4 / Step 1 점프 시): 복원된 지원 변수 > TEST_MODE를 표시하고, 이번 실행에서 변경할지 사용자에게 확인한다.

{"title":"테스트 모드 확인","questions":[ {"question":"현재 설정된 테스트 모드: {복원된 테스트 모드}\n\n이번 브라우저 테스트에서 테스트 모드를 변경하시겠습니까?","type":"radio","options":["자동 테스트 유지 (AI가 Playwright Test Suite로 자동 수행)","수동 테스트로 변경 (사람이 브라우저에서 직접 테스트, AI가 수정 지원)"]} ]}

변경 시 AGENTS.md의 지원 변수 > TEST_MODE 값을 갱신한다
Phase 4 / Step 1-1의 "자동 진행 모드 → 자동 테스트 강제" 규칙은 인수 라우팅 점프 시에는 적용하지 않는다 (사용자가 명시적으로 Step을 지정했으므로 테스트 모드 선택을 존중) c. 해당 Step의 체크포인트 파일(.temp/phase4-step{N}-checkpoint.json)이 존재하면 iteration 값을 보존(status가 completed이면 +1)하고 나머지(current_step, completed_steps, status)를 초기화한다. 미존재 시 iteration=1로 새로 생성한다. d. 인증 상태 파일(e2e/.auth/state.json)을 삭제한다 (Phase 4 / Step 1 점프 시) e. 선행 조건 산출물 존재 여부를 확인한다 (미존재 시 사용자에게 경고 후 중단) f. Phase 0을 건너뛰고 해당 Step부터 실행한다

미매칭 시: 진행상황 업데이트 및 재개 로직을 수행한다

name	develop
description	개발 단계 AI 협업 — 백엔드·프론트엔드·AI엔지니어·QA가 API 계약 기반 병렬 개발 수행
type	orchestrator
user-invocable	true

develop

More from this repository

More from this repository

Develop

목표

활성화 조건

선행 조건

작업 환경 변수 로드

AI 개발 키트

에이전트 호출 규칙

프롬프트 조립

서브 에이전트 호출

공통 참조 리소스

가이드 문서 조건 분기 프로토콜

진행상황 업데이트 및 재개

워크플로우

개요

Phase 0: 사전 설정·진행 모드 선택

Step 1. 개발 범위 결정

Step 2. OAuth2 크리덴셜 확인 (조건부)

Step 3. Gemini API Key 확인

Step 4. AI 서비스 크리덴셜 확인 (조건부)

Step 5. 테스트 모드 선택

Step 6. 진행 모드 선택

Phase 1: 환경 구성

Step 1. AI 개발 키트 컴파일 → Agent: architect (주도) + backend-developer + frontend-developer + ai-engineer (병렬 검증)

Step 1-1. 종합 개발 계획 수립

Step 1-2. 행위 계약 테스트 생성

Step 2. 백엔드 환경 구성 → Agent: backend-developer

Step 3. 백킹서비스 + Mock 서버 로컬 구성 → Agent: backend-developer

Step 4. 프론트엔드 프로젝트 초기화 → Agent: frontend-developer

Step 5. AI 서비스 프로젝트 초기화 → Agent: ai-engineer

Step 6. 실행 프로파일 작성 → Agent: backend-developer

Phase 2: API 계약 기반 병렬 개발

Step 1. 백엔드 API 구현 → Agent: backend-developer

Step 2. 프론트엔드 Prism Mock 기반 개발 → Agent: frontend-developer

Step 3. AI 서비스 구현 → Agent: ai-engineer

Phase 3: 통합 연동

Step 1. 프론트엔드 실제 API 연동 → Agent: frontend-developer

Step 2. 백엔드 ↔ AI 서비스 연동 → Agent: backend-developer + ai-engineer

Step 3. API 테스트 → Agent: qa-engineer

Phase 4: 종합 테스트 및 QA

Step 1. 브라우저 테스트

Step 1-1. 테스트 모드 적용

Step 1-2. 자동 테스트 모드 수행 → Agent: qa-engineer + (수정 시) backend-developer, frontend-developer, ai-engineer

Step 1-3. 수동 테스트 모드 수행 → Agent: backend-developer, frontend-developer, ai-engineer (이슈 수정 시)

Step 2. 제품 검증

Step 3. Final Report 작성

Phase 5: 개발 완료

Step 1. 개발 완료

MUST 규칙

완료 조건

검증 프로토콜

상태 정리

인수 라우팅

처리 절차

Develop

목표

활성화 조건

선행 조건

작업 환경 변수 로드

AI 개발 키트

에이전트 호출 규칙

프롬프트 조립

서브 에이전트 호출

공통 참조 리소스

가이드 문서 조건 분기 프로토콜

진행상황 업데이트 및 재개

워크플로우

개요

Phase 0: 사전 설정·진행 모드 선택

Step 1. 개발 범위 결정

Step 2. OAuth2 크리덴셜 확인 (조건부)

Step 3. Gemini API Key 확인

Step 4. AI 서비스 크리덴셜 확인 (조건부)

Step 5. 테스트 모드 선택

Step 6. 진행 모드 선택

Phase 1: 환경 구성

Step 1. AI 개발 키트 컴파일 → Agent: architect (주도) + backend-developer + frontend-developer + ai-engineer (병렬 검증)

Step 1-1. 종합 개발 계획 수립