システムは変わる。業務も変わる。非エンジニアの私がAIと作った「更新し続けられるシステム設計書兼業務マニュアル」

こんにちは。コーポレートG 木川です。

今回は、社内の営業プロセス管理システムについて、設計書と業務フローマニュアルを一体化し、更新・公開までを支援する仕組みを作った取り組みをご紹介します。
目指したのは、「作った時点では正しいけれど、いつの間にか実態と合わなくなる資料」からの脱却です。

なお、この仕組みに必要なコードはすべてAIとの対話で作成しました。
私はコードを書く代わりに、課題の整理、要件の言語化、動作確認、修正の判断を担当しました。

この仕組みによって、設定変更を設計書へ反映する手作業を減らし、対象画面ではキャプチャの撮り直しを不要にしました。
さらに、変更内容だけでなく理由も残せるため、管理者間の共有や引き継ぎにも使えるドキュメントになりました。

この記事では、資料がシステムの変化に追いつかないという課題から出発し、設計書と業務マニュアルを一体化した仕組み、その更新・公開の流れ、そして非エンジニアの私がAIとの対話で形にした過程をご紹介します。

システムは変わる。でも、資料は置いてけぼり。

システムは構築すれば終わりではなく、運用開始後に社内で少しずつ改善しますよね。
項目を追加したり、配置や設定を変えたり。
一つひとつは小さな変更でも、積み重なるうちに、納品時の設計書と実際のシステムが離れていくことがあります。

システム設計書にまつわる悩み

• 実際のシステムと内容がずれていく
  社内で行った変更が反映されず、設計書だけが開発当時のままになってしまう。
• 管理者間で変更内容を把握しきれない
  複数人で管理していると、誰がどこを変更したのか、十分に共有されないことがある。
• 小さな変更でも、資料の手修正が必要になる
  設定変更とは別に、設計書の該当箇所を探して書き直す手間がかかる。

これは、業務フローや手順書も同じです。

業務フロー・手順書にまつわる悩み

• システムの変更に説明が追いつかない
  実際の動きは変わっているのに、資料には以前の手順が残ってしまう。
• 画面キャプチャの差し替えに手間がかかる
  項目や配置が変わるたびに、画面を撮り直して貼り直す必要がある。
• 関連する資料をそれぞれ更新しなければならない
  一つの変更でも、設計書・業務フロー・手順書を個別に見直すことになる。

たとえば項目名や配置を一つ変更しただけでも、設計書の項目一覧、業務フローの説明、操作手順、画面キャプチャを確認し、それぞれの該当箇所を直す必要があります。
修正箇所を見落とせば、資料ごとに異なる説明が残ってしまいます。
更新を後回しにすれば資料が古くなり、最新に保とうとすれば手間がかかる。

この悩みを何とか解消できないかと考えたことが、今回の取り組みの出発点です。

作ったのは、設計書と業務マニュアルをつなぐ仕組み

今回作成したのは、システムの設定情報と業務の説明を組み合わせた「設計書兼業務フローマニュアル」です。
単に資料を一つにまとめるのではなく、次の情報をつなげて確認できる構成にしました。

• 業務の流れ： 誰が、いつ、何をするのか
• 業務の目的： なぜ、その作業が必要なのか
• 具体的な進め方： 何を入力し、どのように判断するのか
• システムの仕組み： どのような設定がされ入力制限や自動処理が関係するのか
• 変更の経緯： 何を、なぜ変更したのか

業務を担当する利用者は作業の流れや入力のポイントを確認でき、システム管理者は関連する設定や自動処理、変更の経緯を確認できます。

それぞれの立場から、必要な情報へたどれる形を目指しました。

たとえば利用者は、全体フローから自分が担当する工程へ進み、入力の目的や注意点を確認できます。
管理者は同じ工程から関連する項目や自動処理、変更履歴へ進み、設定と業務上の理由を一続きで確認できます。

工夫① 全体の流れから、必要な詳細へ

情報をまとめても、必要なところが見つからなければ使いにくい資料になってしまいます。
そこで、全体から詳細へ、段階的に確認できる構成にしました。

1. 全体フローで、業務のつながりをつかむ
2. 個別の業務フローで、担当や作業の順序を確認する
3. 工程の詳細で、業務の理由や進め方を確認する
4. 関連する画面・項目や自動処理の情報を確認する

