Stats
Actions
Tags
Help us improve
Share bugs, ideas, or general feedback.
From npd
Orchestrates parallel backend, frontend, AI, and QA development based on API contracts (OpenAPI specs) in a structured 4-phase workflow. Loads design artifacts from preceding planning phases and delegates to specialized sub-agents.
npx claudepluginhub unicorn-plugins/npd --plugin npdHow this skill is triggered — by the user, by Claude, or both
Slash command
/npd:developThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
[NPD Develop 활성화]
Guides the Develop phase of a Double Diamond design process using multiple AI assistants (Codex, Gemini). Manages state, detects work context, and enforces execution contract.
Orchestrates all code-modifying development tasks like bug fixes, enhancements, and new features using adaptive phases for analysis, specs, TDD, implementation, and verification.
Orchestrates development tasks that modify code—bug fixes, enhancements, new features—with adaptive phases for codebase analysis, specs, planning, implementation, and TDD testing.
Share bugs, ideas, or general feedback.
[NPD Develop 활성화]
백엔드개발자·프론트엔드개발자·AI엔지니어·QA가 협업하여 API 계약(OpenAPI 명세) 기반 병렬 개발 전략으로 개발을 수행함.
사용자가 /npd:develop 호출 시 또는 "개발 시작", "개발해줘", "구현 시작" 키워드 감지 시.
주의사항: 중간 단계부터 시작할 때도 사전 설정 수집 및 진행 모드를 설정하는 Phase 0은 항상 수행해야 합니다.
/npd:create 완료 (프로젝트 디렉토리 및 AGENTS.md 존재)/npd:design 완료 (docs/design/ 산출물 존재)AGENTS.md 파일에서 ## 환경변수 섹션의 환경변수 로딩.
로딩 실패 시 사용자에게 /npd:create를 먼저 수행하라고 안내하고 종료.
설계→개발 경계에서 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=조립된 프롬프트) 호출{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: 개발 완료
{NPD_PLUGIN_DIR}/resources/guides/develop/phase0-presetup.md ← 필수 로드AGENTS.md > ### develop 섹션에 진행 모드·개발 범위·지원 변수(TEST_MODE) 기록{PROJECT_DIR}/.env에 크리덴셜 (또는 .env.example에 키 등록)HighLevel 아키텍처 14.1 개발 단계에서 구현 범위를 사용자에게 선택받음.
설계서의 인증 방식이 OAuth2/하이브리드인 경우 Provider 크리덴셜 수집.
프론트엔드 이미지 생성용 GEMINI_API_KEY 수집.
ai-service-design.md 존재 시 LLM/Tool/RAG 크리덴셜 수집.
브라우저 테스트 모드(자동/수동) 선택 → AGENTS.md 지원 변수 > TEST_MODE에 저장.
단계별 승인/자동 진행 선택. 단계별 승인 시 ASK_USER 형식 정의됨. (중요) 자동 진행 시 사용자에게 진행에 필요한 정보를 한꺼번에 요청. AskUserQuestion 사용하지 않고 대화창으로 질문
Step 1은 두 단계로 구성된다:
{NPD_PLUGIN_DIR}/resources/guides/develop/dev-plan.mddocs/develop/dev-plan.md{NPD_PLUGIN_DIR}/resources/guides/develop/design-contract-compile.mddocs/develop/dev-plan.md (Step 1-1 산출물)docs/design/sequence/inner/*.puml (내부 시퀀스)docs/design/sequence/outer/*.puml (외부 시퀀스)docs/design/api/*.yaml (API 명세)docs/develop/dev-plan.md (확장된 통합 맥락)test/design-contract/*.spec.ts (행위 계약 참고 자료 — 백엔드 구현 시 분기 누락 방지용, 실행 불요){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(행위 계약 참고 자료)
{NPD_PLUGIN_DIR}/resources/guides/develop/backend-env-setup.mdgradlew, gradlew.bat, gradle/wrapper/, settings.gradle, build.gradle(루트), {service-name}/build.gradle(서비스별), {service-name}/src/main/resources/application.yml(서비스별), common/src/main/java/.../common/.env.example 템플릿에 정의되며, 실제 값은 {PROJECT_DIR}/.env에서 통일){PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트{NPD_PLUGIN_DIR}/resources/guides/develop/backing-service-setup.mddocker-compose.yml 작성 → DB(PostgreSQL/MySQL/MariaDB/MongoDB)/Cache/MQ + Prism Mock 서버 구성. 기본 제품(PostgreSQL) 외 선택 시 카테고리 가이드 참조./docker-compose.yml, ./.env.example, docs/develop/backing-service-result.mddocker compose --profile mock up)docker compose --profile ai up, AI 서비스 존재 시만){PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트{NPD_PLUGIN_DIR}/resources/guides/develop/frontend-env-setup-react.md{NPD_PLUGIN_DIR}/resources/guides/develop/frontend-env-setup-vue.md{NPD_PLUGIN_DIR}/resources/guides/develop/frontend-env-setup-flutter.mdfrontend/ 프로젝트 골격, tools/generate-runtime-env.sh (프로젝트 서비스 구성에 맞게 동적 생성됨), npm run dev 실행 확인{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트{NPD_PLUGIN_DIR}/resources/guides/develop/ai-service-env-setup.mdai-service/ 프로젝트 골격, uvicorn 실행 확인{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트Phase 1 / Step 2 ~ Step 5는 병렬 실행: 4개 에이전트가 동시에 작업. Step 2와 Step 3의 환경변수 정합성은 placeholder 방식으로 해결 (각자 독립 작성, 값은
{PROJECT_DIR}/.env에서 통일..env.example은 키 템플릿)
{NPD_PLUGIN_DIR}/resources/guides/develop/run-profile.md{service-name}/.run/{service-name}.run.xml (서비스별){PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트참고: Phase 0 / Step 2에서 OAuth2 크리덴셜을 사전 수집하였다. '나중에 설정'을 선택한 경우: 본 Step 에이전트에 "OAuth2 크리덴셜 미설정, 코드 구현만 진행하고 통합 테스트는 생략" 지시를 포함한다. Phase 3 진입 전에
{PROJECT_DIR}/.env파일에서 다시 확인한다.
{NPD_PLUGIN_DIR}/resources/guides/develop/backend-api-dev.mddocs/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 (행위 계약 참고 자료)test/design-contract/{service-name}/*.spec.ts의 it() 케이스를 참고하여 alt/else 분기 누락 방지 (테스트 실행 불요){service-name}/src/main/java/.../{service-name}/(API 구현 코드), {service-name}/src/test/java/.../{service-name}/(단위 테스트 코드){PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트참고: Phase 0 / Step 3에서 Gemini API Key를 사전 수집하였다. '나중에 설정'을 선택한 경우: 본 Step 에이전트에 "Gemini API Key 미설정, 이미지 생성 불가 — 이미지가 필요한 곳은 CSS/SVG 기반 대체 구현" 지시를 포함한다.
{NPD_PLUGIN_DIR}/resources/guides/develop/frontend-dev-react.md{NPD_PLUGIN_DIR}/resources/guides/develop/frontend-dev-vue.md{NPD_PLUGIN_DIR}/resources/guides/develop/frontend-dev-flutter.mdfrontend/src/components/, frontend/src/layouts/, frontend/src/services/api/, frontend/src/hooks/, frontend/src/pages/docker compose --profile mock up (Phase 1 / Step 3에서 구성){PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트SKIP 조건: Phase 1 / Step 1에서 AI SKIP으로 결정된 경우 건너뜀
참고: Phase 0 / Step 4에서 AI 서비스 크리덴셜을 사전 수집하였다. '나중에 설정'을 선택한 경우: 본 Step 에이전트에 "LLM 크리덴셜 미설정, 코드 구현만 진행하고 실제 LLM 호출 테스트는 생략" 지시를 포함한다. Phase 3 진입 전에
{PROJECT_DIR}/.env파일에서 다시 확인한다.
{NPD_PLUGIN_DIR}/resources/guides/develop/ai-service-dev.md{service-name}/models/, {service-name}/clients/, {service-name}/prompts/, {service-name}/services/, {service-name}/routers/, {service-name}/tests/{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트Phase 2 / Step 1 ~ Step 3은 병렬 실행: 백엔드는 실제 API 구현, 프론트엔드는 Prism Mock으로 독립 개발, AI는 별도 서비스로 독립 개발
{NPD_PLUGIN_DIR}/resources/guides/develop/frontend-integration-react.md{NPD_PLUGIN_DIR}/resources/guides/develop/frontend-integration-vue.md{NPD_PLUGIN_DIR}/resources/guides/develop/frontend-integration-flutter.mdfrontend/public/runtime-env.js, frontend/src/services/api/client.ts, frontend/src/services/api/authService.ts, frontend/src/store/authStore.ts, frontend/(실제 API 연동 완료){PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트{NPD_PLUGIN_DIR}/resources/guides/develop/backend-ai-integration.md.../client/AiServiceClient.java(인터페이스), .../client/AiServiceClientImpl.java(HTTP 클라이언트), {service-name}/src/main/resources/application.yml(resilience4j 섹션), .../client/AiServiceClientTest.java(통합 테스트){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 완료 필요)
{NPD_PLUGIN_DIR}/resources/guides/develop/test-api.md./gradlew clean build 성공)docs/develop/api-test-result.md (API 테스트 결과){service}/src/test/resources/data/ (SQL seed, JSON fixture){PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트선행 조건: Phase 3 / Step 3 (API 테스트) 전체 PASS 필수
Phase 0 / Step 5에서 사전 수집된 테스트 모드를 적용한다.
결정된 테스트 모드를 AGENTS.md의 ### develop > 지원 변수 섹션에 TEST_MODE: {AUTO|MANUAL} 로 기록한다.
{NPD_PLUGIN_DIR}/resources/guides/develop/test-browser-auto.md ← 필수 로드TEST_MODE = AUTO인 경우만.temp/phase4-step1-checkpoint.json) + 재테스트 루프(최대 3회) 수행docs/develop/test/e2etest-{N}.mde2e/tests/scenarios.spec.ts.temp/iter-{N}/tc-*.png (Step 2 입력){PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트{NPD_PLUGIN_DIR}/resources/guides/develop/test-browser-manual.md ← 필수 로드TEST_MODE = MANUAL인 경우만{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트선행 조건: Phase 4 / Step 1 완료
{NPD_PLUGIN_DIR}/resources/guides/develop/product-verify.md ← 필수 로드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 사용 금지)docs/develop/test/verify-po-{N}.md, verify-sp-{N}.md, .temp/iter-{N+1}/{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트선행 조건: Phase 4 / Step 2 완료
docs/develop/test/e2etest-*.md, verify-po-*.md, verify-sp-*.mddocs/develop/test/final-report.md{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트{NPD_PLUGIN_DIR}/resources/guides/develop/dev-complete.md ← 필수 로드tools/run-backend.py, tools/run-frontend.py)readme-generation.md)/npd:deploy)tools/run-backend.py, tools/run-frontend.py, {PROJECT_DIR}/README.md{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트| # | 규칙 |
|---|---|
| 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: 사유 --> 주석으로 사유를 명시한다 |
docs/develop/dev-plan.md 확장 + test/design-contract/*.spec.ts 참고 자료)docs/develop/test/final-report.md)README.md 생성 완료 (프로젝트 루트)MOCK_*/SAMPLE_*/FAKE_*, TODO/FIXME/HACK, log.info(EVENT) 패턴) 결과 0건 (의도적 잔존은 ALLOW: 주석으로 사유 명시)log.info()만 있는 발행 메서드 금지)MOCK_*·SAMPLE_*·FAKE_* 명명 상수 0건 (grep으로 검증)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 |
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 값을 갱신한다.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부터 실행한다