担当者しか分からなくなった業務の VBA マクロを読ませて、処理の流れ・入力と出力・前提を仕様書に起こし、引き継ぎに使える形にする

処理の起点を決める

分析用のフォルダにファイルの写しが置かれたことを起点にします。 今月の対象は月初に台帳から選びますが、写しが届く日はばらばらです。届いたものから1本ずつ動かし、月末にまとめて処理することはしません。 利用部門への確認は往復に日数がかかるので、早く出すほど月内に閉じられます。

ファイルが更新されたマクロも、同じトリガーで受けます。 台帳にはファイルのハッシュ値を記録しておき、月に1回、ファイルサーバーの実物と比べます。値が変わっていれば、前の仕様書と並べて差分を見られるように、作り直しの対象にします。

分析用のフォルダは、分析用の端末の中に置きます。 利用部門のファイルサーバーから直接読まず、写しを置いてから処理します。元のファイルには触れません。

入力データを集める

質を決めるのは、下から2番目です。 コードだけからでも処理の流れは書けますが、「いつ、誰が、何のために」が一言でもあると、AIはそれを手がかりにコードのどこが中心かを見分けられます。 写しを受け取るときに、3行でよいので書いてもらいます。

利用部門のメモは、仕様書の「目的」にそのまま写しません。 メモとコードが食い違っていることがあるからです。AIには、メモとコードが食い違う箇所を「確認する点」に挙げさせます。

データの取得方法を決める

解析の印は、JSON で受け取ります。 olevba には詳しい結果を JSON で出す -j のオプションがあり、印の種類とキーワードを機械で読めます。 AutoExec に Workbook_Open があれば「ファイルを開くと動く」、IOC にファイルのパスがあれば「このフォルダに依存する」という下書きを、AIに渡す前に作れます。

--decode で文字列が復号されて出てきたら、仕様書を作る前に止めます。 業務のマクロで文字列を難読化する理由はほとんど無く、マルウェアの可能性を先に調べるべきだからです。

AIへ渡す前に整形する

1. 形式の確認 … olevba が扱える形式かを確かめます。Access のデータベースなど対象外の形式は、この構成から外します
2. 難読化・不審な印の確認 … Suspicious に外部のプログラムの実行やダウンロードに当たる命令があり、IOC に社外の URL があれば、仕様書の作成を止めて情報セキュリティの担当に回します
3. 認証情報らしき文字列を伏せる … Password、pwd、接続文字列、@ を含むアドレスなどに当たる行の値を [MASKED_01] のように置き換え、置き換えた行の番号だけを記録します
4. 行番号の付与 … モジュールごとに1から行番号を振ります。根拠を行番号で返させるためです
5. プロシージャの一覧 … Sub、Function、Property の開始と End の行から、プロシージャごとの範囲を作ります
6. 長さで分ける … 1モジュールが決めた行数を超えるものは、プロシージャの境目で分けて渡します
7. 文字化けの確認 … 日本語のコメントや文字列が化けていれば、元のファイルの文字コードを確かめて取り出し直します

3番目は、外部へ渡す前の最後の関門です。 業務のマクロには、データベースの接続文字列、共有のメールアドレス、ときにはパスワードがそのまま書かれています。伏せた後の文字列だけをAIに渡し、伏せた値は仕様書にも書きません。 仕様書には「この行に認証情報が書き込まれている」という事実だけを残し、それ自体を改善の候補として台帳に印を付けます。

AIに処理させる

1回目はモジュールごと、2回目はファイル全体で、AIに読ませます。

2回に分けるのは、長いマクロでも行番号を見失わないためです。 数千行を一度に渡すと、処理の流れは書けても、根拠の行番号がずれたり抜けたりします。1回目で細かく根拠を付けておき、2回目はその結果を束ねるので、仕様書の各項目を1回目の行番号までたどれます。

「前提」は、項目を決めて探させます。 決まったシート名や列の位置、決まったフォルダやファイル名、日付や数値の書式、ほかのブックのマクロの呼び出し、Outlook など別のアプリの起動、実行する人の権限。項目を決めずに「前提を書いて」と頼むと、当たり前すぎるものが落ちます。 第3章の（b）は、ここで防ぎます。

1行目がいちばん起きやすい失敗です。 Sub 月次締め() という名前があれば、AIは「月次の締め処理を行う」と書きます。名前は作った人の当時の意図で、いまの業務と一致している保証はありません。 名前から読んだことは、根拠に「プロシージャ名から」と書かせ、確かめた事実と分けます。

指示内容を固定する

あなたは情報システム部で、業務で使われている VBA マクロの仕様書を作る立場です。
渡されたソースコードと解析の結果だけを根拠にしてください。

【いまのファイル】{file_name}（所管部門：{department}）
【利用部門のメモ】{user_memo}
【解析の印（olevba）】{olevba_flags}
【モジュールごとの要約（1回目の結果）】{module_summaries}

【仕様書の9項目】
1. 目的 ............ 利用部門のメモとコードの両方から書く。食い違いは8へ
2. 起動のしかた .... ボタン、ファイルを開いたとき、ほかのマクロからの呼び出し など
3. 処理の流れ ...... 起動から終了までを、手順の番号付きで
4. 入力 ............ 読むシート・範囲・ファイル・フォルダ
5. 出力 ............ 書くシート・範囲・ファイル・フォルダ、送るメール
6. 外部とのつながり  ほかのブック、ほかのアプリ、ネットワーク上の場所、データベース
7. 前提 ............ シート名・列の位置・フォルダ・書式・権限・起動しているべきアプリ
8. 確認する点 ...... コードからは分からないこと、メモとコードの食い違い
9. エラー時の動き .. エラー処理があるか、どこで止まり、何が書きかけで残るか

