bpmn

BPMN 2.0：プロセス図の読み取りと編集

このスキルでできること

既存の .bpmn ファイルの内容を平易な言葉で理解し、どのモデラー（Camunda Modeler、bpmn.io、Cawemo など）で開いても、有効で見やすい新規ファイルや編集済みファイルを作成できます。

役割は明確に分かれています。

• あなたが意味を考えます。プロセスが何を意味するのか、何を追加または変更するのかを判断します。
• 付属のスクリプトが決定的な処理を担当します。解析、レイアウトの再生成、検証を行います。毎回これらを手作業で行わず、スクリプトを活用してください。

BPMNを扱いやすくする一つの考え方：二つのレイヤー

.bpmn ファイルには、一つの XML ドキュメントに二つのレイヤーが含まれています。

1. 意味情報 - 実際のプロセスです。タスク、ゲートウェイ、イベント、それらを接続する bpmn:process と sequenceFlow で構成されます。これが意味を表します。
2. ダイアグラム交換形式（DI） - すべての図形の x/y 座標と、すべてのエッジのウェイポイントを含む bpmndi:BPMNDiagram です。これは図示だけを担います。

DIを手作業で編集すると、座標がずれたり、図形が重なったり、エッジが交差したりして、BPMNの作業がうまくいかなくなります。そのため、DIを手書きすることはありません。 意味情報を編集し、DIは layout コマンドに任せます。これにより、整然とした左から右へのレイアウトが決定的に生成され、図が「見やすく」なります。

layout はデフォルトでは非破壊的です。これにより問題を避けられます。すでにダイアグラムがあるファイルでは、既存のレイアウトを保持し、編集内容に合わせて同期するだけです（削除した要素の図形を取り除き、新しい要素の図形を配置します）。DIがないファイルでは、新しいレイアウトを生成します。ダイアグラム全体を破棄してゼロから再構築するのは、--rebuild を指定した場合だけです。つまり、習慣にすることは簡単です。意味情報を編集したら、必ず layout を実行してください。既存の良好なダイアグラムが壊れることはありません。

セットアップ（各マシンで一度）

このスクリプトには二つの npm パッケージが必要です。スキルのディレクトリから実行してください。

npm install --prefix "<SKILL_DIR>"

<SKILL_DIR> は、この SKILL.md を含むフォルダーです。その後、以下の四つのコマンドを使用できます。実行時に「Cannot find package」エラーが発生した場合、インストール手順を省略しています。インストールを実行してから、もう一度試してください。

図の読み取り／説明

1. 構造化された概要を取得します（生の DI 座標を読み取ろうとしないでください）。

   node "<SKILL_DIR>/scripts/bpmn-tool.mjs" summarize path/to/file.bpmn
   

   プール／レーン、開始／終了イベント、アクティビティ（タイプを含む）、 ゲートウェイ（方向を含む）、境界イベント（ホストと割り込みの有無）、 およびすべてのシーケンスフローを source -> target [condition] の形式で出力します。 プログラムで処理する場合は --json を追加してください。

2. プロセスを人が理解しやすい形で説明します。まず通常の流れを説明し、次に 判断ポイント（各ゲートウェイが何を条件に分岐するか）、並行作業、 例外／境界処理を説明します。要素 ID ではなく、実際の業務ステップの名前を 使います。ユーザーと同じ言語を使ってください。

summarize の出力を、「この図が何をするか」を把握するための信頼できる情報源として 使用してください。特に複雑な図では、XML を目視するのではなく、出力を読んでください。

編集前に特定の要素の場所を特定するには、find <file> <term> を使います （名前またはタイプに一致します）。As-Is と To-Be の比較や、編集による変更点を 正確に示すために 2 つの図を比較するには、diff <a> <b> を使います。 追加、削除、名前変更、タイプ変更された要素と、接続し直されたシーケンスフローを 報告します。

ユーザーがレビュー（「これは正しいか？」「バグを見つけて」「なぜ停止するのか？」） を求めた場合は、lint も実行してください。XML として有効で validate に 合格するものの、動作として誤っている制御フローのバグを検出します。目視では 見落としやすい種類の問題です。

node "<SKILL_DIR>/scripts/bpmn-tool.mjs" lint path/to/file.bpmn

