트러블슈팅

핵심 요약

• "스크립트를 실행할 수 없습니다" 오류는 실행 정책을 확인하고, 조직 정책이 허용하는 경우 현재 세션 범위에서 조정합니다.
• 명령을 못 찾을 때는 PowerShell 재시작 → 재부팅 → 수동 PATH 추가 순으로 시도하며, Git·Node.js·npm global의 기본 경로를 참고합니다.
• 포트 3000 충돌은 npx next dev -p 3001로 다른 포트를 쓰거나, netstat·taskkill로 점유 프로세스를 종료합니다.
• 브라우저 오류가 잘 전달되지 않으면 next.config.ts에 logging.browserToTerminal: 'warn'을 켜고 dev 서버를 재시작합니다.
• 응답이 멈추면 Ctrl + C 취소 후 claude --resume으로 세션을 이어받고, 검색이 느리면 시스템 ripgrep 설치나 claude doctor 점검을 활용합니다.

2026-10-23 설치 진단 순서

Get-Command claude, claude --version, claude doctor, Get-ExecutionPolicy -List로 증상을 구분합니다. native·npm 설치는 자동 업데이트를 지원하고 Homebrew·WinGet 등의 기본 갱신 방식과 다릅니다. 영구적인 CurrentUser 정책 변경을 먼저 적용하지 말고, 조직 정책·서명 오류·PATH·global 디렉터리 권한을 확인합니다.

Next.js 16.2에서 agent 파일이 자동 생성되지 않는 것은 16.3+의 관리 지침과 기능 차이입니다. Next.js AI 세팅 장의 버전 표를 확인하고 문서 연결 문제를 앱 의존성 전체 업그레이드로 해결하지 않습니다.

Claude Code setup · Next.js AI agents.

Windows 환경에서 자주 발생하는 문제와 해결 방법을 정리했습니다. 문제가 발생하면 아래에서 해당 증상을 찾아보세요.

PowerShell 관련

PATH 환경 변수

Claude Code 설치

Git Bash 관련

Node.js 관련

개발 서버

Claude Code 성능과 안정성

Windows Terminal

Windows Terminal은 Microsoft Store에서 업데이트합니다. Claude Code처럼 터미널 출력이 많은 도구를 쓴다면 최신 버전으로 유지하는 게 좋습니다.

확인 방법:

1. Microsoft Store를 엽니다
2. Windows Terminal을 검색합니다
3. 업데이트 버튼이 있으면 업데이트합니다

기타 문제

도움 요청

위 방법으로도 안 풀리면 아래 채널에서 도움을 요청하세요:

• Claude Code 공식 트러블슈팅 문서 — 공식 해결 가이드
• Claude Help Center — 계정, 결제, 구독 문제

---

참고 자료

1. Claude Code 트러블슈팅
2. PowerShell 실행 정책
3. PowerShell Set-ExecutionPolicy
4. Git for Windows
5. Node.js 다운로드
6. VS Code 터미널 셸 통합
7. Windows 환경 변수
8. Next.js 16.2: AI Improvements
9. Next.js MCP Server
10. Next.js logging 설정
11. Claude Code setup