hanifalkauni/uml-architect

UML-Architect スキルインストラクション

このインストラクションは、AIエージェントがUML-Architect MCPサーバーの100%同一かつ一貫性のある決定的エンジン出力を生成するように指示します。

---

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トークンチェック、セッション、リクエストスキーマ検証（Zod, Joi, Pydantic, DTOバリデータ）を追跡。
3. コントローラ/ハンドラ: リクエストパラメータ抽出ロジックとサービスレイヤーへの委譲を確認。
4. サービス/ドメインレイヤー: コアビジネスフロー、ヘルパー呼び出し、データ計算を追跡。
5. データベースとORM: クエリ/ミューテーション操作（SELECT, INSERT, UPDATE, トランザクションコミット/ロールバック）を追跡。
6. 外部統合: HTTP呼び出し（Stripe, 銀行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
サードパーティ/外部	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 Validasi Input / Auth Gagal
         Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
     else Validasi Lolos (Happy Path)
         Ctrl->>Svc: processRequest(payload)
         ...
     end
     

3. 自己修復シンタックス（エラー防止）:
   • メッセージ内で引用符なしの角括弧文字を避ける。
   • 参加者IDにスラッシュ文字（/）を直接使用しない（常に Ctrl、Svc などのクリーンなエイリアスを使用）。

---

4. 必須出力形式（標準出力契約）

図作成の各レスポンスは、MCPサーバーの出力と同一にするために、以下のMarkdown構造に厳密に従う必要があります:

# UML Diagram: <Target / Endpoint Name>

> *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 <ControllerName> (Controller)
    participant Svc as <ServiceName>
    participant DB as Database (Storage / ORM)
    participant Queue as Message Broker (Kafka / Queue)

    Client->>Ctrl: <HTTP_METHOD> <URL_PATH>
    alt Validasi Input / Auth Gagal
        Ctrl-->>Client: 400 Bad Request / 401 Unauthorized
    else Validasi Lolos (Happy Path)
        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 "<ControllerName> (Controller)" as Ctrl
participant "<ServiceName>" as Svc
participant "Database (Storage / ORM)" as DB
participant "Message Broker (Kafka / Queue)" as Queue

Client -> Ctrl: <HTTP_METHOD> <URL_PATH>
alt Validasi Input / Auth Gagal
Ctrl --> Client: 400 Bad Request / 401 Unauthorized
else Validasi Lolos (Happy Path)
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メソッド` `URLパス` のリクエストを **Ctrl** に送信。
   * *条件チェック*: パラメータが無効または認証に失敗した場合、フローは直ちにHTTP 400/401レスポンスで中断。
2. **Ctrl** が有効なペイロードを **Svc** に委譲。
3. **Svc** が **DB** に対してクエリ/ミューテーションを実行し、保存確認を受信。
4. **Ctrl** が通知イベントを **Queue** に発行。
5. **Ctrl** がHTTP 200/201成功レスポンスを **Client** に返す。

#### エラー処理と例外（エラーパス）:
* **ValidationException**: ペイロードがスキーマ要件を満たさない場合、HTTP `400` レスポンスを生成。
* **UnauthorizedException**: 認証トークンが無効または期限切れの場合、HTTP `401` レスポンスを生成。
* **InternalException**: ネットワーク障害またはデータベースロールバックが発生した場合、HTTP `500` レスポンスを生成。

---

5. その他の図タイプ（ユーザーから要求された場合）

• フローチャート/アクティビティ図: 開始/終了ノードに丸括弧 ([ ... ])、決定ダイヤモンドに { "条件?" }、プロセスボックスに [ ... ] を使用した flowchart TD を使用。
• ステートマシン図: 初期状態 [*]、遷移状態、ガード、終了状態 [*] を持つ stateDiagram-v2 を使用。
• コンポーネント/アーキテクチャ図: ネストされた subgraph（プレゼンテーションレイヤー、ビジネスロジックレイヤー、データ＆永続化レイヤー）を持つ graph TD を使用。