이 페이지의 목차
확인 2026-09-16근거 자료 32건갱신 2026-10-26언급 72곳
이 페이지의 목차
확인 날짜 안내

확인 날짜: 풀이에 들어간 변하는 사실(기본값, 명령, 설정 키)은 공식 문서 수집일 2026-10-18·2026-10-21 기준이고, Cowork 통합 상태는 Help Center 문서 수정일(2026-09-16) 기준이다. 페이지 확인 날짜는 그중 가장 오래된 날짜다. 블로그·2024~2025년 글에서 온 풀이는 개념 정의라 날짜 계산에서 뺐다. 각 용어의 조건과 예외는 "자세히" 페이지가 기준이다.

용어마다 원어 표기, 쉬운 풀이, 자세히 볼 페이지, 근거 원본 순으로 적었다. 묶음은 주제별이고, 묶음 안에서는 가나다순(영문은 뒤)이다. 찾아보기의 괄호 숫자는 묶음 번호이고, "핵심"은 맨 앞 "핵심 용어" 묶음이다.

찾아보기 (가나다)#

ㄱ~ㅅ: 권한 모드(핵심), 도구 호출(1), 마켓플레이스(1), 마크다운(2), 메모리 도구(1), 백그라운드(1), 범위(6), 샌드박스·fail open(6), 서브에이전트(핵심), 세션·재개(1), 셸·Bash·PowerShell(3), 스킬(핵심), 슬래시 명령(1), 시스템 프롬프트(1)

ㅇ~ㅎ: 에이전트 루프(1), 오케스트레이터(1), 자격 증명(3), 자동 모드·분류기(6), 작업 공간 신뢰(6), 점진적 공개(1), 정규식(2), 종료 코드(5), 체크포인트(1), 출력 스타일(핵심), 커넥터(1), 커밋(4), 컨텍스트·컨텍스트 창(1), 컴팩션(1), 터미널(3), 토큰(1), 트랜스크립트(1), 포크(1), 프록시·도메인(3), 프롬프트 인젝션(1), 프롬프트 캐싱(1), 플러그인(핵심), 하네스(1), 헬퍼 명령(3), 환경 변수(3), 훅(핵심)

영문: @ 참조(1), AGENTS.md(2), allow·ask·deny(6), API(3), BM25·벡터 검색(1), CI(3), CLAUDE.md(2), CLI·플래그(3), Cowork(핵심), frontmatter(2), git·저장소(4), glob 패턴(2), IDE(3), JSON(2), LSP(6), managed settings·MDM(6), matcher(5), MCP(핵심), MCP 서버(1), mod(6), -p(3), plan·acceptEdits·bypassPermissions(6), PR·diff(4), push·브랜치(4), SDK(3), settings.json(2), stderr(3), stdin·stdout(5), system reminder(1), worktree(4), WSL(3), YAML(2)

핵심 용어: 자기 페이지가 있는 것#

이 위키의 주제가 되는 기능 이름이다. 한 줄 풀이만 두고, 조건과 예외는 "자세히" 페이지가 기준이다.

1. 기본: 대화와 작동 방식#

2. 파일과 형식#

