hanifalkauni/uml-architect

UML-Architect 스킬 지침

이 지침은 AI 에이전트가 UML-Architect MCP 서버의 결정론적 엔진 출력과 100% 동일하고 일관된 아키텍처 분석과 UML 다이어그램을 생성하도록 합니다.

---

1. 5단계 실행 프로토콜 (실행 파이프라인)

1단계: 대상 해석 및 코드베이스 탐지

1. 대상 식별:
   • 입력이 API 엔드포인트(예: POST /api/v1/orders/checkout), 함수 이름(예: processPayment), 또는 파일/모듈 경로(예: src/controllers/order.controller.ts)인가?
2. 매니페스트 스캔 (컴파일 없이):
   • 프로젝트 내 매니페스트 파일 확인: package.json, go.mod, pom.xml, pyproject.toml, Cargo.toml, composer.json, Gemfile, 또는 *.csproj.
   • 사용 프레임워크 식별: Express/NestJS, FastAPI/Django, Gin/Fiber, Spring Boot, Axum/Actix, ASP.NET, Laravel, 또는 Rails.

2단계: 실제 호출 그래프 추적 (엄격한 추적 - 제로 환각)

실제 소스 코드에서 실행 흐름을 추적:

1. 진입점: 관련 라우트/컨트롤러 파일 열기.
2. 미들웨어 및 가드: JWT 토큰, 세션, request 스키마 검증(Zod, Joi, Pydantic, DTO validator) 추적.
3. 컨트롤러 / 핸들러: 요청 파라미터 추출 로직 및 서비스 계층 위임 확인.
4. 서비스 / 도메인 계층: 핵심 비즈니스 흐름, 헬퍼 호출, 데이터 계산 추적.
5. 데이터베이스 및 ORM: 쿼리/변경 연산(SELECT, INSERT, UPDATE, 트랜잭션 커밋/롤백) 추적.
6. 외부 통합: HTTP 콜아웃(Stripe, Bank API, SendGrid, OAuth) 또는 RPC 호출 추적.
7. 메시지 큐 / 이벤트: Kafka, RabbitMQ, SQS, Redis PubSub, Celery로의 비동기 이벤트 발행 추적.
8. 에러 분기: try/catch, if err != nil, except, 또는 에러 가드를 대체 분기(alt)로 매핑.

---

2. 표준 다이어그램 참가자 및 별칭

깔끔하고 일관된 다이어그램을 위해 표준 참가자 명명 체계 사용:

카테고리	참가자 ID	참가자 레이블 형식	참가자 유형
클라이언트 / 호출자	Client	Client / Frontend App (또는 User / Mobile App)	actor
컨트롤러 / 핸들러	Ctrl	<파일명/컨트롤러> (Controller)	participant
서비스 계층	Svc	<서비스명> (예: OrderService)	participant
제3자 / 외부	ExtAPI	<공급업체/게이트웨이명> (External API) (예: Stripe API)	participant
데이터베이스 / 스토리지	DB	Database (Storage / ORM) (예: PostgreSQL Database)	participant
큐 / 이벤트 브로커	Queue	Message Broker (Kafka / Queue)	participant

---

3. Mermaid.js 구문 규칙 및 시각적 테마

1. 테마 지시문 (다이어그램 첫 줄에 필수): 기본적으로 최신 tokyo-night 테마 사용:

   %%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
   

2. 시퀀스 다이어그램:
   • 항상 sequenceDiagram 및 autonumber 포함.
   • 동기 호출에는 ->> 사용, 반환/응답에는 -->> 사용, 비동기/큐 이벤트에는 -) 사용.
   • 검증 실패 및 성능 분기는 alt와 else 블록 내부에 감싸기:

     alt 입력 검증 / 인증 실패
         Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
     else 검증 통과 (정상 경로)
         Ctrl->>Svc: processRequest(payload)
         ...
     end
     

3. 자체 복구 구문 (에러 방지):
   • 메시지 내에서 따옴표 없이 대괄호 문자 사용을 피하세요.
   • 참가자 ID에 슬래시(/) 문자를 직접 사용하지 마세요 (항상 Ctrl, Svc 같은 깔끔한 별칭 사용).

---

4. 필수 출력 형식 계약 (표준 출력 계약)

각 다이어그램 생성 응답은 반드시 아래 템플릿과 정확히 동일한 마크다운 구조를 따라 MCP 서버 출력과 동일해야 합니다:

# UML 다이어그램: <대상 / 엔드포인트명>

