Claude Code 업데이트 내역: 내 버전 이후 변경 찾기와 롤백

Claude Code에서 바뀐 모든 내용은 공식 changelog에 버전별로 실립니다. 이 페이지는 GitHub 저장소의 CHANGELOG.md에서 만들어지며 영어로만 제공됩니다. 한국어로 읽을 수 있는 공식 기록은 주간 요약인 새로운 기능입니다. 다만 이 요약은 눈에 띄는 기능만 고르고, 버그 수정과 작은 개선은 changelog에만 남깁니다.

2026년 9월 23일 기준 latest 버전은 2.1.280(9월 22일)이고, stable은 2.1.267(9월 9일)입니다. 지금 쓰는 버전은 claude --version으로 확인합니다. 그 버전 이후 바뀐 항목만 필요하다면 아래의 "내 버전 이후 바뀐 항목만 뽑기" 명령을 쓰면 됩니다. 업데이트 뒤 무언가 깨졌다면 수정 버전이 이미 나왔는지 먼저 찾고, 아직 없으면 stable 채널로 옮기거나 문제 이전 버전을 설치한 뒤 자동 업데이트를 잠시 끕니다.

어떤 공식 기록이 어떤 질문에 답하나

기록마다 답하는 질문이 다릅니다. 필요한 답에 맞는 곳을 먼저 여는 편이 빠릅니다.

날짜를 맞춰 볼 때는 시간대에 주의해야 합니다. changelog는 시간대 없이 날짜만 적고, GitHub Releases는 UTC로 표시합니다. 예를 들어 2.1.280은 changelog에 9월 22일로 나오지만 GitHub 게시 시각은 2026-09-22T16:38:14Z, 한국 시간으로는 9월 23일 오전 1시 38분입니다. 한국에서 "어제 밤 업데이트"라고 느낀 변경이 changelog에서는 하루 앞 날짜에 있을 수 있습니다.

서드파티 정리 사이트는 최신성이 제각각입니다. 2026년 9월 23일 기준, 제목에 2026년이 들어간 claudefa.st의 changelog 정리 페이지는 2026년 5월까지의 기록을 다룬다고 밝히고 있었고 가장 최근 항목이 v2.1.128이었습니다. 버전 번호가 중요한 판단이라면 공식 changelog로 다시 확인합니다.

지금 쓰는 버전과 최신 버전 확인

설치된 버전은 터미널에서 확인합니다.

claude --version
# 2.1.275 (Claude Code)

세션 안이라면 /status가 버전, 모델, 계정, 연결 상태를 함께 보여 줍니다. 설치 상태를 더 자세히 보려면 터미널에서 claude doctor를 실행합니다. 읽기 전용 진단을 출력하고 마지막 자동 업데이트 시도 결과도 보여 줍니다. 세션 안의 /doctor는 여기에 더해 내 릴리스 채널에 더 새 버전이 있는지도 확인합니다(명령어 문서).

채널별 현재 버전은 npm 레지스트리에서 바로 볼 수 있습니다.

npm view @anthropic-ai/claude-code dist-tags

2026년 9월 23일에는 stable이 2.1.267, latest가 2.1.280이었습니다. 두 태그는 13일, 발행된 릴리스로는 12개 차이가 났습니다. 태그는 승격될 때마다 바뀌므로 판단 직전에 다시 실행합니다.

네이티브 설치기 쪽 값은 설치 스크립트가 읽는 주소로 확인할 수 있습니다.

curl -fsSL https://downloads.claude.ai/claude-code-releases/stable
# 2.1.267 (2026년 9월 23일 기준, 같은 경로의 /latest는 2.1.280)

2026년 9월 23일에는 이 두 주소가 npm 태그와 똑같이 2.1.267과 2.1.280을 돌려줬습니다. 그날은 npm과 네이티브 설치기의 stable이 같은 버전이었다는 뜻입니다. 다만 이 주소는 공식 설치 스크립트가 쓰는 것일 뿐 문서에 설명된 기능이 아니므로, 예고 없이 바뀔 수 있는 관측값으로 봐야 합니다.

버전 번호가 건너뛰어도 기록이 빠진 것은 아닙니다. 2.1.278 다음은 2.1.280이고, 2.1.279는 npm 레지스트리와 GitHub 릴리스 태그 모두에 존재하지 않습니다(2.1.262, 2.1.264도 마찬가지). 2.1.x 범위에서 changelog 항목이 없는 번호는 57개이며, 확인한 세 번호는 모두 발행되지 않은 번호였습니다.

