# ❓ 자주 묻는 질문 (FAQ) & 해결 가이드
> 2026.01.14 AI워크스페이스 1주차 줌 스터디 세션 피드백 기반
수강생분들이 가장 많이 겪으신 기술적 문제와 해결책을 정리했습니다. 실습 중 막히는 부분이 있다면 이 문서를 먼저 확인해주세요.
---
## 🛠️ 1. VS Code 설치 및 기본 설정
### Q. VS Code를 설치했는데 파일이 안 열려요 / 화면이 달라요.
**A. "폴더 열기(Open Folder)"로 시작해야 합니다.**
많은 분들이 단순히 파일을 더블 클릭하거나 `Open File`로 텍스트 파일 하나만 여시는 경우가 많습니다. 우리는 **프로젝트 전체**를 관리해야 하므로 반드시 폴더를 열어야 합니다.
1. VS Code 실행
2. 상단 메뉴 **File > Open Folder...** (맥: Cmd+O, 윈도우: Ctrl+O)
3. 다운로드 받은 실습 자료 폴더(전체)를 선택
### Q. 맥(Mac)과 윈도우(Windows) 화면이 달라요. (확장 프로그램이 안 보여요)
**A. 사이드바(Side Bar) 위치와 아이콘이 다를 수 있습니다.**
- **확장 프로그램(Extension) 메뉴**: 왼쪽 사이드바에 '테트리스 블록' 모양 아이콘입니다. 안 보인다면 `Ctrl+Shift+X` (윈도우) / `Cmd+Shift+X` (맥) 단축키를 눌러보세요.
- **터미널 열기**: 상단 메뉴 **Terminal > New Terminal** 또는 `(Ctrl + shift+ `) `.
---
## 🤖 2. Claude Code & AI 도구 사용
### Q. 터미널이 그냥 검은 화면이고 로그인을 어떻게 하는지 모르겠어요.
**A. 명령어 입력을 통해 로그인을 트리거해야 합니다.**
Claude Code나 관련 CLI 도구는 검은 터미널 창에서 명령어를 쳐야 반응합니다.
1. 터미널에 `claude` 입력 후 엔터.
2. 화면에 나오는 인증 URL을 클릭하여 열리는 브라우저창에서 로그인 버튼을 클릭하거나 웹주소창에 URL을 복사해서 로그인 버튼 클릭.
3. "Login Successful" 메시지가 나오면 성공입니다.
### Q. "Command not found" 또는 "No matching commands" 에러가 떠요.
**A. 설치가 안 되었거나 환경 변수(Path) 문제일 수 있습니다.**
1. **설치 확인**: 터미널에 `claude --version` 입력. 버전이 안 뜨면 설치가 안 된 것입니다.
2. **터미널 재시작**: 설치 직후라면 VS Code를 껐다 켜거나 새 터미널을 열어야 명령어가 인식됩니다.
3. **경로 확인**: 현재 작업 폴더가 올바른지 확인하세요 (`pwd` 또는 `dir` 명령어로 확인).
### Q. 401 API Error가 발생해요.
**저희 대부분은 클로드코드 PRO 요금제를 가입했기 때문에 위 로그인 방식을 따르면 됩니다.**
**A. API선택을 하시는 분은 API 키 설정이나 결제 정보 문제입니다.**
- **원인 1**: API Key가 환경 변수에 제대로 설정되지 않음. `.env` 파일을 확인하세요.
- **원인 2**: Anthropic Console(또는 OpenAI)에 결제 카드 등록이 안 되어 있거나 잔액이 부족함(선불충전).
- **해결**:
1. [Anthropic Console](https://console.anthropic.com/) 접속 -> Settings -> Billing 확인.
2. 새로운 API Key를 발급받아 다시 로그인 시도 (`claude logout` -> `claude login`).
---
## 📂 3. 지식 관리 (Johnny Decimal)
### Q. 폴더 번호가 꽉 차면(10개 이상) 어떡하나요?
**A. 유연한 넘버링을 사용하세요.**
- `10~19` 대분류 안에서 `11`, `12`... 로 확장합니다.
- 한 폴더 안에 파일이 너무 많다면 `11.01`, `11.02` 처럼 소수점을 쓰거나 `11_01_` 처럼 하위 뎁스를 하나 더 만드셔도 됩니다.
- 100단위 하위 폴더로 사용하는것도 방법입니다.
- **핵심**: 번호는 '찾기 쉽게 하기 위함'이지 절대적인 규칙에 얽매일 필요는 없습니다.
### Q. 기존 자료가 업데이트되면 어떻게 관리하나요? (중복 파일)
**A. "Source of Truth(유일한 진실)" 원칙을 지키세요.**
- AI에게 "기존 문서 A와 새로운 내용 B를 병합해서 문서 A를 업데이트해줘"라고 요청하세요.
- 파일이 여러 개 생기는 순간 관리는 실패합니다. 파일 하나를 계속 고쳐 쓰는 것이 좋습니다.
- 물론 목적에 따라 이것도 정답은 아닙니다. 협업시 파일 버전을 관리하듯 AI도 수정하면서 내용을 없애기도하고 추가하기도 하기 때문에 별도의 파일로 버전관리 할 수도 있습니다.
---
## 🔌 4. VS Code Claude 확장 프로그램 설치
### Q. "git-bash를 찾을 수 없습니다" 오류가 떠요.
**A. Git for Windows가 설치되어 있지 않거나 PATH에 등록되지 않은 경우입니다.**
Claude Code는 Windows에서 bash 명령을 실행하기 위해 git-bash가 필요합니다.
**해결 방법 (3가지 중 택1):**
**옵션 1: Git for Windows 설치 (권장)**
1. https://git-scm.com/download/win 에서 다운로드
2. VS Code 재시작 후 확인:
```powershell
bash --version
git --version
```
**옵션 2: 환경변수 영구 설정 (PowerShell 관리자 권한)**
```powershell
[System.Environment]::SetEnvironmentVariable('CLAUDE_CODE_GIT_BASH_PATH', 'C:\Program Files\Git\bin\bash.exe', 'User')
```
설정 후 VS Code 재시작 필요
**옵션 3: 시스템 PATH에 직접 추가**
- 시스템 환경변수 PATH에 `C:\Program Files\Git\bin` 추가
> ⚠️ **참고**: VS Code 확장 프로그램 일부 버전에서 환경변수를 인식하지 못하는 버그가 보고되고 있습니다. 이 경우 터미널에서 직접 `claude` 명령어로 실행하면 정상 작동합니다.
### Q. OAuth 인증 화면이 안 뜨거나 연결이 안 돼요.
**A. 인증 절차를 순서대로 따라주세요.**
1. VS Code에서 Claude 확장 프로그램 설치
2. 인증 방식 선택: "Claude.ai Subscription" (Pro 가입자)
3. "Code에서 외부 웹 사이트를 여시겠습니까?" → 허용
4. 브라우저에서 '승인' 클릭
5. "You're all set up!" 메시지 확인되면 완료
---
> **💡 팁**: 문제가 생기면 에러 메시지를 그대로 복사해서 주고 AI(ChatGPT, Claude, Antigravity, Cursor, Gemini 등)에게 "이 에러가 왜 나는 거야?"라고 물어보세요. 가장 빠르고 정확한 튜터가 되어줍니다!
1주차: 첫 스터디에서 클로드 코드 설치시 자주 묻는 질문 (FAQ)
2
