この勉強会のゴールと基本方針

ゴール（勉強会が終わったときの状態）

1. 渡された .bat を読んで、何をしているか説明できる
2. 数十行規模の .bat を、テンプレートを土台に自分で書ける
3. バッチ特有の落とし穴（遅延展開・エスケープ・文字コード）に自力で気づける
4. 「これはバッチで書くべきではない」という判断ができる

決定した進行形式

読み物中心にするうえでの設計判断

ハンズオンをしない代わりに、資料側で以下を担保します。

• コードは必ず実行結果とセットで載せる。手を動かさない参加者が「で、どうなるの?」で止まらないようにする
• 誤りコードを先に見せて、直す。正解だけ並べると読み流されるため、落とし穴は「動かないコード → 出力 → 原因 → 修正」の4点セットで書く
• 後で1人で読み返せる密度にする。スライドではなく HTML の読み物として作り、勉強会後はそのままリファレンスとして機能させる

対象者の前提と、そこから決まる説明順

参加者が持っているもの / 持っていないもの

説明順を決める原則

プログラミング経験者にバッチを教えるときの最大の障害は、「言語だと思って読む」ことです。バッチは構文解析してから実行する言語ではなく、1行ずつテキストを置換してからコマンドを起動する仕組みです。ここを最初に壊さないと、遅延展開もエスケープも「よく分からない例外規則」として暗記対象になってしまいます。

したがって説明順は次の通りにします。

1. 実行モデル（第1回前半）— なぜ罠が多いのかの根拠を先に置く
2. 変数と終了コード（第1回後半）— バッチの2大データ経路
3. 制御構文と展開の罠（第2回）— 実行モデルの帰結として説明する
4. 実務の型（第3回）— 罠を回避済みのテンプレートに落とす

全3回の全体構成

回ごとの狙いと成果

全体を貫く「1本のサンプル」

回をまたいで同じ題材を育てる形にします。毎回まったく別の例を出すより、同じスクリプトが3回で実務品質に到達する過程を見せたほうが、読み物として最後まで読まれます。

第1回: バッチの実行モデル

時間配分

中心に置く図: 1行が実行されるまで

載せる対比表（第1回分）

第2回: 制御構文と展開の罠

時間配分

山場の作り方: 遅延展開

この回の中心はここです。「動かないコードを見せる → 出力を見せる → 実行モデルの図に戻って原因を示す → 修正する」の順に書きます。

@echo off
setlocal
set count=0
for %%f in (*.txt) do (
    set /a count=count+1
    echo 現在: %count%
)
echo 合計: %count%

動かない3ファイルあっても 現在: 0 が3回出て、合計: 3 になります。for の括弧内は、ループが始まる前に丸ごと1回だけ文字列置換されるため、%count% はすべて 0 に確定済みです。

@echo off
setlocal enabledelayedexpansion
set count=0
for %%f in (*.txt) do (
    set /a count=count+1
    echo 現在: !count!
)
echo 合計: !count!

動く!count! は行の解析時ではなく実行の直前に展開されます。

載せる対比表（第2回分）

エスケープはまとめて1ページにする

^ & | > < % " の扱いは、都度説明すると散らばって覚えられません。「どの文字が、どの文脈でエスケープを必要とするか」の一覧表を1つ作り、そこを参照する形にします。

第3回: 実務で使えるバッチを書く

時間配分

配布するテンプレートの骨格

第3回の実質的な成果物です。参加者が翌日からコピーして使えることを最優先にし、行ごとに「なぜ必要か」のコメントを日本語で入れます。

@echo off
rem ==== 実行環境を固定する ====
rem  ダブルクリック実行だとカレントがバッチの場所とは限らないため、必ず移動する
pushd "%~dp0" || exit /b 1

rem ==== 変数の影響をこのスクリプト内に閉じる ====
setlocal enabledelayedexpansion

rem ==== 引数チェック ====
if "%~1"=="" (
    echo 使い方: %~nx0 ^<対象フォルダ^>
    exit /b 1
)
set "TARGET=%~1"
if not exist "!TARGET!\" (
    echo エラー: フォルダが見つかりません: !TARGET!
    exit /b 1
)

rem ==== 本処理 ====
call :main
set "RC=!errorlevel!"

rem ==== 後始末（成功・失敗にかかわらず通る） ====
endlocal & set "RC=%RC%"
popd
exit /b %RC%

:main
rem ここに処理を書く。失敗したら exit /b で 0 以外を返す
goto :eof

載せる対比表（第3回分）

最後に置く「バッチの限界」

PowerShell との比較章は作らない方針ですが、判断基準だけは示します。配列や連想配列が必要、JSON を扱う、エラー処理が数階層になる、文字列処理が主目的のいずれかに該当したらバッチで書くべきではない、という4条件に絞って提示します。

