bpmnemonic は何をしますか？
bpmnemonic — BPMN + ニーモニック（記憶補助）。プロセス図を、実際に読めて、検索でき、バージョン管理できるドキュメントに変換します。夜中の2時にエディタで .bpmn ファイルを開く人はいませんが、マークダウンなら誰でも読めるからです。
なぜこれが必要か
BPMNファイルは、アクター、判断、例外パス、データフロー、メッセージ交換といった豊富なセマンティクスを保持していますが、それはビューアを開いているときだけです。以下のような場面に直面した瞬間、
- PRレビューでプロセスを議論する
- 要件を外部委託先に送る
- 新しいエンジニアをオンボーディングする
- プロセスを言語モデルに入力する
…図は障害物になります。散文が必要です。図と完全に一致した散文が必要です。そして、図が変わるたびに手書きしたくはありません。
このスキルは、BPMN構造から2種類のマークダウン形式への変換をコード化します：
specs.md— エンジニア向けの技術仕様書。番号付きステップ、網羅的なフロー、データ契約、受入基準。prd.md— ステークホルダー向けの製品要件ドキュメント。問題定義、アクター、ユーザージャーニー、成功指標、スコープ。
どちらも同じ図から導出されます。対象読者、用語、強調するBPMN要素が異なります。
呼び出し方
| トリガー | 動作 |
|---|---|
/bpmnemonic または /bpmn-to-spec または /flow-to-doc | デフォルト — ファイルを分析し、生成する形式を尋ね、生成 |
/bpmnemonic spec [path] | BPMNファイルから specs.md を生成 |
/bpmnemonic prd [path] | BPMNファイルから prd.md を生成 |
/bpmnemonic both [path] | 両方のドキュメントを生成 |
/bpmnemonic analyze [path] | scripts/analyze-bpmn.sh を実行し、要素数と複雑さを報告 |
| 自然言語: "このBPMNをspecに変換して"、"この図からPRDを作って"、"このワークフローを文書化して" | 同上 |
停止/無効化
セッション型ではありません。ファイルごとに一回限り実行します。
変換プレイブック（5ステップ）
ステップ1：解析と棚卸し
.bpmn ファイル（単なるXMLです）を読み込み、棚卸しを行います：
- プロセス 名、id、およびドキュメント
- 参加者（
bpmn:participant） — これらは「アクター」または「外部システム」になります - レーン（
bpmn:laneSet内のbpmn:lane） — これらは「役割」または「責任範囲」になります - タスク（
bpmn:task、bpmn:userTask、bpmn:serviceTask、bpmn:sendTask、bpmn:receiveTask、bpmn:scriptTask、bpmn:businessRuleTask、bpmn:manualTask） — これらは番号付きステップになります - イベント（
bpmn:startEvent、bpmn:endEvent、bpmn:intermediateThrowEvent、bpmn:intermediateCatchEvent、bpmn:boundaryEvent） — トリガー、終了、エラー捕捉、タイムアウト - ゲートウェイ（
bpmn:exclusiveGateway、bpmn:parallelGateway、bpmn:inclusiveGateway、bpmn:eventBasedGateway） — 分岐ポイント - シーケンスフロー（
bpmn:sequenceFlow） — 矢印 - メッセージフロー（
bpmn:messageFlow） — プール間の通信、連携ポイント - データオブジェクト（
bpmn:dataObject、bpmn:dataObjectReference） — ドキュメント、レコード、ペイロード - サブプロセス（
bpmn:subProcess、bpmn:callActivity） — 入れ子の複雑さ
scripts/analyze-bpmn.sh を実行すると、この棚卸しが自動的に生成されます。
ステップ2：線形ナラティブの構築（ハッピーパス）
各開始イベントから各終了イベントまでシーケンスフローを辿り、すべてのゲートウェイで逸脱しないパス（つまり最も成功する可能性の高いパス）を選択します。これが「ハッピーパス」であり、specとPRDの両方の背骨になります。
番号付きステップとしてフォーマットします。各ステップはアクター（レーンから）とアクション（タスク名から）を示します。
ステップ3：分岐（代替フロー）
ハッピーパス上で遭遇する各ゲートウェイについて、他の分岐はspecでは代替フロー、PRDではエッジケースになります。メインフローの後に番号を振ります。
ステップ4：例外の捕捉
タスクに付随する境界イベント（bpmn:boundaryEvent）— エラーイベント、タイマイベント、エスカレーションイベント — は例外フローになります。これらは通常PRDでは欠落しますが、specでは重要です。
ステップ5：プール間通信の特定
プール間のメッセージフローは連携ポイントになります。specでは、これらは外部API契約です。PRDでは、「これは～に依存する」セクションです。
出力形式の選択
ユーザーが指定しない場合は質問します。それ以外は以下のヒューリスティックを使用します：
| 図に含まれるもの... | 推奨形式 |
|---|---|
| 1つのプール、主にユーザータスク、合計10要素未満 | PRD — 機能説明として十分小さい |
| 複数のプール、メッセージフロー、エラーイベント | specs.md — エンジニアリングに詳細が必要 |
| サブプロセスまたは呼び出しアクティビティ | specs.md + 各サブプロセスを個別に変換することを推奨 |
| 「決定表」ゲートウェイ（DMN） | 両方 — PRDはルールを説明、specは表を記録 |
| 迷った場合 | 両方 — 互いに参照し合う |
実行フロー（Claudeの動作）
.bpmnファイルを読み込む（XMLです。Readツールを使用し、その後手動またはscripts/parse-bpmn.shで解析）。- ステップ1に従って要素を棚卸しする。
- 指定がない場合は形式を提案する。確認を得る。
- ハッピーパスを辿り、線形ナラティブを構築する。
- 代替フロー（ゲートウェイ分岐）、例外フロー（境界イベント）、連携ポイント（メッセージフロー）を特定する。
playbook/templates.mdから選択したテンプレートをレンダリングし、実際の内容を埋め込む。- ファイルを書き込む前にユーザーにプレビューする。確認を求める。
./specs.mdおよび/または./prd.mdに書き込む。ファイルが既に存在する場合は差分を表示し、上書き前に確認する。
安全ガードレール
- ソースは読み取り専用。
.bpmnファイルを決して変更しない。マークダウンのみを出力する。 - 元のIDを保持する。 生成されたマークダウン内でBPMN要素IDをコメントとして参照することで、将来の更新時に相互参照できるようにする。（
<!-- from bpmn:userTask id="UserTask_1a2b3c" -->） - フローをでっち上げない。 図にパスが示されていない場合は、書かない。曖昧な点がある場合は、推測せずにドキュメント内で未解決の質問として提示する。
- DMNテーブルはインライン翻訳しない。 ごく小規模な場合を除き、参照し、ルールを要約し、別の決定表ドキュメントを推奨する。
- 名前のない要素をフラグする。
name属性のないbpmn:task id="Task_42"は図のバグです。出力では名前をでっち上げずに[名前なしタスク — ラベルが必要]として表示する。 - プレビューと確認なしに既存の specs.md / prd.md を上書きしない。 手動で追記された内容が含まれている可能性がある。
このスキルに含まれるファイル
SKILL.md— このファイルplaybook/elements.md— BPMN要素リファレンス（各タグの意味）playbook/extraction.md— .bpmn XMLファイルの読み方：タグ名、属性、フローの追跡方法playbook/templates.md—specs.mdとprd.mdの目標構造playbook/pitfalls.md— プロセス図を文章化する際のよくある間違いexamples/01-approval.md— 小さな経費承認フロー → 両方の出力examples/02-loan.md— 複数レーンとゲートウェイがあるローン申請 → specexamples/03-errors.md— タイマー/エラーイベントを含む注文フルフィルメント → specscripts/analyze-bpmn.sh— BPMN要素をカウントし、複雑性スコアを算出scripts/parse-bpmn.sh— .bpmnファイルから構造化情報を抽出（ベストエフォート、xmlstarletが利用可能な場合に使用）README.md— インストールとクイックスタート