Claude Code Deep Dive Workshop Chapter 5 - CLI Reference

Intro

Claude Code Deep Dive Workshop

Chapter 5는 대화형을 벗어나 CLI와 무인 자동화를 다룹니다. Chapter 1~4에서 만든 설정, 훅, MCP, 커스텀 명령이 그대로 살아 있는 상태로 스크립트에서 돌아갑니다. 사람이 확인하고 반복하던 자리를 스크립트가 대신하고, 판정은 exit code와 JSON으로 합니다.

 

2026.08.23 - [Study/Claude Code Workshop] - Claude Code Deep Dive Workshop Chapter 4 - Settings

2026.08.16 - [Study/Claude Code Workshop] - Claude Code Deep Dive Workshop Chapter 3 - Admin Setup

2026.08.09 - [Study/Claude Code Workshop] - Claude Code Deep Dive Workshop Chapter 2 - Agents (Subagents)

2026.08.02 - [Study/Claude Code Workshop] - Claude Code Deep Dive Workshop Chapter 1 - Overview

 

 

---

본론

Part 1. claude 명령과 플래그

명령 구조

claude                              # 대화형 세션
claude "explain this project"       # 초기 프롬프트로 시작
claude -p "query"                   # 실행 후 종료 (headless)
cat logs.txt | claude -p "explain"  # 파이프 입력
claude -c                           # 이 디렉토리 최근 대화 계속
claude -r "auth-refactor" "Finish this PR"

서브커맨드는 오타를 교정해 제안합니다. claude udpate → Did you mean claude update?

서브커맨드

계정과 설치 쪽입니다.

명령	용도
auth login / logout	--email, --sso, --console. 구독 과금과 API 과금 선택
auth status	JSON 상태, exit 0/1. 스크립트 로그인 판정용
setup-token	CI용 장기 OAuth 토큰 발급. 출력만 하고 저장하지 않음
update / install	갱신, 버전 지정 재설치
doctor	환경 진단과 자동 수정
project purge [path]	프로젝트 로컬 상태 일괄 삭제. --dry-run 지원

 

운영 쪽입니다.

명령	용도
agents / attach / logs	백그라운드 에이전트 뷰, 접속, 로그 (--json)
stop / respawn / rm	중지, 재기동(--all), 목록 제거
daemon status / stop	슈퍼바이저 진단과 정지
mcp login / logout	패널 없이 OAuth. SSH 환경용 --no-browser
gateway --config	엔터프라이즈 게이트웨이 서버 기동 (Ch.3)
ultrareview [PR]	비대화 심층 리뷰. exit 0/1, --json

플래그 6분류

60여 개를 여섯 서랍으로 나눕니다.

분류	대표 플래그
동작 모드	-p, --bg, --remote, --worktree, --bare, --safe-mode
세션	-c, -r, --from-pr, --fork-session, -n
모델과 사고	--model, --effort, --fallback-model, --advisor
권한과 도구	--permission-mode, --tools, --allowed/disallowedTools
구성과 확장	--settings, --agents, --mcp-config, --plugin-dir
출력과 진단	--output-format, --json-schema, --verbose, --debug

모델과 사고

claude --model opus              # 별칭 또는 전체 ID
claude --effort high             # low..max, 모델별로 단계 상이
claude --fallback-model sonnet,haiku   # 과부하 시 순서대로 시도
claude --advisor opus            # 어드바이저 도구 활성

별칭은 sonnet, opus, haiku, fable 네 종입니다. 우선순위는 플래그 > ANTHROPIC_MODEL > 설정입니다.

권한과 도구 - 세 플래그의 차이

여기가 이 파트의 핵심입니다. 이름이 비슷하지만 하는 일이 다릅니다.

claude --permission-mode plan             # 6모드 (Ch.4)

# 무확인 허용 (규칙 문법)
claude -p --allowed-tools "Bash(git log *)" "Read" ...

# 도구 자체 제거 vs 특정 호출만 거부
claude --disallowedTools "Edit"          # Edit 도구를 목록에서 제거
claude --disallowedTools "Bash(rm *)"    # 해당 호출만 거부
claude --disallowedTools "mcp__*"        # 전 MCP 도구 제거

# 내장 도구 제한 (MCP는 영향 없음)
claude --tools "Bash,Edit,Read"

• --allowedTools - 묻지 않고 실행할 목록. 능력 부여가 아니라 확인 프롬프트 제거
• --disallowedTools - 베어 이름을 주면 도구 컨텍스트에서 제거, 스코프 규칙을 주면 그 호출만 거부
• --tools - 내장 도구 집합 자체를 한정. MCP 도구에는 영향 없음
• --add-dir - 접근 범위 확장. 다만 그 디렉토리의 구성 파일은 탐색하지 않음

