業務フロー整理ドキュメントの書き方
構成要素・なぜ必要か・実際の経験談・ツール選定

「このタスク、誰がどの順番でやるんだっけ？」

チームが大きくなるにつれ、こういう疑問が増えてくる。オンボーディングのたびに口頭で説明し、属人化したフローがブラックボックスになり、バグ報告で初めて手順の抜け漏れに気づく——そんな経験があるエンジニアは多いのではないだろうか。

この記事では、業務フローを整理するドキュメントの構成・書き方・運用方法について、実際のプロジェクトでの経験をもとに解説する。

業務フロー整理ドキュメントとは

業務フロー整理ドキュメントとは、誰が・何を・どの順番で・どの条件で行うかを記述した文書だ。コードで言えば README に近い位置づけで、実装の「なぜ」と「どうやって」をつなぐ役割を持つ。

対象は社内業務に限らない。たとえば：

• ユーザー登録〜本人確認までの処理フロー
• 障害発生時のエスカレーションフロー
• リリース前のチェック・承認フロー
• データ取り込みのバッチ処理フロー

これらすべてがドキュメント化の対象になりうる。

なぜ業務フロードキュメントを整備しなければならないか

フロー概要（全体像）

アクター・担当者の整理

条件分岐・例外処理

入力・出力（インプット／アウトプット）

更新・メンテナンスルール

関連リソースへのリンク

なぜエンジニアが書くべきか

「業務フローはビジネスサイドの仕事」と思われがちだが、実際にはエンジニアが書いた方が精度が高くなるケースが多い。理由は3つある。

1. システムの制約を知っている
「ここで非同期処理が入るので、ユーザーへの通知は数分後になる」といった実装上の制約を、ビジネスサイドだけでは正確に記述できない。

2. 例外パターンを把握している
コードレビューやバグ対応を通じて、エラーケースや境界値を最もよく知っているのはエンジニアだ。

3. 更新コストを下げられる
ドキュメントをコードに近い場所（リポジトリ内など）に置くことで、実装変更時に一緒に更新しやすくなる。

ドキュメントの構成要素

1. フロー概要

最初に全体像をつかめる記述を置く。1〜3文で「このフローは何をするものか」を書く。

## 注文キャンセルフロー

ユーザーが注文をキャンセルする際の処理フロー。
注文ステータスが「発送前」の場合のみキャンセル可能。
返金はStripeのrefund APIを通じて自動で行われる。

2. 登場人物（アクター）の整理

誰が関与するかを最初に明示する。

3. フロー図

フロー図は Mermaid で書くのが現在のベストプラクティスのひとつだ。Gitリポジトリに置けるテキスト形式で、レビューも差分確認もできる。

flowchart TD
    A[ユーザーがキャンセルリクエスト] --> B{注文ステータス確認}
    B -->|発送前| C[ステータスをCANCELLEDに更新]
    B -->|発送済み| D[エラー: キャンセル不可]
    C --> E[Stripe refund API呼び出し]
    E -->|成功| F[通知メール送信]
    E -->|失敗| G[Slackアラート + 手動対応キュー追加]
    F --> H[完了]

4. 条件分岐・例外処理

フロー図で表現しきれない細かい条件は、テキストで補足する。

## 例外ケース

- **注文から30日以上経過している場合**: 自動返金不可。CSチームが手動対応。
- **部分キャンセル（商品の一部のみ）**: 現在未対応。全件キャンセルのみ受け付ける。
- **Stripe APIタイムアウト**: リトライ最大3回。それでも失敗した場合は手動対応キューに追加。

5. 入力・出力の定義

6. 関連リンク・参照

## 関連リソース

- 実装: `src/order/cancel.ts`
- Stripe Refund API: https://stripe.com/docs/api/refunds
- CSチーム手動対応手順: Notion > CS > 返金手動対応

実際の経験談：「ないと困る」を実感した瞬間

オンボーディングの口頭説明が毎回15分かかっていた

あるプロジェクトで、新メンバーが参加するたびに「データ取り込みバッチの流れ」を毎回口頭で説明していた。S3からファイルを取得して、バリデーションして、DBに書き込んで、失敗したらDLQに入って……という10ステップ程度のフローだ。

ドキュメントがないため説明する人によって微妙に内容が違い、「DLQの確認って毎日やるんでしたっけ？」という質問がSlackに繰り返し飛んできた。

障害対応中に手順が曖昧で時間を溶かした

深夜の障害対応中、「決済フローのどのステップでエラーが起きているか」を特定するのに30分以上かかったことがある。コードを読めば分かるが、障害対応中にコードを全部追うのは辛い。

フロー図があれば「ステップ3のStripe呼び出し後でコケている」とすぐ絞り込めた。事後にドキュメントを整備したが、「もっと早く書いておけば」という後悔が残った。

仕様変更時にドキュメントだけ更新されなかった

逆に失敗した経験もある。コードは更新したがドキュメントを放置した結果、3ヶ月後に自分が「古い手順を正として」バグを仕込んだ。

書き方のポイント

粒度の決め方

粒度は「新人が一人で作業できるか」を基準にするとちょうどいい。細かすぎると更新コストが増し、粗すぎると役に立たない。

図と文章の使い分け

更新しやすくする工夫

• コードと同じリポジトリに置く: docs/flows/ ディレクトリを作る
• PRテンプレートに「フロー変更の有無」を含める: 実装変更時にドキュメント更新を促す
• 最終更新日を書く: 古さを可視化する。<!-- last updated: 2026-06 --> でよい

ツール選定

エンジニアチームだけで完結するなら Mermaid + リポジトリ管理 が最もメンテナンスしやすい。

まとめ

業務フロー整理ドキュメントで押さえるべきポイントをまとめると：

• 構成: 概要・アクター・フロー図・例外ケース・入出力・関連リンク
• 図はMermaid: テキスト形式でリポジトリ管理できる
• 粒度: 「新人が一人で作業できるか」を基準に
• 運用: コードと同じPRで更新するルールを作る

※ この記事は実際のプロジェクト経験をもとに構成しています。フロー図のサンプルは説明用に簡略化しています。