막혔을 때

증상

PowerShell에서 claude를 입력하면 claude : The term 'claude' is not recognized as the name of a cmdlet, function, script file, or operable program.이라는 빨간 글씨가 나옵니다. CMD(명령 프롬프트)에서는 'claude' is not recognized as an internal or external command가 나옵니다. 한국어 Windows에서는 같은 뜻의 한글 문장이 나올 수 있습니다.

원인

Claude Code는 설치되었지만, 설치된 폴더(보통 C:\Users\[내 사용자 이름]\.local\bin)가 Windows의 PATH(프로그램을 찾아다니는 폴더 목록)에 아직 없거나, 설치하기 전에 열어 둔 터미널 창이 그 변경을 모르는 경우입니다. 열려 있던 창은 PATH의 변경을 바로 알지 못합니다.

해결 방법

1. 열려 있는 PowerShell 창을 모두 닫습니다. Win+X를 누르고 Windows PowerShell(또는 Terminal)을 골라 새 창을 엽니다.
2. claude --version을 입력합니다. 2.1.211 (Claude Code)처럼 숫자와 "(Claude Code)"가 나오면 성공입니다. 숫자는 설치 시점에 따라 다릅니다.
3. 여전히 안 되면 설치 파일이 실제로 있는지 확인합니다. 아래 첫 줄에서 True가 나오면 파일은 있는 것입니다.
4. 파일은 있는데 두 번째 줄에서 아무것도 안 나오면 PATH에 폴더가 빠진 것입니다. 세 번째 묶음 두 줄로 "내 계정의" PATH에 폴더를 추가하고, PowerShell 창을 닫았다 다시 열어 claude --version을 확인합니다.
5. 첫 줄에서 False가 나오면 설치가 끝나지 않은 것이므로, 설치 명령 irm https://claude.ai/install.ps1 | iex를 PowerShell에서 한 번 더 실행합니다.

# 1) 설치 파일이 있나? (True면 있음)
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

# 2) PATH에 폴더가 들어 있나? (아무것도 안 나오면 없음)
$env:PATH -split ';' | Select-String '\.local\\bin'

# 3) 없다면 내 계정의 PATH에 추가 (한 줄씩 입력, 끝나면 새 창 열기)
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

직접 입력이 부담스럽다면 Claude 데스크톱 앱의 Code 탭에서 Claude에게 맡길 수 있습니다. 이 방법은 설치 단계에서 이미 배운 "PATH로 잡아 달라고 부탁하기"와 같습니다.

내 Windows PC의 PowerShell에서 claude 명령이 "not recognized"라고 나와요.
1) %USERPROFILE%\.local\bin\claude.exe 파일이 실제로 있는지 확인해 주세요.
2) 내 "사용자" PATH에 %USERPROFILE%\.local\bin 폴더가 들어 있는지 확인해 주세요.
3) 없다면 "사용자" PATH에만 추가해 주세요. 시스템 전체 설정은 바꾸지 마세요. 바꾸기 전에 현재 PATH 값을 보여 주고 제 확인을 받아 주세요.
4) 끝나면 새 PowerShell 창에서 claude --version 이 되는지 확인하는 방법을 알려 주세요.

증상

다음 중 하나가 보입니다. 'irm' is not recognized as an internal or external command, The token '&&' is not a valid statement separator, A parameter cannot be found that matches parameter name 'fsSL', 'bash' is not recognized as the name of a cmdlet. 또는 설치는 안 되고 긴 글자(스크립트 내용)만 줄줄이 출력됩니다.

원인

Windows에는 비슷하게 생긴 창이 두 가지(PowerShell, CMD)가 있고 설치 명령이 서로 다릅니다. 또는 macOS/Linux용 명령을 붙여넣었거나, 명령의 앞부분만 복사해서 실행한 경우입니다.

해결 방법

1. 창의 맨 앞 글자를 봅니다. PS C:\Users\...>처럼 PS로 시작하면 PowerShell이고, PS 없이 C:\Users\...>로 시작하면 CMD입니다.
2. PowerShell이라면 아래 PowerShell용 명령 한 줄을 통째로 붙여넣습니다. | iex까지 있어야 설치가 실행됩니다.
3. CMD라면 CMD용 명령을 통째로 붙여넣습니다. 가장 쉬운 방법은 PowerShell을 새로 여는 것입니다. Win+X를 누르고 Windows PowerShell을 고릅니다.
4. 성공하면 "Claude Code successfully installed!" 같은 완료 문구가 나옵니다. 그다음 새 창에서 claude --version으로 확인합니다.

irm https://claude.ai/install.ps1 | iex

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

증상

npx, npm, claude 같은 명령을 PowerShell에서 실행하면 File C:\Program Files\nodejs\npx.ps1 cannot be loaded because running scripts is disabled on this system.이라는 빨간 글씨와 PSSecurityException이 나옵니다. 8장 hyperframes의 npx hyperframes ...를 실행할 때 특히 자주 만납니다.

원인

PowerShell의 "실행 정책(Execution Policy)"이 .ps1 스크립트 파일 실행을 막고 있습니다. npm, npx는 이런 스크립트 파일을 통해 실행되기 때문입니다. 참고로 irm https://claude.ai/install.ps1 | iex 설치 명령은 이 정책의 영향을 받지 않습니다.

해결 방법

1. 먼저 지금 적용되는 정책을 확인합니다. 첫 번째 명령의 결과가 Restricted(또는 AllSigned)이면 막혀 있는 것입니다. 두 번째 명령의 표에서 MachinePolicy나 UserPolicy에 값이 있으면 회사가 정한 정책이므로 3번으로 갑니다.
2. 내 계정에만 "내 PC에서 만든 스크립트는 허용"하도록 바꿉니다. 확인 질문이 나오면 Y를 입력하고 Enter를 누릅니다. 그다음 새 PowerShell 창에서 다시 실행합니다.
3. 회사 정책이어서 바꿀 수 없다면(바꿔도 "overridden by a policy"라는 안내가 나옵니다), 같은 일을 하는 .cmd 버전으로 실행하는 방법이 있습니다. 예를 들어 npx 대신 npx.cmd를 입력합니다. 그래도 안 되면 사내 IT 담당자에게 문의하세요.

# 1) 지금 적용되는 정책 확인 (두 번째 줄은 범위별 상세)
Get-ExecutionPolicy
Get-ExecutionPolicy -List

# 2) 내 계정에만 허용 (확인 질문에 Y)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 3) 바꿀 수 없을 때의 대안: .cmd 로 실행
npx.cmd hyperframes --help

증상

winget : The term 'winget' is not recognized as the name of a cmdlet, function, script file, or operable program. 또는 CMD에서 'winget' is not recognized as an internal or external command가 나옵니다.

원인

winget(Windows 패키지 관리자)은 Windows의 "앱 설치 관리자(App Installer)"에 들어 있는 프로그램입니다. 이 구성 요소가 없거나 오래되었거나, Windows에 처음 로그인한 직후라 등록이 덜 끝났거나, 회사 PC가 Microsoft Store를 막아 둔 경우입니다. Windows 10 버전 1809 이상이어야 합니다.

해결 방법

1. 새 PowerShell 창에서 winget --version을 입력합니다. v1.로 시작하는 번호가 나오면 이미 쓸 수 있는 것입니다.
2. 안 나오면 시작 메뉴에서 "Microsoft Store"를 열고 앱 설치 관리자(App Installer)를 검색해 설치하거나 업데이트합니다.
3. Windows에 처음 로그인한 직후라면 아래 한 줄로 등록을 요청한 뒤 새 창에서 다시 확인합니다.
4. 회사 PC라서 Store를 쓸 수 없으면 사내 IT 담당자에게 문의하세요.

Add-AppxPackage -RegisterByFamilyName -MainPackage Microsoft.DesktopAppInstaller_8wekyb3d8bbwe

증상

git : The term 'git' is not recognized as the name of a cmdlet, function, script file, or operable program., CMD의 'git' is not recognized as an internal or external command, 또는 플러그인을 설치할 때 Failed to clone marketplace repository: Command 'git' not found or is in an unsafe location이 나옵니다.