구성과 확장

claude --settings ./ci-settings.json      # 세션 한정 설정 오버레이
claude --settings '{"model":"haiku"}'     # 인라인도 가능
claude --setting-sources user,project     # 로드할 설정 소스 선별
claude --agents '{"reviewer":{...}}'
claude --mcp-config ./mcp.json --strict-mcp-config
claude --plugin-dir ./my-plugin --disable-slash-commands

CI에서 로컬 환경 차이를 없애려면 --setting-sources로 소스를 고정하고 --settings로 오버레이하는 조합이 재현성이 좋습니다.

시스템 프롬프트 4종

플래그	동작
--append-system-prompt	기본 프롬프트 뒤에 텍스트 추가. 정체성 유지 + 규칙
--append-system-prompt-file	파일 내용을 추가. 긴 규칙, 버전 관리
--system-prompt	전체 대체. 안전 지침도 함께 사라짐
--system-prompt-file	파일로 전체 대체. 대체 계열끼리는 상호 배타

선택 기준은 단순합니다. 코딩 조수 정체성을 유지할 거면 append, 비코딩 에이전트로 완전히 바꿀 거면 대체입니다. 대체는 안전 지침까지 책임이 넘어옵니다. 영구 페르소나는 output style, 상시 규범은 CLAUDE.md가 제자리입니다.

--bare vs --safe-mode

둘 다 "최소 기동"이지만 목적이 반대입니다.

	--bare (스크립트 가속)	--safe-mode (고장 진단)
대상	훅, 스킬, 플러그인, MCP, CLAUDE.md 미탐색	전 커스터마이즈 비활성
도구	Bash, 읽기, 편집 사용 가능	인증, 권한 정상 동작
managed 정책	-	여전히 적용됨
환경변수	CLAUDE_CODE_SIMPLE	CLAUDE_CODE_SAFE_MODE
목적	-p 반복 호출의 기동 시간 절약	커스텀이 원인인지 이분 판정

조합 관용구 5

# 1. CI 리뷰: 예산과 도구를 잠근 헤드리스
claude -p --max-budget-usd 2 --allowed-tools "Read" "Grep" ...

# 2. 빠른 배치: 최소 기동 + 저비용 모델
claude --bare -p --model haiku "..."

# 3. 격리 실험: PR 분기 워크트리
claude -w '#123' --permission-mode plan

# 4. 세션 재현: 소스 고정 + 오버레이
claude --setting-sources project --settings ./ci.json -p "..."

# 5. 무인 야간: dontAsk + 폴백 체인
claude -p --permission-mode dontAsk --fallback-model sonnet,haiku "..."

 

 

---

Part 2. Headless 심화

-p의 정체

-p는 출력 모드가 아니라 Agent SDK 경로를 타는 단발 에이전트 실행입니다. 도구 실행, 훅, MCP, 권한이 대화형과 동일하게 살아 있고 결과만 표준출력에 남습니다.

계약은 세 가지입니다. stdout = 결과, stderr = 진단, exit code = 판정.

--max-turns, --max-budget-usd, --json-schema는 -p 전용 플래그입니다.

입력 6경로

claude -p "직접 인자"                        # 1 인자
cat error.log | claude -p "원인 분석"         # 2 파이프
claude -p "$(cat prompt.txt)"               # 3 명령 치환
claude -p "요약해" < notes.md                # 4 리다이렉트
claude -p <<'EOF'                           # 5 히어독
여러 줄 지시문 ...
EOF
claude -c -p "이어서 리팩토링"                # 6 세션 이어받기

원칙은 파이프는 데이터, 인자는 지시입니다. 프롬프트 안의 @경로 파일 참조도 그대로 유효합니다.

Exit code 계약

claude -p "테스트 실패 원인을 찾아 수정" --max-turns 15
case $? in
  0) echo OK ;;
  *) echo "FAIL (code $?)" ; exit 1 ;;
esac

• 0 = 정상 완료, 비0 = 오류 또는 상한 도달
• --max-turns 초과도 오류 종료이므로 그대로 게이트 재료가 됩니다
• claude auth status - 로그인 0, 미로그인 1
• claude ultrareview - 통과 0, 발견 1

set -e를 쓸 때는 의도적 분기와 충돌하지 않게 처리해야 합니다.

--output-format json

{
  "type": "result",
  "subtype": "success",
  "result": "1. src/auth/... (본문)",
  "session_id": "...",
  "total_cost_usd": 0.0284,
  "num_turns": 4,
  "duration_ms": 21033,
  "usage": { "input_tokens": ..., "output_tokens": ... }
}

