1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Claude Codeのアップデートで壊れた設定を見つける — changelogとsettings.jsonを突き合わせる確認スクリプト

1
Posted at

はじめに

当社(合同会社ジョインクラス)は社員のいない会社で、記事の公開・SNS配信・売上集計などを launchd のジョブから Claude Code を呼んで回しています。困るのは、Claude Code が自動で新しいバージョンになり、設定がいつの間にか効かなくなることです。エラーは出ず、hooks が動いていない、許可したはずのコマンドで止まる、といった形でしか気づけません。

僕は以前、macOS の cron がフルディスクアクセスの制限で全部止まっていたのに気づかず、launchd に移したことがあります。「黙って止まる」ものは、機械で確かめるしかありません。

この記事では、changelog と自分の settings.json を突き合わせて、影響がありそうな設定キーを書き出すスクリプトを作ります。自社で毎週動かしている、バージョンの変化を検知するシェルスクリプトに組み込む形です。

全体の流れ

  1. claude --version を前回の値と比べ、変わった週だけ処理する
  2. 前回から今回までの changelog の節を取り出す
  3. settings.json のキーを全部並べる(hooks.PreToolUse のような形にする)
  4. changelog の中で「deprecated / removed / renamed / breaking」を含む行と、キー名を照らし合わせる
  5. 当たった行を Slack に送り、記録ファイルに残す

LLM に「影響ある?」と聞くだけだと、毎回答えが揺れます。キーの照合は決まった手順のスクリプトでやり、LLM は当たった行の解説だけにしています。

1. 元にしたスクリプト(バージョンの変化の検知)

当社で毎週月曜 10:00 に launchd から動かしている auto-upgrade-check.sh の、バージョンを比べる部分です。

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 以上で動作します。

check-settings-vs-changelog.py
#!/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 の、バージョンを比べた直後に足します。

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の無料相談

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?