【厳守事項】
- すべての記述に、根拠を「モジュール名:行番号」で付けてください。
  根拠が付けられない記述は書かないでください。
- 業務上の目的や理由は、コードから断定しないでください。
  プロシージャ名やコメントから読み取ったことは、basis を "name_or_comment" にしてください。
- コードに書かれていないシート名、セル番地、フォルダ名を補わないでください。
- [MASKED_xx] の中身を推測しないでください。「認証情報が書き込まれている」とだけ書いてください。
- 改善の提案、書き換えの提案、不要な処理の指摘はしないでください。
- 動きが条件によって変わるときは、条件ごとに分けて書いてください。
- 分からないことは、8 の確認する点に、利用部門が答えられる問いの形で書いてください。

「根拠が付けられない記述は書かない」が、この指示の芯です。 仕様書の文章は、すべて行番号まで戻れる状態にします。戻れない文章は、どれほどもっともらしくても仕様書に入れません。

basis を分けさせるのは、確かめ方が違うからです。 処理から読んだことは担当者がコードで確かめられ、名前やコメントから読んだことは利用部門に聞かないと確かめられません。同じ文に見えても、確かめる人が違います。

出力形式を固定する

次の形のJSONで受け取ります。

{
  "file_name": "",
  "file_hash": "",
  "spec": {
    "purpose": [ { "text": "", "basis": "code | name_or_comment | user_memo", "refs": ["Module1:12-40"] } ],
    "triggers": [ { "text": "", "refs": [""] } ],
    "flow": [ { "step": 1, "text": "", "refs": [""] } ],
    "inputs": [ { "kind": "sheet | range | file | folder | database | other", "name": "", "refs": [""] } ],
    "outputs": [ { "kind": "sheet | range | file | folder | mail | other", "name": "", "refs": [""] } ],
    "external": [ { "kind": "workbook | application | network_path | database | url", "name": "", "refs": [""] } ],
    "assumptions": [ { "category": "sheet_layout | folder | format | permission | running_app | other", "text": "", "refs": [""] } ],
    "error_handling": [ { "text": "", "refs": [""] } ],
    "questions": [ { "question": "", "why": "", "refs": [""] } ]
  },
  "masked_lines": ["Module2:15"]
}

1つ目の理由は、根拠の行番号を機械で確かめられることです。 refs がプロシージャの一覧の範囲に収まっているかを、受け取った側で照合します。範囲の外を指す根拠は、担当者に知らせます。

2つ目は、仕様書の様式に機械で流し込めることです。 構造化出力は、応答をJSONスキーマに沿わせ、output_config.format にスキーマを渡して使います。9項目の並びと、kind や category の値を固定できるので、600本の仕様書の見出しと粒度がそろいます。第3章の（a）は、ここで防ぎます。

3つ目は、マクロどうしを横に並べられることです。 external と inputs が同じ形でたまると、「このフォルダに依存するマクロは何本あるか」「このブックを呼ぶマクロはどれか」を台帳の側で数えられます。 ファイルサーバーの移行や、フォルダの整理の前に、影響の範囲が分かります。

システムへ連携する

台帳への書き込みは、状態と依存関係の列だけです。 「仕様書あり」に変えるのは、利用部門の確認が終わった後です。AIの下書きができた時点で「仕様書あり」にすると、確かめていない仕様書が台帳上は完了に見えます。

元のファイルには何も書き込みません。 仕様書の置き場所をマクロの中にコメントとして足したくなりますが、それは利用部門のファイルを変えることになります。

人が確認する

1. 根拠の行番号を開く … 担当者が refs の行を開き、書かれている内容がコードと合っているかを確かめます。特に flow と assumptions は全件見ます
2. basis が name_or_comment のものを確認する点に移す … コードで確かめられないものは、利用部門に聞く側に回します
3. 利用部門に聞く … questions を送り、答えを仕様書に書き込みます。作った人が社内にいれば、その人にも送ります
4. 画面で一度動かしてもらう … 利用部門に、普段どおりの手順で一度実行してもらい、仕様書の flow と合っているかを見ます

4番目は、仕様書を完成させるための最後の確認です。 コードの読みが正しくても、ボタンを押す前に手で貼り付ける作業があった、という手順はコードには現れません。 実際の操作を一度見れば分かります。

例外に対処する

5行目は、仕様書の単位を決める問題です。 1本のブックのボタンが、別のブックを開いてそのマクロを動かすことがあります。呼ばれる側を読まずに仕様書を書くと、処理の流れが途中で切れます。 external に workbook が出たら、台帳でそのブックを探し、まとめて対象にします。

最後の行も、この構成の成果の1つです。 台帳の600本には、もう誰も使っていないものが混ざっています。確認の問いを送った時点で「もう使っていない」と返ってくれば、そのマクロは仕様書ではなく廃止の手続きに回せます。 一巡にかかる20か月が、そのぶん縮みます。

記録を残す

• 元のファイルのハッシュ値と、写しを受け取った日
• olevba の出力（ソースと解析の結果）と、伏せた行の番号（値は残さない）
• AIの1回目と2回目の出力の全文
• 担当者が直した箇所と、利用部門の答え
• 確認を終えた仕様書の版と、確認した人

1つ目のハッシュ値が、作り直しの判断の材料です。 ファイルが更新されたかは、ハッシュ値を比べれば分かります。仕様書がどの版のファイルについて書かれたかが、いつでもたどれます。