FDEのドキュメンテーション術：現場で残すべき「引き継げる記録」

結論

FDEが残すべき最も重要なドキュメントは、技術仕様書でも運用マニュアルでもなく、「なぜそう設計したか」の記録です。技術仕様は後から読み解けますが、当時の判断の文脈は担当者がいなくなると永久に消えます。設計書・運用手順書・意思決定ログという3種類の記録を整えることが、FDEが去った後も現場が自走できる状態をつくる唯一の方法です。

FDEの仕事は現場に入り込み、業務とAIシステムのギャップを埋めることにあります。詳しくはFDEとは何かで解説していますが、その性質上、FDEは深く関わるほど代替不可能な存在になりやすい。この依存構造を断ち切るのが、ドキュメントの本来の役割です。

---

FDEが残すべきドキュメントの3種類

現場で機能するドキュメントは、大きく3つに分かれます。

設計書は、システムがどのように動いているかを示す記録です。フローチャート・データの流れ・外部サービスとの接続関係を図と文章で示します。新しい担当者がシステム全体を把握するための地図になります。

運用手順書は、日常業務でシステムを動かすための実行ガイドです。画面操作の手順・エラー時の対処法・定期メンテナンスの作業内容を書きます。現場担当者がFDEなしで操作できることを目的とします。

意思決定ログは、なぜその構成を選んだかを記録する文書です。検討した選択肢・捨てた理由・当時の制約条件を書きます。この記録がないと、後から「なぜこうなっているのか」という問いに誰も答えられなくなります。

3つの中で最も軽視されやすく、最も価値があるのが意思決定ログです。設計書と運用手順書はシステムを見れば後から書けますが、意思決定の文脈はFDEの頭の中にしかありません。

---

意思決定ログとは何か、なぜFDEに特に重要か

意思決定ログとは、設計の「なぜ」を時系列で残す記録です。開発界隈では「Architecture Decision Record」という形式が知られていますが、FDE文脈では会議の場での口頭合意や現場特有の制約も対象に含める必要があります。

たとえば、あるFDEが顧客対応フローにAIを組み込む際、メール送信を自動化せず手動承認を残した判断があったとします。技術的には自動送信も可能でしたが、「クレームが多い顧客には担当者が一読してから送りたい」という現場の運用ルールがありました。この判断はドキュメントに残さなければ、半年後に次の担当者が「なぜ自動化されていないのか」と疑問を持ち、理由もわからないまま自動化に変更して問題が再発するリスクがあります。

意思決定ログの基本フォーマットは次の4要素です。

項目	内容
日付	意思決定した日
決定事項	何を選んだか（1〜2文）
検討した選択肢	候補として上がったもの
理由と背景	なぜそれを選んだか、当時の制約や優先事項

この4要素を1決定につき10〜15行程度で記録するだけで十分です。報告書のような完成度は求めません。

---

現場担当者が読める運用手順書の書き方

運用手順書の失敗パターンは2つあります。一つは「FDEにしか読めない技術的な記述」、もう一つは「抽象的すぎて実際に操作できない記述」です。どちらも、いざというときに役に立ちません。

現場担当者が読める運用手順書には、次の構造が機能します。

冒頭に「この手順書でできること」を1行で書く。 たとえば「この手順書では、AIが生成した回答下書きを月次レポートに書き出す手順を説明します」のように、対象作業を一文で示します。

操作は画面の動きに合わせた番号付き手順で書く。 「管理画面にアクセスする」ではなく、「ブラウザで https://（システムURL）にアクセスし、右上の『エクスポート』ボタンをクリックする」のように、画面の何をどうするかを書きます。

エラーへの対処を「もし〜なら〜する」の形で入れる。 操作手順の直後に「もし〜というメッセージが出たら〜を確認する」という形で対処法を添えると、担当者が一人でトラブルを解決できる確率が上がります。

「最終確認」ステップを毎手順の末尾に入れる。 「〇〇の画面に『完了』と表示されれば成功です」という確認基準を書くことで、担当者が自分で正否を判断できます。

FDEの1日の流れについてはFDEの1日で触れていますが、良い運用手順書を書くには、実際に現場担当者に読んでもらいながら修正するプロセスが欠かせません。FDE自身が書いた手順書は、FDE目線の用語や省略が混ざりやすいためです。

---

ドキュメントをいつ書くか：リアルタイムと後追いの使い分け

