---
title: "Claude Code CLI는 시작하자마자 무엇을 정리할까"
slug: "02-cli-bootstrap"
canonicalUrl: "https://moonshotnotes.com/posts/02-cli-bootstrap/"
sourceUrl: "https://moonshotnotes.com/posts/02-cli-bootstrap/"
markdownUrl: "https://moonshotnotes.com/agent/posts/02-cli-bootstrap.md"
language: "ko"
category: "AI Agent"
updatedAt: "2026-04-30"
agentTokenEstimate: 1325
---

# Claude Code CLI는 시작하자마자 무엇을 정리할까

Claude Code CLI 분석을 바탕으로 agent runtime의 bootstrap 단계가 설정, 정책, 인증, 실행 모드를 어떻게 정리해야 하는지 설명합니다.

## Agent metadata

- Source: https://moonshotnotes.com/posts/02-cli-bootstrap/
- Markdown: https://moonshotnotes.com/agent/posts/02-cli-bootstrap.md
- Language: ko
- Category: AI Agent
- Tags: Claude Code, AI Agent, Runtime, CLI
- Updated: 2026-04-30
- Estimated tokens: 1325

## 핵심 요약

- Agent CLI의 bootstrap은 단순한 argument parsing이 아니다.
- 실제 실행 전에 설정, 인증, 조직 정책, 작업 디렉터리, 확장 기능, 실행 모드가 정리되어야 한다.
- 도움말/버전 출력처럼 가벼운 경로와 실제 agent 실행 경로는 초기화 비용이 달라야 한다.
- agent를 만들 때는 `LaunchContext`를 먼저 만들고 downstream 계층에 넘기는 방식이 안정적이다.

Claude Code류의 CLI agent를 분석하다 보면 흥미로운 지점이 하나 보입니다. 실행 시작점이 생각보다 중요하다는 점입니다.

보통 CLI를 만들 때 bootstrap은 `argv`를 읽고 command를 고르는 정도로 생각하기 쉽습니다. 하지만 AI coding agent에서는 시작 단계가 훨씬 더 많은 것을 결정합니다. 이 프로세스가 어떤 권한으로 실행될지, 어떤 작업 디렉터리를 신뢰할지, 어떤 도구를 노출할지, 어떤 모델과 정책을 사용할지가 여기서 정리됩니다.

## 1. Agent CLI의 bootstrap이 중요한 이유

AI agent는 로컬 파일과 셸, 네트워크, 외부 API를 다룰 수 있습니다. 따라서 프로세스가 시작되자마자 “어떤 환경에서 무엇을 할 수 있는가”를 정리해야 합니다.

이 단계가 흐트러지면 이후 모델 루프와 도구 runtime은 이미 잘못된 전제를 가지고 출발합니다. 예를 들어 프로젝트 설정을 신뢰하기 전에 읽어버리면 외부에서 받은 repository가 실행 정책에 영향을 줄 수 있습니다. 인증 상태가 불분명한데 도구 목록을 노출하면 사용자는 실행 가능한 것처럼 보이는 기능을 보게 됩니다.

> **주의:**
> agent bootstrap에서 가장 위험한 실수는 “처음부터 모든 초기화를 다 해버리는 것”과 “아무 검증 없이 바로 대화 화면으로 들어가는 것”입니다. 전자는 사용성을 망치고, 후자는 보안 경계를 흐립니다.

## 2. 가벼운 경로와 무거운 경로 나누기

CLI에는 도움말, 버전 확인, 진단, batch 실행, interactive 실행처럼 여러 경로가 있습니다. 모든 경로에 같은 초기화 비용을 부과하면 도구는 무거워집니다.

| 실행 경로 | 필요한 초기화 | 피해야 할 초기화 |
|---|---|---|
| help/version | parser 구성, 텍스트 출력 | 네트워크, 인증 저장소, 확장 로딩 |
| diagnostic | 설정 읽기, 일부 환경 검사 | 전체 agent loop 실행 |
| batch prompt | 정책, 모델, 도구, 기록 | 대화형 UI overlay |
| interactive shell | 대부분의 runtime context | 불필요한 remote refresh blocking |

실무적으로는 “실행을 막아야 하는 초기화”와 “실패해도 계속 가능한 초기화”를 분리해야 합니다.

## 3. 실행 전 신뢰 경계 만들기

agent는 프로젝트 내부 설정, 사용자 전역 설정, 조직 정책, 환경 변수, command line option을 함께 봅니다. 이때 중요한 질문은 우선순위가 아니라 신뢰입니다.

프로젝트 내부 파일은 현재 작업 디렉터리의 일부입니다. 사용자가 직접 만든 프로젝트라면 괜찮을 수 있지만, 외부에서 clone한 repository일 수도 있습니다. 이런 상황에서는 프로젝트 설정을 읽기 전에 “이 위치를 신뢰할 수 있는가”라는 판단이 필요합니다.

```text
# 읽는 법: 아래 항목은 동작 흐름을 빠르게 확인하기 위한 요약 예시입니다.
전역 설정
→ 작업 위치 신뢰 확인
→ 프로젝트 설정 반영 여부 결정
→ 조직/보안 정책 적용
→ 실행 모드 확정
```

이 흐름은 AI를 쓰는 개발자에게도 중요합니다. 어떤 AI 도구가 프로젝트를 열자마자 내부 설정을 자동으로 적용한다면, 그 설정이 무엇을 바꾸는지 확인해야 합니다.

## 4. Launch context 설계