次の問題を検出します。排他（XOR）分岐から入力される並列（AND）合流 （デッドロック）、排他合流で統合される並列分岐（2 回実行）、 デフォルト条件がなく、すべての条件が偽になる可能性がある排他ゲートウェイ （トークン停止）、到達不能なノード、行き止まり （終了ノードではないが、出力フローがないノード）、開始／終了の欠落、 暗黙的な分岐（複数の出力フローを持つ非ゲートウェイノード）、 方向が誤ったイベント（入力フローがある開始イベント、または出力フローがある 終了イベント）、アクティビティではない要素上の境界イベント、レーンを使う プロセスでどのレーンにも属さないノード、および同じプール内にとどまる メッセージフローです。検出結果を読み、モデルと照らし合わせて確認してから、 分かりやすい言葉で説明してください。

図の作成または編集

新しいプロセスの XML を作成する前に、ビジネスアナリストのように考えて構造を明確にしてください。明確なモデルと、箱と矢印が乱雑に並んだだけの図を分けるのは、この作業です。依頼内容から以下のいずれかが不明な場合は、確認してください。

• トリガー - プロセスを開始するものは何か（通常の開始、メッセージ、タイマーのどれですか？）。
• 参加者 - 誰が何をするのか。複数のアクターがいる場合は通常、レーン（1 つのプール）またはプールとメッセージフロー（別々のプロセス）を使います。
• 正常系 - 問題が起きなかった場合の主なアクティビティの流れ。
• 判断ポイント - どこでフローが分岐するのか、どの条件に基づくのか、どのゲートウェイが適切か（排他的＝どちらか一方、並列＝すべて、包含的＝1 つ以上）。
• 例外／代替 - タイムアウト、却下、エラーなど。多くの場合、境界イベントまたは追加の分岐を使います。
• 終了状態 - プロセスが終了するそれぞれのパターン。

ユーザーが現状と将来の状態を記録している場合は、As-Is と To-Be を別々の図／ファイルとして扱い、そのようにラベルを付けてください。

信頼できる手順は、セマンティクスを編集 -> レイアウトを再生成 -> 検証 -> リントです。

1. セマンティクスを記述または変更します。 新しい図の場合は、セマンティクスのみを含むドキュメント（bpmndi: ブロックなし）を手作業で作成します。簡潔で、正しく作成しやすい形式です。編集の場合は、まず summarize を実行して現在のモデルを把握し、それから bpmn:process の本体を変更します。基本構造、各要素の XML 形式、コピーして使えるレシピ（排他的／並列／包含的ゲートウェイ、境界イベント、プール、レーン、メッセージフロー）については、references/bpmn-reference.md を参照してください。

2. レイアウトを設定します。 図を編集内容に合わせて同期します。

   node "<SKILL_DIR>/scripts/bpmn-tool.mjs" layout in.bpmn out.bpmn
   

   ファイルを上書きする場合は、out.bpmn を省略してください。すでに DI があるファイルでは、既存のレイアウト（手動調整した位置、Camunda の複数図サブプロセスページ）が保持され、変更に合わせて図形が整理・配置されるだけです。新しいセマンティクスのみのファイルでは、整ったレイアウトが生成されます。ユーザーが図全体を最初からレイアウトし直すことを明示的に希望している場合に限り、--rebuild を追加してください（手動での位置調整がすべて失われることを伝えてください）。

3. 検証します。 ファイルを解析できること、すべてのフロー要素に図形があること、図形が重なっていないことを確認します。

   node "<SKILL_DIR>/scripts/bpmn-tool.mjs" validate out.bpmn
   

   指摘された問題を修正してください（参照先のない参照は解析時の警告として表示されます。図形がない場合は通常、layout を実行し忘れています。重なりは図ごとの平面で確認されるため、実際に重なりがある場合はレイアウトが詰まりすぎています。layout --rebuild を再実行してください）。

4. 制御フローをリントします。特にゲートウェイや分岐を追加または再配線した場合は重要です。

   node "<SKILL_DIR>/scripts/bpmn-tool.mjs" lint out.bpmn
   

   validate はファイルの形式が正しいことを確認し、lint はロジックが妥当であることを確認します。ゲートウェイの分岐と合流の不一致（デッドロック、二重実行）、トークンの停滞、到達不能ノード、行き止まり、開始／終了の欠落、暗黙的な分岐、開始／終了イベントの誤った方向付け、アクティビティ以外に設定された境界イベント、レーンが割り当てられていないノード、プール内にとどまるメッセージフローなど、見過ごされがちなバグを検出します。