원인

Git(코드의 변경 기록을 관리하는 프로그램)이 설치되지 않았거나, 설치했어도 열어 둔 터미널 창이 아직 모르는 경우입니다. 이 교육에서는 3장에서 GitHub에 올릴 때 Git이 필요합니다.

해결 방법

1. 가장 쉬운 방법은 Claude에게 부탁하는 것입니다(아래 프롬프트). 직접 하려면 브라우저에서 git-scm.com/downloads/win을 열어 설치 파일을 내려받아 실행하고, 모든 화면에서 기본값 그대로 Next를 누릅니다. 중간에 "Adjusting your PATH environment" 화면이 나오면 추천 옵션이 선택된 상태로 둡니다.
2. winget이 있다면 PowerShell에서 winget install --id Git.Git -e로도 설치할 수 있습니다.
3. 설치가 끝나면 모든 터미널을 닫고 새 창을 엽니다. git --version을 입력해 git version 2.xx.x.windows.x 같은 줄이 나오면 성공입니다.
4. Claude Code를 켰을 때 Claude Code on Windows requires either Git for Windows (for bash) or PowerShell이 나온다면, Git Bash와 PowerShell을 둘 다 찾지 못했다는 뜻입니다. Claude Code는 Git 없이 PowerShell만으로도 실행되므로 보통은 PowerShell 위치(C:\Windows\System32\WindowsPowerShell\v1.0\)가 PATH에서 빠진 경우이고, Git for Windows를 설치해도 해결됩니다. Git을 설치했는데도 Git Bash를 못 찾는다고 하면 Claude에게 where.exe git 결과를 보여 주고 설정을 부탁하세요. 회사 PC에서 막히면 사내 IT 담당자에게 문의하세요.

내 Windows PC에 Git이 설치되어 있는지 확인해 주세요. 설치되어 있다면 버전을 알려 주세요.
설치되어 있지 않다면 winget으로 설치할 수 있는지 먼저 확인하고, 설치 명령과 이유를 알려 준 뒤 제 확인을 받고 진행해 주세요. 설치가 끝나면 새 터미널에서 git --version 이 되는지 확인하는 방법도 알려 주세요.

증상

다음과 같은 메시지가 나옵니다. Failed to fetch version from downloads.claude.ai(PowerShell 설치에서는 Failed to get latest version), Could not create SSL/TLS secure channel, curl: (35) TLS connect error, unable to get local issuer certificate, SELF_SIGNED_CERT_IN_CHAIN, curl: (22) The requested URL returned error: 403. 설치 파일을 받았는데 보안 프로그램이 실행을 막거나, 앱 화면이 하얗게 뜨는 경우도 같은 원인일 수 있습니다.

원인

회사의 방화벽, 프록시, 암호화 통신 검사 장비, 백신/보안 에이전트가 외부 주소 접속이나 새 프로그램 실행을 막고 있습니다. 이것은 내 설정 실수가 아니라 "회사가 정한 규칙"인 경우가 많아서, 내가 고치는 것이 아니라 사내 IT 담당자와 풀어야 합니다.

해결 방법

1. 먼저 접속이 되는지 확인합니다. 아래 첫 명령을 실행해서 맨 첫 줄에 HTTP/1.1 200 OK가 나오면 접속은 됩니다. 아무 글자도 안 나오거나 Could not resolve host, 시간 초과가 나오면 막혀 있는 것이고, 403이면 필터링 장비가 막았거나 지원하지 않는 지역일 수 있습니다.
2. Windows에서 SSL/TLS secure channel 오류가 나면 아래 두 번째 묶음처럼 TLS 1.2를 켠 뒤 설치 명령을 다시 실행해 보세요.
3. 그래도 안 되면 아래 표의 주소를 사내 IT 담당자에게 전달해 허용을 요청하세요. 회사가 프록시를 쓰는 경우 프록시 주소와 인증서 파일(CA)을 IT 담당자에게 받아야 합니다.
4. IT 담당자가 허용해 주면, 새 PowerShell 창에서 다시 시도합니다.

# 1) 설치 서버에 접속되는지 확인 (curl.exe 라고 정확히 입력)
curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest

# 2) TLS 오류가 날 때 (두 줄을 차례로)
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

위 주소는 Claude Code 공식 문서의 "Network access requirements"를 기준으로 정리했습니다. 이 외에 Vercel(vercel.com)과 GitHub 웹 화면도 브라우저에서 열려야 합니다. 사내 정책에 따라 필요한 주소가 달라질 수 있으니 IT 담당자의 안내를 우선하세요.

사내 IT 담당자에게 보낼 요청 메일 초안을 정중하게 써 주세요.
- 목적: 사내 AI 활용 교육 실습을 위해 Claude Code와 GitHub, Vercel을 사용해야 함
- 상황: [예: Claude Code 설치 중 downloads.claude.ai 접속이 막혀 있음]
- 화면에 나온 메시지: [메시지 전체]
- 요청: 아래 주소의 접속 허용 여부 확인
  downloads.claude.ai, claude.ai, claude.com, platform.claude.com, api.anthropic.com, github.com, registry.npmjs.org
- 보낸 사람: [내 이름], [부서]
회사 내부 정보나 개인정보는 넣지 말고, 읽는 사람이 바로 판단할 수 있게 짧게 써 주세요.

증상

Claude 데스크톱 앱에서 Code 탭을 눌렀더니 업그레이드 안내가 나옵니다. 또는 Error 403: Forbidden, API Error: 403 Request not allowed, OAuth error: Invalid code. Please make sure the full code was copied, Not logged in(이어서 /login을 입력하라는 안내), Claude Code access has not been granted for this account. Contact your administrator.가 나옵니다. 로그인 창이 열리지 않기도 합니다.

원인

Claude Code는 유료 구독(Pro, Max, Team, Enterprise) 또는 Console 계정이 있어야 쓸 수 있고, 무료 플랜에는 포함되지 않습니다. 그 밖에 로그인 코드가 오래되어 만료되었거나, 복사하다 잘렸거나, 회사(Enterprise) 조직에서 내 역할에 Claude Code 권한이 없거나, 프록시가 통신을 막는 경우가 있습니다.

해결 방법

1. 내 계정의 플랜을 확인합니다. 무료 플랜이면 Code 탭을 쓸 수 없으니 교육 담당자에게 사용 가능한 계정 안내를 받으세요. Pro나 Max라면 claude.ai/settings에서 구독이 활성 상태인지도 확인합니다. 플랜 종류와 가격은 자주 바뀌므로 공식 요금 안내 페이지(claude.com/pricing)에서 확인하세요.
2. 데스크톱 앱이라면 앱 메뉴에서 로그아웃한 뒤 다시 로그인합니다. 그래도 같으면 창만 닫지 말고 앱을 완전히 종료합니다. Ctrl+Shift+Esc로 작업 관리자를 열어 Claude 프로세스를 끝낸 뒤 다시 실행합니다.
3. 터미널이라면 Claude 화면에서 /logout을 입력하고, 창을 닫은 뒤 claude를 다시 실행해 로그인합니다. 브라우저가 자동으로 열리지 않으면 터미널에서 c를 눌러 주소를 복사하고 브라우저에 붙여넣으세요.
4. 브라우저에서 로그인이 끝나면 터미널로 돌아와 빨리 이어 갑니다. 코드는 오래 지나면 만료되므로 천천히 하다 만료되었다면 3번을 다시 합니다.
5. 회사 Enterprise 계정에서 access has not been granted 메시지가 나오면 내가 바꿀 수 있는 것이 아닙니다. 조직 소유자(Owner)에게 "Claude Code를 쓸 수 있는 역할로 바꿔 달라"고 요청하세요.

증상

You've hit your session limit, You've hit your weekly limit, You've hit your Opus limit(또는 Sonnet), You've hit your monthly spend limit처럼 "한도(limit)에 도달했다"는 문장이 나옵니다. 뒤에 resets 3:45pm처럼 다시 쓸 수 있게 되는 시각이 함께 표시되는 경우가 많습니다.

