45395 - シコウサクゴ -

本番・Pre・開発の3環境を1台のMacで1人で運用する:Dry-Run検証、取り違え防止、共有リソースの罠

2026-04-03
AI駆動開発
AI駆動開発
Claude Code
DevOps
環境分離
Dry-Run
launchd
ヒューマンエラー防止
Last updated:2026-11-08
22 Minutes
4238 Words

本番稼働中のシステムに新機能を安全に入れるには、環境の分離が欠かせません。ただ、個人開発で Production / Pre-Production / Development の3環境を維持するのは、チーム開発よりも負担が大きくなります。

この記事では、1台の macOS 上に3つのワークスペースを作り、1人で運用している実践を記録します。中心は「Pre 環境で Dry-Run してから本番に入れる」流れで、これが AI の書いたコードの品質確認にどう効いたかを説明します。あわせて、3環境を同じマシンに置いたことで起きた「取り違え」と「共有リソースの罠」と、その対策もまとめます。


なぜ3環境が必要になったか

Dev では動くのに、launchd 経由では動かない

Claude Code が書くコードは、Dev 環境でターミナルから手動実行すると問題なく動きます。しかし、launchd(macOS の定時実行の仕組み)から起動すると、実行条件が次のように変わります。

項目Dev(手動実行)Pre/本番(launchd)
環境変数シェルプロファイルから読み込まれるplist の EnvironmentVariables だけ
カレントディレクトリ任意/
PATHフルに設定済み最小限
.env ファイルload_dotenv() で読めるパスを明示しないと読めない

AI は「ターミナルから実行する」前提でコードを書きがちで、os.getenv("API_KEY") が None を返す状況を想定していないことがよくあります。

1
# AIが書いたコード
2
api_key = os.getenv("API_KEY")
3
client = APIClient(api_key) # api_key=None でも初期化は成功する
4
result = client.fetch_data() # ここで初めて認証に失敗する
5
6
# fetch_data() が Exception を捕まえて None を返す実装だったため、
7
# エラーは表に出ず、機能が静かに無効になった

実際に、これと同じ形の不具合で、本番の機能が長期間止まっていたことがあります。テストも CI も通っていて、エラーも出ていませんでした。この経験から、「テストと CI だけでは足りない。本番と同じ条件で、実害なく動かせる環境が要る」と考えるようになりました。その事故の経緯と検知の仕組みは「監視ハーネスでサイレント障害を1時間以内に検知する」にまとめています。


3ワークスペースの設計

全体構成

