外部連携バッチシステムの動作確認をしやすくする

はじめに

こんにちは。リテールハブ開発部の清水です。
私たちのチームでは、外部システムと深夜帯にCSVをやり取りするバッチシステムを開発・運用しています。
これらのバッチ群は適切な順番で適切な設定で実行することが求められるのですが、
新メンバーがジョインしたとき、これをローカル環境で実際に動かして確かめるのはハードルが高いと感じていました。
本記事ではこのようなバッチシステムを動作確認しやすくするために考えた点をご紹介します。

対象のバッチシステム

本番のインフラ構成イメージ

ローカル開発環境

Docker Composeで FTP / S3互換ストレージ / MySQL を立てて、Goバッチがそれらに対して動作する形です。

動作確認が大変な理由

外部システム連携であること
外部システム側のフォーマット仕様書は手元にあるのですが、仕様書を読むだけだとピンとこない箇所がそれなりにあります。
さらに本物のCSVは非常にカラム数が多い上、センシティブな情報も含まれるので、軽い気持ちで実物を見るのはためらわれるものです。
こういった状況から気軽にローカルで試すためのテストデータを作成することのハードルがかなり高いです。
バッチ処理を複数に分けていること
リトライしやすさを優先して、CSV取得・ETL変換・計算処理・CSVエクスポート・FTP送信・ファイル送信履歴更新とバッチを6つに分けています。
途中まで処理したファイルは都度S3に設置する形を取っています。
初見だと「どの順番でどの環境変数で動かせばいいんだっけ？」と混乱しやすいです。
一度ローカルで一通り実行してみるのがいちばん早いのですが、その「一度通す」までのお膳立てが意外に重い、というのが課題でした。

工夫1: テストデータ作成用コマンドを実装

JSONからテストデータを生成するmakeコマンドを用意しました。

make gen-testdata CONFIG=test_20260507.json

{
  "a": "2026-05-07",
  "b": [
    {
      "c": "TEST_001",
      "d": [
        {
          "e": 1,
          "f": "10:30:00",
          "g": [
            {"h": 1, "i": 2, "j": 500}
          ]
        }
      ]
    }
  ]
}

JSONを差し替えるだけでさまざまなテストケースを切り替えられます。
本物のCSVに触らずにテストできるようになり、テストデータ作成のハードルがだいぶ下がりました。
実際に使用するときは人間がJSONを用意するのではなく、Claude Codeに「こういうテストケースのデータを作って」と指示を出すとこちらのコマンドが使われる形になります。

工夫2: Claude Codeでオンボーディングスキルを作成

スキルのディレクトリ

.claude/skills/onboarding/
├── SKILL.md
├── references/
│   ├── architecture.md
│   └── batch-pipeline.md
└── scripts/
    ├── check_env.sh
    └── check_step.sh

SKILL.md がスキル本体で、references/ 以下にアーキテクチャ説明やパイプラインの全体像を、scripts/ 以下に通過判定用のスクリプトを置いています。

大まかな内容

Phase 1: 環境チェック
Docker / docker compose / make / コンテナの起動・healthy 状態をスクリプトで判定する

Phase 2: アーキテクチャ説明 + 動作確認
references/ 以下のドキュメントで全体像を伝えてから、6本のバッチを1本ずつ手で動かしてもらう

こだわったポイント

実際に手で動かせるようにする
- 私はどうしてもコードを読むだけでは理解できないと感じることが多いので、ローカル環境で立ち上げて一通り動作させることにこだわりました
- 表示されたコマンドをコピーして、別タブのターミナルで実行して進める形にしました
通過判定をスクリプトで行う
- 最初は「ステップごとに Claude Code がユーザーに確認して、その回答を信じて進める」くらいの素朴な作りで考えていました
- 実際にはまだ前のステップが完了していない (例: DB初期化を忘れている) のに気づかず進んでしまい、後段でエラーになってからようやく手戻りが発生する、ということが起こりました

おわりに

新メンバーが触れたときに迷子になりがちな部分を、テストデータ作成コマンドとオンボーディングスキルでだいぶ楽にできた手応えがあります。
特にスキル側では、ステップごとの通過判定をスクリプトに寄せたことで、Claude Codeが「分かったつもり」で先に進んでしまう問題を防げました。
同じように複雑なシステムの動作確認に悩まれている方の参考になれば嬉しいです。

every Tech Blog

株式会社エブリーのTech Blogです。