harumiWeb/xlflow has 95 GitHub stars and 11 forks. GitHot measured 0 stars in 24 hours, +2 in 7 days, and +2 in 15 days. Last checked 2026-11-17 03:25 UTC. Last push 2026-11-03.
できること
- Source control - Export and import standard modules, class modules, UserForms, and document modules
- Formula snapshots - Extract worksheet formulas and defined names into region-based JSONL files with xlflow formulas pull or refresh them with xlflow pull --formulas
- Execution - Run macros from the CLI with typed arguments
- Testing - Discover and run VBA test procedures
計測したスター増加
- 24時間
- 0
- 7日間
- +2
- 15日間
- +2
- 1か月
- 履歴を収集中
期間ごとの純増数です。期間は重複しており、日別の値ではありません。未計測の値は空欄です。スター数は注目度の指標であり、品質の保証ではありません。
概要
AI-Agent-ready CLI framework for editing, testing, running, tracing, and diffing Excel VBA projects.
開発ツールREADME.ja.md
オリジナル
Excel VBA development, rebuilt for CLI-first humans and AI agents.
:surfing_man: xlflow
xlflow は、AIエージェント時代のための Excel VBA 開発フレームワークです。
.xlsm ブック、.xlam アドイン、.xlsb バイナリブックに閉じ込められがちな VBA を、ソース管理しやすく、CLI から扱いやすい開発ワークフローに変換します。
VBA のエクスポート、編集、lint、インポート、テスト、デバッギング、実行、差分確認をコマンドラインから行えます。

[!TIP] xlflow は Excel を置き換えるツールではありません。Excel VBA の周囲に CLI ベースの開発ハーネスを用意し、人間・スクリプト・AIエージェントが扱いやすい形にするためのツールです。
デモ
これらの サンプル は xlflow を使用して僅かな自然言語指示のみでAIエージェントによって作成されました。
セル色表現で QRコードを生成して Excel に表示するマクロ
|
Excel 上でテトリスをプレイできるマクロ
|
ユーザーフォーム上でスペースインベーダーをプレイできるマクロ
|
リッチなカレンダーピッカー
|
法令データ検索ツール
|
パックマン風ゲーム
|
なぜ xlflow が必要か
従来の VBA 開発は、Excel 画面と Visual Basic Editor に強く依存しています。 小さな手作業の修正であれば問題ありませんが、ソース管理、テスト、差分確認、AIエージェントによる修正、再現可能な実行を考えると扱いづらくなります。
| 通常の VBA 開発でつらいこと | xlflow でできること |
|---|---|
VBA コードが .xlsm / .xlam / .xlsb の中に閉じ込められている |
.bas / .cls / .frm としてエクスポート・インポートできる |
| UserFormを宣言的に扱えない | xlflow form build で yaml 定義から UserForm を生成できる |
| 実行エラーの場所や原因が分かりにくい | 構造化エラー、診断情報、debug log を返せる |
| workbook の変更をレビューしにくい | セル値、数式、シート、VBA ソースの差分を確認できる |
| AIエージェントが Excel UI を安全に操作しにくい | CLI コマンドと安定した JSON 出力を提供できる |
pull → fmt → edit → push → lint → test/run → inspect
できること
| 領域 | 機能 |
|---|---|
| ソース管理 | 標準モジュール、クラスモジュール、UserForm、Workbook / Worksheet モジュールをエクスポート・インポート |
| 実行 | CLI から型付き引数つきでマクロを実行 |
| テスト | VBA のテスト手続きを検出して実行 |
| フォーマット | .bas / .cls ソースファイルに対する保守的で非破壊な VBA フォーマット |
| lint | Option Explicit 不足、Select / Activate、広すぎるエラー処理、暗黙の Variant、Public module field、対話的処理を検出 |
| デバッグ | terminal log と runtime diagnostic を収集 |
| 差分確認 | workbook のセル値、数式、シート構成、VBA ソース差分を比較 |
| AIエージェント連携 | 安定した JSON を返し、Codex / Claude / Cursor / Gemini / GitHub Copilot 風ワークフローなどに使わせるための Skill をインストール |
| LSPサーバー | 入力補完、定義ジャンプ、リアルタイム診断などを提供 |
| VS Code 拡張機能 | xlflowのあらゆる操作をGUI化し、LSPサーバーを利用した優れた開発体験 |
[!IMPORTANT] xlflow は workbook 実行について Windows-first のツールです。Workbook 操作には Windows 上の Microsoft Excel + COM と
.NETExcel bridge を使用します。WSL は Windows 側の xlflow へ Excel 関連コマンドを委譲することで、開発 frontend として利用できます。
VS Code 拡張機能
xlflowは人間にとっても最も優れたExcelVBAマクロ開発ツールを目指し、VS Code拡張機能も提供しています。 拡張機能では、xlflow CLIが提供する主要操作の大部分をGUIから呼べるようにします。
また、LSPサーバーとの連携によってエディタ編集中の型推論に基づく入力補完、定義ジャンプ、リアルタイム診断など人が手でコードを書く際に有用な機能を提供します。
Visual Studio Marketplace からインストールすることができます。