環境ディレクトリデータDBブランチ用途
本番/path/to/project外付けSSD上の共有ストレージproject_dbmain実際に外部APIへリクエストを送る
Pre/path/to/project-pre本番と共有(読み取り専用・symlink)project_pre_dbpre本番と同じデータで Dry-Run。リクエストは送らない
開発/path/to/project-devローカルなし(テスト用SQLite)develop・feature/*実装・テスト

設計判断1:Pre 環境は本番のデータを読み取り専用で参照する

Pre 環境に別のデータを用意すると、「Pre では動くが本番では動かない」問題が起きます。本番と同じデータを使えば、この食い違いをなくせます。

1
本番の分析プログラムが出力した結果ファイル
2
↓ シンボリックリンクで共有
3
Pre 環境の処理エンジンが読み込む
4
↓ Dry-Run モードで処理
5
外部APIは呼ばない(ログ出力のみ)

ただし、共有にはそれ自体の罠がありました。後半の「同じマシンに3環境を置く罠」で説明します。

設計判断2:Pre の launchd ジョブは本番の5分後に動かす

1
<!-- 本番: 毎時00分に実行 -->
2
<key>Minute</key><integer>0</integer>
3
4
<!-- Pre: 毎時05分に実行 -->
5
<key>Minute</key><integer>5</integer>

本番と同じスケジュールで、5分遅れて実行します。こうすると次の2つが成り立ちます。

  • 本番がデータを作った後に Pre が読み込む(データの依存関係を守れる)
  • 同じデータ状況での本番と Pre のログを、時系列で比べられる

設計判断3:DB は完全に分ける

Pre 環境が本番 DB に書き込む事故を防ぐため、データベースは完全に分け、接続文字列は環境変数で切り替えます。

設計判断4:Dry-Run は「書き込みだけ止める」

すべてのエントリポイントに --dry-run フラグを実装しました。

1
import sys
2
import logging
3
4
logger = logging.getLogger(__name__)
5
6
def main() -> None:
7
dry_run = "--dry-run" in sys.argv
8
if dry_run:
9
logger.info("[DRY-RUN] No actual operations will be executed")
10
11
# データ取得と分析は dry-run でも実行する
12
items = build_work_items()
13
logger.info("Built %d items", len(items))
14
15
for item in items:
9 collapsed lines
16
task = create_task(item)
17
if dry_run:
18
logger.info("[DRY-RUN] Would execute: %s", task)
19
else:
20
result = execute_task(task)
21
logger.info("Executed: %s -> %s", task, result)
22
23
# 集計も dry-run でも実行する
24
logger.info("Summary: %s", summarize(items))

原則は3つです。

  1. データ取得と分析は実行する: 読み取り系の処理は普段どおりに動かします
  2. 書き込み系だけを止める: 外部APIへのリクエスト、ファイルの書き込み、DB の更新を止めます
  3. ログに [DRY-RUN] を付ける: 後からログを見て、Dry-Run の実行だったと分かるようにします

Pre 環境の plist には、--dry-run を最初から付けています。

1
<key>ProgramArguments</key>
2
<array>
3
<string>/usr/bin/python3</string>
4
<string>main.py</string>
5
<string>--dry-run</string> <!-- Pre環境は常にdry-run -->
6
</array>

Pre 環境での Dry-Run 検証フロー

新機能を本番に入れるまでの標準フロー

1
1. Dev 環境で実装 + テスト(CI の PASS を確認)
2
↓
3
2. feature/* ブランチを pre ブランチにマージ
4
↓
5
3. Pre 環境の launchd に新しい plist を登録
6
↓
7
4. 3段階の確認:
8
a. plutil -lint <plist> → XML の構文が正しい
9
b. 手動実行してログを確認 → 初期化に成功する
10
c. 翌日、ヘルスチェックで確認 → スケジュールどおりに発火した
11
↓
12
5. 1〜4週間の Dry-Run 運用
13
↓
14
6. 統計的な Go/No-Go 判断(30回以上の処理をサンプルにする)
15
↓
1 collapsed line
16
7. GO なら本番に適用

3段階の確認が必要な理由

  • 1段階目(plutil)だけでは足りません。 plist の構文が正しくても、実行時に ModuleNotFoundError が出ることがあります。
  • 2段階目(手動実行)だけでも足りません。 手動実行では環境変数が揃っていても、launchd のスケジュール実行では揃っていないことがあります。
  • 3段階目(翌日のログ鮮度の確認)で、スケジュールが実際に発火したかを確かめます。 launchctl list にジョブが表示されていても、発火しないことがあるためです。

「exit code 0 でも、意図どおりに動いたとは限らない」という考え方は「exit code 0は正常ではない」に詳しく書きました。


環境の取り違えを防ぐ

3つのワークスペースをターミナルのタブで同時に開いていると、タブを間違えただけで本番に影響が出かねません。「本番・Pre・開発のワークスペースを開いているときに、見た目を変えたい」という要望から始めた小さな対策が、いくつかの層の防御として定着しました。

ターミナルの背景色とプロンプトで環境を示す

iTerm2 のプロファイル機能で、ディレクトリに応じて背景色を自動で切り替えます。色だけに頼ると、見落としたときや色の区別がつきにくいときに役に立たないので、プロンプトにも環境名を文字で出します。

プロファイル名背景色プロンプトの表示
Production暗い赤(#1a0000)[PROD]
PreProduction暗い黄(#1a1a00)[PRE]
Development暗い緑(#001a00)[DEV]
Terminal window
1
# ~/.zshrc に追加
2
function get_env_label() {
3
case "$PWD" in
4
*/project-pre*) echo "PRE" ;;
5
*/project-dev*) echo "DEV" ;;
6
*/project*) echo "PROD" ;;
7
esac
8
}
9
10
function set_iterm_profile() {
11
case "$(get_env_label)" in
12
PROD) echo -e "\033]1337;SetProfile=Production\a" ;;
13
PRE) echo -e "\033]1337;SetProfile=PreProduction\a" ;;
14
DEV) echo -e "\033]1337;SetProfile=Development\a" ;;
15
esac
7 collapsed lines
16
}
17
18
# ディレクトリを移動するたびに切り替える
19
chpwd() { set_iterm_profile }
20
21
setopt PROMPT_SUBST
22
PS1='[$(get_env_label)] %~ $ '

case 文はパターンの順番が大事です。*/project* を先に書くと、project-pre も project-dev も本番として判定されてしまいます。名前が長い(より限定的な)パターンから先に書きます。

本番を一瞬で止める「緊急停止ファイル」

特定のファイルがあれば、すべてのプロセスが起動時にそれを見つけて止まる仕組みです。

