Claude Code, 터미널에서 코딩 에이전트를 쓰는 방법

# Claude Code, 터미널에서 코딩 에이전트를 쓰는 방법

Claude Code는 터미널에서 코드베이스를 읽고 파일을 고치고 명령을 실행하는 에이전트형 코딩 도구이며, 프로젝트 폴더에서 설치 후 로그인하면 사용할 수 있습니다.

이 글은 Anthropic 공식 문서를 2026-08-27 기준으로 정리한 일반 설치·사용 안내이며, 제품·계정·요금 조건은 바뀔 수 있습니다.

## 설치와 시작은 어떻게 하나?

**한 줄 답:** 지원 운영체제에 맞는 공식 설치 명령을 실행한 뒤 버전을 확인하고 프로젝트 폴더에서 `claude`를 실행해 로그인합니다.

macOS·Linux·WSL에서는 공식 네이티브 설치 명령을 사용할 수 있습니다. 터미널에서 다음 명령을 실행하면 설치가 시작됩니다.

```sh
curl -fsSL https://claude.ai/install.sh | bash
```

Windows PowerShell에서는 아래 공식 설치 명령을 사용합니다. Windows CMD에서는 claude.ai가 제공하는 `install.cmd` 설치 경로를 사용할 수 있습니다.

```powershell
irm https://claude.ai/install.ps1 | iex
```

Homebrew cask `claude-code`와 WinGet 패키지 `Anthropic.ClaudeCode`도 대체 설치 경로로 제공됩니다. 네이티브 설치는 백그라운드에서 자동 업데이트되지만, Homebrew와 WinGet 설치는 자동 업데이트되지 않습니다.

설치가 끝나면 아래 명령으로 버전을 확인합니다. 특정 버전 번호를 고정하지 않고 현재 설치 상태를 확인하는 용도입니다.

```sh
claude --version
```

설치 후에는 작업할 프로젝트 폴더에서 프로그램을 시작합니다. 첫 실행에서는 브라우저 로그인을 요청할 수 있습니다.

접근에는 Pro·Max·Team·Enterprise 플랜 또는 Anthropic Console 계정이 필요합니다. 무료 Claude.ai 플랜에는 접근이 없습니다. `ANTHROPIC_API_KEY`가 설정되어 있으면 로그인 요청을 건너뛰고 해당 키 사용 승인을 요청합니다.

## 프로젝트 폴더에서는 어떻게 쓰나?

**한 줄 답:** 작업할 프로젝트 디렉터리에서 실행하고 첫 질문으로 코드베이스를 파악하게 한 뒤 변경 요청은 승인하며 진행합니다.

터미널을 작업할 프로젝트 디렉터리에서 열고 프로젝트 경로로 이동합니다. 이어서 `claude`를 실행하면 해당 디렉터리를 기준으로 세션이 시작됩니다.

```sh
cd /path/to/your/project
claude
```

시작 화면에는 버전, 현재 모델, 작업 디렉터리가 표시됩니다. `/help`로 사용 가능한 명령을 확인하고 `/resume`으로 이전 대화를 이어갈 수 있습니다.

첫 질문은 프로젝트의 목적이나 주요 기능을 묻는 내용으로 시작합니다. 이 에이전트는 필요한 프로젝트 파일을 읽어 맥락을 모으므로 모든 파일을 처음부터 수동으로 제공할 필요가 없습니다.

설치 후 첫 세션에서는 변경할 때마다 승인을 요청합니다. 변경 요청을 검토한 뒤 승인하면 다음 작업으로 진행합니다.

대화형 터미널 세션의 기본 권한 모드는 Pro·Max·Team 플랜에서 Auto로 시작하고, 그 밖의 플랜에서는 Manual로 시작합니다. `Shift+Tab`으로 권한 모드를 전환할 수 있습니다.

자주 쓰는 실행 형태와 세션 명령은 다음과 같습니다. 명령의 용도에 따라 실행 형태를 구분할 수 있습니다.

| 용도 | 명령 |
| --- | --- |
| 대화형 시작 | `claude` |
| 작업을 인자로 전달 | `claude "task"` |
| 질의 결과만 출력 | `claude -p "query"` |
| 현재 대화 계속 | `claude -c continue` |
| 이전 대화 재개 | `claude -r resume` |
| 화면 초기화·도움말·종료 | `/clear` · `/help` · `/exit` |

## 터미널 코딩 에이전트는 무엇을 하나?

**한 줄 답:** 이 에이전트는 맥락을 모으고 작업한 뒤 결과를 검증하는 순환으로 파일·검색·셸·Git·웹 도구를 사용합니다.

작동 과정은 맥락 수집, 행동, 결과 검증의 순환입니다. 먼저 필요한 정보를 모은 다음 파일을 편집하거나 명령을 실행하고 결과를 확인합니다.