[!IMPORTANT] xlflow 拡張機能はあくまで xlflow CLI をGUIから呼び出すラッパーです。 使用する場合は xlflow CLI も同時にインストールする必要があります。
UserForm Designer
VSCode 拡張機能では、UserForm Designer も提供しています。 ユーザーはVBEを開くことなく、VSCode上でUserFormを視覚的に作成・編集することができます。 また、内部では、UserFormの状態をyaml形式で保存しているので、AIエージェントとの共同編集も可能です。

動作要件
| 要件 | 必要になる場面 |
|---|---|
| Windows | Excel COM automation |
| Microsoft Excel | new, init, list forms, inspect form, form snapshot, form build, form export-image, pull, push, run, export-image, edit, test, macros, doctor |
| VBA プロジェクト オブジェクト モデルへのアクセスを信頼する | VBA プロジェクトの読み書き |
[!NOTE]
lint、fmt、一部のdiff、Go のユニットテストなど、Excel COM を使わない処理は非 Excel 環境でも検証できます。
[!NOTE] xlflow は COM 操作を .NET bridge で行います。レガシー PowerShell bridge は v0.16.0 で削除され、対応する bridge mode は
autoとdotnetです。
[!WARNING] Excel の設定で VBA プロジェクト オブジェクト モデルへのアクセスを信頼する を有効にしてください。これが無効だと、Excel がインストールされていても
pull/push/runなどが失敗する場合があります。詳細 Excel のオプションで「トラスト センター」→「マクロの設定」→「VBA プロジェクト オブジェクト モデルへのアクセスを信頼する」を有効にしてください。
インストール
Quick install
人間と AI エージェント向けの最短導線:
irm https://harumiweb.github.io/xlflow/install.ps1 | iex
Uninstall
PATH entry と %LOCALAPPDATA%\xlflow 配下のインストールを削除する場合は、同じ script を file 実行で使います。
irm https://harumiweb.github.io/xlflow/install.ps1 -OutFile .\install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Action uninstall
winget
winget install HarumiWeb.Xlflow
既存のインストールを更新する場合:
winget upgrade HarumiWeb.Xlflow
[!NOTE] winget は manifest を upstream へ提出して承認されるまで、GitHub Release より反映が遅れる場合があります。 最新 release をすぐに使いたい場合は installer script、Scoop、または GitHub Releases の ZIP を使ってください。
Scoop
scoop bucket add harumiweb https://github.com/harumiWeb/scoop-bucket
scoop install xlflow
GitHub Releases
Windows x64 と Linux x64 向けの事前ビルド済みバイナリは次のページから取得できます。
https://github.com/harumiWeb/xlflow/releases
[!IMPORTANT] Workbook を操作する command には、Windows 上の Microsoft Excel、Excel COM automation、VBA プロジェクト オブジェクト モデルへのアクセスを信頼する 設定が必要です。 Windows 向け release ZIP には
xlflow.exeとxlflow-excel-bridge.exeの両方が含まれます。Workbook command はautomode で同梱の.NETbridge を使います。 Linux x64 archive は WSL/frontend CLI のみを含み、Windows.NETbridge は含みません。
[!WARNING]
xlflow-excel-bridge.exeは PowerShell execution policy の影響を受けませんが、AppLocker、WDAC、Defender / EDR policy、antivirus reputation、unsigned executable rule などでブロックされる可能性はあります。公開している checksum と GitHub attestation で確認できるのは artifact の integrity と provenance であり、Windows の Authenticode signing ではありません。
ダウンロードした ZIP は、公開されている checksums.txt と照合して SHA256 を確認できます。
Get-FileHash .\xlflow_windows_x86_64.zip -Algorithm SHA256
certutil -hashfile .\xlflow_windows_x86_64.zip SHA256
表示された SHA256 が checksums.txt 内の xlflow_windows_x86_64.zip の値と一致することを確認してください。
この確認で分かるのは、ダウンロードしたファイルが公開された checksum file と一致していることです。配布者の本人性を証明するものではなく、Windows の Authenticode signing の代替でもありません。
GitHub CLI では、GitHub Actions provenance attestation も検証できます。
gh attestation verify .\xlflow_windows_x86_64.zip --repo harumiWeb/xlflow
この検証で分かるのは、release artifact に対する GitHub artifact attestation が存在し、検証できることです。Windows の publisher certificate による Authenticode signing を意味するものではありません。
Go install
go install github.com/harumiWeb/xlflow/cmd/xlflow@latest
go install は Go 環境に設定された module mirror や checksum database へアクセスすることがあります。source checkout からの開発や CI では、go.mod に書かれた Go version を正式サポート toolchain の source of truth としてください。リポジトリの CI / release workflow もその値から Go を解決します。
[!WARNING]
go installで入るのはxlflow本体だけです。Windows の release ZIP に含まれる.NETbridge sidecarxlflow-excel-bridge.exeはインストールされません。 Windows release archive には.NETbridge sidecar が含まれます。Source checkout ではxlflow.exeとxlflow-excel-bridge.exeの両方を入れるためにtask installを使ってください。
インストール後、次のコマンドで確認できます。
xlflow version
xlflow --help
開発中のリポジトリから直接実行する場合:
go run ./cmd/xlflow --help
Taskfile を使用している場合:
task run -- --help
WSL で開発する
WSL は編集と自動化の frontend として利用でき、Excel の実行 backend は Windows のままです。
Excel は WSL 内では起動しません。Workbook command は Windows 側の xlflow.exe へ委譲され、そこから同梱の .NET bridge と Microsoft Excel COM automation が使われます。
推奨セットアップ:
- まず Windows 側に xlflow をインストールします。installer、winget、Scoop、または Windows release ZIP を使えます。
- WSL shell から WSL frontend をインストールします。
curl -fsSL https://harumiweb.github.io/xlflow/install.sh | sh
- xlflow project は
/mnt/c/dev/my-vba-projectのような Windows-mounted path 配下に置いてください。
[!WARNING]
/home/user/projectのような WSL 専用 path は、委譲された Excel automation では正式サポート外です。Windows Excel と COM から見える workbook path が必要です。
作業を始める前に WSL から診断を実行します。
xlflow doctor --json
Windows Excel が設定済み workbook を開けることまで確認したい場合は xlflow doctor --workbook --json を使います。
WSL から Windows 側の executable を見つけられない場合は、明示的に指定できます。
export XLFLOW_WINDOWS_EXE='C:\Users\you\AppData\Local\xlflow\xlflow.exe'
日常的な macro 開発では、Excel を開いたまま編集ループを回せる session workflow を推奨します。
xlflow session start --json
xlflow push --fast --session --no-save --json
xlflow run Main.Run --session --json
xlflow inspect cell --sheet Sheet1 --address A1 --session --json
xlflow save --session --json
xlflow session stop --json
run、test、bridge cleanup が Excel/VBA の停止を保証できない状態で戻った場合、xlflow は workbook を quarantine します。以後の workbook command は workbook_recovery_required を返し、--wait では回避できません。xlflow status --json を確認し、session stop --discard、対応する process cleanup、または xlflow recovery clear で復旧してください。
lint、fmt、analyze、diff などの source-only command は WSL 内で実行できます。new、init、pull、push、run、test、inspect、save、doctor などの Excel-backed command は Windows へ自動委譲されます。
クイックスタート
1. プロジェクトを作成または初期化する
新しい xlflow プロジェクトと macro-enabled workbook を作成します。
xlflow new Book.xlsm
new は scaffold した VBA module を新しい workbook へ自動 push するため、その後の pull でも同じ初期状態から始められます。
既存の Excel ブックから始める場合は init を使用します。
xlflow init Book.xlsm
init はコピーした workbook から src/ へ自動 pull するため、追加の bootstrap pull なしでそのまま source 編集を始められます。
AI エージェント向けの Skill も同時にインストールする場合:
xlflow new Book.xlsm --with-skill --agent codex
interactive な xlflow new / xlflow init では welcome banner を表示し、最新 GitHub Release を GitHub Releases API で確認することがあります。このリクエストを今回だけ止めたい場合は --no-update-check、環境全体で止めたい場合は XLFLOW_NO_UPDATE_CHECK=1 を使ってください。
2. Excel automation 環境を確認する
xlflow doctor --json
[!TIP]
doctorはデフォルトでは軽量診断です。設定済み workbook を開けることまで確認したい場合はxlflow doctor --workbook --jsonを実行してください。
pull/push/run/testが Excel、COM、bridge、VBIDE、または workbook open 設定の問題で失敗する場合は、まずdoctorを実行してください。
3. VBA をソースファイルとして取り出す
xlflow pull --json
エクスポートされた .bas / .cls / .frm は src/ 配下に出力されます。
folder mode が有効な場合、各 source root 配下のネストしたディレクトリは push 時に Rubberduck 互換の @Folder(...) annotation へマッピングされます。
通常のエディタや AI エージェントで編集できます。
4. 編集したソースを workbook に反映する
xlflow push --json
5. マクロを検出して実行する
xlflow macros --json
xlflow run Main.Run --json
無人実行では headless mode を推奨します。
xlflow run Main.Run --headless --json
マクロが XlflowUI.MsgBox や XlflowUI.InputBox を使う場合は、scripted response を渡すことで headless のまま実行できます。JSON stdout を壊さずにダイアログ解決の様子をターミナルへリアルタイム表示したい場合は --ui-stream を付けてください。
xlflow run Main.Run --headless --msgbox confirm-save=yes --inputbox customer-name=fallback-user --ui-stream --json
--ui-stream は xlflow: ui kind=msgbox id=confirm-save source=default result=yes のような行を stderr に出力します。InputBox の値は既定で redact され、--ui-stream を有効にした実行では最終 JSON 結果にも同じダイアログイベントが top-level の ui.events として含まれます。
ファイル選択、MsgBox、UserForm などを人間が操作する場合は interactive mode を使用します。
xlflow run Main.Run --interactive --timeout 5m --json
6. lint と test を実行する
xlflow lint --json
xlflow test --json
テストが XlflowUI を使う場合も、同じ response flag と realtime stream を使えます。
xlflow test --msgbox test-confirm=ok --inputbox test-user=alice --ui-stream --json
よく使うワークフロー
AIエージェントに VBA を編集させる
Skill をインストールする
AIエージェントに xlflow を使って VBA を編集させる場合、xlflow が提供している Skill をエージェントの環境にインストールすることを推奨します。
xlflow skill install
プロジェクトの立ち上げと同時にインストールすることもできます。
xlflow new Book.xlsm --with-skill
スキルをvercel-labs/skillsなどのマネージャーで管理したい場合などは以下のようにスキルをインストールしてください。
npx skills add harumiWeb/xlflow/internal/agentskill/templates --skill xlflow
プロジェクトを作成する
プロジェクトを作成させるところからAIエージェントに任せることもできますが、最初のプロジェクトセットアップは人間が行うことを推奨します。
xlflow new Book.xlsm --with-skill
AIエージェントに編集させる
インストールしたスキルを使って、あなたが実現したいことを自然言語で指示してください。
/xlflow VBAでセルA1に"Hello, world!"と入力するマクロを作成して
同梱されている xlflow skill は、headless な XlflowUI フローで --ui-stream をいつ付けるべきか、stdout の JSON をどう安全に保つか、実行後の human-readable UI section や JSON の ui.events をどう読むかもガイドします。
人間が Excel を操作しながら進める
人間が Excel を開いた状態で作業する場合は、attach で active workbook を確認できます。
xlflow attach --active --json
[!NOTE]
attachは安全確認用です。active workbook がxlflow.tomlのexcel.pathと一致するかを検証します。pull/push/runの対象を切り替えるコマンドではありません。
Windows では attach、session、runner、list forms、ui button、edit、new も auto mode で .NET bridge を使います。
GUI を含むマクロを扱う
headless 実行できるか判断する前に、GUI boundary を確認します。
xlflow inspect-gui --json
| 結果 | 推奨される対応方法 |
|---|---|
| GUI boundary なし | xlflow run ... --headless --json |
ファイル選択、InputBox、modal MsgBox、UserForm などを検出 |
XlflowUI.MsgBox や XlflowUI.InputBox を使用してください |
| GUI 処理が実処理を包んでいる | core logic を引数付きの headless 手続きへ分離する |
[!WARNING] headless automation と modal な Excel UI は相性が悪いです。無人実行前に
inspect-guiを使い、既存のMsgBoxやInputBoxはXlflowUIを使うように置き換えることを推奨します。
実行モードを VBA から参照する
新しく xlflow new で作るプロジェクトには src/modules/Xlflow/XlflowRuntime.bas が含まれます。xlflow run や xlflow test の実行前に、xlflow は workbook-scoped の実行モード marker を一時注入するため、VBA 側は process inspection に頼らずに分岐できます。
If XlflowRuntime.IsHeadless() Then
Debug.Print "running unattended in " & XlflowRuntime.ModeName()
Else
MsgBox "Running interactively"
End If
run --headless は headless、run --interactive は interactive、test は test に解決されます。plain run は、xlflow 実行プロセスの環境変数 XLFLOW_MODE=interactive|headless|ci|agent|test が無い限り interactive にフォールバックします。
コマンドマップ
| コマンド | 目的 | 代表的な使い方 |
|---|---|---|
new |
新しい xlflow プロジェクトと .xlsm workbook を作成 |
xlflow new Book.xlsm |
init |
既存 workbook から xlflow プロジェクトを初期化 | xlflow init Book.xlsm |
doctor |
Excel、COM、.NET bridge、VBIDE access、任意の workbook open を診断 |
xlflow doctor --workbook --json |
attach |
Excel で現在 active な workbook を検証 | xlflow attach --active --json |
backup list |
rollback 用 workbook backup を一覧表示 | xlflow backup list --json |
pull |
VBA component を src/ へエクスポート |
xlflow pull --json |
push |
VBA source を workbook へインポート | xlflow push --json |
rollback |
保存済み backup から workbook を復元 | xlflow rollback --latest --json |
session |
高速ループ用に workbook を開いたままにする | xlflow session start |
status |
プロジェクト、source、workbook、session の状態を表示 | xlflow status --json |
save |
session 中の workbook を保存 | xlflow save --session --json |
recovery |
workbook の recovery-required state を検証して解除 | xlflow recovery clear --json |
runner |
永続 xlflow runner marker module を管理 | xlflow runner install --json |
process |
ローカル Excel プロセスの管理 (一覧表示、終了) | xlflow process list --json |
macros |
実行可能な macro entrypoint を検出 | xlflow macros --json |
list forms |
workbook の UserForm と想定 source path を列挙 | xlflow list forms --json |
form snapshot |
Designer UserForm state を JSON/YAML spec に保存 | xlflow form snapshot UserForm1 --out src/forms/specs/UserForm1.yaml --json |
form build |
保存済み spec から Designer-backed UserForm を作成 | xlflow form build src/forms/specs/UserForm1.yaml --json |
form export-image |
runtime UserForm を PNG 画像として出力 | xlflow form export-image UserForm1 --out artifacts/UserForm1.png --json |
run |
CLI から macro を実行 | xlflow run Main.Run --json |
export-image |
worksheet range を PNG 画像として出力 | xlflow export-image --sheet QR --range A1:AE31 --json |
edit |
live session workbook を準備・調整用に変更する | xlflow edit cell --sheet Input --cell B2 --value ABC123 --session --json |
test |
VBA test を実行 | xlflow test --json |
diff |
workbook 内容と任意の VBA source を比較 | xlflow diff before.xlsm after.xlsm --json |
inspect |
保存済み workbook snapshot または明示的な live session 状態を確認 | xlflow inspect range --sheet Result --address A1:F20 --session --json |
lint |
VBA source を lint | xlflow lint --json |
fmt |
VBA source を保守的にフォーマット | xlflow fmt --write --json |
encoding |
管理対象 VBA source の encoding を検証・変換 | xlflow encoding check --json |
analyze |
Excel を開かず runtime-risk pattern を解析 | xlflow analyze --json |
check |
lint / analyze / doctor をまとめて実行 |
xlflow check --keepalive --json |
inspect-gui |
GUI interaction boundary を検出 | xlflow inspect-gui --json |
skill install |
AI エージェント向け Skill をインストール | xlflow skill install --agent codex |
version |
インストール済み xlflow の build metadata を表示 | xlflow version |
コマンド詳細
各コマンドの詳しい挙動、オプション、JSON 出力、トラブルシューティングはドキュメントサイトへ移しました。
README は概要と最短導線に絞り、詳細はドキュメントサイトを参照してください。
設定ファイル
xlflow はプロジェクトルートの xlflow.toml を読み込みます。
# プロジェクトの識別情報およびエントリポイント
[project]
# 出力メッセージで使用するプロジェクト名。省略時はワークブックのベース名が使用されます。
name = "Book"
# xlflow run実行時にマクロが指定されなかった場合に呼び出されるデフォルトのマクロ。
entry = "Main.Run"
# Excelの自動化設定
[excel]
# ワークブックへのパス。プロジェクトルートからの相対パス、または絶対パスで指定します。
path = "build/Book.xlsm"
# 自動化中にExcelアプリケーションのウィンドウを表示するかどうか。
visible = false
# Excelの警告ダイアログ(上書き確認など)を抑制します。
display_alerts = false
# Excel bridge mode。指定可能な値は "auto" と "dotnet" です。
bridge = "auto"
# ソースツリーのディレクトリ
[src]
# 標準モジュール(.bas)用のディレクトリ。
modules = "src/modules"
# クラスモジュール(.cls)用のディレクトリ。
classes = "src/classes"
# ユーザーフォーム(.frm)ファイル用のディレクトリ。
forms = "src/forms"
# ワークブックのドキュメントモジュール用テキストのディレクトリ。
workbook = "src/workbook"
# VBEコンポーネントのフォルダサポート(Rubberduckスタイル)
[vba]
# @Folder("A.B") アノテーションとネストされたソースパスを有効にします。
folders = true
# push実行時にxlflowが @Folder アノテーションをどのように扱うか。
# 指定可能な値: "update", "preserve", "ignore"
# "update" – ソースディレクトリのレイアウトに基づいて書き換えます。
# "preserve" – 既存のアノテーションをそのまま保持します。
# "ignore" – フォルダアノテーションの読み書きを無効にします。
folder_annotation = "update"
# ソースパスに基づいてデフォルトのフォルダアノテーションを自動的に割り当てます。
default_component_folders = true
# オプションのErl計測。有効にすると、push時の一時インポートコピーにのみ
# 行番号を付与し、追跡対象のソースは番号なしのまま維持します。
# [vba.line_numbers]
# enabled = true
# ユーザーフォームのソースモード
[userform]
# ユーザーフォームのコードビハインドがソースツリーのどこに配置されるか。
# 指定可能な値: "frm", "sidecar"
# "frm" – コードはエクスポートされた .frm ファイル内に保持されます。
# "sidecar" – コードは src/forms/code/<フォーム名>.bas に分離されます。
code_source = "sidecar"
# テンプレート pack は省略した UserForm を既定で保持します。
# "source" は省略フォームを削除し、canonical spec を必須にします。
[pack]
userform_topology = "template"
# リリース用ビルドのソースフィルタリング。これは `build` のみに適用され、
# `push` と `pack` では常にソースツリー全体が使用されます。
[build]
# `xlflow build` から除外するプロジェクトルート相対のdoublestar glob。
exclude = [
"src/modules/Tests/**",
"src/modules/Xlflow/XlflowAssert.bas",
]
# procedureの複雑度メトリクス。
[metrics]
# メトリクス収集から除外するプロジェクトルート相対のdoublestar glob。
exclude = []
# 0はその閾値を無効化し、正の値は厳密な上限値として扱われます。
[metrics.thresholds]
cyclomatic_complexity = 0
max_nesting_depth = 0
statement_count = 0
source_line_count = 0
branch_count = 0
loop_count = 0
goto_count = 0
exit_point_count = 0
parameter_count = 0
byref_parameter_count = 0
local_variable_count = 0
call_fan_out = 0
# オプションのhotspotランキング。top-Nまたはスコア閾値が0の場合は無効です。
[metrics.hotspots]
procedure_top_n = 0
module_top_n = 0
procedure_score_threshold = 0
module_score_threshold = 0
# 自動バックアップ保持はデフォルトで無効です。セクションのコメントを外し、enabled = true にすると、
# 設定されたワークブックに対するバックアップ生成を伴うpushとrollbackの成功後に、古いメタデータ付き
# バックアップを削除します。
# [backup.retention]
# enabled = false
# max_count = 20
# max_age_days = 30
# min_keep = 5
# max_total_size_mb = 2048
# VBA formatterの設定
[fmt]
# xlflow fmtで安全な二項演算子の前後の空白を正規化します。
operator_spacing = true
# xlflow fmtで安全なVBA宣言の空白を正規化します。
declaration_spacing = true
# VBAキーワードの大文字・小文字を正規化します。
keyword_casing = true
# 既知のVBA/Excel/Office組み込み識別子の大文字・小文字を正規化します。
builtin_casing = true
# source-preflight診断のwaiver
[preflight]
# ここで許可した診断も表示されますが、source-preflightをブロックする効果だけを
# 解除します。Excel/VBEのコンパイルが失敗する可能性は残ります。
allowed_diagnostics = []
# 静的解析ルール
[lint]
# 診断 ID で特定の lint ルールを無効化します。
#
# 例:
# disabled_rules = [
# "VB006", # このレガシープロジェクトでpublicなモジュールフィールドを許可します。
# ]
disabled_rules = []
# VB020(未使用ローカル変数)の警告はデフォルトで有効です。
# スクラッチ用ローカル変数を意図的に残すプロジェクトでは disabled_rules に "VB020" を追加します。
#
# プロジェクト全体に適用するオプションのlintルールです。callback中心または
# workbook駆動のVBAではノイズになりやすいため、デフォルトでは無効です。
# 個別の設定のコメントを外して有効化してください。
# detect_scope_shadowing = true # VB018
# detect_unused_private_procedures = true # VB021
# detect_nested_with_ambiguity = true # VB027
# detect_empty_if = true # VB067
# ... (VB068-VB092 および競合注意; 生成される xlflow.toml を参照)
# Note: VB084 (detect_redundant_step_one) と VB085 (require_explicit_step) は
# For Step 句について相反するポリシーを表すため、同時には有効化しません。
# オプションのprocedure名定数チェック(VB044)。
# [lint.procedure_name_constant]
# enabled = true
# constant_name = "PROCEDURE_NAME"
# runtime-risk analyzerルール
[analyze]
# 診断 ID で特定の analyzer ルールを無効化します。
#
# 例:
# disabled_rules = [
# "VBA205", # このレガシープロジェクトでactive worksheet依存を許可します。
# ]
disabled_rules = []
# この正規化された http://host[:port] のorigin完全一致allowlistは、VBA246の
# plain_http_credentials 検出だけを抑制します。HTTPリクエストを許可するものではなく、
# credentials_in_url、authorization_logging、TLS/証明書、sensitive_module_constant、
# download_and_execute の検出は抑制しません。
development_http_origins = []
# オプションのdataflow対応 analyzerルールはデフォルトで無効です。
# FunctionおよびProperty Getのreturn pathを検査するには、次の設定のコメントを外してください。
# detect_function_return_path = true # VBA210
# その他のオプション analyzer ルール(コメント形式の候補。診断カタログも参照):
# detect_dictionary_collection_guard = true # VBA207
# ... (VBA213, VBA240, VBA242-VBA243, VBA248, VBA253-VBA275, VBA277-VBA282 の opt-in ルールと
# 競合注意; 生成される xlflow.toml を参照)
# Note: detect_implicit_byref_parameters (VBA273) と
# detect_redundant_byref_modifiers (VBA277) は相反する ByRef スタイルポリシーを
# 表すため、両方を有効化すると設定検証に失敗します。
project.entry は xlflow run の macro 名を省略した場合に使われます。
対話前提の project で UserForm やダイアログを意図的に使う場合は、[lint].disabled_rules = ["VB007"] にすると VB007 警告を抑止できます。これは lint だけに効き、xlflow run --headless の GUI 境界チェックは引き続きブロックします。forbid_interactive_input = false のような従来の per-rule boolean も互換性のため受け付けますが、非推奨です。
typographic quote、C-style quote escape、閉じられていないまたは対応がずれた procedure、行継続 _ の空白不足を検出する構文安全 lint は常に有効です。push や run が Excel を開く前に VBE compile dialog を防ぐためのルールです。
analyzer ルールは [analyze].disabled_rules = ["VBA205"] のように無効化できます。VBA101 から VBA106 までの analyzer 診断は常に有効です。
xlflow 専用組み込みモジュール
新しい project では、workbook 側 helper module として
src/modules/Xlflow/XlflowRuntime.bassrc/modules/Xlflow/XlflowUI.bassrc/modules/Xlflow/XlflowDebug.bassrc/modules/Xlflow/XlflowAssert.basが scaffold されます。
各モジュールの目的は次の通りです。
XlflowRuntimeはinteractive/headless/ci/agent/testの実行モード分岐に使います。XlflowUIはMsgBox、InputBox、Application.GetOpenFilename、openApplication.FileDialog、Application.GetSaveAsFilename、folder picker を包み、同じ VBA を対話実行と無人実行の両方で使えるようにします。XlflowDebugはXlflowDebug.Logをxlflow run/xlflow test中のターミナルへミラーしつつ、通常の VBA Immediate Window 出力も維持します。XlflowAssertは workbook 側 test で使う assertion helper で、scalar equality、strict equality、Null/Empty、数値許容誤差、文字列、配列、Range.Value2、object identity を検証できます。
例:
Dim answer As VbMsgBoxResult
Dim files As Variant
answer = XlflowUI.MsgBox("confirm-save", "Save workbook?", vbYesNo + vbQuestion, "Orders")
files = XlflowUI.GetOpenFilename("source-files", MultiSelect:=True)
XlflowDebug.Log "running in", XlflowRuntime.ModeName()
無人実行では CLI から dialog response を与えます。
xlflow run Main.Run --headless --msgbox confirm-save=yes --filedialog get-open:source-files=C:\temp\a.txt --filedialog get-open:source-files=C:\temp\b.txt --ui-stream --json
headless file dialog を Cancel 扱いにしたい場合は @cancel を使います。
xlflow run Main.Run --headless --filedialog folder:export-dir=@cancel --json
既存 project に bundled helper module を導入したい場合は、bootstrap 時か後付けで次の command を使えます。
xlflow init LegacyBook.xlsm --with-module
xlflow module install --push
AI エージェント・レビュー向けのプロジェクト構造
xlflow architecture
xlflow architecture --json
xlflow architecture --module Billing --json
モジュール、入口、依存関係、循環、到達可能性、hotspot、可変状態、 副作用、不確実性を一度のソース解析で取得できます。Excel や workbook は不要です。 module/path フィルターでもプロジェクト全体の解決結果と hotspot 順位を維持します。 情報提供用のレポートであり、lint・analyze・metrics の閾値を適用しません。 詳細は architecture コマンドガイドを参照してください。
JSON 出力
すべてのコマンドは --json を付けることで、AIエージェントやスクリプトから扱いやすい JSON を返します。
基本的な envelope は次の形式です。
{
"status": "ok",
"command": "lint",
"error": null,
"logs": []
}
失敗時は status が failed になり、error.code と error.message が返ります。
{
"status": "failed",
"command": "run",
"error": {
"code": "macro_failed",
"message": "Main Err 5: inputPath is required",
"source": "Main",
"number": 5,
"phase": "invoke_macro"
},
"logs": []
}
[!TIP] AIエージェントや自動化スクリプトでは、
status、command、error.code、各コマンド固有の top-level field を主な contract として扱うことを推奨します。
workbook_recovery_required は通常の lock contention ではなく、操作上の安全性エラーです。xlflow status --json の coordination.recovery と recovery action を確認してください。force clear は xlflow の marker だけを削除し、VBA の停止や Excel state の修復は行いません。
Exit code
| Code | 意味 |
|---|---|
0 |
成功 |
1 |
error/unknown/空の severity の lint/analyze 診断(check のソース診断を含む)、macro、test などの検証失敗 |
2 |
CLI 引数または設定エラー |
3 |
busy/recovery state、Excel、COM、bridge などの操作・環境エラー |
[!NOTE]
diffは差分が見つかった場合でも exit code0を返します。差分の有無はdiff.summary.total_diffsを確認してください。lint/analyze の結果、または
checkのソース診断が warning または information の診断だけの場合、診断は出力に残したまま exit code0を返します。unknown または空の severity は blocking として exit code1を返します。
License
MIT License. See LICENSE.
開発環境のセットアップ
このセクションは、ソースコードから xlflow を開発する場合や、ソースのみのコマンド、Go CLI、.NET Excel ブリッジ、Excel COM ワークフローを含むローカルのツールチェーン一式が必要な場合に使用してください。
必要なツール
| 要件 | 用途 |
|---|---|
| Windows x64 | ワークブックベースの開発および Excel COM の完全な検証 |
go.mod に記載された Go のバージョン |
Go CLI のビルドおよびテスト |
MSYS2 UCRT64 mingw-w64-ucrt-x86_64-gcc |
inspect symbols で使用する CGO ベースの tree-sitter VBA 統合のビルド |
| .NET SDK 8.0 以降 | xlflow-excel-bridge.exe のビルド |
| Task | task install などのリポジトリタスクの実行 |
| Microsoft Excel | エンドツーエンドのワークブックコマンドおよびリリースレベルの COM 検証 |
| VBA プロジェクト オブジェクト モデルへのアクセスを信頼する | VBA のインポート/エクスポート、コンパイル、ユーザーフォーム、実行、テストワークフロー |
xlflow inspect symbols は、Go CGO バインディングを通じて tree-sitter-vba を使用します。そのため、ソースから xlflow をビルドする際は、正常に動作する Windows C コンパイラが必須となります。古い TDM-GCC インストール環境ではなく、MSYS2 UCRT64 GCC を使用してください。
MSYS2 コンパイラをインストールします:
winget install MSYS2.MSYS2
C:\msys64\usr\bin\bash.exe -lc "pacman -Syu --noconfirm"
C:\msys64\usr\bin\bash.exe -lc "pacman -S --noconfirm mingw-w64-ucrt-x86_64-gcc"
次に、UCRT64 コンパイラを選択した状態でリポジトリからビルドおよびインストールを行います:
$env:CC = "C:\msys64\ucrt64\bin\gcc.exe"
task install
xlflow --help
xlflow version
もし task install で生成された xlflow.exe を実行した際に「指定された実行ファイルは、この OS プラットフォーム用の有効なアプリケーションではありません (The specified executable is not a valid application for this OS platform)」というエラーが出る場合は、現在有効な C コンパイラを確認してください:
go env GOOS GOARCH CGO_ENABLED CC
where.exe gcc
このエラーは、互換性のない GCC ディストリビューション(例:C:\TDM-GCC-64\bin\gcc.exe)を経由して CGO がリンクされた場合に発生することがあります。壊れたバイナリを削除し、CC 環境変数を MSYS2 UCRT64 GCC に指定し直してから再インストールしてください:
Remove-Item "$env:USERPROFILE\go\bin\xlflow.exe" -Force
$env:CC = "C:\msys64\ucrt64\bin\gcc.exe"
task install
開発中の素早い確認には、引き続き go run が便利です:
go run .\cmd\xlflow --help
go run .\cmd\xlflow inspect symbols --json
go test ./...
Excel COM の検証
ソースのみのテストは Excel なしでも実行可能ですが、ワークブックの自動化、VBA のインポート/エクスポート、マクロの実行、セッション、ユーザーフォーム、ブリッジに関わる変更については、実際の Windows 版 Excel による検証が必要です。リリースレベルの検証を行う前に、Excel で「VBA プロジェクト オブジェクト モデルへのアクセスを信頼する」を有効にし、task install を実行して xlflow.exe と xlflow-excel-bridge.exe の両方が Go の bin ディレクトリに配置されていることを確認してください。
ワークブックを用いた繰り返しのチェックには、セッションベースのワークフローを推奨します:
xlflow session start --json
xlflow push --fast --session --no-save --json
xlflow run Main.Run --session --json
xlflow test --session --json
xlflow save --session --json
xlflow session stop --json
セル色表現で QRコードを生成して Excel に表示するマクロ
Excel 上でテトリスをプレイできるマクロ
ユーザーフォーム上でスペースインベーダーをプレイできるマクロ
リッチなカレンダーピッカー
法令データ検索ツール
パックマン風ゲーム