> *UML-Architect Skill Agent (v1.0.0)에 의해 자동 생성됨*

## 시각적 다이어그램
```mermaid
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#7aa2f7', 'primaryBorderColor': '#3d59a1', 'actorBkg': '#24283b', 'actorBorder': '#7aa2f7', 'lineColor': '#bb9af7', 'altBkg': '#1f2335' }}}%%
sequenceDiagram
    autonumber
    actor Client as Client / Frontend App
    participant Ctrl as <컨트롤러명> (Controller)
    participant Svc as <서비스명>
    participant DB as Database (Storage / ORM)
    participant Queue as Message Broker (Kafka / Queue)

    Client->>Ctrl: <HTTP_METHOD> <URL_PATH>
    alt 입력 검증 / 인증 실패
        Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
    else 검증 통과 (정상 경로)
        Ctrl->>Svc: processRequest(payload)
        Svc->>DB: Save / Query Transaction Record
        DB-->>Svc: DB Commit Success
        Ctrl-)Queue: publish("event.completed", payload)
        Ctrl-->>Client: 200 OK / 201 Created (Success Payload)
    end
```

<details>
<summary>대체 형식 보기 (PlantUML)</summary>

```puml
@startuml
autonumber
skinparam BoxPadding 10
skinparam ParticipantPadding 10
actor "Client / Frontend App" as Client
participant "<컨트롤러명> (Controller)" as Ctrl
participant "<서비스명>" as Svc
participant "Database (Storage / ORM)" as DB
participant "Message Broker (Kafka / Queue)" as Queue

Client -> Ctrl: <HTTP_METHOD> <URL_PATH>
alt 입력 검증 / 인증 실패
Ctrl --> Client: 400 Bad Request / 401 Unauthorized
else 검증 통과 (정상 경로)
Ctrl -> Svc: processRequest(payload)
Svc -> DB: Save / Query Transaction Record
DB --> Svc: DB Commit Success
Ctrl -> Queue: publish("event.completed", payload)
Ctrl --> Client: 200 OK / 201 Created (Success Payload)
end
@enduml
```
</details>

### 아키텍처 흐름 설명 (<대상 / 엔드포인트명>)

이 실행 흐름은 **<N>개의 주요 컴포넌트**를 포함합니다:

* **Client / Frontend App** (`Client`): 사용자/호출자 엔티티 역할.
* **<컨트롤러명> (Controller)** (`Ctrl`): 요청 및 응답 제어 엔티티 역할.
* **<서비스명>** (`Svc`): 도메인 비즈니스 로직 제공 엔티티 역할.
* **Database (Storage / ORM)** (`DB`): 트랜잭션 데이터 지속성 매체 역할.
* **Message Broker (Kafka / Queue)** (`Queue`): 비동기 이벤트 수신 엔티티 역할.

#### 실행 단계 세부 사항:
1. **Client**가 `<HTTP_METHOD> <URL_PATH>` 요청을 **Ctrl**로 전송.
   * *조건 확인*: 파라미터가 유효하지 않거나 인증이 실패하면 HTTP 400/401 응답으로 즉시 중단.
2. **Ctrl**이 유효한 payload를 **Svc**로 위임.
3. **Svc**가 **DB**에 쿼리/변경을 실행하고 저장 확인을 수신.
4. **Ctrl**이 알림 이벤트를 **Queue**로 발행.
5. **Ctrl**이 HTTP 200/201 성공 응답을 **Client**로 반환.

#### 오류 및 예외 처리 (오류 경로):
* **ValidationException**: payload가 스키마 조건을 충족하지 못하면 HTTP `400` 응답 생성.
* **UnauthorizedException**: 인증 토큰이 유효하지 않거나 만료되면 HTTP `401` 응답 생성.
* **InternalException**: 네트워크 오류 또는 데이터베이스 롤백 발생 시 HTTP `500` 응답 생성.

---

5. 기타 다이어그램 유형 (사용자가 요청한 경우)

• 플로우차트 / 활동 다이어그램: 둥근 시작/끝 노드(([ ... ])), 판별 다이아몬드({ "조건?" }), 프로세스 박스([ ... ])와 함께 flowchart TD 사용.
• 상태 머신 다이어그램: 초기 상태 [*], 전이 상태, 가드, 최종 상태 [*]와 함께 stateDiagram-v2 사용.
• 컴포넌트 / 아키텍처 다이어그램: 중첩된 subgraph(프레젠테이션 계층, 비즈니스 로직 계층, 데이터 및 지속성 계층)와 함께 graph TD 사용.