bootstrap의 산출물은 흩어진 전역 변수가 아니라 하나의 context가 되는 편이 좋습니다.

| 필드 | 의미 |
|---|---|
| `mode` | interactive, batch, diagnostic, server 등 실행 모드 |
| `workspace` | 작업 디렉터리, 신뢰 여부, project metadata |
| `policy` | 권한 모드, 조직 규칙, 위험 옵션 허용 여부 |
| `model_options` | 모델 선택, 토큰 제한, 출력 모드 |
| `capability_set` | 활성화된 도구, 확장, command 목록 |
| `ledger_config` | transcript 저장 위치, 비용 추적 설정 |

이 context를 downstream 계층에 넘기면 session shell, model loop, tool runtime이 각자 환경 탐색을 다시 하지 않아도 됩니다.

## 5. 개념 코드로 보는 bootstrap 흐름

아래 예시는 원본 구현이 아니라 agent CLI bootstrap을 설명하기 위한 새 코드입니다.

```python
# 읽는 법: 실제 구현 복제가 아니라 runtime 경계를 설명하는 개념 코드입니다.
class LaunchContext:
    # 객체가 이후 단계에서 참조할 runtime 의존성과 상태 저장소를 초기화합니다.
    def __init__(self, mode, workspace, policy, model_options, capabilities):
        self.mode = mode
        self.workspace = workspace
        self.policy = policy
        self.model_options = model_options
        self.capabilities = capabilities

# CLI 시작 요청을 가벼운 출력 경로와 실제 agent runtime 경로로 나눕니다.
async def start_agent_process(argv):
    command = parse_cli_request(argv)

    if command.is_help_or_version:
        return print_lightweight_output(command)

    base_config = read_user_config(command)
    workspace = inspect_workspace(command.cwd)

    if not workspace.is_trusted:
        workspace.project_config = None

    policy = build_runtime_policy(base_config, workspace, command)
    await policy.require_blocking_checks()

    capabilities = load_capabilities_safely(policy, workspace)
    context = LaunchContext(
        mode=command.mode,
        workspace=workspace,
        policy=policy,
        model_options=resolve_model_options(base_config, command),
        capabilities=capabilities,
    )

    schedule_non_blocking_refresh(context)
    return await route_launch_mode(context, command)
```

이 코드의 포인트는 `schedule_non_blocking_refresh()`입니다. 원격 정책 갱신이나 추천 설정 업데이트처럼 실패해도 당장 실행을 막지 않는 작업은 background로 보내고, 인증이나 명시적 금지 정책처럼 반드시 필요한 검사는 blocking으로 처리합니다.

## 6. AI 도구 사용자 관점의 체크포인트

AI coding agent를 쓰는 개발자는 다음을 확인해야 합니다.

- 현재 작업 디렉터리를 도구가 신뢰된 workspace로 보는가?
- 프로젝트 설정 파일이 실행 정책에 영향을 주는가?
- 조직 정책이나 팀 설정이 있는 경우 로컬 설정보다 우선하는가?
- batch 모드와 interactive 모드에서 권한 정책이 달라지는가?
- help/version 같은 단순 명령이 과도한 초기화를 수행하지 않는가?

이 질문들은 단순한 사용법이 아닙니다. 팀에서 AI 도구를 도입할 때 보안 검토 체크리스트가 됩니다.

## 7. Agent 개발자 관점의 체크포인트

agent를 직접 만든다면 bootstrap에서 “실행 모드”를 가능한 빨리 확정해야 합니다. interactive, batch, diagnostic, server 모드가 한 함수 안에서 계속 섞이면 이후 계층이 예외 처리를 떠안게 됩니다.

또한 fail-open과 fail-closed를 구분해야 합니다.

| 상황 | 권장 처리 |
|---|---|
| 인증 실패 | fail-closed, 실행 중단 |
| 명시적 조직 정책 위반 | fail-closed, 실행 중단 |
| 원격 추천 설정 조회 실패 | fail-open, 로컬 기본값 사용 |
| 확장 command 일부 로딩 실패 | fail-open, 기본 기능 유지 |
| transcript 저장소 준비 실패 | 보수적으로 실행 제한 또는 사용자에게 명확히 고지 |

## 8. 실전 체크리스트

```text
# 읽는 법: 아래 항목은 동작 흐름을 빠르게 확인하기 위한 요약 예시입니다.
CLI Agent Bootstrap 체크리스트

[ ] help/version은 무거운 초기화 없이 끝난다.
[ ] 실제 실행 전에는 인증과 정책 검사를 통과한다.
[ ] workspace 신뢰 여부가 프로젝트 설정 반영보다 먼저 결정된다.
[ ] interactive/batch/diagnostic/server 모드가 초기에 확정된다.
[ ] blocking initialization과 background refresh가 분리되어 있다.
[ ] 확장 로딩 실패가 기본 대화 기능을 죽이지 않는다.
[ ] LaunchContext 하나로 downstream 계층에 실행 조건을 넘긴다.
```

## 마무리

Agent CLI의 bootstrap은 작은 시작점이지만, 실제로는 runtime의 첫 번째 안전 경계입니다. 여기서 설정, 인증, 정책, 실행 모드를 정리해두면 뒤쪽 계층은 자신의 책임에 집중할 수 있습니다.

다음 글에서는 대화형 terminal 화면을 보겠습니다. Claude Code류의 화면은 단순 UI가 아니라 메시지, 입력, 승인, 실행 상태를 담는 runtime shell에 가깝습니다.