.result가 본문이고 나머지는 관측 메타데이터입니다. 비용은 .total_cost_usd에 이미 계산되어 들어옵니다.

stream-json 이벤트

이벤트	내용
system (init)	세션 시작, 모델과 도구 목록. 첫 이벤트
assistant	모델 응답 메시지 단위
user (tool_result)	도구 실행 결과 회신
result	최종 봉투. json 모드와 동일 형식

--include-partial-messages로 토큰 단위 부분 이벤트를, --include-hook-events로 훅 수명주기 이벤트를 추가할 수 있습니다.

--json-schema - 파싱이 아니라 계약

claude -p "이 diff의 위험도를 평가해" \
  --json-schema '{
      "type": "object",
      "properties": {
        "risk":    { "enum": ["low", "medium", "high"] },
        "reasons": { "type": "array", "items": {"type":"string"} },
        "block":   { "type": "boolean" }
      }, "required": ["risk", "block"] }'

프롬프트에 "JSON으로만 답해"라고 쓰고 정규식으로 긁어내는 방식과 다릅니다. 워크플로 완료 후 스키마 검증을 통과한 JSON만 반환합니다. enum과 required를 게이트 친화적으로 설계하는 게 요령입니다.

jq 파싱 기초

OUT=$(claude -p "..." --output-format json)

echo "$OUT" | jq -r '.result'          # 본문
echo "$OUT" | jq -r '.total_cost_usd'  # 비용
echo "$OUT" | jq -r '.session_id'      # 재개 키

# 구조화 출력 결합: 게이트 한 줄
RISK=$(claude -p "..." --json-schema "$SCHEMA" | jq -r '.risk')
[ "$RISK" = "high" ] && exit 1

# stream-json: 줄 단위 select
... | jq -c 'select(.type == "result")'

예산과 턴 상한

claude -p "의존성 취약점 정리해 패치 PR 초안까지" \
  --max-turns 20 \
  --max-budget-usd 3.00

• --max-turns - 에이전틱 턴 수 상한. 기본이 무제한이라 무인 실행에서는 반드시 지정
• --max-budget-usd - 달러 상한. 도달 시 중단

상한 산정은 파일럿 실측 p95의 1.5배에서 시작하는 것을 권합니다. 초과 종료는 실패가 아니라 신호이므로 로그와 알람으로 받습니다.

캐시 최적화

claude -p --exclude-dynamic-system-prompt-sections "이 모듈의 순환 의존을 정리해"

시스템 프롬프트의 기기별 섹션(작업 경로, 환경 정보)이 프롬프트 캐시 재사용을 깨뜨립니다. 이 플래그는 해당 섹션을 첫 사용자 메시지로 옮겨서, 여러 사용자와 여러 기계가 같은 작업을 돌릴 때 캐시 적중률을 올립니다. 기본 시스템 프롬프트를 쓸 때만 적용됩니다.

재시도 골격

run_claude() {
  local attempt=1
  while [ $attempt -le 3 ]; do
    OUT=$(claude -p "$1" --output-format json \
          --max-turns 15 2>err.log) && { echo "$OUT"; return 0; }
    grep -qiE 'rate|overloaded|529' err.log || break
    sleep $(( attempt * 20 )); attempt=$((attempt+1))
  done
  return 1        # 진짜 실패: 재시도 무의미
}

일시 오류와 진짜 실패를 stderr 패턴으로 가르는 게 핵심입니다. 다만 모델 과부하에 대한 1차 방어는 --fallback-model이 더 간결합니다.

다중 호출 집계