「後でまとめて書く」が機能しない理由は単純で、後になるほど文脈を忘れるからです。ただし、すべてをリアルタイムに書くのも非現実的です。3種類のドキュメントごとにタイミングを変えるのが現実的な方法です。

意思決定ログはリアルタイムに書く。 意思決定の直後、その場で4要素を記録します。「後でまとめよう」という選択肢はありません。打ち合わせの終わりに3分間でログに追記する習慣を作ることで、記録が抜けるリスクを下げられます。

運用手順書は実装直後に書く。 システムを動かしたばかりの時点が、手順を最も正確に書けるタイミングです。実装から2週間以上経つと、「あれ、このステップはどの順番だっけ」という記憶のあいまいさが出始めます。

設計書は実装前と完成後の2回更新する。 実装前に設計の方針を書き、実装後に実際の構成との差分を反映します。この2段階で書くことで、「設計では〜だったが実装では〜に変えた」という経緯も記録できます。

現場では、会議の議事録・Slackの会話・口頭説明の中にドキュメントの原材料が散らばっています。それを構造化ドキュメントにまとめ直すのに、AIを活用する余地があります。

---

AIを使ったドキュメント作成の効率化

Claude・ChatGPTなどの生成AIは、ドキュメント作成の特定のステップを加速できます。

会議の文字起こしからの構造化。 打ち合わせの録音を文字起こしして、「この会議から意思決定ログの4要素を抽出してください」と指示するだけで、骨格が出てきます。FDEが確認・補正する手間は残りますが、白紙から書く時間は削減できます。

口頭説明からの手順書生成。 「私が操作しながら説明するので、それを運用手順書の形式にまとめてください」という使い方も機能します。FDEが実際の操作を実況しながらAIに話し、生成された文章を修正する流れです。

ドキュメントレビューの省力化。 書き上げた手順書をAIに渡し、「現場担当者が理解できない専門用語や省略がないか確認してください」と依頼することで、抜け漏れを発見できることがあります。

ただし、AIが生成した文書には固有名詞・設定値・判断の背景に誤りが混ざりやすいため、そのまま使うことはできません。FDEが確認・補記する前提で使うのが基本です。FDEがプロンプトを活用して現場作業を効率化する具体的な方法は、FDEのプロンプトエンジニアリングで詳しく解説しています。

---

ドキュメントが形骸化しないための仕組み

ドキュメントは書いた瞬間から陳腐化が始まります。「書いた」だけでは現場に残りません。形骸化を防ぐには、「更新のトリガー」と「レビューのタイミング」を仕組みとして決めておく必要があります。

更新トリガーを明示する。 ドキュメントの冒頭に「このドキュメントは、システムの設定を変更したとき・エラー対応手順を変えたとき・外部サービスの仕様変更があったときに更新してください」と書き、現場担当者が判断できるようにします。

月1回の棚卸しを仕組みにする。 FDEが現場を去る前に、「月末に担当者がドキュメントを一読し、操作手順に変更があれば更新する」というルーティンを現場に定着させます。カレンダーへの登録や、Slackのリマインダー設定まで一緒に行うと継続率が上がります。

「読める人」を指定する。 ドキュメントごとに更新担当者を1名明記します。担当者が決まっていないドキュメントは誰も更新しません。

古いバージョンを分かりやすく扱う。 古い手順を削除せず「旧手順」セクションに移動し、更新日を残します。「なぜ手順が変わったか」を1行添えると、次に変更が必要になった際の参考になります。

FDEの成果は、プロジェクト終了後もシステムが動き続けることで証明されます。その仕組みを支えるのがドキュメントです。FDE成功事例でも触れていますが、現場に自走の文化を残すことが、FDEの最終的な仕事と言えます。

---

FDEが去る前に整えるドキュメントの最終チェック

引き継ぎの時点で以下が揃っていれば、現場が迷子になるリスクは大きく下がります。

チェック項目	確認内容
設計書	システム全体の構成図と各コンポーネントの役割が書かれているか
運用手順書	画面操作の手順とエラー対処が現場担当者に読めるか
意思決定ログ	主要な設計判断について日付・決定・理由が残っているか
更新ルール	いつ誰が更新するかが明示されているか
連絡先	手に負えない問題が起きたときの問い合わせ先があるか

「引き継げる記録」とは、FDEがいない状態で現場が意思決定できるための情報です。技術的に精緻な文書を作ることが目的ではなく、現場担当者が自分で動けることが目的です。ドキュメントの質は、FDEが去った後に現場が迷わずに動けるかどうかで決まります。