bpmn

bpmn skillの概要

bpmn skill は、PlantUML で BPMN、EIP、Lean Mapping のステンシルアイコンを使い、業務プロセス図や連携図を作成するための skill です。ワークフローの自動化、承認、オーケストレーション、メッセージング、ETL のロジックを、チームメンバーがそのまま動けるレベルまで明確に説明する図が必要な場面に特に向いています。

bpmn skill を使うべきなのは、ざっくりした業務イメージを、適切な gateway、event、task、pool/lane の選択を含む構造化された図に落とし込む仕事をしているときです。一般的なソフトウェアアーキテクチャ図や、実質的にはデータ可視化であるチャートにはあまり向いていません。

bpmn skill が最も得意なこと

• ワークフロー自動化: 承認、エスカレーション、引き継ぎ、再試行、SLA パス
• メッセージベースの連携: router、channel、translator、adapter、dead-letter の処理
• 業務フロー: 受注処理、サポートのトリアージ、saga オーケストレーション、ETL、value stream

この skill が他と違う理由

この repo は、自由描画ではなくステンシルの使い分けに最適化されています。つまり、単なる四角形と矢印ではなく、start/end event、message flow、gateway、lane といった BPMN 固有の要素が必要なときに、よりよい出力が得られます。bpmn skill はまた、process、integration、value-stream のどの視点を使うべきかを選びやすくします。

使わないほうがよいケース

class diagram、component diagram、一般的なソフトウェアモデリングが目的なら、代わりに uml を使ってください。ダッシュボード、チャート、データ可視化が必要なら、代わりに vega を使ってください。こうした用途のズレがあると、bpmn skill を前提にしたプロンプトより結果が弱くなりがちです。

bpmn skill の使い方

skill ファイルをインストールして開く

bpmn skill は次のコマンドでインストールします:

npx skills add markdown-viewer/skills --skill bpmn

そのあと、最初に SKILL.md を開き、続けて自分の業務フローに合う example ファイルを確認してください。example は、この repo の記法の選び方を最短で理解し、壊れた PlantUML を避けるための近道です。

bpmn 用のよいプロンプトを作る

強い bpmn プロンプトには、次の要素を入れてください:

• プロセス名
• トリガーまたは開始 event
• 主要な担当者または pool
• 重要な判断と例外
• BPMN、EIP、Lean Mapping のどれを重視するか
• SLA、再試行、補償処理の有無

プロンプトの例:

“Create a bpmn skill diagram for an invoice approval workflow. Start with invoice submission, route small invoices to auto-approval, medium invoices to manager review, and large invoices to manager plus finance. Include an SLA timer, escalation path, and rejection end state.”

この程度まで構造を与えると、モデルが適切な stencil family と flow logic を選びやすくなります。

先に読むべきファイル

まず次を確認してください:

• SKILL.md — 基本ルールと fence の要件
• examples/approval-workflow.md — 判断分岐の多い BPMN
• examples/microservice-orchestration.md — saga 風のオーケストレーション
• examples/eip-messaging.md — integration pattern の図
• examples/etl-pipeline.md — バッチ処理とデータ移動の flow

これらは、どの stencil family がどの用途に対応するかを示しているので、bpmn skill の理解に特に役立ちます。

出力を良くする実践的なコツ

• fence は ```plantuml か ```puml のみを使う
• 図は必ず @startuml / @enduml で囲む
• 開始から終了まで自然に読める処理には left to right direction を優先する
• 責任分界が重要なら、pool/lane を早めに指定する
• flow が sequence flow なのか message flow なのかを明示する
• 判断ポイントはラベルではなく質問文として命名する

たとえば、“Payment OK?” のほうが “Payment status” よりも、次に何を判断するのかが明確です。

bpmn skill FAQ

bpmn はプロセス図専用ですか？

いいえ。bpmn skill は、BPMN のプロセス flow に加えて、EIP の integration pattern や Lean Mapping の記号も扱います。そのため、標準的な承認フローだけでなく、ワークフロー自動化、サービスオーケストレーション、運用 value-stream 図にも使えます。

bpmn を使う前に BPMN を知っている必要がありますか？

いいえ、ただし基本的なプロセス表現は知っていたほうが有利です。誰が作業を開始するのか、どこに判断点があるのか、どこで止まる・失敗するのかを説明できれば、skill 側で実用的な図に変換できることが多いです。

bpmn は普通のプロンプトより何が優れていますか？

普通のプロンプトだと、ただの四角形と矢印になりがちです。bpmn skill は、適切な stencil family、PlantUML の書式、ワークフロー向けの慣例に寄るよう出力を誘導するため、手直しが減り、ワークフロー自動化の文脈でも読みやすい図になります。

いつ別の skill を選ぶべきですか？

主目的がソフトウェア構造、UI モック、分析チャート、データ可視化なら、別の skill を選んでください。bpmn skill が最も強いのは、「システムに何が入っているか」ではなく「仕事がどう流れるか」を問う場面です。

bpmn skill を改善する方法

テーマだけでなく、プロセスの状態を伝える

bpmn の結果が最もよくなるのは、実際のワークフローの状態遷移を説明する入力です。開始、分岐、例外、完了、引き継ぎの境界を含めてください。たとえば:

• 弱い: “Make an order diagram”
• より良い: “Order starts after checkout, validates payment, checks inventory in parallel, sends shipment and notification after reserve, and routes failures to cancel or backorder paths”

この追加情報によって、構造も stencil の選択も大きく改善します。

何を最優先したいかを明示する

承認ポリシーを重視したいなら、そのように書いてください。連携の信頼性を重視したいなら、それを伝えてください。スループットや引き継ぎの分かりやすさを重視したい場合も同様です。bpmn skill は flow の重点を変えられますが、判断基準を明示した場合に限ります。

よくある失敗パターンに注意する

典型的な問題は、gateway が曖昧になること、lane の責任分担が抜けること、message flow と sequence flow を混同することです。もうひとつよくあるのは、装飾的な step を増やしすぎて図が肥大化することです。ルーティング、責任、システム挙動を変える step だけを残してください。

ターゲットを絞って修正を重ねる

最初の出力のあと、次の版では一度に一つだけ直してください:

• “Add a timer escalation after 48 hours”
• “Split human tasks into manager and finance lanes”
• “Replace generic task boxes with EIP message translator and router icons”
• “Show compensation steps for payment failure”

このやり方は全面的な書き直しを依頼するより効果的で、bpmn skill をワークフロー自動化設計の詰まりポイントに集中させたまま改善できます。