validate と lint の両方に合格するまでは、図が完成したと断言しないでください。どちらもすばやく実行でき、ファイルが壊れているように見えたり、実際のエンジンで処理が停止したりする原因となるミス（参照のタイプミス、レイアウトの欠落、ゲートウェイのデッドロック）を検出できます。

妥当性だけでなく、明瞭さを重視したモデリング

自動レイアウトで設定できるのは配置です。モデリングの方法も、図の明瞭さを左右します。図を読みやすくするための習慣をいくつか紹介します。

• 業務用語で名前を付けます。 タスクには動詞句（「請求書を承認する」）、ゲートウェイには答えを示す質問（「金額 > 1000？」）を使い、出力フローには回答（「はい」／「いいえ」）をラベル付けします。
• 開始は 1 つにし、終了を明確にします。 すべてを 1 つの終了イベントにまとめるより、結果ごとに異なる終了イベントを設けるほうが分かりやすくなります。
• ゲートウェイを対にします。 分岐ゲートウェイには通常、合流ゲートウェイが必要です。また、トークンが行き詰まらないように、排他的ゲートウェイにはデフォルト／その他の経路を設定してください。
• 1 つの図に詰め込みすぎないでください。 図が広がりすぎる場合は、詳細をサブプロセスに移してください。

自動レイアウト：対応範囲

layout は、単一プールのフローだけでなく、日常的な BPMN の幅広いケースに対応します。

• **コラボレーション：**すべてのプールを垂直に並べてレイアウトし、プール間にメッセージフローを配置します（最初の参加者だけではありません）。
• **レーン（スイムレーン）：**ノードを各レーンの横方向の領域に配置し、レーンの図形を描画します。
• サブプロセスには、専用のドリルダウン図ページ（別個の BPMNDiagram プレーン）が用意されます。これは Camunda のエクスポートと同様です。メインキャンバスではサブプロセスはボックスとして表示され、「開く」と、そのページに内部のステップがレイアウトされて表示されます。サブプロセスはメインキャンバスにフラット化されず、空にもなりません。summarize では内部のステップが表示され、モデラーでは開いたときに確認できます。
• データオブジェクト／データストア、テキスト注釈、関連付けは、関連する要素の近くに図形やエッジが配置されます。

リクエストで以下の制限が関係する場合は、率直に伝えてください。

• グループは自動配置されません（グループはモデル内にメンバーシップを持たない純粋な視覚上の四角形なので、サイズを決める基準がありません）。必要に応じてモデラーで追加してください。
• プール、レーン、データオブジェクト、注釈の自動配置は概算です。整然としていて有効なレイアウトですが、モデラーで間隔を微調整したくなる場合があります。

詳細と回避策については、references/bpmn-reference.md を参照してください。

同梱ツール

コマンド	用途
summarize <file> [--json]	プロセスの構造化された概要を出力します。説明や編集前の把握に使用します
layout <in> [out] [--rebuild]	意味モデルに合わせて図を同期します。既存の DI を保持して更新するか、存在しない場合は生成します。--rebuild はレイアウトを一からやり直します
validate <file>	ファイルを解析して警告を報告し、フロー要素に図形が欠けていないか、またはプレーンごとに図形が重なっていないかを確認します
lint <file>	制御フローや構造上の問題を検出します。ゲートウェイの分岐／合流の不一致、トークンが停止するゲートウェイ、到達不能なノード、行き止まり、開始／終了の欠落、暗黙の分岐、イベントの誤った方向付け、不正な境界イベントのホスト、レーン未割り当てのノード、同一プール内のメッセージフローなどが対象です
diff <a> <b>	意味上および構造上の差分を出力します。追加／削除／名前変更／型変更された要素や、接続先が変更されたシーケンスフローを確認できます（現状と目標の比較や編集内容のレビューなど）
find <file> <term>	名前または型に term を含むフロー要素を一覧表示します（大文字と小文字は区別しません）。編集前の簡単な検索に使用します

これら4つのツールはすべて scripts/bpmn-tool.mjs にあります。要素の詳細なリファレンス、レシピ、エッジケースについては references/bpmn-reference.md を参照してください。要素やパターンの正確な XML が必要なときは、必ず読んでください。