# Claude Code 입문 공부 노트

채팅으로 코딩하다가 Claude Code로 넘어오면서 정리한 개념들. 비전문가 기준.

## 왜 Claude Code인가 (채팅과 뭐가 다른가)

일반 채팅에서 코딩하면 이런 한계가 있다:

- AI가 내 PC 파일을 직접 못 본다 → `type`으로 보여주고, 수정본 받아서 복붙하고, 결과 다시 알려주는 왕복이 필요하다.
- 대화가 길어지면 컨텍스트가 쌓이고, 결국 인수인계하면서 맥락이 날아간다.
- 매번 cmd에 명령어를 직접 친다.

Claude Code는 터미널에서 도는 AI 코딩 에이전트다. 핵심 차이는 **내 코드베이스를 직접 읽고, 파일을 직접 고치고, 명령을 직접 실행한다**는 것. 복붙 왕복이 사라진다.

## CLAUDE.md — 인수인계를 없애는 파일

프로젝트 폴더에 두는 규칙 파일. Claude Code가 **세션 시작할 때마다 자동으로 읽는다.**

여기에 내 작업 규칙(언어, 코딩 스타일, 검증 방식, 금지사항 등)을 적어두면:

- 매번 규칙을 다시 말할 필요가 없다. 한 번 적으면 영구 적용.
- 새 세션을 열든, 컨텍스트가 차든 규칙이 항상 살아있다. → **인수인계 문제 자체가 사라진다.**

규칙 추가는 `#`(샵)을 문장 앞에 붙여 말하면 자동으로 CLAUDE.md에 추가된다.

`/init` 명령으로 Claude가 프로젝트를 훑어 CLAUDE.md 초안을 자동 생성할 수도 있다.

## 권한 모드 — 어디까지 자동으로 맡길까

`Shift+Tab`을 누를 때마다 모드가 바뀐다:

- 기본: 파일 수정/명령 실행 때마다 "해도 돼?" 물어본다. (가장 안전, 처음엔 이게 좋다)
- `accept edits`: 파일 편집을 자동 승인. 손이 덜 간다.
- `plan mode`: 아래 참고.

주의: `accept edits`는 **파일 편집만** 자동이다. 파이썬 실행 같은 **명령 실행은 따로 묻는다** (시스템에서 뭐든 할 수 있어서 더 조심스럽게). 명령까지 자동 승인하는 건 위험하니 신중히.

## Plan Mode — 큰 작업은 계획부터

`Shift+Tab` 두 번. 화면에 `plan mode` 표시가 뜬다.

- 일반 모드: "고쳐줘" → 바로 파일을 고치기 시작.
- Plan Mode: "고쳐줘" → **아무것도 안 건드리고, 어떻게 할지 글로 먼저 보여준다** → 내가 승인하면 그때 실행.

공사로 치면 — 일반 모드는 바로 망치 들고 벽 부수기, Plan Mode는 설계도 먼저 보여주고 OK 받고 시작.

언제 쓰나:
- 작은 일(한 파일, 단순 수정) → 그냥 시킨다.
- 큰 일(여러 파일, 위험한 변경) → Plan Mode로 계획 먼저 검토.

위험한 작업일수록 **실행 전에 계획을 막을 수 있다**는 게 핵심. 운전대를 내가 쥐는 안전장치.

## 작업 방식 — 한 방에 다 시키지 않기

"전체 최적화 한번 해줘" 같은 모호하고 광범위한 지시는 제일 위험하다. AI가 헤매거나, 안 시킨 것까지 건드리거나, 멀쩡한 걸 고치다 망가뜨린다.

대신:

1. **진단부터** — "수정하지 말고, 개선 후보만 목록으로 뽑아줘" (읽기만)
2. 목록을 보고 **위험도/효과로 우선순위**를 정한다 (저위험·고효과부터)
3. **하나씩** 작업한다. 한 작업 끝나면 결과를 보고 다음으로.
4. 몇 개 고치면 **실제로 한 번 돌려본다** (안 깨졌나 확인). 쌓아두고 한꺼번에 확인하면 범인 찾기 어렵다.

## 게임/실행 없이 검증하기

GUI 앱이나 특정 상황(예: 게임에서 날씨 바뀔 때)을 매번 재현하기 어렵다. 그럴 땐 **테스트 스크립트를 짜게 시킨다.**

가짜 상태를 만들어서 "이 입력이면 이 결과가 나와야 한다"를 assert로 확인하는 스크립트. 게임 안 켜고도 모든 경우를 한 번에 검증할 수 있고, 어쩌다 한 번 눈으로 보는 것보다 확실하다.

## 알아두면 좋은 명령어

- `/init` — 프로젝트 훑어서 CLAUDE.md 초안 생성
- `#` — 문장 앞에 붙이면 그 내용을 CLAUDE.md에 자동 추가
- `/clear` — 대화 비우고 새로 시작 (CLAUDE.md는 유지)
- `/compact` — 지금까지 대화를 요약·압축 (길어졌을 때)
- `/resume` (또는 `claude --resume`) — 끊긴 세션 이어가기
- `/model` — Opus / Sonnet 모델 전환
- `/usage`, `/status` — 사용량 남은 거 확인
- `!` — 느낌표 붙이면 셸 명령 직접 실행 (`!ls`, `!git status`)
- `Esc` — AI가 엉뚱한 방향이면 기다리지 말고 멈추고 다시 안내

## 사용량 (Pro/Max 공통 개념)

- 일일 고정 토큰이 아니라 **5시간 롤링 세션 + 주간 한도**로 돈다.
- 첫 프롬프트를 보내면 그때부터 5시간 창이 열린다.
- **채팅과 Claude Code가 같은 통**을 쓴다. 브라우저 채팅 많이 하면 터미널에서 쓸 게 줄어든다.
- Opus가 Sonnet보다 빨리 닳는다. 대부분은 Sonnet, 어려운 것만 Opus.
- `ANTHROPIC_API_KEY` 환경변수가 설정돼 있으면 구독 대신 API 종량제로 청구되니 주의. 구독으로 쓰려면 그 키 없이 로그인.

## 멀티 에이전트 / 여러 프로젝트 동시 작업

- **서브에이전트**: 한 세션 안에서 전문 일꾼을 잠깐 부른다 (자동).
- **에이전트 뷰** (`claude agents`): 여러 로컬 세션을 한 화면에서 관리. 여러 프로젝트 동시 작업.
- **에이전트 팀**: 여러 Claude 인스턴스가 자율적으로 협업·검증. 큰 작업을 쪼개서.

주의: 처음부터 여러 개 켜지 말 것. 단일 세션 → 서브에이전트 → 에이전트 뷰 → 에이전트 팀 순으로 무거워진다. 안전하게 분리되는 작업만 병렬화한다. (에이전트 팀은 토큰도 많이 먹는다.)

여러 프로젝트를 가로질러 보게 하려면 — 그 폴더들이 **한 곳에서 접근 가능**해야 한다. AI는 자기가 접근할 수 있는 파일만 본다. git에만 있고 PC에 없으면, clone해서 폴더로 내려받아야 읽는다.

## 핵심 마인드셋

- AI가 일하는 손, 나는 **판단하고 결정하는 운전대.**
- 모호하게 "다 해줘"가 아니라, **범위를 좁혀서 하나씩.**
- 잘 가는지 **중간중간 실제로 확인.**
- 위험한 건 **계획부터 보고**, 아니면 `Esc`로 멈춘다.
- 한 방에 빨리 가려다 깨지면 그게 제일 느리다.