前回は、ワークフロー図が「何が起きるか」は語っても「なぜそうなっているか」は語らないこと、そのために設計がアプリ管理者一人に属人化することを説明しました。
この記事では、その対策を扱います。新しいツールは要りません。Questetra BPM Suite の記述欄をどう使い分けるか、判断の軸を 2 つ示します。
軸 1 識別と説明の分離
まず、名前とメモの役割の違いです。
| 欄 | 役割 | 処理担当者に見えるか |
|---|---|---|
| 名前（アプリ名・工程名・項目名） | 識別。一覧や図に並んだとき、他と見分けられるか | 見える |
| メモ | 説明。なぜそうなっているか、他とどう関係するか | 見えない |
失敗は二方向に起きます。
名前に説明を詰め込む。 「確認（経理部が金額をチェック。10 万円以上は部長へ）」のような工程名です。情報としては正しいのですが、ワークフロー図が読めなくなります。名前は識別のための欄なので、短く、他と見分けられれば十分です。
名前が識別として働いていない。 「確認」という工程が 3 つあるアプリです。アプリ管理者が設定を追うときに区別できませんし、処理担当者がワークフロー図を見るときにも混乱します。「経理確認」「上長確認」「最終確認」のように分けてください。
ここで大事なのは、メモは処理担当者には見えないということです。だから、名前の分かりにくさをメモで補うことはできません。名前は名前として、識別できる状態にしておく必要があります。
データ項目の三つ組
ここまで名前とメモの二つで説明してきましたが、データ項目にはもう一つ、処理担当者向けの「説明」があります。ここに書いた内容は、ケースのフォームでその項目のすぐ下に表示されます。
| データ項目の欄 | 役割 | 処理担当者に見えるか |
|---|---|---|
| 項目名 | 識別 | 見える |
| 説明 | 入力するときの補足。「税抜で入力してください」など | 見える（フォーム上に表示） |
| メモ | なぜこの項目がこうなっているか | 見えない |
取り違えやすいところです。入力方法の注意をメモに書いてしまうと、それを読んでほしい相手には届きません。処理担当者に読ませたいのは「説明」、アプリ管理者に残したいのは「メモ」です。
一方、工程には処理担当者向けの説明欄がありません。名前とメモだけです。ですから工程について処理担当者に伝えたいことは、業務マニュアルか、フォーム上のガイドパネルに書くことになります。
軸 2 現在形と過去形の分離
次に、メモとバージョンメモの役割の違いです。
| 欄 | 書く内容 | 書き換えるか |
|---|---|---|
| メモ（工程・スイムレーン・データ項目・アプリ管理者向けメモ） | 現在形。いまの設計が、なぜこうなっているか | 設計が変われば書き換える |
| バージョンメモ | 過去形。このバージョンで、何を、なぜ変えたか | リリース後は書き換えられない |
前回の 10 万円の例で言えば、こうなります。
- メモに書く ── 10 万円は購買規程 3 条の決裁権限に対応。規程が変わったらここも変える
- バージョンメモに書く ── 決裁権限の閾値を 10 万円から 20 万円に変更。2026 年 4 月の購買規程改定に対応
両方書きます。片方だけだと、後任者は「いま、なぜこうなっているのか」か「いつ、なぜ変わったのか」のどちらかを失います。
そしてメモのほうは、変更のたびに書き換えることが要点です。設定を 20 万円に変えたのにメモが「10 万円は……」のままなら、その瞬間からメモは嘘になります。
バージョンメモは逆で、書き換えようがありません。編集できるのは開発中のバージョンだけで、リリースの時点でそのバージョンの記録として固定されます。この制約があるので、過去のバージョンの記録は信頼できます。
記述欄ごとの指針
2 つの軸を、Questetra BPM Suite の各記述欄に当てはめると、次のようになります。
| 記述欄 | 主な読み手 | 書く内容 |
|---|---|---|
| 概要 | 処理担当者 | このアプリで何ができるか。一行で |
| 業務マニュアル | 処理担当者 | 使い方。操作手順、入力時の判断基準 |
| データ項目の説明 | 処理担当者 | その項目を入力するときの補足。フォーム上に表示される |
| ガイドパネル | 処理担当者 | フォーム全体や一群の項目にかかる案内。入力欄を持たない表示専用のデータ項目で、本文はその「説明」に書く |
| 注釈 | ワークフロー図を見る人すべて | 図を読むうえでの補足。特に目立たせたい注意 |
| アプリ管理者向けメモ | アプリ管理者 | アプリ全体の設計方針、関連アプリ、外部システム連携の前提 |
| 工程・スイムレーン・データ項目のメモ | アプリ管理者 | その要素が、なぜそうなっているか |
| バージョンメモ | アプリ管理者 | このバージョンで、何を、なぜ変えたか |
読み手が処理担当者の欄と、アプリ管理者の欄が、はっきり分かれています。処理担当者向けの操作説明をアプリ管理者向けメモに書いても、その画面には表示されません。逆に、設計の裏事情を業務マニュアルに書けば、読む人を混乱させます。
何を書き、何を書かないか
メモについては、判断基準を一つ示せます。その要素の設定を見れば分かることは、書かない。設定を見ても分からないことだけを、書く。
書かない例です。
- 「このデータ項目は必須です」── 必須の設定を見れば分かります
- 「金額が 10 万円以上のとき部長承認に分岐します」── 分岐の条件式を見れば分かります
- 「締め切りはトークン到達の 5 日後です」── 締め切りの設定を見れば分かります
- 「この工程は経理部が担当します」── スイムレーンの処理担当者の設定を見れば分かります
書く例です。
- なぜその値なのか
- 10 万円は購買規程 3 条の決裁権限に対応。規程が変わったらここも変える
- 業務ルールは 3 営業日。締め切りに営業日は指定できないため、余裕を見て 5 日にしている
- 選択肢の並び順は申請件数の多い順。年度初めに見直す
- 他とどう関係するか
- この項目の値は、終了直前の自動工程で kintone の「顧客マスタ」へ送っている。空のまま完了させると、kintone 側のレコードが空で上書きされる
- この日付は、子ケースとして開始する「契約更新リマインド」アプリに渡している。渡した値がそのまま子ケース側の締め切りになる
- この選択肢 ID は基幹システムのコード表と一対一。増やすと連携が失敗する
- 何をしてはいけないか
- 件名にケース連番を差し込んでいるのは、この「データ更新」工程。経路から外すと件名が空のままになる
- このスイムレーンの処理担当者から申請者を外しているのは監査要件のため。兼務者がいても戻さない
- 差し戻しの経路を、この自動工程の手前につなぎ直さないこと。二度通ると請求が二重に登録される
- なぜそうしなかったのか
- 自動化を検討したが例外が多く断念。手動のままにしている
- 選択肢マスタ（アドオン）での管理も検討したが、更新が年 1 回なので「固定の選択肢」にしている
- 分岐を 3 本に分ける案もあったが、運用側が判断できないため 2 本にとどめている
設定の言い換えは、書いた気になれるだけで価値がありません。しかも設定を変えたときに更新し忘れやすく、真っ先に嘘になります。書く価値があるのは、アプリ全体を見渡して初めて分かることか、アプリの外にある事情です。
ひとつ、この基準から外れるものがあります。変更の経緯です。 「2026 年 4 月に 20 万円から変更」は、設定を見ても分かりません。それでもメモには書きません。書く場所が別にあるからです。
メモは変更のたびに書き換える欄なので、経緯を書けば、次の変更で消えるか、消されずに積もるかのどちらかになります。過去形の記録はバージョンメモに書いてください。ソフトウェア開発でも、変更の経緯はコードのコメントではなくコミットログに書きます。同じ理由です。
文字数の上限
メモ（工程・スイムレーン・データ項目・アプリ管理者向けメモ）、概要、注釈、バージョンメモは、いずれも 256 文字までです。長い文章を書けるのは、業務マニュアルとデータ項目の説明で、どちらも処理担当者向けの欄です。
メモは、1 要素あたり数行という分量で書きます。そこに収まらないときは、読み手と対象で書く場所を分けてください。その要素固有の理由はその要素のメモに、アプリ全体にかかる方針はアプリ管理者向けメモに、処理担当者に読ませたい説明は業務マニュアルに書きます。
続けるための 3 つのルール
- 変更するときに書く。 「アプリが完成したら設計書を整備しよう」と考えると、その時間は来ません。設定を変えた、その場で、そのときの理由を書きます。分かっているのはその瞬間だけです。
- 空欄を埋めることを目的にしない。 「承認を得るため」のような、内容のない記述で欄を埋めるのは、空欄のままより有害です。空欄は「書かれていない」と正しく伝えますが、無内容な記述は「これが理由です」と嘘をつきます。読んだ人はそこで探すのをやめます。書くべき理由がないなら、空のままで構いません。
- 古くなったメモを放置しない。 設定を変えたら、その要素のメモを読み返します。まだ正しければそのまま、ズレていれば直します。逆に、既存のメモを根拠なく消さないでください。意味が分からないメモは、消すのではなく、書いた人に確認します。分からないということは、そこに記録が必要だったということです。
まとめ
- 名前は識別、メモは説明。名前に説明を詰め込まない
- データ項目は三つ組。処理担当者に読ませたいなら「説明」、アプリ管理者に残したいなら「メモ」
- メモは現在形、バージョンメモは過去形。いまの理由と、変えた理由
- 設定を見れば分かることは書かない
- 変更するときに書く
必要なのは、新しいツールでも、大掛かりな設計書でもありません。すでにある記述欄に、変更のたびに数行書くことです。効果が出るのは、書いた本人がいなくなった後です。
次回
次回は、AI にワークフローアプリを作らせる場面を扱います。設計意図の記録は、AI に仕事を任せるための前提条件でもあります。
- 設計の意図を残そう（AI に任せる編）《近日公開予定》