원인

구독 플랜에는 일정 시간 동안 쓸 수 있는 양(세션 한도)과 일주일 동안 쓸 수 있는 양(주간 한도)이 있고, 이를 다 썼다는 뜻입니다. 대화가 길거나, 큰 파일과 이미지를 계속 붙이거나, 같은 수정을 여러 번 반복하면 사용량이 빨리 줄어듭니다.

해결 방법

1. 메시지에 적힌 시각까지 기다립니다. 시각이 지나면 다시 쓸 수 있습니다.
2. Claude 화면에서 /usage를 입력하면 남은 사용량과 초기화 시각을 볼 수 있습니다. 데스크톱 앱에서는 모델 선택 상자 옆의 사용량 링(원형 표시)을 누르면 보입니다.
3. "Opus limit"처럼 특정 모델의 한도라면 /model로 다른 모델 계열로 바꿔서 이어갈 수 있습니다.
4. /usage-credits를 입력하면 추가 사용량(usage credits) 설정 화면이 열립니다. 추가 비용이 드는 선택이므로 본인이 직접 판단하세요. Team이나 Enterprise 플랜에서 결제 권한이 없으면 같은 명령이 관리자에게 요청을 보내 줍니다.
5. 데스크톱 앱의 세션 한도 안내 카드에는 한도가 풀리면 자동으로 이어서 진행하는 체크 상자("Auto-continue when limits reset")가 있습니다. 주간 한도 카드에는 이 옵션이 없습니다. 화면 문구는 업데이트로 조금 다를 수 있습니다.

증상

앱을 열었는데 화면이 비어 있거나 멈춰 있습니다. 또는 Failed to load session, Git is required, Git LFS is required by this repository but is not installed가 나옵니다.

원인

앱 업데이트가 덜 끝났거나, 선택한 폴더가 이동하거나 지워졌거나, 폴더 접근 권한이 없는 경우입니다. 회사 방화벽이 앱이 쓰는 화면 자료 서버를 막으면 로그인은 되는데 화면만 하얗게 뜨기도 합니다. Git이 필요한 작업인데 Git이 없을 때도 위 메시지가 나옵니다.

해결 방법

1. 앱을 완전히 종료했다가 다시 실행합니다. 앱은 시작할 때 자동으로 업데이트를 확인하므로 한 번 더 열어 보세요.
2. Failed to load session이면 다른 폴더를 선택해 보고, 원래 폴더가 지금도 있는지 탐색기에서 확인합니다.
3. Git is required가 나오면 이 장의 Git 항목을 따라 Git for Windows를 설치한 뒤 앱을 다시 엽니다.
4. 그래도 하얀 화면이면 사내 네트워크 문제일 수 있습니다. 데스크톱 앱은 claude.ai 말고도 화면 자료를 내려받는 별도 주소(assets-proxy.anthropic.com 등)를 쓰는데, 이 주소가 막히면 로그인은 되어도 화면만 하얗게 뜹니다. 이 주소를 사내 IT 담당자에게 알려 허용을 요청하세요.

증상

API Error: 500 Internal server error, API Error: Repeated 529 Overloaded errors, Request timed out, 또는 답변이 한창 나오다가 The response above may be incomplete가 표시됩니다.

원인

내 잘못이 아니라 Claude 서비스가 잠시 바쁘거나 오류가 있는 경우, 또는 내 인터넷이 순간적으로 끊긴 경우입니다. 대부분 잠시 후 저절로 풀립니다.

해결 방법

1. 1~2분 기다린 뒤 같은 요청을 다시 보냅니다. 내가 보낸 메시지는 대화에 그대로 남아 있습니다.
2. 답변이 중간에 끊겼다면 continue(이어서 해 줘)라고 입력하면 이어서 진행합니다.
3. 계속 반복되면 브라우저에서 status.claude.com을 열어 서비스 장애 공지가 있는지 확인합니다.
4. 모델별로 혼잡도가 다르므로 /model로 다른 모델을 골라 다시 시도해 볼 수 있습니다.
5. 인터넷이 불안정하다면 Wi-Fi 연결을 확인하세요.

증상

gh : The term 'gh' is not recognized as the name of a cmdlet, function, script file, or operable program.가 나옵니다.

원인

GitHub CLI(gh, 터미널에서 GitHub 로그인과 저장소 만들기를 도와주는 프로그램)가 설치되지 않았거나, 설치 후 새 터미널을 열지 않은 경우입니다.

해결 방법

1. 모든 터미널을 닫고 새 PowerShell 창에서 gh --version을 다시 입력합니다. gh version 2.xx.x가 나오면 성공입니다.
2. 그래도 없으면 설치합니다. winget이 있으면 아래 명령으로, 없으면 cli.github.com에서 Windows 설치 파일을 내려받아 실행합니다. 회사 PC에서 설치가 막히면 사내 IT 담당자에게 문의하세요.
3. 설치 후 반드시 새 터미널을 열어 gh --version으로 확인하고, 이어서 gh auth login으로 로그인합니다(다음 항목).

winget install --id GitHub.cli

증상

터미널에 "일회용 코드(one-time code)"가 XXXX-XXXX 모양으로 나오고, 브라우저의 github.com/login/device 페이지에 코드를 넣었는데 "코드가 올바르지 않다/만료되었다"고 하거나, 터미널이 로그인 완료를 알려 주지 않고 멈춰 있거나, 오류로 끝납니다. 허락 화면에서 Cancel을 눌렀다면 로그인이 취소됩니다.

원인

이 코드는 한 번의 로그인에만 쓰이고 15분이 지나면 만료됩니다. 이전 시도에서 받은 옛 코드를 입력했거나, 브라우저에 다른 GitHub 계정으로 로그인되어 있거나, 승인 단계에서 취소했거나, 회사 네트워크가 github.com 접속을 막은 경우입니다.

해결 방법

1. 터미널에서 Ctrl+C를 눌러 멈추고, 다시 gh auth login을 입력해 새 코드를 받습니다. 코드는 실행할 때마다 바뀝니다.
2. 선택지는 이렇게 고릅니다(화면 문구는 gh 버전에 따라 조금 다를 수 있습니다). 계정은 GitHub.com, Git 작업 방식은 HTTPS, "GitHub 인증 정보로 Git을 인증하시겠습니까"에는 Yes, 인증 방법은 Login with a web browser입니다. 방향키로 고르고 Enter를 누릅니다.
3. First copy your one-time code 줄의 코드를 눈으로 정확히 확인하고 Enter를 누르면 브라우저가 열립니다. 열리지 않으면 github.com/login/device를 직접 입력해 엽니다.
4. 코드를 입력하고, 오른쪽 위 계정이 "내 GitHub 계정"인지 확인한 뒤, 허락 화면에서 Authorize(승인)를 누릅니다. 계정이 다르면 로그아웃하고 맞는 계정으로 로그인한 뒤 1번부터 다시 합니다.
5. 터미널에 로그인 완료 문구가 나오면 아래 명령으로 확인합니다. Logged in to github.com account [내 사용자 이름] 줄이 보이면 성공입니다.

# 로그인 시작 (실패하면 Ctrl+C 후 다시)
gh auth login

# 로그인 상태 확인
gh auth status

gh auth login 이 실패했어요. gh auth status 를 실행해서 지금 어떤 GitHub 계정으로 로그인되어 있는지 알려 주세요. 로그인이 안 되어 있다면 제가 직접 입력해야 하는 단계(브라우저에서 코드 입력, 승인)를 한 단계씩 안내해 주세요. 토큰이나 비밀번호는 절대 화면에 출력하지 말고, 저에게 요구하지도 마세요.

증상

remote: Permission to [소유자]/[저장소].git denied to [다른 사용자 이름]. 뒤에 fatal: unable to access 'https://github.com/...': The requested URL returned error: 403가 나옵니다. 또는 remote: Repository not found., fatal: repository 'https://github.com/...' not found가 나옵니다.

원인