for f in src/services/*.ts; do
  claude --bare -p "이 파일의 복잡도를 평가" \
    --json-schema '{"type":"object","properties":{
      "file":{"type":"string"},"score":{"type":"number"},
      "top_issue":{"type":"string"}}}' < "$f"
done | jq -s 'sort_by(-.score)' > report.json

jq -r '.[] | [.file, .score, .top_issue] | @csv' report.json > report.csv

jq -s로 배열화하고 @csv로 표를 만듭니다. 집계가 되려면 구조화 출력이 전제입니다.

 

 

---

Part 3. 세션 제어

저장 구조

세션 트랜스크립트는 ~/.claude/projects/ 아래 프로젝트별 JSONL로 저장됩니다. 수명은 cleanupPeriodDays 기본 30일이고, claude project purge로 일괄 정리합니다(--dry-run 지원). 저장을 끄려면 -p에서는 --no-session-persistence, 전 모드에서는 환경변수를 씁니다.

continue vs resume

-c / --continue	-r / --resume
현재 디렉토리 최근 대화로 직행	ID 또는 이름으로 특정 재개
--add-dir로 얹은 세션도 포함	인자 없이 쓰면 대화형 픽커
-c -p로 헤드리스 이어받기	픽커에 백그라운드 세션도 표시
일상 복귀의 기본기	ID 검색은 현 프로젝트와 워크트리 한정

마지막 줄이 실제로 많이 걸리는 지점입니다. 다른 디렉토리에서 세션 ID로 재개하려 하면 못 찾습니다.

--from-pr

claude --from-pr 123
claude --from-pr https://github.com/org/repo/pull/123

Claude가 만든 PR은 세션과 자동 링크됩니다. 리뷰어 코멘트를 받았을 때 그 PR을 만든 맥락 그대로 후속 수정에 들어갈 수 있습니다. GitHub, GitHub Enterprise, GitLab MR, Bitbucket PR URL을 모두 받습니다.

claude -w '#123'은 코드 분기(워크트리) 쪽이라 용도가 다릅니다.

fork와 session-id

# 원본 보존 분기: 재개하되 새 세션 ID로
claude --resume auth-refactor --fork-session

# 고정 좌표: 스크립트가 세션 ID를 소유
SID=$(uuidgen)
claude -p --session-id "$SID" "1단계: 스캔"
claude -p --resume "$SID" "2단계: 스캔 결과로 수정"

다단계 파이프라인에서는 세션 ID를 응답에서 뽑아 오는 것보다 미리 정해서 주입하는 쪽이 단순합니다.

이름과 내보내기

claude -n "payments-refactor"        # 시작부터 이름 부여
> /rename auth-hotfix                # 세션 중 개명
claude -r "payments-refactor" "어제 이어서"   # 이름으로 복귀
> /export                            # 대화를 파일, 클립보드로

팀에서는 티켓 번호를 세션 이름으로 쓰면 픽커 가독성이 좋아집니다.

체크포인트와 /rewind

파일 편집은 체크포인트로 자동 추적되고, /rewind로 코드와 대화를 이전 지점으로 되돌립니다. 다만 Bash 부수효과와 외부 시스템은 복원 밖입니다. 세션 내 무르기는 rewind, 이력 관리는 git으로 분업합니다.

웹 왕복과 Remote Control

claude --remote "로그인 버그 수정"    # claude.ai 샌드박스에서 실행
claude --teleport                    # 로컬로 회수

반대 방향이 Remote Control입니다. 내 기계에서 도는 세션을 claude.ai와 모바일 앱에서 이어 조종합니다. 조직은 disableRemoteControl로 통제합니다.

 

 

---

 

Part 4. 스케줄과 자동 실행

자동화 표면 5종

어디서 반복시킬 것인가의 선택지입니다.

표면	수단	전제
세션 내	/loop, cron 도구, /goal	세션이 떠 있어야 함
Desktop 예약	Desktop 앱 scheduled tasks	내 기계, GUI 관리
Routines	Anthropic 관리 클라우드 실행	기계 불필요, 3종 트리거
CI 파이프라인	이벤트 구동 (push, PR)	Part 5
cron + headless	OS 스케줄러 + -p 스크립트	완전 자가 통제

/loop와 /goal

> /loop 테스트가 전부 통과할 때까지 실패를 고쳐
> 10분마다 배포 파이프라인 상태를 확인하고 실패로 바뀌면 원인을 정리해줘
> 45분 뒤에 스탠드업 준비하라고 알려줘

> /goal 전체 테스트 통과 + 린트 0 경고 상태 도달

/loop은 같은 작업의 반복, /goal은 상태 도달까지 수단을 바꿔가며 지속입니다. 둘 다 세션 종료 시 함께 끝나므로 상주가 필요하면 다른 표면을 씁니다. 무인화할 때는 예산과 턴 상한을 같이 겁니다.

Routines

내 기계 없이 Anthropic 관리 인프라에서 Claude Code를 자동 실행합니다. 트리거는 세 가지입니다.

• 스케줄 - 매일 아침 의존성 감사 같은 정기 실행
• API 호출 - 외부 시스템이 HTTP로 루틴을 발화
• GitHub 이벤트 - 이슈, PR 이벤트에 반응

기계와 cron 관리가 필요 없고 결과는 PR과 알림으로 옵니다.

Deep Links

claude-cli://open?path=~/work/payments&prompt=결제 지연 알람 원인을 조사해

클릭하면 해당 저장소에서 프롬프트가 채워진 세션이 열립니다. 장애 런북의 알람 옆이나 온보딩 문서의 첫 작업에 심는 용도입니다. 조직은 disableDeepLinkRegistration으로 등록을 막을 수 있습니다.

--bg와 --exec

claude --bg "flaky 테스트 원인 조사"   # 세션 ID 반환, 터미널 즉시 복귀
claude logs 7c5dcf5d                 # 진행 확인
claude attach 7c5dcf5d               # 터미널로 회수
claude --bg --exec 'pytest -x'       # 셸 명령을 PTY 잡으로

--bg와 -p는 병용할 수 없습니다.

cron 레시피

# crontab -e
SHELL=/bin/bash
PATH=/usr/local/bin:/usr/bin:/bin:/home/dev/.local/bin

0 7 * * 1-5 cd /home/dev/payments && \
  ./scripts/nightly-deps-audit.sh >> ~/logs/deps.log 2>&1

cron 환경은 PATH가 빈약하므로 명시가 1번 함정입니다. 인증은 Bedrock SSO 만료를 대비한 헬퍼나 역할이 필요합니다.

 

 

---

 

Part 5. CI/CD 통합

비대화 3원칙

모든 CI 통합의 공통 골격입니다.

1. 묻지 않는다 - -p + --allowed-tools 명시로 확인 프롬프트 원천 제거
2. 넘치지 않는다 - --max-turns, --max-budget-usd, 모델 하향 기본
3. 흔적을 남긴다 - --output-format json 저장, 아티팩트 업로드

CI 인증 전략

조직 유형	방식
구독 조직	claude setup-token으로 장기 토큰 발급 후 시크릿 저장소 보관
API 조직	ANTHROPIC_API_KEY 시크릿
AWS 표준 (권장)	OIDC로 역할 인수 + Bedrock. 장기 시크릿 0
게이트웨이 조직	BASE_URL + 서비스 자격

공통으로 잡 권한을 최소화하고 키 마스킹을 확인합니다. 포크 PR에는 시크릿을 주입하지 않습니다.

GitHub Actions 기본 골격

jobs:
  deps-audit:
    runs-on: ubuntu-latest
    permissions: { id-token: write, contents: read }
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with: { role-to-assume: ${{ vars.CLAUDE_ROLE }},
                aws-region: ap-northeast-2 }
      - run: curl -fsSL https://claude.ai/install.sh | bash
      - run: CLAUDE_CODE_USE_BEDROCK=1 ./scripts/nightly-deps-audit.sh

설치는 install.sh 한 줄, 실행은 Part 2에서 만든 스크립트 재사용, 판정은 exit 게이트가 잡 성패에 직결됩니다.

PR 리뷰 잡

on: { pull_request: { types: [opened, synchronize] } }
# ... checkout(fetch-depth: 0), 인증, 설치 생략 ...
- name: Review
  run: |
    git diff origin/${{ github.base_ref }}...HEAD > pr.diff
    claude -p "pr.diff를 리뷰해 심각도별로 정리" \
      --allowed-tools "Read" "Grep" "Bash(git diff *)" \
      --max-turns 12 --max-budget-usd 1.50 \
      --json-schema "$(cat .ci/review-schema.json)" \
      > review.json
    jq -e '.block == false' review.json     # 게이트

공식 claude-code-action과 /code-review도 병행 선택지입니다.

GitLab CI

claude-review:
  stage: test
  image: ubuntu:24.04
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  before_script:
    - apt-get update && apt-get install -y curl git jq
    - curl -fsSL https://claude.ai/install.sh | bash
    - export PATH="$HOME/.local/bin:$PATH"
  script:
    - ./scripts/mr-review.sh
  artifacts: { paths: [review.json], when: always }

Jenkins, CircleCI, Buildkite도 원칙은 동일합니다. 3원칙과 exit 게이트만 지키면 플랫폼은 부차적입니다. 조직 표준 이미지에 Claude Code를 사전 설치하면 설치 단계 자체가 사라집니다.

CI 비용 통제

다이얼	방법
호출 상한	--max-budget-usd, --max-turns 필수
모델 하향	리뷰와 분류는 sonnet, haiku 기본. opus는 선별 잡만
발동 조건	paths 필터, 라벨 조건으로 잡 자체를 축소
캐시	--exclude-dynamic-system-prompt-sections + 설치 캐시
관측	review.json의 cost 집계 대시보드
조직 안전망	게이트웨이 한도, Budgets 알람 (Ch.3)

절감 효과가 가장 큰 것은 잡을 아예 안 돌리는 것입니다. 문서만 바뀐 PR은 스킵합니다.

--init 준비 훅

{ "hooks": { "Setup": [
    { "matcher": "init",
      "hooks": [{ "type": "command",
                  "command": "npm ci && cp .env.ci .env" }] } ] } }

claude -p --init "테스트 실패를 조사해 수정" ...

-p 실행 전에 init 매처 Setup 훅이 선행됩니다. 준비만 따로 검증하려면 claude --init-only로 스텝을 분리합니다.

실패 처리

• 보존 - 결과 JSON과 stderr 로그를 성패 무관하게 아티팩트로 (when: always)
• 분류 - 게이트 실패 / 실행 오류 / 상한 도달을 구분해 출력
• 표면화 - 요약을 PR 코멘트나 잡 서머리에 게시
• 재실행 - 일시 오류는 재시도 함수가 이미 흡수

완성 예시

#!/usr/bin/env bash
set -uo pipefail
git diff "origin/$BASE...HEAD" > pr.diff
OUT=$(run_claude "pr.diff 리뷰: 심각도, 사유, 차단 여부" \
  --json-schema "$(cat .ci/review-schema.json)") || exit 1
echo "$OUT" > review.json
jq -r '"### Claude Review\n" + .summary' review.json > comment.md
gh pr comment "$PR" --body-file comment.md
jq -e '.block == false' review.json   # 최종 게이트

 

 

---

 

Part 6. 자동화 패턴 5종

다섯 패턴이 공유하는 한 문장은 이것입니다. 전처리는 셸, 판정은 스키마, 액션은 CLI 도구, 실패는 큐로.

Pattern 1 - 이슈 트리아지

이슈 오픈 이벤트마다 본문을 분류해 라벨, 담당 팀, 우선순위를 제안합니다.

N=$1
gh issue view "$N" --json title,body > issue.json
OUT=$(claude --bare -p "issue.json을 분류해" \
  --model haiku --max-turns 6 \
  --json-schema "$(cat .ci/triage-schema.json)") || exit 1
LABEL=$(echo "$OUT" | jq -r '.category')
gh issue edit "$N" --add-label "$LABEL,$(echo "$OUT" | jq -r '.priority')"
echo "$OUT" | jq -r '.summary' | gh issue comment "$N" -F -

안전선은 제안까지만 하는 것입니다. 이슈를 닫는 것 같은 확정은 사람이 합니다.

Pattern 2 - 로그 분석

수십만 줄 로그를 통째로 넣지 않습니다. 셸이 압축과 분할을, Claude가 해석과 상관을 맡습니다.

grep -E 'ERROR|FATAL' app.log | \
  sed -E 's/[0-9a-f-]{36}/<id>/g' | sort | uniq -c | \
  sort -rn | head -20 > sigs.txt

while read -r line; do
  echo "$line" | claude --bare -p "이 오류 시그니처를 판정" \
    --model haiku --max-turns 4 \
    --json-schema "$(cat .ci/log-schema.json)"
done < sigs.txt | jq -s '.' > findings.json

claude -p "findings.json을 종합해 인시던트 보고 초안" --max-turns 8 > incident-draft.md

개별 판정은 haiku로 싸게, 최종 종합만 상위 모델로 1회 돌리는 map-reduce 구조입니다.

Pattern 3 - 일일 보고서

SINCE=$(date -d yesterday +%F)
{ git log --since="$SINCE" --oneline;
  gh pr list --state all --search "updated:>=$SINCE" --json number,title,state;
  gh issue list --search "created:>=$SINCE" --json number,title; } > digest.txt

claude -p "digest.txt로 팀 브리핑: 요약, 리스크, 오늘 볼 것 3" \
  --max-turns 8 --max-budget-usd 0.50 > report.md

curl -s -X POST "$SLACK_WEBHOOK" -d "$(jq -n --rawfile t report.md '{text:$t}')"

수집은 gh와 git, 서술은 Claude, 배달은 웹훅으로 분업합니다.

Pattern 4 - 문서 파이프

# 변경된 모듈만 문서 재생성
for m in $(git diff --name-only HEAD~1 | grep '^src/' | cut -d/ -f2 | sort -u); do
  claude -p "src/$m 모듈의 API 문서를 docs/$m.md로 갱신" \
    --allowed-tools "Read" "Grep" "Write(./docs/**)" --max-turns 10
done

# 갱신분만 번역
for f in $(git diff --name-only -- docs/*.md); do
  claude --bare -p "기술 용어를 보존해 영어로 번역" < "$f" > "docs/en/$(basename $f)"
done

Write(./docs/**)로 쓰기 경로를 한정하는 게 안전선입니다.

Pattern 5 - 배치 마이그레이션

파일 단위로 변환, 검증, 커밋을 원자화합니다. 실패 파일은 건너뛰고 목록에 남겨 배치가 멈추지 않게 합니다.

for f in $(cat targets.txt); do
  grep -qx "$f" done.txt 2>/dev/null && continue
  claude -p "$f 를 신규 ORM API로 마이그레이션" \
    --allowed-tools "Read" "Edit" "Bash(npm run test *)" \
    --max-turns 12 --max-budget-usd 0.80
  if npm run test -- --findRelatedTests "$f" >/dev/null; then
    git add -A && git commit -m "migrate: $f"
    echo "$f" >> done.txt
  else
    git checkout -- . && echo "$f" >> failed.txt
  fi
done

done.txt 대조가 재개 메커니즘이고, failed.txt가 사람 개입 큐입니다.

운영 조합

• 공통 골격은 run_claude + 스키마 + exit 게이트
• 이벤트형은 CI, 정기형은 cron이나 Routines
• 결과 JSON의 cost를 월간 집계해 패턴별 단가를 파악
• 신뢰는 제안만 → 게이트 → 액션 순으로 축적하고 권한도 같이 단계 상향

 

 

---

 

Part 7. 환경변수

분류 지도 7칸

분류	대표 변수
인증, 공급자	CLAUDE_CODE_USE_BEDROCK, ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL
네트워크	HTTPS_PROXY, NODE_EXTRA_CA_CERTS
모델, 사고	ANTHROPIC_MODEL, MAX_THINKING_TOKENS
기능 스위치	DISABLE_* 패밀리, CLAUDE_CODE_SIMPLE, SAFE_MODE
관측	CLAUDE_CODE_ENABLE_TELEMETRY, OTEL_*
디렉토리, 기록	CLAUDE_PROJECT_DIR, CLAUDE_CODE_SKIP_PROMPT_HISTORY

인증

export CLAUDE_CODE_USE_BEDROCK=1     # 공급자 강제 스위치
export AWS_REGION=ap-northeast-2
export ANTHROPIC_API_KEY=...          # 직결 경로 키
export ANTHROPIC_BASE_URL=https://claude-gw.corp.example
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000

서열은 플래그 > env > 설정입니다.

네트워크

프록시는 HTTPS_PROXY / HTTP_PROXY, 사내 예외는 NO_PROXY, 사내 루트 CA는 NODE_EXTRA_CA_CERTS로 넣습니다. NODE_TLS_REJECT_UNAUTHORIZED=0은 검증 무력화라 금지입니다. 진단은 curl -v로 프록시 층과 TLS 층을 분리해서 봅니다.

기능 스위치

변수	용도
DISABLE_AUTOUPDATER	자동 갱신 차단. CI 이미지용
DISABLE_AUTO_COMPACT	자동 압축 끄기
CLAUDE_CODE_DISABLE_* 군	AUTO_MEMORY, BUNDLED_SKILLS 등
CLAUDE_CODE_SIMPLE	--bare가 설정. 스크립트 감지용
CLAUDE_CODE_SAFE_MODE	--safe-mode가 설정. 훅에서 모드 인지

점검 원라이너

env | grep -iE 'claude|anthropic|otel|aws_region' | sort

유효 구성의 최종 확인은 세션 안에서 /status로 합니다. 공급자, 모델, managed 소스, 샌드박스 상태가 나옵니다.

충돌 시 서열은 managed 설정 > CLI 플래그 > env > 파일 설정입니다. 단 env가 managed의 env 블록으로 배포되면 강제층으로 승격됩니다.

보안 원칙

• 키 실값을 rc 파일에 저장 금지
• 비밀의 제자리는 helper와 OIDC
• settings의 env 블록에도 비밀 금지
• 로그와 CI 출력의 마스킹 확인

 

 

---

 

Part 8. 디버깅

진단 흐름 6단

각 단이 용의자 절반을 지웁니다.

1. 최소 재현 명령 고정
2. --verbose로 턴 출력 확대
3. --debug 카테고리로 선별 로그
4. doctor로 환경과 설정 유효성 판정
5. --safe-mode로 커스텀 원인 여부 이분
6. --bare 또는 새 디렉토리에서 격리 재현

--debug 카테고리

claude --debug "api,hooks" -p "..."        # 선택 카테고리만
claude --debug "!statsig,!file"            # ! 접두로 제외
claude --debug-file /tmp/claude-debug.log -p "..."

--debug-file은 debug를 자동 활성화하고 CLAUDE_CODE_DEBUG_LOGS_DIR보다 우선합니다. CI에서는 실패 시에만 아티팩트로 올리는 게 요령입니다.

--safe-mode 이분법

safe-mode에서 정상	safe-mode에서도 재현
범인은 커스텀 계층	범인은 코어, 환경, 네트워크
disableAllHooks로 훅 먼저 가름	doctor와 네트워크 진단표 (Ch.3)
--strict-mcp-config로 MCP 가름	버전 회귀 의심 시 install stable
커밋 이력으로 최근 변경 우선 의심	errors 레퍼런스, 이슈 검색

doctor와 auth status

claude doctor              # 설치, 설정 유효성, 무효 항목의 출처까지 표시
claude auth status --text  # 로그인 상태, 계정, 조직
claude auth status; echo $?   # 0 로그인, 1 미로그인

# CI 첫 스텝 관용구
claude auth status || { echo 'auth missing'; exit 1; }

헤드리스 전용 함정

증상	원인	처방
조용히 오래 걸림	확인 대기 상태 (allow 누락)	--allowed-tools 보강, dontAsk
결과가 잘림	stream 미수집, 파이프 버퍼	json 봉투로 수신
turns 초과 빈발	작업 대비 상한 과소	p95 재실측, 작업 분할
로컬 되고 CI 실패	설정 소스, env 차이	--setting-sources 고정
세션 못 찾음	디렉토리 다름 (ID는 프로젝트 한정)	같은 경로, 이름 재개
훅 미발화	bare 기동이 원인	bare 제거 또는 의도 확인

도움 받기

런타임 오류 메시지는 공식 errors 레퍼런스에 의미와 처방이 정리되어 있습니다. 그래도 막히면 재현 번들(버전, 명령, debug-file, doctor 출력)을 묶어 이슈 채널로 갑니다. 세션 안에서는 /bug로 바로 제출할 수 있습니다.

 

 

---

 

Part 9. Recap & Labs

챕터 요약

축	한 줄
플래그	서브커맨드 지도 2 + 서랍 6. 무인은 상한, 진단은 safe-mode
Headless	-p는 SDK 경유 단발 에이전트. 계약은 stdout, stderr, exit
구조화	--json-schema로 파싱에서 계약으로
세션	-c, -r, --from-pr, fork, 웹 왕복
표면 5	loop/goal, Desktop, Routines, CI, cron
운영	3원칙, 비용 다이얼, 실패 큐, 진단 6단

FAQ

질문	답
-p에서도 훅이 도나요	예, 전 기능 동일. --bare만 예외
왜 --max-turns가 필수인가요	기본이 무제한이라 무인 폭주 방지용
JSON을 프롬프트로 요청하면 안 되나요	--json-schema가 검증을 보증
resume이 세션을 못 찾아요	ID 검색은 프로젝트 한정
CI 인증은 뭘로 하나요	OIDC 우선, 다음 setup-token
--bare와 --safe-mode 차이는	가속 vs 진단. managed 적용 여부가 갈림

실습 랩

• Lab 1 (15분) - 세 출력 형식 비교, 봉투에서 .result와 .total_cost_usd 꺼내기, --max-turns 1로 초과 유발
• Lab 2 (25분) - 재시도 함수 완성, --json-schema 판정, jq -e 게이트 연결, nightly-deps-audit.sh 실행
• Lab 3 (25분) - GHA 워크플로 배치, 테스트 PR 생성, 코멘트와 아티팩트, block=true 유발해 게이트 실패 확인
• Lab 4 (15분) - /loop 체험, 세션 내 예약, --bg + logs + attach 왕복, crontab 등록(선택)

실무 로드맵

기간	목표
Week 1-2	개인 파이프. 일일 보고서, 트리아지 1종 가동
Week 3-6	팀 CI. PR 리뷰 잡, 비용 대장 시작
Week 7-12	확장. 배치 마이그레이션, Routines 이주

각 단계 관문은 상한 준수, 실패 큐 소화율, 월 비용 리뷰입니다.

 

 

---

 

정리

이번 챕터에서 바로 적용할 것을 추리면 다섯입니다.

1. 무인 실행에는 --max-turns와 --max-budget-usd를 반드시 건다. 기본이 무제한이다.
2. 자동화 응답은 --json-schema로 계약을 맺는다. 정규식으로 긁지 않는다.
3. 판정은 exit code와 jq -e 한 줄로 한다.
4. 도구 통제는 --allowedTools(확인 제거), --disallowedTools(제거 또는 거부), --tools(내장 한정)를 구분해 쓴다.
5. 반복은 표면 5종 중에 고른다. 세션 안이면 loop/goal, 기계 없이 정기면 Routines, 완전 통제면 cron.

다음은 Chapter 6, Agent SDK입니다. -p가 경유하던 엔진을 TypeScript와 Python 라이브러리로 직접 다루는 내용입니다.