成果物とファイル構成

ファイル構成

20260824-dos-command-learn\
├── index.html                … GitHub Pages の入口（README.html へリダイレクト）
├── .nojekyll                 … Jekyll の処理を無効にする
├── README.html               … プロジェクトの説明と資料一覧（本編・付録・構成の目次）
├── docs\
│   ├── 01-実行モデル.html    … 01. バッチの実行モデル
│   ├── 02-制御構文.html      … 02. 制御構文と展開の罠
│   ├── 03-実務.html          … 03. 実務で使えるバッチを書く
│   ├── A1-逆引き参照.html    … A1. 逆引き参照（3種の索引 / 詳細は各資料へリンク）
│   ├── A2-記法早見表.html    … A2. 記法早見表（変数展開・エスケープ・for のオプション）
│   ├── A3-落とし穴.html      … A3. 落とし穴カタログ（症状 → 原因 → 修正）
│   ├── ZZ-構成.html          … ZZ. 資料の構成（この資料）
│   ├── css\style.css         … 資料の共通スタイル
│   ├── images\               … 各 html から切り出した SVG（Markdown 用）
│   └── samples\
│       ├── README.html       … サンプルとテンプレートの使い方
│       ├── 01\ … 03\         … 各回のデモで使うバッチ
│       └── templates\        … tool.cmd / launcher.cmd / batchjob.cmd
├── tests\
│   └── samples.test.ts       … サンプルの cmd を実行して、出力が資料どおりかを確かめるテスト
└── tools\
    ├── 20_build\
    │   └── update-nav.ps1    … 各資料の前へ・次へ・目次のバッジを作り直す
    └── 40_test\
        └── run-tests.cmd     … テストの一括実行（node と bun）

Markdown（.md）は各 html と同じフォルダに生成されます。

ファイル名の付け方

本編と付録が名前順で混ざらないよう、接頭辞で系列を分けます。

エクスプローラやエディタの名前順で 01 → 02 → 03 → A1 → A2 → A3 → ZZ と並び、本編を読み終えた先に付録が続く形になります。付録を後から追加する場合も A4- 以降を使い、本編の連番には割り込ませません。

資料を追加・改題したら tools\20_build\update-nav.ps1 を実行し、各資料の前へ・次へ・目次のバッジを作り直します。サンプルや、資料に載せた出力を直したときは tools\40_test\run-tests.cmd を実行し、サンプルの出力が資料どおりかを確かめます。

HTML と Markdown の運用

各資料は HTML と Markdown の両方を置きます。HTML が原本で、.md は HTML から変換して生成したものです。

内容を更新する手順は次の通りです。

1. HTML を編集する
2. 共有ツールの html2md で、root の README.html と docs\ 配下をすべて変換する
3. 全 HTML から .md が作り直され、インライン SVG が images\ に切り出される

SVG を切り出すのは、GitHub が Markdown 内のインライン SVG をサニタイズで除去するためです。画像ファイルとして参照すれば Markdown でも図が表示されます。

GitHub Pages での公開

サンプルバッチの扱い

• 要注意サンプルは SJIS + CRLF で作成する。UTF-8 で保存すると日本語メッセージが化け、勉強会中のデモが失敗する
• 各回のサンプルは「失敗版」と「修正版」を対で置く。落とし穴の説明は実物が動かないと説得力が出ない
• サンプルは docs\samples\ 配下に閉じた動作にする。外部フォルダを書き換えるサンプルは作らない（参加者が試したときの事故を避ける）

資料に必ず含める落とし穴リスト

実際にバッチを書く人が踏むものを先に列挙し、これを A3-落とし穴.html の目次とします。各項目は「症状 → 原因 → 修正」の形で書きます。

付録: 逆引き参照の設計

本編（第1〜3回）は学ぶ順に並んでいますが、勉強会後に実際にバッチを書く人が必要とするのは探す順です。この2つは並び方が根本的に違うため、同じ文書では両立できません。そこで付録として逆引き専用のページ（A1-逆引き参照.html）を用意します。

3種類の入口を用意する

「探す」と言っても、探し始める手がかりは人によって違います。次の3つを別々の索引として持ちます。

索引A: やりたいこと逆引き（抜粋）

索引B: 他言語からの逆引き（抜粋）

本編の各回に置く対比表は「学ぶための対比」で、対比が破綻する点の説明を含みます。索引Bは「引くための対比」なので、記法と参照先だけに絞って一覧性を優先します。

索引C: 症状からの逆引き（抜粋）

参照先は落とし穴カタログの項番（この資料の8章のリストと同じ番号）です。