| name | develop |
| description | 개발 단계 AI 협업 — 백엔드·프론트엔드·AI엔지니어·QA가 API 계약 기반 병렬 개발 수행 |
| type | orchestrator |
| user-invocable | true |
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) 내 <!-- IF VAR == VALUE --> 조건 지시문 처리. 지원 변수
(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:
- dev-plan.md를 통합 맥락 문서로 확장 (아키텍처 결정사항, 서비스 간 의존관계 시각화 추가)
- 시퀀스 설계서의 alt/else 분기를 test spec의 describe/it 구조로 1:1 변환
- 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로 호출하여 정상 동작을 검증
- 빌드 사전 확인 (
./gradlew clean build 성공)
- Controller 레이어에서 API 목록 정리
- 샘플 데이터 작성 (seed.sql, JSON fixture)
- 백킹서비스 + 백엔드 서비스 기동
- 각 API를 curl로 호출하여 응답 확인
- 실패 시 원인 분석 → 코드 수정 → 재테스트
- 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단계 절차 수행
- 서비스 중지 (백엔드/프론트/백킹/AI)
- 실행 도구 복사 (
tools/run-backend.py, tools/run-frontend.py)
- README.md 생성 (참조:
readme-generation.md)
- 축하 메시지 출력
- 실행 가이드 템플릿 출력
- 다음 단계 안내 (
/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부터 실행한다
- 미매칭 시: 진행상황 업데이트 및 재개 로직을 수행한다