업데이트 속도도 알아 둘 만합니다. 2026년 1월부터 9월 22일까지 changelog에 올라온 버전은 226개로, 매달 20~28개입니다. 버전 하나에 담긴 항목 수는 1개(2.1.270, 2.1.272, 2.1.276)부터 114개(2.1.280)까지 편차가 큽니다. 며칠만 업데이트를 미뤄도 읽을 항목이 수백 줄로 늘어나는 이유입니다.

내 버전 이후 바뀐 항목만 뽑기

changelog는 최신 버전이 위에 오고, 버전마다 ## 2.1.280 같은 제목으로 시작합니다. 그래서 파일을 위에서부터 읽다가 내 버전 제목에서 멈추면 "내 버전보다 새로운 변경"만 남습니다. macOS, Linux, WSL에서 다음처럼 실행합니다.

# 1. changelog 원본을 먼저 파일로 저장
curl -fsSL https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md -o CHANGELOG.md

# 2. 설치된 버전 번호만 꺼내기 ("2.1.275 (Claude Code)" → "2.1.275")
mine=$(claude --version | awk '{print $1}')

# 3. 내 버전 제목이 나오기 전까지만 출력
awk -v mine="$mine" '/^## /{ if ($2==mine) exit } {print}' CHANGELOG.md

2.1.275에서 실행하면 2.1.280, 2.1.278, 2.1.277, 2.1.276 네 버전의 제목과 204줄의 항목이 나옵니다(2026년 9월 23일 기준). 실행 전에 알아 둘 점이 세 가지 있습니다.