가장 흔한 원인은 "로그인된 GitHub 계정이 그 저장소의 주인(또는 쓰기 권한자)이 아닌 경우"입니다. 회사 계정과 개인 계정을 둘 다 쓰면 자주 생깁니다. 저장소 주소의 오타나 이름 불일치도 같은 메시지로 나옵니다. GitHub는 권한이 없는 비공개 저장소를 "없다(not found)"고 알려 주기도 합니다.

해결 방법

1. gh auth status를 실행해 지금 로그인된 계정(Active account)이 내가 만든 저장소의 주인 계정인지 확인합니다.
2. git remote -v를 실행해 올릴 주소를 확인합니다. https://github.com/[내 사용자 이름]/[저장소 이름].git에서 내 사용자 이름과 저장소 이름이 GitHub 웹 화면의 주소와 같은지 비교합니다.
3. 주소가 틀렸다면 아래처럼 고칩니다. 계정이 틀렸다면 gh auth login으로 맞는 계정에 로그인합니다.
4. gh auth setup-git를 한 번 실행하면 Git이 gh의 로그인 정보를 사용하도록 연결됩니다.
5. 예전 계정 정보가 Windows에 남아 계속 그 계정으로 시도된다면, 작업 표시줄 검색에서 "자격 증명 관리자(Credential Manager)"를 열고 Windows 자격 증명 목록의 git:https://github.com 항목을 삭제한 뒤 다시 push합니다. 삭제해도 내 GitHub 계정에는 영향이 없고, 다음 push 때 다시 로그인하게 됩니다.

gh auth status
git remote -v

# 주소가 틀렸을 때만 (대괄호 부분을 내 값으로)
git remote set-url origin https://github.com/[내 사용자 이름]/[저장소 이름].git

# Git이 gh 로그인 정보를 쓰도록 연결
gh auth setup-git

증상

push 명령 뒤에 다음 중 하나가 나옵니다. fatal: 'origin' does not appear to be a git repository, fatal: No configured push destination, error: src refspec main does not match any, ! [rejected] main -> main (non-fast-forward), fatal: refusing to merge unrelated histories.

원인

메시지마다 뜻이 다릅니다. 아래 "해결 방법"에 각각 풀어 두었습니다. 공통점은 "내 PC의 저장소와 GitHub의 저장소를 이어 주는 이름(원격 이름, 보통 origin)이나 브랜치 이름(보통 main)이 맞지 않는 것"입니다.

해결 방법

• 'origin' 또는 No configured push destination: 내 PC 저장소에 GitHub 주소가 아직 연결되지 않았습니다. git remote -v를 입력했을 때 아무것도 안 나오면 연결이 없는 것입니다. 아래 git remote add 명령으로 연결합니다.
• src refspec main does not match any: 올릴 "main"이라는 이름의 기록이 없다는 뜻입니다. 아직 커밋(저장)을 하나도 하지 않았거나, 브랜치 이름이 main이 아닙니다(예: master). git branch --show-current로 현재 브랜치 이름을, git log --oneline -3으로 커밋이 있는지 확인합니다. 커밋이 없으면 Claude에게 "변경 사항을 커밋해 줘"라고 부탁하세요.
• non-fast-forward: GitHub에는 내 PC에 없는 기록이 이미 있다는 뜻입니다. 저장소를 GitHub에서 만들 때 README 파일을 자동으로 만들었다면 이런 일이 생깁니다. git pull origin main으로 먼저 GitHub의 기록을 가져와 합친 뒤 다시 push합니다.
• refusing to merge unrelated histories: 서로 처음부터 다른 기록이라 합칠 수 없다는 뜻입니다. 이 경우는 Claude에게 상황을 설명하고 안전한 방법을 골라 달라고 부탁하세요.

# 연결 상태 확인 (아무것도 안 나오면 연결 없음)
git remote -v

# GitHub 주소 연결 (대괄호 부분을 내 값으로)
git remote add origin https://github.com/[내 사용자 이름]/[저장소 이름].git

# 현재 브랜치 이름과 커밋 확인
git branch --show-current
git log --oneline -3

# GitHub의 새 기록을 가져와 합치기 (non-fast-forward일 때)
git pull origin main

git push 가 거절됐어요. 메시지는 이렇습니다: [에러 메시지 전체]
git remote -v, git branch --show-current, git status, git log --oneline -5 를 실행해서 원인을 쉬운 말로 설명해 주세요.
고치는 방법은 2가지 이내로 제안하고, 어떤 방법이 안전한지 이유와 함께 알려 주세요. 제 확인 없이 push 를 다시 실행하거나 기록을 덮어쓰는 명령은 실행하지 마세요.

증상

Author identity unknown, *** Please tell me who you are., fatal: unable to auto-detect email address가 나오면서 커밋이 되지 않습니다.

원인

Git은 모든 커밋에 "누가 저장했는지"(이름과 이메일)를 적는데, 이 PC에 아직 그 정보를 설정하지 않았기 때문입니다.

해결 방법

1. 아래 두 줄을 PowerShell에 입력합니다. 이름은 닉네임이어도 되고, 이메일은 3장에서 확인해 둔 GitHub의 noreply 주소를 쓰는 것을 권장합니다. 큰따옴표는 그대로 둡니다.
2. 설정 확인은 git config --global user.name과 git config --global user.email을 입력하면 방금 넣은 값이 그대로 나옵니다.
3. 다시 커밋하면 됩니다. 이미 만든 커밋의 이름은 바뀌지 않고, 앞으로의 커밋부터 적용됩니다.

git config --global user.name "[내 이름 또는 닉네임]"
git config --global user.email "[숫자]+[내 사용자 이름]@users.noreply.github.com"

# 확인
git config --global user.name
git config --global user.email

git 커밋을 하려는데 "Author identity unknown" 오류가 나요.
현재 git config --global user.name 과 user.email 이 설정되어 있는지 먼저 확인해 주세요. 설정되어 있지 않으면 아래 값으로 설정해 주세요.
- 이름: [내 이름 또는 닉네임]
- 이메일: [내 GitHub noreply 주소]
회사 이메일은 쓰지 마세요. 설정한 뒤에 확인한 결과를 보여 주세요.

증상

Vercel 대시보드에서 Add New, Project(또는 New Project 버튼)로 들어간 Import 화면의 저장소 목록에 방금 만든 저장소가 없습니다. 검색해도 나오지 않습니다.

원인

Vercel이 내 GitHub에서 볼 수 있는 저장소는 내가 허락한 범위까지입니다. 허락할 때 "Only select repositories"(선택한 저장소만)를 골랐다면 그 뒤에 만든 새 저장소는 목록에 없습니다. 또 개인 저장소는 내가 소유자여야 하고, 조직 저장소는 조직의 소유자이거나 저장소 접근 권한이 있는 구성원이어야 합니다.

해결 방법

1. Import 화면에서 Configure GitHub App(이름은 조금 다를 수 있음) 링크를 누릅니다. GitHub 화면으로 이동합니다.
2. Repository access에서 "Only select repositories"가 골라져 있다면 Select repositories를 눌러 내 새 저장소를 추가하고 Save를 누릅니다. 간단히 모든 저장소를 허용해도 됩니다.
3. Vercel Import 화면으로 돌아와 새로고침(F5)하고 저장소를 다시 검색합니다.
4. 조직(회사) 저장소라면 조직의 소유자에게 권한을 확인해야 하며, 교육 실습에는 개인 GitHub 계정의 저장소를 쓰는 것이 가장 쉽습니다.

증상

Deployments 목록에 빨간 Error 상태가 뜨고, 배포 상세 화면의 Build Logs 마지막에 Error: Command "npm run build" exited with 1이나 No Output Directory named "dist" found after the Build completed 같은 줄이 보입니다. 사이트 주소를 열어도 새 화면이 아닙니다.

원인

이 교육에서 만드는 사이트는 HTML, CSS, JavaScript만으로 만든 "정적 사이트"라서 별도의 빌드(조립) 과정이 필요 없습니다. 그런데 Vercel이 프로젝트를 잘못 판단해 빌드 명령을 실행하려 하면 실패합니다.

해결 방법

