당사(주식회사 JoinClass)는 직원이 없는 회사이며, 기사 공개, SNS 배포, 매출 집계 등의 작업을 launchd의 job에서 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은 일치한 줄에 대한 설명만 담당하도록 했습니다.
당사에서 매주 월요일 10:00에 launchd로부터 실행되는 auto-upgrade-check.sh의 버전 비교 부분입니다.
#!/bin/bash
set -uo pipefail
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
...
이전까지는 이 코드 다음에 Claude Code에게 "새 기능을 조사해 줘"라고 요청하는 것만 했습니다. 새 기능은 찾을 수 있지만, 자신의 설정이 깨졌는지 여부는 알 수 없었습니다. 그래서 다음 대조 스크립트를 추가했습니다.
표준 라이브러리만으로 작동합니다. Python 3.9 이상에서 동작합니다.
""changelog의 '비권장・삭제・이름변경' 줄과 settings.json의 키를 대조한다.""
import json
...
핵심 포인트는 세 가지입니다.
추출하는 것은 이전부터 현재까지의 섹션만입니다. changelog 전체와 대조하면, 몇 년 전 변경 사항까지 매주 감지하게 됩니다 -
비교하는 것은 키의 끝부분만입니다(hooks.PreToolUse라면 PreToolUse). changelog는 키를 마지막 이름으로 작성하는 경우가 많기 때문입니다 -
일치하면 종료 코드 1을 반환합니다. 셸 측에서 분기 처리가 가능하도록 했습니다.
앞서 언급한 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)
...
cd "$PROJECT_ROOT"를 잊지 마십시오. launchd에서 실행할 경우 작업 디렉터리가 /가 되기 때문에, 프로젝트의 .claude/settings.json을 읽어오지 못합니다.
수동으로 이전 버전을 전달하고 의도적으로 범위를 넓히면 동작을 확인할 수 있습니다.
일치하는 경우 다음과 같이 출력됩니다(키와 줄은 당시 내용에 따라 달라집니다).
[.claude/settings.json] hooks.PreToolUse
→ - Hooks: ... PreToolUse ... renamed ...
exit: 1
설정 파일의 JSON이 손상되어 있어도 [손상된JSON]
이러한 방식으로 출력하도록 하고 있습니다. 수동으로 편집한 후 쉼표(,) 하나를 빠뜨려 모든 설정이 읽히지 않게 되는 것은 실제로 매우 흔하게 발생하는 실수입니다.
오탐지는 발생합니다. model이나 timeout과 같은 일반적인 단어는 관련 없는 줄에도 일치할 수 있습니다. 노이즈가 심한 키(key)는 IGNORE_KEYS에 추가해 주세요. 놓치는 것보다 너무 많이 보여서 사람이 검토하는 쪽을 선택하고 있습니다 -
changelog에 기록되지 않은 변경 사항은 포착할 수 없습니다. 이것은 '명시적으로 언급된 변경'만을 다루는 그물망입니다. 실제로 작동하는지 여부는 hooks를 하나 실제로 호출하는 테스트 작업을 별도로 배치하는 것이 더 확실합니다 -
자동으로 새 버전이 되는 시점과 주간 확인 주기는 어긋날 수 있습니다. 확인하기까지 며칠 동안은 알 수 없습니다. 급한 경우라면, 매일 실행되는 작업의 시작 부분에서 버전 비교만 실행하세요 -
GitHub의 raw URL은 가져오는 데 실패할 수 있습니다. 예외로 인해 종료되더라도 종료 코드가 0이 아니기 때문에 Slack에는 '대조 실패'로 도착합니다. 실패와 '문제 없음'을 혼동하지 않는 것이 중요합니다
자동화 수준이 높아질수록, 기반 도구의 업데이트가 '조용히 고장 날' 원인이 됩니다. 당사는 새로운 기능을 찾는 것보다 먼저 현재 설정이 유효한지를 매주 확인하도록 했습니다. 키 대조는 기계가 수행하고 판단은 사람이 합니다. 이 역할 분담을 통해 검증 결과가 흔들리지 않게 됩니다.
settings.json이나 CLAUDE.md의 설계, 그리고 설정 분리 방법은 서적 『CLAUDE.md 설계 패턴』에 정리되어 있습니다.
도서 목록: https://zenn.dev/joinclass?tab=books
사내에서 비슷한 시스템을 만들고 싶지만 시간이 부족하다면, 주식회사 Join Class에서 중소기업 대상 업무 시스템 개발 및 DX 지원(국내) 서비스를 제공하고 있습니다.
👉 업무 시스템・DX 무료 상담