# 소개

> Claude Code는 터미널에서 실행되는 AI 코딩 에이전트로, 전체 코드베이스에 걸쳐 코드를 읽고, 편집하고, 실행합니다.

Claude Code는 Claude를 기반으로 만들어진 터미널 기반 AI 에이전트입니다. 파일 시스템, 셸, 도구에 직접 접근할 수 있어서, 자연어로 작업을 설명하면 Claude가 처음부터 끝까지 구현을 처리합니다 — 복사&붙여넣기 없이, 컨텍스트 전환 없이.

## Claude Code가 할 수 있는 일

- **파일 읽기 및 편집** — 소스 파일을 읽고, 새 내용을 작성하고, 정밀하게 편집합니다. 변경 사항을 적용하기 전에 diff를 보여줘서 사용자가 통제권을 유지합니다.
- **셸 커맨드 실행** — 테스트, 빌드 스크립트, git 작업 등 모든 셸 커맨드를 실행합니다. 설정 가능한 권한 제어로 안전성을 보장합니다.
- **코드베이스 검색** — glob 패턴으로 파일을 찾고, 정규식으로 내용을 검색하며, 모든 파일을 수동으로 읽지 않아도 대규모 코드베이스를 탐색합니다.
- **웹에서 정보 가져오기** — 문서를 가져오거나, API 스펙을 읽거나, 웹을 검색합니다 — 모두 터미널 세션에서 벗어나지 않고.
- **서브에이전트 생성** — 복잡한 작업을 병렬 워크스트림으로 분리합니다. Claude가 여러 에이전트를 스폰하고 조율해서 문제의 각 부분을 동시에 처리합니다.
- **MCP 서버 연결** — 데이터베이스, API, 내부 도구 등을 위한 Model Context Protocol 서버로 Claude의 역량을 확장합니다.

## 권한 시스템

Claude Code의 모든 도구 사용은 권한 확인을 거칩니다. 사용자가 Claude에게 얼마나 많은 자율성을 줄지 제어합니다.

| 모드 | 동작 |
|------|------|
| `default` | 셸 커맨드 실행 및 편집 전에 Claude가 확인을 요청합니다. 각 작업을 승인하거나 거부할 수 있습니다. |
| `acceptEdits` | 파일 편집이 자동으로 적용됩니다. 셸 커맨드는 여전히 승인이 필요합니다. |
| `plan` | Claude가 계획을 만들고 어떤 작업도 실행하기 전에 승인을 요청합니다. 큰 변경 사항이 발생하기 전에 검토하기 좋습니다. |
| `bypassPermissions` | 모든 작업이 프롬프트 없이 실행됩니다. 샌드박스 환경의 자동화 파이프라인 전용 — 대화형 사용에는 적합하지 않습니다. |

> ⚠️ `bypassPermissions` 모드는 모든 확인 프롬프트를 비활성화합니다. Claude가 작업 범위 외부의 시스템에 영향을 줄 수 없는 격리된 환경(Docker 컨테이너, CI 샌드박스)에서만 사용하세요.

시작 시 `--permission-mode` 플래그로 설정하거나, 세션 중 `/permissions`로 변경하세요:

```bash
claude --permission-mode acceptEdits
```

## CLAUDE.md 메모리 시스템

Claude Code는 매 세션 시작 시 저장소의 `CLAUDE.md` 파일을 읽습니다. 이 파일을 통해 프로젝트별 지식 — 빌드 커맨드, 코딩 컨벤션, 아키텍처 노트, 필요한 환경 변수 등 — 을 인코딩할 수 있어서, Claude가 매번 처음부터 다시 발견할 필요가 없습니다.

세 가지 범위:

- **프로젝트** (`CLAUDE.md` — 저장소 루트) — 팀 전체가 공유, 소스 컨트롤에 커밋
- **개인** (`CLAUDE.local.md` — 저장소 루트) — 이 프로젝트에 대한 개인 설정, gitignore됨
- **서브디렉토리** (서브디렉토리 안의 `CLAUDE.md`) — Claude가 해당 디렉토리에서 작업할 때 자동으로 로드됨. 별개의 모듈이 있는 모노레포에 유용

Claude Code 세션 안에서 `/init`을 실행하면 프로젝트의 `CLAUDE.md`가 자동으로 생성됩니다.

> 💡 `CLAUDE.md`는 간결하게 유지하세요. 모든 줄이 이 테스트를 통과해야 합니다: "이것을 제거하면 Claude가 실수를 할까?" 그렇지 않다면 삭제하세요.

## 인증

Claude Code는 두 가지 방식으로 인증합니다:

1. **OAuth (권장)** — `claude.ai`에서 Anthropic 계정으로 로그인. 처음 `claude`를 실행하면 브라우저 프롬프트가 나타납니다.
2. **API 키** — `ANTHROPIC_API_KEY` 환경 변수를 설정. CI 파이프라인과 비대화형 세션에 유용합니다.