1. Vercel 대시보드에서 해당 프로젝트를 열고 Settings, Build and Deployment로 갑니다.
2. Framework Preset을 Other로 고릅니다.
3. Build Command의 Override 스위치를 켜고, 입력 칸은 비워 둡니다. 빈 칸이 "빌드를 하지 않고 파일을 그대로 올린다"는 뜻입니다.
4. Output Directory에 이름이 적혀 있다면(예: dist) 비워 두거나, 해당 폴더가 실제로 있는지 확인합니다. 프리셋이 Other이고 public 폴더가 없으면 프로젝트 맨 위 폴더가 그대로 쓰입니다.
5. 맨 아래 Save를 누릅니다. 설정은 다음 배포부터 적용되므로 Deployments에서 실패한 배포의 오른쪽 점 세 개(...) 메뉴를 열어 Redeploy를 누릅니다.
6. 상태가 Building에서 Ready로 바뀌면 성공입니다. 또 실패하면 배포 상세의 Build Logs 마지막 20줄 정도를 복사해 Claude에게 보여 주세요.

Vercel 배포가 Error로 실패했어요. 이 사이트는 HTML, CSS, JavaScript만 쓰는 정적 사이트이고 빌드 과정은 필요 없습니다.
Build Logs의 마지막 부분은 이렇습니다:
[Build Logs 마지막 20줄 붙여넣기]

1) 프로젝트 폴더에 package.json이나 vercel.json 같은, Vercel이 빌드가 필요하다고 오해할 만한 파일이 있는지 읽어서 확인해 주세요.
2) 원인을 쉬운 말로 설명하고, Vercel 대시보드에서 제가 직접 눌러야 할 설정(Framework Preset을 Other로, Build Command 비우기)이 있다면 단계별로 알려 주세요.
3) 파일을 바꿔야 한다면 바꾸기 전에 무엇을 바꿀지 먼저 말해 주세요.

증상

내 Vercel 주소를 열면 흰 화면 가운데에 404: NOT_FOUND와 함께 Code: NOT_FOUND, ID: ...가 나옵니다. 배포 상태는 Ready인데도 이렇습니다.

원인

Vercel이 첫 화면으로 보여 줄 index.html을 찾지 못한 경우가 가장 흔합니다. 보통 이런 이유입니다. (1) index.html이 저장소의 맨 위가 아니라 하위 폴더(예: my-site/) 안에 있습니다. (2) 파일 이름이 Index.html처럼 대문자로 시작합니다. (3) 주소에 오타가 있거나 삭제된 배포의 주소입니다.

해결 방법

1. 주소창의 주소에 오타가 없는지, 뒤에 이상한 경로(/abc)가 붙지 않았는지 확인하고 맨 앞 주소만 다시 열어 봅니다.
2. GitHub의 내 저장소 첫 화면을 열어, 파일 목록 맨 위에 index.html이 있는지 봅니다. 폴더 안에 들어 있고 맨 위에 없다면 2번 이유입니다.
3. 방법 A: index.html을 저장소 맨 위로 옮기고 커밋과 push를 합니다(Claude에게 부탁하면 됩니다). 방법 B: Vercel에서 Settings, Build and Deployment의 Root Directory에 그 폴더 이름을 적고 Save를 누른 뒤 Redeploy합니다. Root Directory는 다음 배포부터 적용됩니다.
4. 파일 이름은 반드시 소문자 index.html이어야 합니다. 대문자가 섞였다면 이름을 고쳐 push합니다.
5. Vercel의 Deployments에서 해당 배포를 눌러 상세 화면을 열면, Resources 항목에서 실제로 올라간 파일(Static Assets) 목록을 볼 수 있습니다. 거기에 index.html이 폴더 없이 바로 보이는지 확인하세요. 화면 구성은 업데이트로 조금 다를 수 있습니다.

Vercel에 배포했는데 내 사이트 주소에서 "404: NOT_FOUND"가 나와요.
이 프로젝트 폴더에서 index.html 이 어디에 있는지, 파일 이름이 정확히 소문자 index.html 인지 확인해 주세요. 맨 위 폴더에 없다면 Vercel의 Root Directory 설정으로 풀지, 파일을 옮겨서 풀지 두 방법의 장단점을 쉬운 말로 알려 주고, 제가 고른 방법으로만 진행해 주세요. 파일을 옮기면 HTML 안의 경로(css, js, 이미지)가 깨지지 않는지도 확인해 주세요.

증상

Claude에게 화면을 고치게 했고 push까지 했는데, 내 사이트 주소를 열면 수정 전 모습이 보입니다.

원인

원인은 크게 네 가지입니다. (1) 브라우저가 예전 파일을 저장해 둔 것(캐시). (2) push가 되지 않아 GitHub에 새 내용이 없음. (3) Vercel 배포가 아직 Building 중이거나 Error로 실패해서 예전 배포가 그대로 서비스되고 있음. (4) 새 내용을 production 브랜치가 아닌 다른 브랜치에 올려 Preview 배포만 만들어짐.

해결 방법

1. 강제 새로고침부터 합니다. Windows에서는 Ctrl+F5(또는 Ctrl+Shift+R), Mac에서는 Cmd+Shift+R입니다. 시크릿(InPrivate) 창이나 스마트폰에서 열어 보는 것도 좋은 확인 방법입니다.
2. GitHub의 내 저장소 첫 화면에서 가장 최근 커밋의 시간과 이름이 방금 한 수정과 맞는지 봅니다. 아니라면 push가 안 된 것이니 Claude에게 "변경 사항을 커밋하고 push해 줘"라고 부탁합니다.
3. Vercel 대시보드의 Deployments를 엽니다. 맨 위 배포의 상태가 Ready이고 Production 표시가 있어야 합니다. Building이면 1~2분 기다리고, Error이면 위 "빌드가 실패해요" 항목을 보세요.
4. 맨 위 배포가 Preview라면 production 브랜치(보통 main)가 아닌 곳에 올린 것입니다. git branch --show-current로 내 브랜치 이름을 확인하고, production 브랜치는 Settings, Environments에서 Production을 눌러 Branch Tracking에서 볼 수 있습니다.
5. 그래도 이상하면 Deployments에서 가장 최근 배포의 점 세 개(...) 메뉴로 Redeploy를 눌러 다시 배포합니다.

수정한 내용이 배포된 사이트에 반영되지 않아요. 아래를 읽기만 하는 명령으로 확인해 주세요.
- git status (저장하지 않은 변경이 남아 있는지)
- git branch --show-current (지금 어느 브랜치인지)
- git log --oneline -3 (최근 커밋)
- git status 의 "ahead of origin" 표시 (아직 push 안 된 커밋이 있는지)
결과를 보고 "아직 커밋 안 됨", "커밋했지만 push 안 됨", "push 됨, Vercel 쪽 확인 필요" 중 어디인지 알려 주세요. push가 필요하면 하기 전에 제 확인을 받아 주세요.

증상

내 PC에서 열면 이미지가 잘 보이는데, 배포한 사이트에서는 이미지 자리에 깨진 그림 아이콘이나 빈칸이 나옵니다. 브라우저에서 F12를 눌러 Console 탭을 보면 Failed to load resource: the server responded with a status of 404가 빨간 글씨로 나옵니다.

원인

내 PC(Windows)는 Photo.PNG와 photo.png를 같은 파일로 봅니다. 하지만 Vercel의 서버는 두 이름을 다른 파일로 봅니다(대소문자 구분). 그 밖에 흔한 이유는 다음과 같습니다. 파일 이름의 한글이나 공백, 이미지 경로가 C:\Users\...처럼 내 PC 안의 주소로 적힌 경우, 이미지 파일이 GitHub에 올라가지 않은 경우입니다.

해결 방법

