# Claude Code 핵심 개념

> **카테고리:** 패턴 & 레시피
> **최종 수정:** 2026-05-13
> **관련:** [[claude-code-project-setup]], [[claude-code-hooks]], [[claude-code-workflow-patterns]]

## 요약

Claude Code는 챗봇이 아니라 **에이전틱 코딩 환경**이다. 파일 읽기·명령 실행·자율적 문제 해결이 가능하며, 모든 성능 전략은 하나의 핵심 제약에서 출발한다: **컨텍스트 윈도우**.

---

## 에이전트 루프

효과적인 에이전트는 이 사이클을 반복한다:

```
Gather Context → Take Action → Verify Work → Iterate
(정보 수집)      (도구 실행)    (출력 검증)    (목표까지 반복)
```

---

## 컨텍스트 윈도우 — 모든 것의 근원

| 임계치 | 현상 |
|---|---|
| 0~20% | 최적 성능 |
| 20~40% | 품질 저하 시작 |
| **60% 초과** | ⚠️ 실무 검증 경계선 — 이 이상 채우지 말 것 |

컨텍스트 관리 명령:

| 명령 | 용도 |
|---|---|
| `/clear` | 무관한 작업 사이 컨텍스트 전체 초기화 |
| `/compact <지시>` | 부분 요약 (예: `/compact API 변경 위주로`) |
| `/btw` | 컨텍스트에 남기지 않는 사이드 질문 (오버레이) |
| `Esc + Esc` / `/rewind` | 이전 체크포인트로 복원 |

---

## 작업 흐름: Explore → Plan → Implement → Commit

곧바로 코딩하면 잘못된 문제를 풀 위험이 있다. Plan mode로 탐색과 실행을 분리하라.

```
1. Explore  (Plan mode): 파일 읽기, 질문 — 수정 없음
2. Plan     (Plan mode): 상세 구현 계획 작성
3. Implement          : Plan mode 해제, 코딩 + 테스트
4. Commit             : 설명적 메시지 + PR
```

> 💡 경험: 오타 수정, 변수 이름 변경 같은 작은 수정은 계획 없이 바로 실행해도 된다. 계획은 오버헤드다.

---

## 효과적인 프롬프트 작성

### 검증 수단을 항상 함께 제공

Claude는 스스로 검증할 수 있을 때 성능이 극적으로 오른다.

| 상황 | Before | After |
|---|---|---|
| 기능 구현 | "이메일 검증 함수 구현해줘" | "validateEmail 작성. 테스트: user@example.com → true, invalid → false. 구현 후 테스트 실행해" |
| UI 변경 | "대시보드 보기 좋게 만들어줘" | "[스크린샷] 이 디자인 구현. 결과 스크린샷 찍어서 원본과 비교. 차이점 나열 후 수정" |
| 버그 수정 | "빌드가 실패해" | "빌드 오류: [오류]. 수정 후 빌드 성공 확인. 에러 억제 말고 근본 원인 해결해" |

### 구체적인 컨텍스트 제공

| 전략 | 예시 |
|---|---|
| 파일 직접 참조 | `@src/auth.ts` — Claude가 파일을 먼저 읽고 답변 |
| 기존 패턴 지목 | "HotDogWidget.php 패턴 따라서 캘린더 위젯 만들어줘" |
| 증상 + 위치 + 완료 기준 | "세션 만료 후 로그인 실패. src/auth/ 확인. 실패 재현 테스트 먼저 작성 후 수정" |
| 이미지/파이프 | `cat error.log \| claude` |

### Subagent로 조사 위임

조사 시 파일을 많이 읽어 컨텍스트를 소비한다. 조사는 subagent에 위임해 메인 컨텍스트 오염을 방지하라.

```
Use subagents to investigate how our authentication system handles token refresh,
and whether we have any existing OAuth utilities I should reuse.
```

---

## 흔한 실수 패턴

| 패턴 | 문제 | 해결 |
|---|---|---|
| 주방 싱크 세션 | 무관한 작업이 섞여 컨텍스트 오염 | 작업 사이마다 `/clear` |
| 반복 수정 루프 | 틀림 → 수정 → 또 틀림 → 컨텍스트 오염 | 두 번 실패 후 `/clear` + 더 구체적인 프롬프트로 재시작 |
| 비대한 CLAUDE.md | 규칙이 묻혀서 무시됨 | 불필요한 내용 제거, hook으로 이전 |
| 검증 없이 신뢰 | 그럴듯하지만 엣지케이스 미처리 | 항상 검증 수단 제공 |
| 무한 탐색 | 수백 개 파일 읽어 컨텍스트 폭발 | 조사 범위 좁게 잡거나 subagent 사용 |

---

## 참고 / 출처

- `raw/claude-code-best-practices-official.md` (code.claude.com 공식 문서)
- `raw/claude-agent-sdk-overview.md` (claude.com 블로그)