本番稼働中のシステムに新機能を安全に入れるには、環境の分離が欠かせません。ただ、個人開発で 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が書いたコード2api_key = os.getenv("API_KEY")3client = APIClient(api_key) # api_key=None でも初期化は成功する4result = client.fetch_data() # ここで初めて認証に失敗する5
6# fetch_data() が Exception を捕まえて None を返す実装だったため、7# エラーは表に出ず、機能が静かに無効になった実際に、これと同じ形の不具合で、本番の機能が長期間止まっていたことがあります。テストも CI も通っていて、エラーも出ていませんでした。この経験から、「テストと CI だけでは足りない。本番と同じ条件で、実害なく動かせる環境が要る」と考えるようになりました。その事故の経緯と検知の仕組みは「監視ハーネスでサイレント障害を1時間以内に検知する」にまとめています。
3ワークスペースの設計
全体構成
| 環境 | ディレクトリ | データ | DB | ブランチ | 用途 |
|---|---|---|---|---|---|
| 本番 | /path/to/project | 外付けSSD上の共有ストレージ | project_db | main | 実際に外部APIへリクエストを送る |
| Pre | /path/to/project-pre | 本番と共有(読み取り専用・symlink) | project_pre_db | pre | 本番と同じデータで Dry-Run。リクエストは送らない |
| 開発 | /path/to/project-dev | ローカル | なし(テスト用SQLite) | develop・feature/* | 実装・テスト |
設計判断1:Pre 環境は本番のデータを読み取り専用で参照する
Pre 環境に別のデータを用意すると、「Pre では動くが本番では動かない」問題が起きます。本番と同じデータを使えば、この食い違いをなくせます。
1本番の分析プログラムが出力した結果ファイル2 ↓ シンボリックリンクで共有3Pre 環境の処理エンジンが読み込む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 フラグを実装しました。
1import sys2import logging3
4logger = logging.getLogger(__name__)5
6def main() -> None:7 dry_run = "--dry-run" in sys.argv8 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つです。
- データ取得と分析は実行する: 読み取り系の処理は普段どおりに動かします
- 書き込み系だけを止める: 外部APIへのリクエスト、ファイルの書き込み、DB の更新を止めます
- ログに
[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 検証フロー
新機能を本番に入れるまでの標準フロー
11. Dev 環境で実装 + テスト(CI の PASS を確認)2 ↓32. feature/* ブランチを pre ブランチにマージ4 ↓53. Pre 環境の launchd に新しい plist を登録6 ↓74. 3段階の確認:8 a. plutil -lint <plist> → XML の構文が正しい9 b. 手動実行してログを確認 → 初期化に成功する10 c. 翌日、ヘルスチェックで確認 → スケジュールどおりに発火した11 ↓125. 1〜4週間の Dry-Run 運用13 ↓146. 統計的な Go/No-Go 判断(30回以上の処理をサンプルにする)15 ↓1 collapsed line
167. 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] |
1# ~/.zshrc に追加2function get_env_label() {3 case "$PWD" in4 */project-pre*) echo "PRE" ;;5 */project-dev*) echo "DEV" ;;6 */project*) echo "PROD" ;;7 esac8}9
10function set_iterm_profile() {11 case "$(get_env_label)" in12 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 esac7 collapsed lines
16}17
18# ディレクトリを移動するたびに切り替える19chpwd() { set_iterm_profile }20
21setopt PROMPT_SUBST22PS1='[$(get_env_label)] %~ $ 'case 文はパターンの順番が大事です。*/project* を先に書くと、project-pre も project-dev も本番として判定されてしまいます。名前が長い(より限定的な)パターンから先に書きます。
本番を一瞬で止める「緊急停止ファイル」
特定のファイルがあれば、すべてのプロセスが起動時にそれを見つけて止まる仕組みです。
1from pathlib import Path2import logging3
4logger = logging.getLogger(__name__)5
6EMERGENCY_STOP_FILE = Path("/tmp/project_emergency_stop")7
8def check_emergency_stop() -> bool:9 if EMERGENCY_STOP_FILE.exists():10 logger.warning("Emergency stop file detected: %s", EMERGENCY_STOP_FILE)11 return True12 return False13
14# 各エントリポイントの冒頭で呼ぶ15def main() -> None:3 collapsed lines
16 if check_emergency_stop():17 return18 # ... 通常の処理1touch /tmp/project_emergency_stop # 全システムを止める2rm /tmp/project_emergency_stop # 再開するDB のフラグや API ではなくファイルにしたのは、DB が落ちていてもファイルは作れること、そして慌てているときでもコマンド1つで済むことが理由です。実際に、負荷が急に上がったときに touch 一発で全エンジンを止められました。
main への直接 push を止める pre-push フック
1#!/bin/bash2# 標準入力に「ローカルref ローカルSHA リモートref リモートSHA」が1行ずつ渡される3while read -r local_ref local_sha remote_ref remote_sha; do4 if [ "$remote_ref" = "refs/heads/main" ]; then5 echo "Direct push to main is not allowed. Push a feature branch and create a PR."6 exit 17 fi8done9exit 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_a4Pre: com.example.pre.collect.daily.feed_a1# Pre のジョブだけ表示2launchctl list | grep 'com\.example\.pre\.'3
4# 環境別の件数5echo "本番: $(launchctl list | grep 'com\.example\.' | grep -vc 'com\.example\.pre\.')"6echo "Pre: $(launchctl list | grep -c 'com\.example\.pre\.')"効果
これらの対策を入れる前と後の、それぞれ3ヶ月を比べました。
| 指標 | 導入前(3ヶ月) | 導入後(3ヶ月) |
|---|---|---|
| 環境の取り違えによるインシデント | 4件 | 0件 |
| 本番(main)への直接 push | 2件 | 0件(フックで遮断) |
| サイレント障害に気づくまで | 平均8.3日 | 平均0.5日 |
| 緊急停止にかかる時間 | 3分(DBフラグの変更) | 2秒(touch) |
3行目は、毎朝のヘルスチェック(ログの鮮度確認と、届かなければ異常とみなす定時通知)による効果です。それぞれの対策は単純ですが、背景色を見落としても pre-push フックが止める、というように、1つが破られても次が受け止める形になっています。
同じマシンに3環境を置く罠
企業のようにサーバーを分けていれば起きない問題が、1台に同居させたことで起きました。「分けたつもりで、実は共有していた」ものが原因です。
罠1:PIDファイルの共有で、4日間ジョブが起動しなかった
本番ジョブと、5分遅れで動く Pre のジョブが、同じ /tmp/daily_pipeline.pid を参照していました。
- 本番ジョブがハングした(プロセスは残っているが処理が進まない)
- PIDファイルに、そのプロセスのPIDが残り続けた
- Pre のジョブは起動時に「既に実行中」と判定して起動をやめた
- 起動をやめるときに exit 0 で終わるため、監視は「正常」と判断した
この状態が4日間続き、両方のジョブが動いていませんでした。対策として、まず環境ごとに PID ファイルのパスを分けました。
1_WORKSPACE_SUFFIX = "_pre" if "project-pre" in str(PROJECT_ROOT) else ""2PID_FILE = Path(f"/tmp/daily_pipeline{_WORKSPACE_SUFFIX}.pid")あわせて、プロセスが既にいなくなっているのに PID ファイルだけ残っている場合(stale PID)は、ファイルを消して起動するようにしました。
1def _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 を入れて、同時書き込みがぶつからないようにする
1def _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 を入れたら、同じ日のうちに他のブランチへ同期する」とルールにしました。
1git checkout develop && git merge main && git push origin develop2git checkout pre && git merge main && git push origin preAI は作業中のブランチの 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() を足すようになりました。
まとめ
- Pre 環境は本番データを共有し、書き込みだけ止める: データの食い違いをなくし、Dry-Run の結果を信頼できるものにします
- 3段階で確認する: plutil の構文確認 → 手動実行 → 翌日のログ鮮度。どれか1つでは足りません
- 取り違えは文字と仕組みで防ぐ: 背景色にプロンプトの環境名を添え、pre-push フックと緊急停止ファイルで操作ミスを受け止めます。取り違えは3ヶ月で4件から0件になりました
- 1台に同居させるなら、共有されるものを分ける: PIDファイルの共有だけで、4日間ジョブが止まりました
「AI が書いたコードは正しいか」を確かめるいちばん確実な方法は、本番と同じ条件で動かすことです。Pre 環境は、その「同じ条件」を安全に用意してくれます。