1. GitHub의 내 저장소에서 이미지 폴더를 열어 이미지 파일이 실제로 올라가 있는지 봅니다. 없다면 커밋과 push가 빠진 것입니다.
2. HTML에 적힌 이미지 이름과 GitHub의 파일 이름이 대소문자까지 똑같은지 비교합니다. Hero.JPG와 hero.jpg는 다른 이름입니다.
3. 앞으로는 이미지 파일 이름을 소문자 영문, 숫자, 하이픈(-)만 쓰세요. 예: strawberry-hero.jpg. 공백과 한글은 피합니다.
4. HTML의 경로가 C:\, file:///로 시작하면 내 PC에서만 열리는 주소이므로, assets/img/strawberry-hero.jpg처럼 프로젝트 안의 상대 경로로 바꿔야 합니다.
5. 배포 주소 뒤에 이미지 경로를 직접 붙여 https://[내 사이트 주소]/assets/img/strawberry-hero.jpg를 열었을 때 이미지가 보이면 파일은 올바르게 올라간 것이고, 404가 나오면 이름이나 위치가 다른 것입니다.
6. Windows에서는 파일 이름의 대소문자만 바꾸면 Git이 변경으로 인식하지 못하는 일이 있습니다. 이름을 바꿀 때는 Claude에게 맡기세요.

배포한 사이트에서 이미지가 안 보여요. 내 PC에서는 보입니다.
1) 프로젝트 안의 이미지 파일 목록과, HTML과 CSS에서 이미지를 가리키는 경로를 모두 찾아 비교해 주세요.
2) 대소문자가 다른 것, 공백이나 한글이 들어간 파일 이름, C:\ 나 file:/// 로 시작하는 경로를 찾아 목록으로 보여 주세요.
3) 목록을 보여 준 뒤 제 확인을 받고, 파일 이름은 소문자 영문과 하이픈으로 바꾸고 HTML과 CSS의 경로도 같이 고쳐 주세요.
4) 고친 뒤 커밋하고 push 하기 전에 한 번 더 확인을 받아 주세요.

증상

동료나 내 스마트폰에서 Vercel 주소를 열었더니 사이트 대신 "Vercel에 로그인하라"는 화면이 나옵니다. 또는 접근 권한을 요청하라는 안내가 나옵니다. 내 PC에서는 로그인되어 있어서 정상으로 보입니다.

원인

Vercel에는 "배포 보호(Deployment Protection)"라는 기능이 있습니다. 보호 방식 중 Vercel Authentication이 켜져 있으면 해당 주소를 Vercel에 로그인하고 권한이 있는 사람만 볼 수 있습니다. 새 프로젝트에서는 미리보기(Preview) 배포와 배포마다 생기는 긴 주소가 보호 대상인 경우가 많습니다. 반면 프로젝트의 정식(Production) 주소(보통 프로젝트이름.vercel.app 형태)는 기본 설정에서 보호하지 않습니다. 설정에 따라 다를 수 있으니 아래에서 확인하세요.

해결 방법

1. Vercel 대시보드의 프로젝트 첫 화면(Overview)에서 Domains 아래의 정식 주소를 확인하고, 다른 사람에게는 그 주소를 알려 줍니다. 긴 해시가 들어간 주소(프로젝트-abc123-내이름.vercel.app)는 공유하지 않습니다.
2. 정식 주소에서도 로그인 화면이 나오면 Settings, Deployment Protection을 엽니다. 보호 범위가 All Deployments로 되어 있으면 정식 주소도 보호됩니다. 사이트를 누구나 볼 수 있게 하려는 경우에만 Standard Protection으로 바꾸거나 Vercel Authentication을 끄고 Save를 누릅니다.
3. 특정 사람 한두 명에게만 보여 주고 싶다면 보호를 끄지 말고, 브랜치 배포를 공유하는 Shareable Links 기능을 쓰거나 그 사람에게 Vercel 접근 권한을 주는 방법을 쓰세요.

증상

스마트폰에서 열면 PC 화면이 통째로 줄어들어 글자가 아주 작게 보입니다. 가로로 흔들리는 스크롤이 생기거나, 글자와 그림이 겹치거나, 버튼이 너무 작아 누르기 어렵습니다. 어떤 효과는 마우스를 올려야만 나타나서 폰에서는 안 보입니다.

원인

원인은 보통 다음과 같습니다. 화면 폭에 맞추라는 안내(viewport 메타 태그)가 HTML에 없음, 픽셀로 고정한 너비, 화면 높이 100vh 계산이 모바일 주소창 때문에 어긋남, 마우스 올리기(hover)에만 반응하는 효과입니다.

해결 방법

1. 내 PC에서 미리 확인하는 방법: 사이트를 연 브라우저(Chrome, Edge)에서 F12를 누른 뒤 Ctrl+Shift+M을 눌러 휴대폰 화면 모드로 바꿉니다. 화면 위쪽에서 기기 크기(예: 폭 375px)를 고를 수 있습니다.
2. 이상한 부분이 보이면 캡처하거나 어느 부분인지 설명해서 Claude에게 고쳐 달라고 합니다. 아래 프롬프트를 쓰세요.
3. 고친 뒤 배포하고, 실제 스마트폰에서도 한 번 엽니다. 이때 위의 "미리보기 주소에서 로그인 화면이 나와요" 항목처럼 보호 설정 때문에 폰에서 못 열 수 있으니 정식 주소를 쓰세요.

이 사이트를 스마트폰(화면 폭 360~430px)에서 볼 때 깨지는 부분을 점검하고 고쳐 주세요.
- HTML에 viewport 메타 태그가 있는지 확인해 주세요.
- 가로 스크롤이 생기는 원인(고정 너비, 너무 큰 이미지)을 찾아 주세요.
- 글자 크기와 버튼 크기를 손가락으로 누르기 편하게 맞춰 주세요.
- 마우스를 올려야만 보이는 효과는 터치(누르기)로도 보이게 해 주세요.
- 바꾼 내용은 어느 파일의 무엇을 바꿨는지 목록으로 알려 주세요.
데스크톱 화면의 디자인은 바뀌지 않게 해 주세요.

증상

페이지에 영상이 있는데 첫 화면(정지된 그림)이나 검은 화면으로 멈춰 있고, 재생 버튼을 눌러야 움직입니다. 특히 스마트폰에서 자주 생깁니다.

원인

브라우저는 소리가 나는 영상이 저절로 시작되는 것을 막습니다. 자동 재생은 "소리를 끈(muted) 영상"일 때만 허용됩니다. 아이폰 Safari는 추가로 playsinline이 있어야 영상이 화면 안에서 자동 재생됩니다. 또 영상 파일 경로나 이름이 틀려도 비슷하게 보입니다.

해결 방법

1. HTML의 video 태그에 autoplay muted loop playsinline이 모두 들어 있는지 확인합니다. 이 교육 사이트의 첫 화면 영상도 같은 속성으로 만들었습니다.
2. 영상 파일이 MP4 형식인지, 그리고 이름과 경로가 정확한지(대소문자까지) 확인합니다. 이름은 소문자 영문과 하이픈으로 만드세요.
3. Windows의 접근성 설정에서 "애니메이션 효과"를 끄면 이 사이트는 자동 재생을 멈추고 재생 버튼을 보여 줍니다. 설정 > 접근성 > 시각 효과에서 확인할 수 있습니다(메뉴 이름은 Windows 버전에 따라 다를 수 있습니다).
4. 스마트폰의 절전 모드나 데이터 절약 모드에서는 자동 재생이 막힐 수 있습니다. 이때는 영상에 controls 속성을 더해 사용자가 직접 재생 버튼을 누를 수 있게 해 두면 안전합니다.

<video src="/assets/video/intro.mp4" autoplay muted loop playsinline></video>

내 사이트의 영상이 자동으로 재생되지 않아요. 특히 스마트폰에서요.
video 태그에 autoplay, muted, loop, playsinline 속성이 모두 있는지 확인하고 빠진 것을 추가해 주세요. 영상 파일 이름과 경로(대소문자 포함)가 실제 파일과 일치하는지도 확인해 주세요. 자동 재생이 막히는 환경에서는 사용자가 재생 버튼을 누를 수 있게 controls 도 함께 넣는 방법을 제안해 주세요.

증상

브라우저에서 localhost:숫자 주소를 열면 "연결을 거부했습니다" 또는 This site can't be reached, ERR_CONNECTION_REFUSED가 나옵니다.