1
from pathlib import Path
2
import logging
3
4
logger = logging.getLogger(__name__)
5
6
EMERGENCY_STOP_FILE = Path("/tmp/project_emergency_stop")
7
8
def check_emergency_stop() -> bool:
9
if EMERGENCY_STOP_FILE.exists():
10
logger.warning("Emergency stop file detected: %s", EMERGENCY_STOP_FILE)
11
return True
12
return False
13
14
# 各エントリポイントの冒頭で呼ぶ
15
def main() -> None:
3 collapsed lines
16
if check_emergency_stop():
17
return
18
# ... 通常の処理
Terminal window
1
touch /tmp/project_emergency_stop # 全システムを止める
2
rm /tmp/project_emergency_stop # 再開する

DB のフラグや API ではなくファイルにしたのは、DB が落ちていてもファイルは作れること、そして慌てているときでもコマンド1つで済むことが理由です。実際に、負荷が急に上がったときに touch 一発で全エンジンを止められました。

main への直接 push を止める pre-push フック

.git/hooks/pre-push
1
#!/bin/bash
2
# 標準入力に「ローカルref ローカルSHA リモートref リモートSHA」が1行ずつ渡される
3
while read -r local_ref local_sha remote_ref remote_sha; do
4
if [ "$remote_ref" = "refs/heads/main" ]; then
5
echo "Direct push to main is not allowed. Push a feature branch and create a PR."
6
exit 1
7
fi
8
done
9
exit 0

今いるブランチ名(git rev-parse --abbrev-ref HEAD)で判定すると、feature ブランチにいながら git push origin HEAD:main とした場合を止められません。push 先の ref で判定します。

launchd ジョブの名前に環境を入れる

本番で約77、Pre で13、合わせて約90の launchd ジョブがあるため、名前だけで環境が分かるようにしています。

1
命名規則: com.example.{pre.}{engine}.{type}.{target}
2
3
本番: com.example.collect.daily.feed_a
4
Pre: com.example.pre.collect.daily.feed_a
Terminal window
1
# Pre のジョブだけ表示
2
launchctl list | grep 'com\.example\.pre\.'
3
4
# 環境別の件数
5
echo "本番: $(launchctl list | grep 'com\.example\.' | grep -vc 'com\.example\.pre\.')"
6
echo "Pre: $(launchctl list | grep -c 'com\.example\.pre\.')"

効果

これらの対策を入れる前と後の、それぞれ3ヶ月を比べました。

指標導入前(3ヶ月)導入後(3ヶ月)
環境の取り違えによるインシデント4件0件
本番(main)への直接 push2件0件(フックで遮断)
サイレント障害に気づくまで平均8.3日平均0.5日
緊急停止にかかる時間3分(DBフラグの変更)2秒(touch)

3行目は、毎朝のヘルスチェック(ログの鮮度確認と、届かなければ異常とみなす定時通知)による効果です。それぞれの対策は単純ですが、背景色を見落としても pre-push フックが止める、というように、1つが破られても次が受け止める形になっています。


同じマシンに3環境を置く罠

企業のようにサーバーを分けていれば起きない問題が、1台に同居させたことで起きました。「分けたつもりで、実は共有していた」ものが原因です。

罠1:PIDファイルの共有で、4日間ジョブが起動しなかった

本番ジョブと、5分遅れで動く Pre のジョブが、同じ /tmp/daily_pipeline.pid を参照していました。

  1. 本番ジョブがハングした(プロセスは残っているが処理が進まない)
  2. PIDファイルに、そのプロセスのPIDが残り続けた
  3. Pre のジョブは起動時に「既に実行中」と判定して起動をやめた
  4. 起動をやめるときに exit 0 で終わるため、監視は「正常」と判断した

この状態が4日間続き、両方のジョブが動いていませんでした。対策として、まず環境ごとに PID ファイルのパスを分けました。

1
_WORKSPACE_SUFFIX = "_pre" if "project-pre" in str(PROJECT_ROOT) else ""
2
PID_FILE = Path(f"/tmp/daily_pipeline{_WORKSPACE_SUFFIX}.pid")

あわせて、プロセスが既にいなくなっているのに PID ファイルだけ残っている場合(stale PID)は、ファイルを消して起動するようにしました。

1
def _acquire_pid_lock() -> bool:
2
if PID_FILE.exists():
3
old_pid = int(PID_FILE.read_text().strip())
4
try:
5
os.kill(old_pid, 0) # プロセスの存在確認(シグナルは送らない)
6
return False # プロセスが生きている → ロックを取れない
7
except ProcessLookupError:
8
PID_FILE.unlink() # プロセスがいない → 古いPIDファイルを消す
9
PID_FILE.write_text(str(os.getpid()))
10
return True

