はじめに
当社(合同会社ジョインクラス)は社員のいない会社で、記事の公開・SNS配信・売上集計などを launchd のジョブから Claude Code を呼んで回しています。困るのは、Claude Code が自動で新しいバージョンになり、設定がいつの間にか効かなくなることです。エラーは出ず、hooks が動いていない、許可したはずのコマンドで止まる、といった形でしか気づけません。
僕は以前、macOS の cron がフルディスクアクセスの制限で全部止まっていたのに気づかず、launchd に移したことがあります。「黙って止まる」ものは、機械で確かめるしかありません。
この記事では、changelog と自分の settings.json を突き合わせて、影響がありそうな設定キーを書き出すスクリプトを作ります。自社で毎週動かしている、バージョンの変化を検知するシェルスクリプトに組み込む形です。
全体の流れ
-
claude --versionを前回の値と比べ、変わった週だけ処理する - 前回から今回までの changelog の節を取り出す
- settings.json のキーを全部並べる(
hooks.PreToolUseのような形にする) - changelog の中で「deprecated / removed / renamed / breaking」を含む行と、キー名を照らし合わせる
- 当たった行を Slack に送り、記録ファイルに残す
LLM に「影響ある?」と聞くだけだと、毎回答えが揺れます。キーの照合は決まった手順のスクリプトでやり、LLM は当たった行の解説だけにしています。
1. 元にしたスクリプト(バージョンの変化の検知)
当社で毎週月曜 10:00 に launchd から動かしている auto-upgrade-check.sh の、バージョンを比べる部分です。
#!/bin/bash
set -uo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
LOG_DIR="$SCRIPT_DIR/logs"
VERSION_FILE="$LOG_DIR/.claude-version-last"
mkdir -p "$LOG_DIR"
CURRENT_VERSION=$(claude --version 2>/dev/null || echo "unknown")
LAST_VERSION=$(cat "$VERSION_FILE" 2>/dev/null || echo "none")
VERSION_CHANGED=false
if [ "$CURRENT_VERSION" != "$LAST_VERSION" ]; then
VERSION_CHANGED=true
echo "$CURRENT_VERSION" > "$VERSION_FILE"
fi
これまでは、この後に Claude Code へ「新機能を調べて」と頼むだけでした。新機能は見つかりますが、自分の設定が壊れたかどうかは分かりません。そこで、次の照合スクリプトを足します。
2. 照合スクリプト(check-settings-vs-changelog.py)
標準ライブラリだけで動きます。Python 3.9 以上で動作します。
#!/usr/bin/env python3
"""changelogの「非推奨・削除・名前変更」行と settings.json のキーを照合する。"""
import json
import re
import sys
import urllib.request
from pathlib import Path
CHANGELOG_URL = "https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md"
SETTINGS_FILES = [
Path.home() / ".claude/settings.json",
Path(".claude/settings.json"),
Path(".claude/settings.local.json"),
]
RISK_WORDS = re.compile(r"deprecat|remov|renam|breaking|no longer|replaced", re.I)
# どの設定にもありふれていて、誤検知しか生まない語
IGNORE_KEYS = {"type", "command", "matcher", "allow", "deny", "env"}
def parse_version(text):
match = re.search(r"(\d+)\.(\d+)\.(\d+)", text)
return tuple(int(part) for part in match.groups()) if match else None
def changelog_between(changelog, last, current):
"""last より新しく current 以下の節だけ返す。"""
lines, keep = [], False
for line in changelog.splitlines():
if line.startswith("## "):
version = parse_version(line)
keep = bool(version) and (last is None or version > last) and version <= current
continue
if keep:
lines.append(line)
return lines
def flatten_keys(node, prefix=""):
if not isinstance(node, dict):
return
for key, value in node.items():
path = f"{prefix}.{key}" if prefix else key
yield path
yield from flatten_keys(value, path)
def main():
last = parse_version(sys.argv[1]) if len(sys.argv) > 1 else None
current = parse_version(sys.argv[2]) if len(sys.argv) > 2 else (999, 0, 0)
with urllib.request.urlopen(CHANGELOG_URL, timeout=20) as response:
changelog = response.read().decode("utf-8")
risky_lines = [line for line in changelog_between(changelog, last, current)
if RISK_WORDS.search(line)]
hits = []
for settings_file in SETTINGS_FILES:
if not settings_file.exists():
continue
try:
settings = json.loads(settings_file.read_text())
except json.JSONDecodeError as error:
hits.append(f"[壊れたJSON] {settings_file}: {error}")
continue
for key_path in flatten_keys(settings):
leaf = key_path.split(".")[-1]
if leaf in IGNORE_KEYS or len(leaf) < 4:
continue
for line in risky_lines:
if re.search(rf"\b{re.escape(leaf)}\b", line):
hits.append(f"[{settings_file}] {key_path}\n → {line.strip()}")
print("\n".join(hits) if hits else "影響のありそうな設定は見つかりませんでした")
return 1 if hits else 0
if __name__ == "__main__":
sys.exit(main())
ポイントは3つです。
- 取り出すのは前回から今回までの節だけ。changelog 全体と照合すると、何年も前の変更まで毎週当たってしまいます
-
比べるのはキーの末尾だけ(
hooks.PreToolUseならPreToolUse)。changelog はキーを末尾の名前で書くことが多いためです - 当たったら終了コード 1。シェル側で分岐できるようにしています
3. シェルスクリプトに組み込む
先ほどの auto-upgrade-check.sh の、バージョンを比べた直後に足します。
if [ "$VERSION_CHANGED" = true ]; then
cd "$PROJECT_ROOT"
REPORT=$(python3 "$SCRIPT_DIR/check-settings-vs-changelog.py" "$LAST_VERSION" "$CURRENT_VERSION" 2>&1)
STATUS=$?
printf '\n## 設定照合 %s (%s → %s)\n%s\n' "$(date +%F)" "$LAST_VERSION" "$CURRENT_VERSION" "$REPORT" >> "$UPGRADE_LOG"
if [ "$STATUS" -ne 0 ] && [ -n "${SLACK_WEBHOOK_URL:-}" ]; then
curl -sf -X POST -H "Content-Type: application/json" \
-d "$(jq -n --arg text "$(printf '⚠️ 設定に影響しそうな変更\n%s' "$REPORT")" '{text: $text}')" \
"$SLACK_WEBHOOK_URL" >/dev/null 2>&1 || true
fi
fi
cd "$PROJECT_ROOT" を忘れないでください。launchd から動かすと作業ディレクトリは / になるので、プロジェクトの .claude/settings.json が読まれません。
4. 動作確認
手で前のバージョンを渡して、わざと範囲を広げると動きを確かめられます。
# 現在のバージョンを確認
claude --version
# 範囲を広めにして試す(例: 1.0.0 から今のバージョンまで)
python3 .company/scripts/check-settings-vs-changelog.py 1.0.0 "$(claude --version)"
echo "exit: $?"
当たった場合は次のように出ます(キーと行はその時の内容で変わります)。
[.claude/settings.json] hooks.PreToolUse
→ - Hooks: ... PreToolUse ... renamed ...
exit: 1
設定ファイルの JSON が壊れていても [壊れたJSON] として出すようにしています。手で編集したあと、カンマを1つ消し忘れて全ての設定が読まれなくなるのは、実際によくある失敗です。
落とし穴
-
誤検知は出ます。
modelやtimeoutのような一般的な語は、関係ない行にも当たります。うるさいキーはIGNORE_KEYSに足してください。見逃すより、多めに出して人が見るほうを選んでいます - changelog に書かれない変更は拾えません。これは「明記された変更」の網です。本当に動くかは、hooks を1つ実際に呼ぶテストのジョブを別に置くほうが確実です
- 自動で新しいバージョンになるタイミングと週1回の確認はずれます。確認するまでの数日は気づけません。急ぐ場合は、毎日のジョブの先頭でバージョンの比較だけを動かします
- GitHub の raw URL は取得に失敗することがあります。例外で落ちた場合も終了コードが 0 以外になるので、Slack には「照合失敗」として届きます。失敗と「問題なし」を混同しないことが大事です
おわりに
自動化を増やすほど、土台のツールの更新が「静かに壊れる」原因になります。当社では、新しい機能を探すより先に、今ある設定が効いているかを毎週確かめるようにしました。キーの照合は機械で行い、判断は人がする。この役割分担で、確認の結果が揺れなくなります。
settings.json や CLAUDE.md の設計、設定の分け方は、書籍『CLAUDE.md設計パターン』にまとめています。
書籍一覧: https://zenn.dev/joinclass?tab=books
社内で同じような仕組みを作りたいが手が回らない場合は、合同会社ジョインクラスで中小企業向けの業務システム開発・DX支援(国内)を受けています。
👉 業務システム・DXの無料相談