원인

localhost는 "내 PC 안에서만 열리는 주소"입니다. 이 주소는 미리보기용 프로그램(작은 서버)이 켜져 있는 동안에만 열립니다. 서버를 켠 터미널이나 세션을 닫았거나, 주소의 포트 번호(콜론 뒤의 숫자)가 달라졌을 때 이런 메시지가 나옵니다.

해결 방법

1. Claude에게 "미리보기 서버를 다시 켜 주고, 열어야 할 주소를 알려 줘"라고 부탁합니다.
2. 서버가 켜져 있는 동안에는 그 터미널 창이나 앱의 세션을 닫지 않습니다.
3. 주소의 숫자는 매번 다를 수 있으니 Claude가 알려 준 주소를 그대로 복사해 열어 보세요.
4. index.html 파일을 더블클릭해 열면 주소가 file:///C:/...로 시작합니다. 이것은 localhost 주소가 아니며, 일부 기능이 제한될 수 있습니다.

내 사이트의 로컬 미리보기가 열리지 않아요 (localhost 연결 거부). 미리보기 서버가 켜져 있는지 확인하고, 꺼져 있다면 다시 켜 주세요. 그리고 제가 브라우저에서 열어야 할 정확한 주소를 알려 주세요.

증상

부탁하지 않은 부분까지 바뀌었거나, 디자인이 오히려 나빠졌거나, 잘 되던 기능이 망가졌습니다.

원인

요청이 넓거나 모호해서 Claude가 의도와 다르게 해석한 경우가 대부분입니다. 잘못이 아니고 다시 되돌릴 수 있습니다. 중요한 것은 "되돌릴 방법"을 알고 있는 것입니다.

해결 방법

1. Claude Code의 되돌리기 기능(터미널의 claude 화면 기준): 입력창이 비어 있을 때 Esc를 두 번 누르거나 /rewind를 입력합니다. 이전에 보낸 메시지 목록이 나오면 돌아가고 싶은 시점을 고르고 Restore code(코드만 되돌리기)나 Restore code and conversation(코드와 대화 모두 되돌리기)을 선택합니다. 화면 문구는 업데이트로 조금 다를 수 있습니다. 데스크톱 앱에서 이 메뉴가 보이지 않으면 아래 Git 방법을 쓰세요.
2. 이 기능은 Claude의 "파일 편집"만 되돌립니다. Claude가 명령으로 파일을 지우거나 옮긴 것(삭제, 이동, 복사)은 되돌리지 못하고, 내가 직접 고친 것도 되돌리지 못합니다.
3. Git으로 되돌리기: 앞서 커밋(저장)해 둔 시점이 있다면 Git이 더 확실한 안전망입니다. Claude에게 아래 프롬프트로 부탁하세요.
4. 앞으로 예방하기: 큰 변경을 시키기 전에 "먼저 지금 상태를 커밋해 줘"라고 하세요. 그러면 언제든 그 시점으로 돌아올 수 있습니다. 수정은 "한 번에 한 가지"로 요청하세요.

방금 한 수정이 마음에 들지 않아서 되돌리고 싶어요. 아래 순서로 해 주세요.
1) git status 와 git diff 로 지금 무엇이 바뀌어 있는지 파일별로 쉬운 말로 요약해 주세요.
2) 되돌리는 방법을 2가지 정도 제안해 주세요. 되돌리면 사라지는 것이 무엇인지도 알려 주세요.
3) 되돌리기 전에 현재 변경을 나중에 다시 꺼낼 수 있게 보관해 주세요(git stash 등).
4) 제가 방법을 고르면 그때 진행해 주세요. git reset --hard 나 push --force 처럼 기록을 지우는 명령은 쓰지 마세요.
되돌린 뒤에는 이번에 원했던 것을 더 정확하게 요청하는 문장도 같이 제안해 주세요.

증상

앞에서 말한 지시를 잊어버리거나, 같은 실수를 반복하거나, 답이 점점 느려집니다. 또는 Prompt is too long, Context limit reached, Autocompact is thrashing 같은 메시지가 나옵니다.

원인

Claude가 한 번에 기억할 수 있는 양(컨텍스트)에는 한계가 있습니다. 대화가 길어지고 파일과 결과가 쌓이면 이 공간이 가득 차서, 앞부분이 요약되거나 흐려집니다. 사람이 아주 긴 회의록을 한 번에 기억하지 못하는 것과 같습니다.

해결 방법

1. 한 세션에는 한 가지 주제만 다루는 것이 가장 좋은 예방입니다. 하나가 끝나면 새 세션을 엽니다(데스크톱 앱은 사이드바의 새 세션, 터미널은 /clear).
2. /compact를 입력하면 지금까지의 대화를 짧게 요약해서 공간을 확보합니다. 다만 요약 과정에서 세부 지시가 빠질 수 있습니다.
3. 작업을 이어 가야 하는데 엉켰다면 인수인계 메모를 만든 뒤 새 세션에서 이어 가는 방법이 가장 확실합니다. 아래 첫 번째 프롬프트로 메모를 받고, 새 세션을 열어 두 번째 프롬프트로 시작하세요.
4. 창을 닫았더라도 대화는 사라지지 않습니다. 같은 폴더에서 claude --continue(가장 최근 대화 이어가기)나 claude --resume(목록에서 고르기)로 다시 열 수 있고, 대화 안에서는 /resume을 쓸 수 있습니다.

이 세션이 길어졌어요. 새 세션에서 이어서 작업할 수 있게 인수인계 메모를 만들어 주세요. 15줄 안쪽으로, 쉬운 말로 아래 항목을 정리해 주세요.
1) 만들고 있는 것 (주제, 주요 파일 이름)
2) 지금까지 끝낸 일
3) 지금 막혀 있는 일과 이미 시도해 본 것
4) 제가 정한 디자인 방향과 하지 않기로 한 것
5) 다음에 할 일 3가지
파일로 저장하지 말고 화면에 그대로 보여 주세요. 제가 복사해서 새 세션에 붙여넣겠습니다.

앞선 세션에서 이어서 작업하려고 합니다. 아래는 인수인계 메모입니다.

[여기에 메모를 붙여넣기]

먼저 현재 폴더의 파일과 git 상태를 읽어서 메모와 맞는지 확인하고, 이해한 내용을 5줄로 요약해 주세요. 제가 맞다고 확인하면 "다음에 할 일" 1번부터 시작해 주세요.

증상

작업 중 표시가 오래 돌고 있고 화면이 바뀌지 않습니다. 또는 같은 수정을 계속 시도하며 제자리를 맴돕니다.

원인

작업이 크거나, 인터넷이 느리거나, 요청이 모호해서 Claude가 방향을 못 잡는 경우입니다. 터미널 창이 일시적으로 응답하지 않는 경우도 있습니다.

해결 방법

1. 터미널에서는 Esc를 눌러 Claude를 멈춥니다. 데스크톱 앱에서는 정지 버튼을 누릅니다. 멈춘 뒤에 "방향을 바꿀게요. 이번에는 [원하는 것] 한 가지만 해 주세요"라고 입력합니다.
2. Esc로 안 멈추면 Ctrl+C를 누릅니다.
3. 그래도 반응이 없으면 터미널 창을 닫고, 같은 폴더에서 새 창을 열어 claude --resume을 입력합니다. 대화는 사라지지 않습니다.
4. 큰 작업은 쪼개서 요청하세요. 예를 들어 "사이트 전체를 예쁘게 해 줘" 대신 "첫 화면의 제목 글자만 크고 굵게 해 줘"로 시작합니다.

증상

스킬을 설치했는데 대화창에 /를 입력했을 때 /design-taste-frontend, /impeccable, /ui-ux-pro-max:ui-ux-pro-max, /hyperframes:hyperframes가 목록에 나오지 않습니다.

원인