3. 실행 환경#

  • 셸·Bash·PowerShell (shell): Claude가 내 기기에서 명령을 실행할 때 쓰는 통로다(일반적인 뜻이다. 원본은 정의하지 않는다). Claude Code에는 Bash·PowerShell 도구가 있다. 권한 규칙의 Bash(...)와 샌드박스가 이 셸 명령을 대상으로 한다.
  • 자격 증명 (credentials): 서비스에 접근하는 비밀값이 든 파일·변수다(원본 예: ~/.ssh, ~/.aws/credentials). 샌드박스 기본값에서는 이런 파일도 읽히고 내장 차단 목록이 없어, 막을 파일은 직접 적어야 한다.
  • 터미널 (terminal): Claude Code가 기본으로 도는 명령줄 화면이다. 공식 문서는 Claude Code를 터미널에서 도는 에이전트형 도우미로 소개하고, 다른 인터페이스로 데스크톱 앱·IDE 확장·claude.ai/code 등을 든다.
  • 프록시·도메인 (proxy, domain): 도메인은 인터넷 주소의 이름이고, 프록시는 나가는 연결을 중간에서 받아 주는 관문이다(일반적인 뜻이다. 원본은 정의하지 않는다). 샌드박스 안 명령은 직접 나가지 못하고 프록시를 거치며, 프록시가 허용 도메인 목록(빈 목록에서 시작)과 대조한다.
  • 헬퍼 명령 (helper command, 예: apiKeyHelper): 설정 파일에 적어 두면 Claude Code가 대신 실행하는 보조 명령이다. 예를 들어 apiKeyHelper는 API 자격 증명을 내 명령으로 만들게 한다. 저장소 설정 파일에 든 헬퍼 명령은 상위 폴더만 신뢰했거나 -p·SDK로 돌릴 때 작업 공간 신뢰 전에도 쓰이므로, 남의 저장소를 열 때 확인할 대상이다.
  • 환경 변수 (environment variable, env): 프로그램이 실행될 때 함께 받는 이름·값 쌍 설정이다(일반적인 뜻이다. 원본은 정의하지 않는다). 이 위키에서는 CLAUDE_CODE_SUBAGENT_MODEL처럼 대문자 이름으로 나온다. 설정 파일의 env 블록에 적을 수도 있고, 셸에서 준 값과 설정 키 중 무엇이 이기는지는 쌍마다 다르다.
  • API: 이 위키에서는 두 자리에 나온다. 체크포인트가 되돌리지 못하는 바깥 시스템의 예(데이터베이스·API·배포)와, Gemini API 키처럼 모델을 직접 부르는 계정 방식이다. 원본들은 API 자체를 정의하지 않는다.
  • CI (CI/CD): 사람 없이 자동으로 빌드·배포를 돌리는 파이프라인이다(일반적인 뜻이다. 원본은 정의하지 않는다). Claude Code는 여기서도 돌 수 있다. 권한 모드 dontAsk의 원본 용도가 "잠근 CI와 스크립트"다.
  • CLI·플래그 (command-line interface, flag): CLI는 터미널에서 명령으로 쓰는 프로그램이고, 플래그는 claude --resume의 --resume처럼 명령 뒤에 붙여 동작을 바꾸는 옵션이다(일반적인 뜻이다. 원본은 정의하지 않는다). 원본은 claude --help가 모든 플래그를 보여 주지는 않는다고 말한다.
  • IDE (integrated development environment): VS Code 같은 개발용 편집기다(일반적인 뜻이다. 원본은 정의하지 않는다). Claude Code는 IDE 확장으로도 쓸 수 있다.
  • -p (비대화형, print mode): 대화 화면 없이 Claude Code를 돌리는 비대화형 실행 방식으로, 이 위키에서는 자동화·스크립트 맥락에서 나온다. 작업 공간 신뢰 대화상자를 띄우지 않는 등 대화형 세션과 규칙이 다른 곳이 있다.
  • SDK (Agent SDK): 다른 앱이 Claude Code를 자기 안에서 띄워 쓸 때 쓰는 개발 도구다(일반적인 뜻이다. 원본은 정의하지 않는다). 이 위키에서는 주로 "-p·SDK 세션은 규칙이 다르다"는 조건으로 나온다. 예를 들어 SDK 세션은 작업 공간 신뢰 대화상자를 띄우지 않는다.
  • stderr (standard error): 프로그램이 오류·경고 메시지를 내보내는 출력 통로다(일반적인 뜻이다. 원본은 정의하지 않는다). 이 위키에서는 claude -p로 신뢰하지 않은 폴더에서 돌릴 때 this workspace has not been trusted 경고가 나오는 자리로 나온다. 일반 출력 통로 stdout은 5절에 있다.
  • WSL (Windows Subsystem for Linux): 원본들은 지원 플랫폼을 말할 때 macOS·Linux와 함께 WSL(WSL2)을 든다. 샌드박스는 macOS·Linux·WSL2에서 돌고 Windows 네이티브에서는 돌지 않는다.