프로젝트 디렉터리에서 실행하면 프로젝트 파일, 터미널 명령, Git 상태, `CLAUDE.md`, 자동 메모리, 설정된 MCP·skills에 접근할 수 있습니다. 파일 작업, 검색, 셸·테스트·Git 실행, 웹 사용이 공식 문서에 설명된 도구 범위입니다.

코드 인텔리전스 플러그인은 선택 사항입니다. 공식 문서의 작업 예시에는 테스트 작성, 기능 구현, 버그 수정, 커밋 및 풀 리퀘스트 생성이 포함됩니다.

세션은 서로 독립적이며 대화는 로컬 `~/.claude/projects/` 아래에 저장됩니다. 파일 편집에는 체크포인트가 제공되며 `Esc`를 두 번 눌러 되돌릴 수 있습니다.

## 공식 문서에서 말하는 한계는 무엇인가?

**한 줄 답:** 무료 플랜에서는 사용할 수 없고 인터넷·지원 환경·권한 승인 조건을 충족해야 하며, 제안된 코드와 명령은 사용자가 검토해야 합니다.

무료 Claude.ai 플랜에는 접근 권한이 없으며 인터넷 연결이 필요합니다. 계정 조건과 지원 국가 조건도 설치 전에 확인해야 합니다.

공식 설치 문서에는 macOS 13.0 이상, Windows 10 1809 이상 또는 Windows Server 2019 이상, Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상이 지원 하한으로 제시되어 있습니다. 하드웨어는 4GB 이상 RAM과 x64 또는 ARM64를 요구합니다.

Manual 모드는 읽기 전용으로 시작합니다. 파일 편집이나 변경하는 Bash 명령을 실행하기 전에는 승인을 요청하며, 쓰기 범위는 작업 디렉터리 경계로 제한됩니다.

처음 사용하는 코드베이스에서는 신뢰 확인이 필요합니다. 홈 디렉터리에서 시작한 신뢰는 디스크에 저장되지 않고 세션에만 남으므로 프로젝트 하위 디렉터리에서 시작해야 합니다.

사용자는 승인 전에 제안된 코드와 명령을 검토해야 합니다. 공식 보안 안내는 어떤 시스템도 완전히 안전하다고 보장할 수 없다고 전제하며, 좋은 보안 관행을 유지하도록 안내합니다.

구독에는 세션 및 주간 사용 창이 있습니다. 맥락 창이 가득 차면 자동 압축으로 초기의 상세 지시가 빠질 수 있으므로, 지속적으로 적용할 규칙은 `CLAUDE.md`에 기록해야 합니다.

구독 경로를 확인하려면 [Gamsgo](https://www.gamsgo.com/partner/UYm3c) 제휴 페이지에서 코드 `NUFUY`를 확인할 수 있습니다.

[Claude Code에 Ollama Cloud를 붙여 월 20달러로 쓰는 후기](https://donggrri.tistory.com/51)는 다른 글입니다.

## FAQ

**한 줄 답:** 설치 확인, 로그인, 권한 모드처럼 시작 단계에서 자주 묻는 내용을 공식 문서 범위에서 짧게 정리합니다.

다음 표는 설치와 첫 실행에서 확인할 항목을 정리한 것입니다. 요금 계산이나 타사 모델 연결, 실제 사용 후기는 포함하지 않습니다.

| 질문 | 답변 |
| --- | --- |
| 무료 Claude.ai 플랜으로 접근할 수 있습니까? | 무료 Claude.ai 플랜에는 접근이 없으며 Pro·Max·Team·Enterprise 플랜 또는 Anthropic Console 계정 조건을 확인해야 합니다. |
| 첫 실행은 어디에서 합니까? | 작업할 프로젝트 디렉터리에서 `claude`를 실행합니다. |
| 처음부터 모든 파일을 붙여야 합니까? | 필요한 프로젝트 파일을 읽어 맥락을 모으므로 모든 파일을 처음부터 수동으로 제공할 필요는 없습니다. |
| 변경이나 명령을 바로 실행해도 됩니까? | 아닙니다. 승인 전에 제안된 코드와 명령을 검토해야 합니다. |

## 출처

**한 줄 답:** 설치·시작·작동 방식·보안·인증 안내는 아래 Anthropic 공식 문서만 출처로 사용합니다.

이 글의 기준일은 2026-08-27입니다. 제품·계정·요금 조건은 공식 문서에서 다시 확인해야 합니다.

- [Overview](https://code.claude.com/docs/en/overview)
- [Quickstart](https://code.claude.com/docs/en/quickstart)
- [Install](https://code.claude.com/docs/en/install)
- [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works)
- [Security](https://code.claude.com/docs/en/security)
- [Authentication](https://code.claude.com/docs/en/authentication)

도구 구독이 부담되면 [할인 경로](https://donggrri.tistory.com/42)만 보시면 됩니다.