가장 흔한 이유는 "설치하기 전에 시작한 세션을 그대로 쓰고 있는 것"입니다. 그 밖에 설치 명령이 중간에 실패했거나, 다른 프로그램(예: Codex)용으로 설치했거나, 목록에서 꺼져 있거나, 플러그인 스킬이라 플러그인이름:스킬이름 형태로 표시되는 경우가 있습니다.

해결 방법

1. 새 세션을 시작합니다. 데스크톱 앱은 새 세션을 만들고, 터미널은 /exit로 나갔다 claude를 다시 실행합니다. 플러그인으로 설치한 스킬은 대화 안에서 /reload-plugins를 입력해도 반영됩니다.
2. 대화창에 /skills를 입력하면 설치된 스킬 목록이 나옵니다. 이름을 입력해 걸러 볼 수 있고, 꺼져 있는(off) 스킬이 있으면 다시 켭니다.
3. 플러그인 설치 상태는 터미널에서 claude plugin list로 확인합니다. hyperframes가 Status 줄과 함께 보여야 합니다.
4. 스킬 파일이 실제로 있는지 아래 명령으로 확인합니다. 스킬은 .claude\skills나 .agents\skills 폴더 아래에 스킬 이름의 폴더로 설치됩니다.
5. npx skills add로 설치했는데 안 보인다면 설치 대상 에이전트를 잘못 골랐을 수 있습니다. Claude Code용인지(-a claude-code) 확인하고, 다시 설치할 때는 5장의 방법을 따르세요.
6. 세션을 연 뒤에 스킬 파일을 직접 넣거나 바꿨다면 /reload-skills를 입력해 다시 읽게 할 수 있습니다.

# 스킬 폴더 확인 (없는 폴더는 오류가 나도 괜찮습니다)
Get-ChildItem "$env:USERPROFILE\.claude\skills", "$env:USERPROFILE\.agents\skills" -ErrorAction SilentlyContinue

# 플러그인 설치 상태 확인
claude plugin list

제가 설치한 스킬이 / 목록에 안 보여요. 아래를 확인해 주세요.
1) 지금 이 세션에서 사용할 수 있는 스킬 목록에 design-taste-frontend, impeccable, ui-ux-pro-max, hyperframes 가 있는지
2) 내 PC의 .claude\skills 와 .agents\skills 폴더에 이 스킬들이 설치되어 있는지 (읽기만 하세요)
3) claude plugin list 의 결과
빠진 것이 있으면 어떤 방법으로 설치하면 되는지 알려 주고, 설치 전에 제 확인을 받아 주세요. 설치가 끝나면 새 세션을 시작해야 하는지도 알려 주세요.

증상

다음 중 하나가 나옵니다. PowerShell에서 The term '/plugin' is not recognized as the name of a cmdlet, 데스크톱 앱 Code 탭에서 /plugin isn't available in this environment, Marketplace "..." not found, Plugin "..." not found in marketplace "...", Failed to clone marketplace repository, Git clone timed out after 120s.

원인

같은 설치라도 입력하는 장소에 따라 명령 모양이 다릅니다. 터미널(PowerShell)에서는 claude plugin ..., Claude 대화창 안에서는 /plugin ...입니다. 데스크톱 앱 Code 탭은 /plugin 명령을 지원하지 않고 대신 버튼으로 설치합니다. 그 밖에 Git이 없거나, 마켓플레이스 이름 오타, 느린 네트워크가 원인입니다.

해결 방법

1. 입력하는 장소에 맞는 명령을 아래 표에서 골라 씁니다. 대화창 안의 명령은 먼저 claude를 실행해 대화 화면을 연 뒤 입력합니다.
2. 데스크톱 앱 Code 탭에서는 프롬프트 입력창 옆의 + 버튼, Plugins, Add plugin 순서로 플러그인 목록을 열어 고릅니다. 화면 문구는 업데이트로 조금 다를 수 있습니다.
3. Failed to clone marketplace repository가 나오면 Git이 없는 것이니 이 장의 Git 항목을 먼저 해결합니다. Git clone timed out은 인터넷이 느리거나 막힌 것이니 잠시 후 다시 시도하고, 계속되면 사내 네트워크 항목을 보세요.
4. not found in marketplace는 이름 오타일 가능성이 높으니, 대화창에서 /plugin을 입력해 Discover 탭에서 이름을 복사해 쓰세요.
5. 설치가 성공하면 터미널 명령은 Successfully installed plugin: hyperframes@hyperframes처럼, 대화창 안에서는 Installed hyperframes처럼 완료 문구가 나옵니다. 그 뒤 /reload-plugins를 입력하거나 새 세션을 시작합니다.

hyperframes와 디자인 스킬을 한꺼번에 설치하는 전체 과정은 5장과 8장에 있습니다.

증상

npx hyperframes render를 실행했는데 중간에 오류로 끝나거나 영상(MP4)이 만들어지지 않습니다. 메시지에 ffmpeg를 찾을 수 없다는 내용, Node 버전이 낮다는 내용, Chrome not found가 보이기도 합니다.

원인

hyperframes는 HTML 화면을 영상으로 바꾸는 도구라서, 내 PC에 Node.js 22 이상, FFmpeg(영상을 만드는 프로그램), 그리고 화면을 그려 줄 크롬(Chrome Headless Shell, 화면 없이 동작하는 크롬)이 있어야 합니다. 크롬은 hyperframes가 필요할 때 자동으로 내려받아 쓰는 것이 보통이지만, 이 중 하나가 없거나 오래되었거나 내려받기가 막히면 렌더가 실패합니다.

해결 방법

1. 가장 먼저 npx hyperframes doctor를 실행합니다. 실행 환경, 브라우저, FFmpeg 등 필요한 것이 갖춰졌는지 점검해 줍니다. 결과를 그대로 복사해 Claude에게 보여 주면 가장 빠릅니다.
2. node --version을 입력해 v22 이상인지 봅니다. 낮으면 Node.js를 새로 설치하거나 업데이트합니다(nodejs.org 또는 아래 winget 명령).
3. ffmpeg -version을 입력합니다. 없다는 메시지가 나오면 FFmpeg를 설치하고 새 터미널을 엽니다.
4. npx hyperframes lint로 화면 구성 파일에 문제가 없는지 검사합니다. 문제가 있으면 Claude에게 결과를 보여 주고 고쳐 달라고 하세요.
5. Chrome not found가 나오면 화면을 그려 줄 크롬이 아직 준비되지 않은 것입니다. 메시지에 안내된 npx hyperframes browser ensure를 실행하면 필요한 크롬을 찾거나 내려받습니다. 회사 네트워크 때문에 내려받기가 막히면 사내 IT 담당자에게 문의하세요. Docker를 쓸 수 있는 환경이라면 npx hyperframes render --docker도 대안이지만 사무용 PC에서는 보통 필요하지 않습니다.
6. npx 자체가 스크립트 실행 오류로 막히면 이 장의 "running scripts is disabled" 항목을 따릅니다. 처음 실행할 때는 필요한 파일을 내려받느라 시간이 걸릴 수 있습니다.

# 환경 점검 (가장 먼저)
npx hyperframes doctor

# 필요한 프로그램 확인
node --version
ffmpeg -version

# 없거나 낮을 때 (winget이 있다면, 설치 후 새 터미널)
winget install OpenJS.NodeJS.LTS
winget install ffmpeg

# 크롬이 없다는 메시지가 나올 때 (필요한 크롬을 찾거나 내려받음)
npx hyperframes browser ensure

# 화면 구성 파일 검사
npx hyperframes lint

hyperframes 렌더가 실패했어요. 메시지는 이렇습니다: [에러 메시지 전체]
1) npx hyperframes doctor, node --version, ffmpeg -version 을 실행해서 결과를 쉬운 말로 설명해 주세요. (읽기만 하는 명령입니다)
2) 부족한 것(Node.js 22 이상, FFmpeg, 브라우저)이 있다면 무엇을 어떻게 설치할지 알려 주고, 설치하기 전에 제 확인을 받아 주세요.
3) npx hyperframes lint 로 영상 구성 파일에 문제가 있는지도 확인해 주세요.
4) 모두 해결되면 같은 명령으로 렌더를 다시 시도해 주세요.