業務フローでは、担当ごとの作業とシステムによる自動処理を区別しています。
また、工程の詳細を開くことで、説明を確認できるようにしました。

意識したのは、一枚の図にすべてを詰め込まないことです。
まずは全体像をつかみ、必要なところだけ詳しく見る。そんな読み方ができるようにしています。

工夫② 画面を「撮る」のではなく、設定情報から「再現する」

今回、特に工夫したのが、マニュアルに掲載する画面です。
従来のように画面キャプチャを貼り付ける方法では、項目や配置が変わるたびに撮り直しが必要になります。
そこで着目したのが、システムの設定情報を取得するAPIでした。

今回利用したシステムのAPIからは、項目名や種類などの項目情報だけでなく、行ごとの配置や項目の表示サイズといったレイアウト情報も取得できました。
つまり、画面に「何があるか」に加えて、「どのように並んでいるか」も再現に利用できました。

画面変更のたびにキャプチャを撮り直さなくて済むよう、取得した設定情報から、マニュアル用の説明画面をHTML上に組み立てています。

• 項目の情報を取得する
• 配置や表示サイズの情報を取得する
• 取得した情報をもとに、説明用の画面を生成する

つまり、画面を画像として保存するのではなく、画面を構成する情報から作り直す方法です。
これにより、再現対象の画面では、変更のたびにキャプチャを撮り直す必要がなくなりました。

最新の設定情報を取得してドキュメントを再生成することで、項目やレイアウトの変更を反映できます。
ここで再現するのは、マニュアルで説明するための画面表示です。取得した設定情報から項目やレイアウトを組み立てますが、実際のシステムの操作や処理まで複製するものではありません。

工夫③ 設定情報と業務の説明を組み合わせて生成する

裏側では、Python・YAML・Markdownなどを組み合わせています。
それぞれの役割は、次のとおりです。

要素	今回の仕組みでの役割
API	システムの設定情報を取得する
JSON	取得した設定情報を保存する
YAML	業務フロー、入力のポイント、変更理由などを管理する
Python	設定情報と業務の説明を組み合わせ、ドキュメントを生成する
Markdown（.md）	生成するページの内容をまとめる
HTML	ブラウザーで閲覧できる形にする

大まかな流れは、次のようになります。

1. システムの設定情報を取得する
2. YAMLで管理している業務の説明と組み合わせる
3. Pythonで画面や説明ページを生成する
4. Markdown・HTMLとして出力する
5. 社内の情報共有基盤に公開する

ポイントは、完成したページを毎回手で直すのではなく、元になる情報を更新して作り直すことです。

従来は、変更箇所を探し、設計書を書き換え、画面を撮り直し、関連資料にも同じ変更を反映していました。
現在は、設定情報を再取得し、人が業務説明や変更理由を更新したうえでドキュメントを再生成します。
手で直す対象を減らし、確認すべき点を絞れるようになりました。
ただし、何でもシステムから取得できるわけではありません。

たとえば、次のような情報は人が記述します。

• なぜ、その作業が必要なのか
• 入力時に何に注意するのか
• どのような条件で判断するのか
• なぜ、その設定に変更したのか

取得できる設定情報は仕組みに任せ、業務の意味や背景は人が残す。
この役割分担で、更新の負担と説明の分かりやすさの両立を目指しました。

工夫④ 「何が変わったか」と「なぜ変えたか」を残す

複数人で管理する場合、最新の状態だけでなく、変更の経緯も確認できることが重要です。
今回の仕組みでは、前回取得した情報との差分から変更を検出し、変更理由を記入する流れを設けました。

1. 変更を検出する
2. 変更理由の記入欄を用意する
3. 管理者が背景や理由を記入する
4. 設計書の変更履歴へ反映する

たとえば、「通知先が変わった」という事実だけでは、その背景までは分かりません。

• 担当が変更になったのか
• 確認漏れを防ぐためなのか
• 業務の進め方自体が変わったのか

理由まで残すことで、ほかの管理者や、後から引き継ぐ人が見直すときの手がかりになります。
変更を個人の記憶だけにとどめず、共有できる情報として残すことを目指しました。

工夫⑤ 公開・更新までを一つの流れに