4. git (파일 변경 이력 관리)#

  • 커밋 (commit): 변경을 저장소 이력에 한 단위로 남기는 일이다(일반적인 뜻이다. 원본은 정의하지 않는다). 공유 .claude/settings.json은 git 저장소라면 커밋해야 팀원이 받는다.
  • git·저장소 (repository): git은 이 위키에서 팀이 파일과 변경 이력을 나누는 도구로 나오고, 저장소는 그렇게 관리되는 프로젝트 폴더다(일반적인 뜻이다. 원본은 정의하지 않는다). Claude Code가 접근하는 정보에는 현재 브랜치, 커밋하지 않은 변경, 최근 커밋 기록 같은 git 상태가 들어간다(체크포인트는 git과 별개다).
  • PR·diff (pull request, diff): PR은 변경을 합치기 전에 검토를 요청하는 단위이고, diff는 바뀐 부분이다(일반적인 뜻이다. 원본은 정의하지 않는다). 자동 모드는 PR 생성을 기본으로 허용하지만, 사람이 승인하지 않은 PR 병합은 기본 차단 예로 든다.
  • push·브랜치 (push, branch): 브랜치는 저장소 안의 갈래 작업선이고, push는 내 커밋을 원격 저장소로 올리는 일이다(일반적인 뜻이다. 원본은 정의하지 않는다). 자동 모드는 작업 중인 저장소 브랜치로의 push를 기본으로 허용하되, 배포·공개용 이름의 브랜치(production, release 등)는 따로 판단하고 force push는 계속 검사한다.
  • worktree: 서브에이전트가 메인 작업과 섞이지 않도록 격리된 작업 공간으로 쓰는 git 기능이다(일반적인 뜻이다. 원본은 정의하지 않는다). Claude Code는 서브에이전트 호출에 worktree 격리를 요청할 수 있고, Antigravity는 Killed된 서브에이전트의 임시 worktree를 자동으로 정리한다.

5. 훅#

  • 종료 코드 (exit code): 훅 스크립트가 끝나며 돌려주는 숫자다. 0은 성공, 2는 막는 오류(막을 수 있는 이벤트에서 동작 중단)이고, 그 밖의 코드는 동작을 막지 않는다(실패 시 막도록 지정한 훅은 예외).
  • matcher: 훅이 어떤 경우에 돌지 거르는 조건으로, 보통 도구 이름(예: "Bash")을 맞춘다. matcher가 맞추지 않은 도구에는 훅이 돌지 않으므로, 막는 용도의 훅은 matcher 범위부터 확인한다.
  • stdin·stdout: 프로그램이 입력을 받는 통로(stdin)와 출력을 내보내는 통로(stdout)다(일반적인 뜻이다. 원본은 정의하지 않는다). command 훅은 stdin으로 JSON을 받고, PreToolUse 같은 이벤트에서는 stdout 출력과 종료 코드를 함께 봐야 결과가 정해진다.

