Claude Code 개요와 공개 기능 경계

Claude Code를 이해하는 출발점

Claude Code는 개발자가 자신의 작업 환경에서 실행하는 코딩 에이전트다. 대화만 생성하는 도구가 아니라, 사용자 승인을 전제로 파일을 읽고 편집하고 명령을 실행하며 MCP(Model Context Protocol) 서버의 도구도 사용할 수 있다. 모델 호출에는 작업에 필요한 컨텍스트가 서비스로 전송될 수 있으므로, 로컬에서 실행된다는 말은 오프라인 도구 또는 모든 데이터가 로컬에만 남는다는 보장이 아니다.

공식 문서는 사용자에게 제공되는 동작과 설정을 기준으로 삼는다. 반대로 번들 문자열, 역공학한 파일 경로, 추정한 내부 메시지 형식은 버전에 따라 사라지거나 바뀔 수 있다. 이 사이트도 후자를 공개 API처럼 다루지 않는다.

사용자·프로젝트 지시사항 (CLAUDE.md)
                │
                ▼
      Claude Code 세션과 에이전트 루프
        │                    │
        ▼                    ▼
  내장 도구·권한 확인     MCP 도구·외부 서비스
        │                    │
        └──── 작업공간과 결과 ────┘

공개 기능을 기준으로 본 구성

| 영역 | 공개적으로 확인할 수 있는 역할 | 학습할 때 확인할 문서 | | --- | --- | --- | | CLI·IDE | 대화형 작업, 권한 승인, 프로젝트 컨텍스트 | CLI 사용법과 IDE 통합 | | 에이전트 | 서브에이전트와 실험적 agent teams로 작업 분담 | Agents, Agent teams | | 설정 | CLAUDE.md, 권한, skills, hooks, plugins | Configuration | | 연결 | MCP 서버와 OAuth 기반 외부 도구 연결 | MCP | | Agent SDK | TypeScript/Python 애플리케이션 안의 에이전트 루프 | Agent SDK | | 원격 작업 | 로컬 세션을 다른 기기에서 조작하는 Remote Control | Remote Control |

이 표는 소스 디렉터리의 고정된 지도를 뜻하지 않는다. Claude Code는 배포형 제품이고 내부 모듈 이름·도구 수·UI 구현은 릴리스마다 달라질 수 있다. 따라서 실제 자동화를 만들 때는 현재 설치 버전의 claude --help와 공식 레퍼런스를 함께 확인해야 한다.

에이전트 루프와 안전 경계

작업은 보통 지시사항과 프로젝트 맥락을 읽는 것으로 시작해, 모델의 제안과 도구 실행 결과를 반복해 다음 행동을 결정하는 흐름으로 진행된다. 파일을 바꾸거나 명령을 실행하기 전에는 권한 모드와 허용 규칙이 적용된다. 계획만 검토할 때는 Plan mode를 사용해 쓰기 전의 제안을 먼저 확인할 수 있다.

요청 → 맥락·지시사항 로드 → 모델의 다음 행동 제안
                                  │
                           권한·정책 확인
                                  │
                     도구 실행 → 결과 반영 → 다음 턴
                                  │
                             완료 또는 사용자 검토

보안 관점에서는 외부 MCP 도구와 웹에서 읽은 콘텐츠도 신뢰하지 않아야 한다. 도구 설명이나 읽은 문서에 포함된 프롬프트 인젝션이 에이전트의 행동을 유도할 수 있으므로, 최소 권한과 명시적 검토를 기본으로 한다.

이 사이트의 범위

이후 장은 공개 문서로 확인되는 CLI, 권한, 세션, hooks, skills, MCP, Agent SDK를 중심으로 설명한다. 실험 기능은 문서에 명시된 상태와 제한을 함께 적는다. 공개 근거가 없는 기능명·환경 변수·패키지 이름·제어 메시지는 예제로 사용하지 않는다. 이 원칙이 기능 업데이트가 빠른 코딩 에이전트를 안전하게 학습하는 가장 실용적인 기준이다.