ドキュメントは、生成して終わりではありません。
社内で参照できる場所に公開し、その後も更新できるよう、作業の流れを整えました。

1. 元になる情報を最新化する
2. 変更点を確認し、変更理由を記入する
3. ドキュメントを生成する
4. 公開前に更新対象を確認する
5. 差分のあるページを反映する
6. 公開後の表示を確認する

複数の処理を正しい順番で実行できるよう、更新作業を案内するスクリプトも用意しています。
ただし、完全自動ではありません。

• 元データの一部の取得
• 業務説明や変更理由の記入
• 公開後の表示確認

こうした工程は、人が対応します。

目指したのは、人の作業をゼロにすることではありません。
繰り返しの転記や差し替えを減らし、業務の理由を言葉にすること、変更の妥当性を判断すること、公開結果を確認することに時間を使える状態です。

コードはすべてAIに。確認と判断は自分で。

今回、コードはすべてAIに書いてもらいました。私自身はコードを書いていません。
ただし、AIが生成したコードを、そのまま無条件に採用しているわけではありません。

私は、解決したい課題を整理し、必要な動きを言葉にしたうえで、生成されたコードを実際に動かし、処理結果を確認しました。
意図と異なる動きや表示があれば、その内容をAIに伝え、修正と再確認を重ねています。

進め方は、要望を伝えて一度で完成させるものではありませんでした。
まず小さく動かし、結果を確認し、問題があれば修正して、もう一度確かめる。 この往復を重ねながら、業務に合う形へ整えていきました。

AIに任せたこと

• コードの作成
• エラーや実行結果をもとにした修正案の作成
• 要望に合わせたコードの修正

私が行ったこと

• 課題を整理する
  どの作業に手間がかかり、何を解消したいのかを伝える。
• 必要な内容や見せ方を考える
  業務フローの構成や、マニュアルで確認したい情報を伝える。
• 生成されたコードの動作と出力結果を検証する
  想定した処理が行われているか、取得した設定情報が資料に正しく反映されているか、表示や更新結果に問題がないかを確認する。
• 修正後も、もう一度確認する
  エラーや表示の崩れ、業務に合わない部分を具体的に伝え、修正されたコードを再実行して結果を確かめる。
• 業務で使えるかを判断する
  動いたことだけで完了とせず、必要な情報を確認でき、意図した使い方ができるかを確かめる。

「AIに一度お願いして完成」ではなく、対話と検証を繰り返しながら形にしていきました。

コードを書く作業はAIに任せても、その結果を確認し、採用するかを判断する役割までAI任せにはしません。

この取り組みを通じて、コードを自分で書かなくても、業務上の課題を整理し、必要な動きを言語化し、生成されたコードの動作や出力結果を検証することで、課題を解決する仕組みを形にできると分かりました。

「作って終わり」から、「使いながら育てる」へ

今回の取り組みでは、設計書と業務マニュアルを一つにまとめるだけでなく、変更の検出、理由の記録、資料の再生成、公開までを一つの流れにしました。
これにより、システムだけが変わり、資料が置いてけぼりになる状態を減らせるようになりました。

実際に更新作業を行う中で、次の変化を確認できました。

• 設定情報から生成できる箇所について、設計書を手修正する負担を減らせたこと
• 画面を再現することで、対象画面のキャプチャの撮り直しが不要になったこと
• 変更内容と理由を、管理者間で確認できる形にしたこと
• 業務の流れとシステムの仕組みを、一続きで確認できるようにしたこと

もちろん、仕組みができたら終わりではありません。
業務の説明や変更理由は人が残す必要がありますし、生成結果の確認も欠かせません。
今後も、実際に使う中で分かりにくい部分を見直し、内容と更新方法の両方を改善していきたいと考えています。

システムを改善することと、その仕組みを伝え続けること。

同じように資料の更新に悩んでいる場合は、まず「システムから取得できる情報」と「人が意味や背景を残す情報」を分けてみると、仕組み化できる範囲が見えやすくなります。
すべてを自動化しなくても、繰り返し作業を減らし、人が判断や説明に集中できる形を作ることはできます。 この二つを切り離さず、使いながら育てていけるドキュメントにしていきたいです。

この記事は私が書きました

木川 美奈子

記事一覧