存在しないプロセスに os.kill(pid, 0) を送ると、Python では ProcessLookupError が送出されます。なお、ハングしているプロセスは「生きている」と判定されるので、このチェックで解決するのは「プロセスが消えたのに PID が残った」場合だけです。

/tmp/ に置くファイルには環境名のサフィックスを付ける、というルールは、設計の時点で決めておくべきでした。後から気づくと、原因を突き止めるのに時間がかかります。

罠2:共有データディレクトリの競合

Pre は本番のデータを symlink で読んでいるので、本番ジョブが処理済みのファイルを os.remove() で消すと、5分後に動く Pre のジョブはそのファイルを読めなくなります。

  • 処理済みファイルは削除せず、.bak にリネームする
  • Dry-Run 環境では、削除もリネームもしない
  • 書き込み用の一時ファイル名に PID を入れて、同時書き込みがぶつからないようにする
1
def _atomic_write(path: Path, data: bytes) -> None:
2
tmp_path = path.with_suffix(f".tmp.{os.getpid()}")
3
tmp_path.write_bytes(data)
4
tmp_path.rename(path)

罠3:CLAUDE.md のブランチ間の同期

CLAUDE.md は main・pre・develop の各ブランチで別々に更新されるため、コンフリクトが頻繁に起きました。教訓の追記が1つのブランチにだけ残り、他のブランチに反映されないことが続き、2週間で CLAUDE.md の同期コミットが7回必要になりました。

当初は「週1回まとめて同期すれば十分」と考えていましたが、hotfix が16時間ほかのブランチに反映されなかったことがあり、「main に hotfix を入れたら、同じ日のうちに他のブランチへ同期する」とルールにしました。

Terminal window
1
git checkout develop && git merge main && git push origin develop
2
git checkout pre && git merge main && git push origin pre

AI は作業中のブランチの CLAUDE.md しか読みません。ブランチごとにルールが食い違っていると、環境によって AI の振る舞いが変わってしまいます。

チェックリスト:1台で複数の環境を運用するとき

  • PIDファイルなど /tmp/ に置くファイルのパスは、環境ごとに分かれているか
  • テストが本番のファイルや DB に触れないことを確かめる仕組みがあるか
  • 共有ディレクトリのファイルを、本番ジョブが消していないか
  • 一時ファイル名に PID を入れて、書き込みの競合を防いでいるか
  • CLAUDE.md や設定ファイルを、ブランチ間で同期するルールがあるか
  • Pre 環境の plist に --dry-run が付いているか

学んだこと

1. テストが通るだけでは足りない

CI が PASS しても、launchd 環境での動作は保証されません。本番と同じデータ・同じ起動方法で、書き込みだけを止めて動かす Pre 環境が、最後の確認の場になりました。

2. 個人開発でも3環境は保つ価値がある

「1人だから2環境で十分」と思っていましたが、Pre 環境がなければ「本番でいきなり動かして祈る」ことになります。plist の管理や DB の分離といった維持の手間よりも、本番事故の復旧の手間のほうがずっと大きいです。

3. 「分けたつもりで共有しているもの」を列挙する

PIDファイル、データディレクトリ、CLAUDE.md のように、1台に同居させると気づかないうちに共有されるものがあります。環境を作るときに「この環境は何を共有し、何を分けるか」を書き出しておくのが、いちばん効く予防策です。

4. AI への指示に launchd の制約を書く

CLAUDE.md に「launchd 環境ではシェルプロファイルを読まない」と書いておいたことで、AI が os.getenv() を使うコードを書くときに、load_dotenv() を足すようになりました。


まとめ

  1. Pre 環境は本番データを共有し、書き込みだけ止める: データの食い違いをなくし、Dry-Run の結果を信頼できるものにします
  2. 3段階で確認する: plutil の構文確認 → 手動実行 → 翌日のログ鮮度。どれか1つでは足りません
  3. 取り違えは文字と仕組みで防ぐ: 背景色にプロンプトの環境名を添え、pre-push フックと緊急停止ファイルで操作ミスを受け止めます。取り違えは3ヶ月で4件から0件になりました
  4. 1台に同居させるなら、共有されるものを分ける: PIDファイルの共有だけで、4日間ジョブが止まりました

「AI が書いたコードは正しいか」を確かめるいちばん確実な方法は、本番と同じ条件で動かすことです。Pre 環境は、その「同じ条件」を安全に用意してくれます。

AI駆動開発での開発・自動化・監視の仕組みづくりについて、ご相談を受け付けています

お仕事のご相談

記事へのご質問・ご感想はこちらのフォームからお送りください

Article title:本番・Pre・開発の3環境を1台のMacで1人で運用する:Dry-Run検証、取り違え防止、共有リソースの罠
Article author:45395
Release time:2026-04-03