• curl의 출력을 awk에 바로 파이프로 넘기면 awk가 중간에 끝나면서 curl: (56) Failure writing output이 뜹니다. 파일로 먼저 저장하는 이유입니다.
• mine 값은 claude --version에 나오는 번호와 정확히 같아야 합니다. 번호가 틀리면 멈출 지점을 찾지 못해 파일 전체가 출력됩니다.
• 이 방식은 원본 파일의 제목 형식(## 2.1.x)에 기대고 있습니다. 형식이 바뀌면 패턴도 고쳐야 합니다.

항목이 많을 때는 새 기능과 동작 변경부터 봅니다. 각 줄은 대체로 Added, Changed, Fixed로 시작합니다.

awk -v mine="$mine" '/^## /{ if ($2==mine) exit } {print}' CHANGELOG.md | grep -E '^- (Added|Changed)'

2.1.275 기준으로는 204줄 중 22줄이 남습니다. 2.1.280의 "Pro와 Team Standard 요금제의 기본 모델을 Sonnet에서 Opus로 변경" 같은 항목은 비용과 사용량에 바로 영향을 주므로 이 단계에서 걸러 두는 것이 좋습니다. 모델과 가격 변화를 자세히 보려면 Claude Opus 5.5 출시: 가격을 계산하고 Opus 5에서 옮기는 법으로 이어서 읽을 수 있습니다.

Windows에서는 WSL 같은 환경에서 실행해야 합니다. 셸 없이 확인하려면 세션 안에서 /release-notes를 열고 버전을 하나씩 고르는 방법이 있습니다.

특정 동작이 언제 바뀌었는지 찾기

"어제부터 갑자기 이렇게 동작한다"는 상황이라면 키워드로 찾되, 각 줄이 어느 버전에 속하는지 함께 출력하는 편이 쓸모 있습니다.

awk -v kw="default model" '/^## /{v=$2} index(tolower($0), kw){print v": "$0}' CHANGELOG.md

kw는 소문자로 적습니다. 2026년 9월 23일 파일에서 위 명령은 이렇게 시작합니다.

2.1.280: - Changed the default model on Pro and Team Standard plans from Sonnet to Opus, ...
2.1.271: - Fixed `--resume` dropping the 1M context window (`[1m]`) when ...
2.1.268: - Fixed a running session silently switching to the organization's default model when ...

kw를 agents.md로 바꾸면 2.1.277에서 CLAUDE.md가 없는 프로젝트는 AGENTS.md를 읽도록 바뀌었다는 항목이 나옵니다. effort 설정이 갑자기 달라졌다면 effort로 찾아봅니다. 2.1.280부터는 /effort가 모델별 설정이 되기 전에 저장한 effort 수준이 Opus 5.5 같은 새 모델에는 적용되지 않고 기본값에서 시작합니다.

회귀(regression) 표기로 원인 버전 찾기

회귀는 이전 버전에서 되던 기능이 새 버전에서 깨지는 것을 말합니다. changelog에서 24개 항목이 "(regression in 2.1.x)" 형식으로 문제가 생긴 버전을 밝히고 있습니다. 예를 들면 다음과 같습니다.

• 2.1.269: WezTerm, kitty 계열 터미널의 키 입력 문제 수정. 원인 버전은 2.1.247
• 2.1.270: 세션이 오래 이어지면 읽기 전용 git 명령도 권한 확인을 요구하던 문제 수정. 원인 버전은 2.1.269
• 2.1.275: VS Code에서 실행 중인 세션 이름이 자동 생성 이름으로 되돌아가던 문제 수정. 원인 버전은 2.1.269

표기 형식은 "(2.1.275 regression)", "a regression introduced in 2.1.255", "regression in v2.1.147"처럼 조금씩 다릅니다. 그래서 문구보다 버전 번호로 찾는 편이 확실합니다.

awk -v kw="2.1.269" '/^## /{v=$2} index(tolower($0), kw){print v": "$0}' CHANGELOG.md

이 명령은 2.1.269 버전 제목과 함께, 2.1.269에서 생긴 문제를 고친 2.1.270과 2.1.275의 항목을 보여 줍니다. 수정 버전이 이미 있다면 롤백할 필요 없이 업데이트하면 됩니다. 다만 모든 회귀에 표기가 붙지는 않으므로, 표기가 없다고 해서 그 버전에 회귀가 없었다는 뜻은 아닙니다.

2026년에 동작이 크게 바뀐 버전

아래는 2026년 changelog에서 기본 모델, 실행 방식, 프로젝트 설정 읽기처럼 체감이 큰 변경만 고른 것입니다. 버그 수정은 빠져 있으므로 전체 목록은 changelog에서 확인합니다.

가격은 changelog에 적힌 금액이며, 모델을 실제로 쓸 수 있는지는 요금제와 제공업체에 따라 다릅니다. Fable 5.1의 API 가격과 변경점은 Claude Fable 5.1: API 가격·변경점·마이그레이션 가이드에 따로 정리돼 있습니다.

버전이 아니라 날짜로 적용된 변경도 있습니다. 8월 37일 주간 요약(v2.1.220v2.1.224)에 따르면 Pro, Max, Team 요금제의 새 세션은 8월 14일부터 auto mode가 기본 권한 모드가 됐습니다. 확인 창이 갑자기 줄었다면 이 변경일 수 있습니다. 어떤 권한 모드를 쓸지는 Claude Code Auto mode와 bypassPermissions: 확인 창보다 먼저 정할 권한 경계에서 다룹니다.

latest 유지, stable 전환, 하한 설정, 임시 롤백 중 고르기

릴리스 채널은 autoUpdatesChannel 설정으로 정하며, 자동 업데이트와 claude update 모두 이 채널을 따릅니다(설정 문서).

• "latest"(기본값): 새 버전이 나오자마자 받습니다.
• "stable": 보통 약 1주 전 버전을 쓰고, 큰 회귀가 있는 릴리스는 건너뜁니다. 2026년 9월 23일에는 latest와 13일 차이가 났으니 "1주"는 보장이 아니라 대략적인 기준입니다.

apt의 stable 저장소에 남은 버전 목록을 보면 stable이 실제로 어떻게 움직였는지 짐작할 수 있습니다. 목록은 2.1.236(8월 19일 릴리스) 다음이 바로 2.1.267(9월 9일 릴리스)이고, 그 사이에 나온 2.1.237~2.1.266은 하나도 없습니다. 그래서 macOS 12에서 실행되지 않던 2.1.257은 apt stable 사용자에게 가지 않았습니다(이 문제는 2.1.258에서 수정). 날짜는 승격일이 아니라 릴리스일이고, 네이티브 설치기의 stable도 같은 순서를 거쳤다는 것은 추정입니다. 이 구간에서는 다음 stable까지 21일이 걸렸습니다.

상황별로는 다음처럼 고릅니다.

minimumVersion은 버전을 고정하는 설정이 아닙니다. 자동 업데이트와 claude update가 그보다 낮은 버전을 설치하지 않도록 막는 하한일 뿐이고, 더 높은 버전으로 올라가는 것은 막지 않습니다. 반대로 관리형 설정의 requiredMinimumVersion과 requiredMaximumVersion은 범위를 벗어난 버전이면 Claude Code가 아예 시작되지 않게 하며, 업데이트도 최대 버전을 넘지 않습니다(버전 하한 문서).

{
  "autoUpdatesChannel": "stable",
  "minimumVersion": "2.1.267"
}

latest에서 stable로 바꿀 때 /config는 현재 버전에 머무를지, 다운그레이드를 허용할지 묻습니다. 머무르기를 고르면 위처럼 minimumVersion이 현재 버전으로 설정되고, 나중에 latest로 돌아가면 이 값은 지워집니다. 회귀를 피하려고 stable로 옮기는 경우라면 다운그레이드를 허용해야 실제로 이전 버전으로 내려갑니다. 이때 stable 버전이 문제가 생긴 버전보다 앞선 번호인지도 확인합니다. 2026년 9월 23일의 stable 2.1.267은 2.1.269보다 앞서지만, 승격 시점에 따라 달라집니다.

임시 롤백 순서

1. 앞의 방법으로 changelog에서 증상과 버전 번호를 찾아, 수정 버전이 이미 나왔는지 확인합니다. 나왔다면 롤백 대신 업데이트합니다.
2. 수정 버전이 없다면 문제가 시작된 버전 바로 전 버전을 설치합니다. 예를 들어 2.1.269에서 생긴 문제라면 2.1.268입니다. 네이티브 설치라면 문서에 있는 claude install 2.1.268을 쓸 수 있고, 다른 설치 방식의 명령은 아래 설치 방식별 표에 있습니다.
3. settings.json의 env에 DISABLE_AUTOUPDATER를 넣어 백그라운드 업데이트를 멈춥니다.

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

1. claude --version으로 버전을, claude doctor의 Auto-updates 줄이 disabled (set by env: DISABLE_AUTOUPDATER)인지 확인합니다.
2. changelog에 수정 항목이 올라오면 설정을 지우고 claude update를 실행합니다.

3단계를 빼면 롤백이 오래가지 않습니다. 공식 문서에는 이 동작이 적혀 있지 않지만, GitHub 이슈 #91309의 사용자 보고가 이를 보여 줍니다. 2026년 9월 백그라운드 자동 업데이트로 macOS 12 기기가 실행되지 않는 2.1.257로 올라가자, 사용자들은 bash -s 2.1.252로 되돌리면서 DISABLE_AUTOUPDATER도 함께 설정했습니다. 그러지 않으면 다음 백그라운드 업데이트가 깨진 빌드를 조용히 다시 설치한다는 이유였고, 2.1.258에서 수정된 뒤 두 설정을 모두 지웠습니다. 보고자와 추가 확인자 두 명이 같은 OS에서 겪은 사례이므로 모든 환경에서 같다고 보장할 수는 없지만, 롤백할 때는 자동 업데이트도 함께 꺼 두는 편이 안전합니다. 또 Claude 데스크톱 앱에 들어 있는 Claude Code는 별도 경로로 설치·업데이트되므로, 이 롤백과 DISABLE_AUTOUPDATER는 단독 설치한 CLI에만 적용된다는 보고도 있습니다(이슈 #92401). DISABLE_AUTOUPDATER는 백그라운드 확인만 멈추므로 claude update와 claude install은 계속 작동합니다. 수동 업데이트까지 모두 막아야 한다면(자체 채널로 Claude Code를 배포하는 조직 등) DISABLE_UPDATES를 씁니다(자동 업데이트 끄기 문서).

설치 방식별 업데이트와 롤백 명령

같은 "업데이트"라도 설치 방식에 따라 자동으로 되는지, 어떤 명령을 쓰는지가 다릅니다. 어떤 방식으로 설치했는지 모르겠다면 claude doctor로 설치 상태부터 확인합니다.

네이티브 설치에서는 이미 설치된 CLI로 버전을 바꿀 수 있습니다. claude install은 2.1.118 같은 버전 번호나 stable, latest를 받아 네이티브 바이너리를 설치하거나 다시 설치합니다(CLI 참조).

claude install 2.1.268

설치 스크립트로 채널이나 특정 버전을 지정하는 방법도 있습니다(특정 버전 설치 문서).

# macOS, Linux, WSL: stable 채널
curl -fsSL https://claude.ai/install.sh | bash -s stable

# macOS, Linux, WSL: 특정 버전
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.268

# Windows PowerShell: 특정 버전 (stable 채널은 버전 대신 stable)
& ([scriptblock]::Create((irm https://claude.ai/install.ps1 ))) 2.1.268

REM Windows CMD: 특정 버전
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 2.1.268 && del install.cmd

설치할 때 고른 채널이 이후 자동 업데이트의 기본값이 됩니다. 설치 후 claude --version이 2.1.268 (Claude Code)처럼 지정한 번호를 출력하면 성공입니다.

설치 방식별로 걸리기 쉬운 부분은 다음과 같습니다.

• claude update는 설치를 마치면 Successfully updated from <이전 버전> to version <새 버전>을, 이미 최신이면 Claude Code is up to date (<버전>)를 출력합니다. Homebrew, WinGet, apk 설치에서는 Claude is up to date!가 나옵니다.
• npm에서는 npm update -g를 쓰지 않습니다. 처음 설치할 때의 semver 범위를 따르기 때문에 최신 릴리스로 올라가지 않을 수 있습니다. 특정 버전 지정(@2.1.267)은 npm의 표준 문법입니다. 2.1.198부터 Node.js 22 이상이 필요하며, 그보다 낮은 Node.js에서는 EBADENGINE 경고가 나오지만 설치는 끝나고 실행도 됩니다.
• Homebrew와 WinGet은 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE를 1로 두면 Claude Code가 새 버전이 나왔을 때 업그레이드 명령을 대신 실행하고 재시작을 안내합니다. WinGet은 Claude Code가 실행 중이면 파일이 잠겨 실패할 수 있고, 그때는 수동 명령을 보여 줍니다. Homebrew는 이전 버전을 디스크에 남기므로 가끔 brew cleanup을 실행합니다.
• 패키지 관리자 설치에서는 새 버전이 저장소에 올라오기 전에 Claude Code가 업데이트 알림을 먼저 띄울 수 있습니다. 업그레이드가 실패하면 잠시 뒤 다시 시도합니다.

패키지 관리자에서 이전 버전 설치

Claude Code 문서는 패키지 관리자로 특정 번호를 설치하는 방법을 다루지 않습니다. 아래는 2026년 9월 23일에 각 저장소가 실제로 어떤 버전을 제공했는지와 각 패키지 관리자의 표준 문법입니다. Anthropic이 안내한 절차가 아니고, 해당 OS에서 직접 실행해 본 명령도 아닙니다.

• Homebrew: cask는 claude-code(2.1.267)와 claude-code@latest(2.1.280) 두 개뿐입니다(claude-code, claude-code@latest). 임의의 번호로 되돌리는 cask는 없으므로, 선택지는 stable cask로 옮기는 것입니다.
• WinGet: Anthropic.ClaudeCode 패키지의 매니페스트에 2.1.252, 2.1.267, 2.1.268 같은 과거 버전이 남아 있습니다. 가장 새 매니페스트는 2.1.268이어서 그날 WinGet은 stable(2.1.267)과도 latest(2.1.280)와도 달랐습니다. 매니페스트는 자동화 도구가 만들기 때문에 새 버전이 올라오는 시점은 Claude Code 릴리스와 어긋날 수 있습니다.

winget install Anthropic.ClaudeCode --version 2.1.267

• apt, dnf, apk: 저장소가 이전 빌드를 남겨 둡니다. apt stable 저장소에는 2.1.108부터 2.1.267까지 54개 버전이, apt latest 저장소에는 2.1.280까지 134개 버전이 있었습니다. 버전 문자열은 apt가 2.1.267-1, apk가 2.1.267-r1 형식입니다.

# apt: 설치 후 시스템 업그레이드 때 함께 올라가지 않도록 고정
sudo apt install claude-code=2.1.267-1
sudo apt-mark hold claude-code

# dnf
sudo dnf install claude-code-2.1.267

# apk
apk add claude-code=2.1.267-r1

apt에서 고정을 풀 때는 수정 버전이 나온 뒤 sudo apt-mark unhold claude-code를 실행합니다.

자주 묻는 질문

한국어로 된 버전별 changelog가 있나요?

2026년 9월 23일 기준으로 버전별 changelog는 영어로만 제공됩니다. 한국어로 읽을 수 있는 공식 기록은 주간 새로운 기능 요약이며, 주마다 해당 버전 범위가 붙어 있어 내 버전이 어느 주에 해당하는지 맞춰 볼 수 있습니다. 모든 수정 사항이 필요하면 영어 changelog를 봐야 합니다.

/release-notes를 열면 대화 컨텍스트나 토큰을 차지하나요?

현재 문서 기준으로는 차지하지 않습니다. /release-notes는 버전 선택기를 열고 노트를 화면의 대화 기록에만 표시하며, Claude가 보는 대화에는 넣지 않습니다. 예전 빌드에는 "전체 보기"가 changelog를 컨텍스트에 넣던 버그가 있었고 changelog에서 수정된 것으로 나와 있으니, 오래된 버전을 쓰고 있다면 먼저 업데이트합니다.

업데이트 알림은 떴는데 brew upgrade 후에도 버전이 그대로인 이유는?

Homebrew나 WinGet, Linux 패키지 저장소에 새 버전이 올라오기 전에 Claude Code가 먼저 알림을 띄우는 것은 알려진 문제입니다. 잠시 뒤 다시 시도합니다. claude-code cask는 stable 채널을 따르므로, latest 버전을 기대했다면 claude-code@latest cask를 쓰고 있는지도 확인합니다.