6. 권한과 통제#

  • 범위 (scope: user·project·local·managed): 설정 파일이 누구에게 적용되는지 나누는 단위다. user는 내 기기의 모든 프로젝트, project는 그 폴더에서 일하는 모두(커밋해야 팀원에게 닿음), local은 그 프로젝트에서 나만, managed는 조직이 배포한 기기이고 managed가 가장 위다.
  • 샌드박스·fail open (sandbox): 샌드박스는 Claude가 돌리는 셸 명령과 그 하위 프로세스가 닿을 파일·네트워크를 운영체제가 제한하는 경계로, 기본으로 꺼져 있다. fail open은 막는 장치가 실패하면 열린 채로 진행한다는 뜻으로, 기본값에서는 샌드박스가 뜨지 못하면 샌드박스 없이 명령을 돌린다(sandbox.failIfUnavailable: true면 시작 때 종료). 또 샌드박스에서 실패한 명령은 Claude가 샌드박스 밖에서 다시 돌리자고 할 수 있고, 누가 승인하는지는 권한 모드가 정한다(끄려면 allowUnsandboxedCommands: false). excludedCommands에 적은 명령은 처음부터 샌드박스 밖에서 돈다.
  • 자동 모드·분류기 (auto mode, classifier): 사람 대신 두 번째 모델인 분류기가 동작을 검토해, 묻지 않고 진행하게 하는 권한 모드다. 원본은 분류기 규칙을 합치는 방식이 강제 경계가 아니라고("not a hard policy boundary") 하므로, 절대 막을 동작은 managed settings의 permissions.deny로 막는다.
  • 작업 공간 신뢰 (workspace trust): 처음 보는 폴더에서 저장소가 주는 설정 가운데 능력을 주는 것(프로젝트 allow 규칙 등)을, 신뢰 대화상자를 수락한 뒤에만 적용하는 단계다. 모든 저장소 설정이 신뢰 뒤로 미뤄지는 것은 아니고, -p·SDK 세션은 대화상자를 띄우지 않는다.
  • allow·ask·deny 규칙, 허용 목록 (permission rules, allowlist): allow는 묻지 않고 쓰게, ask는 쓸 때마다 묻게, deny는 못 쓰게 하는 권한 규칙이며, deny, ask, allow 순서로 처음 맞는 규칙이 정한다. 다만 설치한 mod(도구 호출을 승인·거부할 수 있는 확장)는 managed settings나 Team·Enterprise 로그인이 없으면 deny가 거부한 호출도 승인할 수 있다. Bash 규칙은 명령 글자만 맞추므로 반드시 지켜야 할 제한은 샌드박스나 PreToolUse 훅과 함께 쓴다.
  • LSP (Language Server Protocol): 이 위키에서는 Claude Code가 코드를 읽을 때 쓰는 도구의 하나로, Read·Grep·Glob과 함께 작업 폴더 밖 읽기 제한이 걸리는 대상, 그리고 --safe-mode가 끄는 항목(LSP 서버)으로 나온다. 원본들은 LSP가 무엇인지는 설명하지 않는다.
  • managed settings·MDM (managed settings, mobile device management): 조직이 모든 개발자 기기에 배포해 다른 모든 설정 위에 적용하는 Claude Code 설정으로, managed-settings.json 파일, MDM·OS 정책, 관리 콘솔 등으로 배포한다. 다만 managed model은 시작 기본값일 뿐 잠금이 아니고, 기기 관리자 권한이 있는 개발자는 관리 파일 자체를 고칠 수 있으며, managed settings는 Claude Code만 묶는다.
  • mod: 설치해 쓰는 확장으로, 도구 호출을 사용자에게 묻기 전에 승인하거나 거부할 수 있다. 기기에 managed settings가 있거나 세션이 Team·Enterprise /login으로 로그인했으면 deny 규칙과 훅의 차단 결과가 기본으로 유지되지만, 둘 다 없으면 mod가 deny 규칙이 거부하거나 PreToolUse 훅이 막은 호출도 승인할 수 있다(API 키 세션은 그 로그인을 쓰는 것이 아니다).
  • plan·acceptEdits·bypassPermissions (권한 모드 이름): Manual(default)은 읽기만 묻지 않고, acceptEdits는 파일 편집과 흔한 파일 명령까지 묻지 않으며, plan은 바꾸기 전 탐색용이다. bypassPermissions는 모든 것을 묻지 않아 원본은 격리된 컨테이너·VM 전용으로 든다.

관련#