Stats
Actions
Tags
From npd
Architecture and technical design workflow for cloud projects: selects architecture patterns, produces logical/sequence/API/class/data designs, and high-level architecture definitions.
How this skill is triggered — by the user, by Claude, or both
Slash command
/npd:designThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
[NPD Design 활성화]
[NPD Design 활성화]
아키텍트·AI엔지니어가 협업하여 클라우드 아키텍처 패턴 선정부터 논리/시퀀스/API/클래스/데이터/AI 서비스 설계 및 HighLevel 아키텍처 정의까지 전체 기술 설계 과정을 수행함.
참고: 서비스 기획(고객 분석, 유저스토리, UI/UX 설계, 프로토타입)은
/npd:plan에서 수행합니다. 본 스킬은 기술 아키텍처 설계에 집중합니다.
사용자가 /npd:design 호출 시 또는 "설계 시작", "설계해줘", "기술 설계" 키워드 감지 시.
주의사항: 중간 단계부터 시작할 때도 사전 설정 수집 및 진행 모드를 설정하는 Phase 0은 항상 수행해야 합니다.
/npd:create 완료 (프로젝트 디렉토리 및 AGENTS.md 존재)/npd:plan 완료 (기획 산출물 존재)AGENTS.md 파일에서 ## 환경변수 섹션의 환경변수 로딩.
로딩 실패 시 사용자에게 /npd:create를 먼저 수행하라고 안내하고 종료.
| 에이전트 | FQN |
|---|---|
| architect | npd:architect:architect |
| ai-engineer | npd:ai-engineer:ai-engineer |
| product-owner | npd:product-owner:product-owner |
| backend-developer | npd:backend-developer:backend-developer |
| frontend-developer | npd:frontend-developer:frontend-developer |
| devops-engineer | npd:devops-engineer:devops-engineer |
| qa-engineer | npd:qa-engineer:qa-engineer |
{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/guides/design/common-principles.md를 준수.
{PROJECT_DIR}/AGENTS.md에 각 Phase의 Step 완료 시 저장. 최종 완료 시 Done으로 표기.
## 워크플로우 진행상황
### design
- 진행 모드: {선택값}
- ORG: {입력값}, ROOT: {입력값} (Phase 0 / Step 1에서 기록)
- CLOUD: {선택값} (Phase 0 / Step 2에서 기록)
- 설계 아키텍처 패턴: {서비스명}→{패턴}, ... (Phase 2 / Step 3-2 완료 후 기록)
- 마지막 완료 Phase/Step: Phase 1/Step 0
{PROJECT_DIR}/AGENTS.md의 ## 워크플로우 진행상황 > ### design에 진행상황 정보가 있는 경우 마지막 완료 Step 이후부터 자동 재개.
Phase 0: 사전 설정·진행 모드 선택 (패키지 네이밍 + Cloud 선택 + 진행 모드)
↓
Phase 1: 아키텍처 기반 설계 (패턴 선정 + 패턴 리뷰 + 논리 아키텍처)
↓
Phase 2: 상세 설계 (시퀀스 + API + 클래스 + 데이터)
↓
Phase 3: 종합 아키텍처 (HighLevel + AI 서비스)
↓
Phase 4: 완료 보고
설계 워크플로우 시작 전, 사전 설정 수집과 진행 모드를 결정합니다. Phase 1 이후 실행 중 사용자 입력이 필요한 항목을 사전에 수집하여, "자동 진행" 선택 후 질문 없이 실행을 보장합니다.
Java 패키지 네이밍에 필요한 정보를 사용자에게 확인하고 프로젝트 AGENTS.md에 기록합니다.
{"title":"패키지 네이밍 정보","questions":[ {"question":"Java 패키지명에 사용할 회사/조직명(ORG)을 입력해 주세요.\n예) unicorn → com.unicorn.{ROOT}.{서비스명}","type":"text"}, {"question":"대표 시스템명(ROOT, Root Project명)을 입력해 주세요.\n예) lifesub → com.{ORG}.lifesub.{서비스명}","type":"text"} ]}
입력된 값을 프로젝트 루트의 AGENTS.md의 ### design 진행상황 섹션에 기록.
이후 모든 설계·개발 가이드에서
AGENTS.md의{ORG},{ROOT}값을 참조합니다.
{"title":"Cloud 서비스 선택","questions":[ {"question":"사용할 Cloud 서비스를 선택해 주세요.","type":"radio","options":["AWS","Azure","GCP"]} ]}
선택된 값을 {CLOUD} 변수에 바인딩하고, AGENTS.md의 ### design 진행상황 섹션에 기록.
{"title":"진행 모드 선택","questions":[ {"question":"각 단계 완료 후 승인을 받고 진행할까요, 자동으로 진행할까요?","type":"radio","options":["단계별 승인","자동 진행"]} ]}
승인 요청 ASK_USER 형식:
{"title":"단계 승인","questions":[ {"question":"{완료된 스텝명} 단계가 완료되었습니다. 결과 파일({생성된 파일 경로})을 검토하고 {다음 스텝명} 단계로 계속 진행할 지 승인해 주십시오.","type":"radio","options":["승인","재작업 요청","중단"]} ]}
{NPD_PLUGIN_DIR}/resources/guides/design/architecture-patterns.mddocs/design/pattern-definition.md (패턴 평가 매트릭스, Mermaid 다이어그램, Phase별 로드맵){PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트리뷰 수행 조건: 단계별 승인 모드일 때만 사용자에게 리뷰 수행 여부를 묻고, 사용자가 희망하는 경우에만 리뷰를 수행합니다. 자동 진행 모드에서는 리뷰를 건너뜁니다.
{"title":"아키텍처 패턴 리뷰","questions":[ {"question":"아키텍처 패턴 선정 결과(docs/design/pattern-definition.md)에 대해 리뷰를 수행할까요?","type":"radio","options":["리뷰 수행","건너뛰기"]} ]}
2a. 리뷰어 1 — product-owner (피오)
docs/design/pattern-definition.md, docs/plan/think/핵심솔루션.md2b. 리뷰어 2 — backend-developer (데브-백)
docs/design/pattern-definition.md, docs/plan/design/userstory.md2c. 수행 방식 및 반영 절차
## 리뷰 의견 ({리뷰어 닉네임})
### 승인/조건부 승인/재작업 요청
### 긍정적 평가
- {항목}
### 개선 필요 사항
- [{심각도: 높음/중간/낮음}] {항목}: {구체적 사유와 대안}
### 질문 사항
- {항목}
pattern-definition.md를 수정 후 재리뷰docs/design/pattern-definition.md{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트{NPD_PLUGIN_DIR}/resources/guides/design/logical-architecture-design.mddocs/design/logical-architecture.md, docs/design/logical-architecture.mmd{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트{NPD_PLUGIN_DIR}/resources/guides/design/sequence-outer-design.md, {NPD_PLUGIN_DIR}/resources/guides/design/sequence-inner-design.mddocs/design/sequence/outer/{플로우명}.puml (플로우별), docs/design/sequence/inner/{서비스명}-{시나리오}.puml (서비스-시나리오별){PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트{NPD_PLUGIN_DIR}/resources/guides/design/api-design.mddocs/design/api/{service-name}-api.yaml (서비스별){PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트Phase 0 / Step 1에서 패키지 네이밍 정보(ORG, ROOT)를 사전 수집하였습니다.
AGENTS.md의## 프로젝트 네이밍섹션에서 값을 참조합니다.
docs/design/logical-architecture.md에서 마이크로서비스 목록을 추출한 뒤, 각 마이크로서비스별로 적용할 설계 아키텍처 패턴을 결정합니다.
docs/design/class/architecture-pattern-rationale.md에 서비스별로 기록3-2a. 마이크로서비스 목록 파악
docs/design/logical-architecture.md를 읽어 마이크로서비스 목록을 파악 (AI Pipeline 등 AI 서비스는 제외 — AI 서비스는 Python/FastAPI 고유 아키텍처를 따르므로 Layered/Clean 선택 불필요).
3-2b. 서비스별 패턴 질문
아래 형식으로 마이크로서비스별 패턴을 질문 (AI 서비스를 제외한 서비스 수만큼 반복):
{"title":"설계 아키텍처 패턴 선택","questions":[ {"question":"{한글명1}({영문명1})에 적용할 설계 아키텍처 패턴을 선택해 주세요.","type":"radio","options":["Layered Architecture","Clean Architecture"]}, {"question":"{한글명2}({영문명2})에 적용할 설계 아키텍처 패턴을 선택해 주세요.","type":"radio","options":["Layered Architecture","Clean Architecture"]}, {"question":"{한글명N}({영문명N})에 적용할 설계 아키텍처 패턴을 선택해 주세요.","type":"radio","options":["Layered Architecture","Clean Architecture"]} ]}
{한글명}({영문명})은logical-architecture.md에서 추출한 실제 마이크로서비스의 한글명과 영문명으로 치환합니다. (예: 여행 서비스(travel-service))
3-2c. 변수 바인딩 및 상태 기록
{설계 아키텍처 패턴} 변수에 서비스명→패턴 매핑으로 바인딩{설계 아키텍처 패턴} 매핑을 전달{설계 아키텍처 패턴} 매핑을 AGENTS.md의 ### design 진행상황 섹션에 기록{NPD_PLUGIN_DIR}/resources/guides/design/class-design.mddocs/design/class/common-base.puml, docs/design/class/{service-name}.puml, docs/design/class/{service-name}-simple.puml, docs/design/class/package-structure.md{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트{NPD_PLUGIN_DIR}/resources/guides/design/data-design.mddocs/design/database/{service-name}.md, docs/design/database/{service-name}-erd.puml, docs/design/database/{service-name}-schema.md, docs/design/database/cache-db-design.md{PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트Phase 0 / Step 2에서 Cloud 서비스를 사전 선택하였습니다.
AGENTS.md의### design진행상황 섹션에서{CLOUD}값을 참조합니다.
{NPD_PLUGIN_DIR}/resources/guides/design/architecture-highlevel.mddocs/design/high-level-architecture.md (전체 아키텍처 종합, 각 산출물 참조 경로, ADR){PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트{NPD_PLUGIN_DIR}/resources/guides/design/ai-service-design.mddocs/design/ai-service-design.md (AI 활용 기회 목록, 엔드포인트·프롬프트 설계, 모델 선정 근거, RAG/FC/MCP 설계, 비용·성능 최적화 전략, 아키텍처 다이어그램){PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트## 설계 완료
### 생성된 산출물
#### 아키텍처
- docs/design/pattern-definition.md — 아키텍처 패턴 정의서
- docs/design/logical-architecture.md — 논리 아키텍처 설계서
- docs/design/logical-architecture.mmd — 논리 아키텍처 다이어그램
- docs/design/high-level-architecture.md — HighLevel 아키텍처 정의서
#### 시퀀스
- docs/design/sequence/outer/{플로우명}.puml — 외부 시퀀스 (플로우별)
- docs/design/sequence/inner/{서비스명}-{시나리오}.puml — 내부 시퀀스 (서비스-시나리오별)
#### API
- docs/design/api/{service-name}-api.yaml — 서비스별 OpenAPI 명세
#### 클래스
- docs/design/class/common-base.puml — 공통 컴포넌트
- docs/design/class/{service-name}.puml — 서비스별 상세 클래스
- docs/design/class/{service-name}-simple.puml — 서비스별 요약 클래스
- docs/design/class/package-structure.md — 패키지 구조도
#### 데이터
- docs/design/database/{service-name}.md — 서비스별 데이터 설계서
- docs/design/database/{service-name}-erd.puml — ERD
- docs/design/database/{service-name}-schema.md — DB 스키마 스크립트
- docs/design/database/cache-db-design.md — 캐시 DB 설계서
#### AI
- docs/design/ai-service-design.md — AI 서비스 설계
### 다음 단계
`/npd:develop` 으로 개발을 시작하세요.
POST-ACTION: {PROJECT_DIR}/AGENTS.md에 마지막 완료 Phase/Step 업데이트
| # | 규칙 |
|---|---|
| 1 | <!--ASK_USER--> 발견 시 AskUserQuestion 도구를 호출할 것 (텍스트 출력 금지) |
docs/design/ 하위 디렉토리에 생성됨/npd:plan) 산출물과의 일관성 확인완료 시 임시 상태 파일 정리. 산출물은 유지.
npx claudepluginhub unicorn-plugins/npd --plugin npdDesigns system architecture and high-level technical strategy. Use for new systems or subsystems, major refactors, technology selections, system boundaries, and long-term decisions with broad impact.
Designs system architecture for tech stack, API contracts, data models, and infrastructure shape. Supports brownfield extensions and engagement modes from Express to Meticulous.
Guides architectural thinking through requirements, high-level design, deep dives, and trade-off analysis. Use for system design, ADRs, and API planning before writing docs.