CLAUDE.md에 규칙을 적었는데 지켜지지 않는다. 긴 세션 도중에 Claude의 정확도가 갑자기 떨어진다. 자동화를 구축했더니 한 달 예산이 몇 시간 만에 바닥났다.

이것들은 별개의 트러블처럼 보이지만, 사실 하나의 제약에서 파생된 동일한 문제다. 컨텍스트 윈도우(Context Window)는 유한하며, 수확 체감한다. Anthropic의 표현을 빌리자면 "LLM의 성능은 컨텍스트가 채워질수록 저하된다". Claude Code의 베스트 프랙티스(Best Practice)는 단편적인 팁의 모음이 아니라, 전부 이 한 지점으로부터 역산하여 만들어져 있다.

잡아야 할 것은 기능명이 아니라, **하나의 제약(컨텍스트는 유한한 자원)과 하나의 축(병렬화는 '계획을 어디에 유지할 것인가'로 선택한다)**이다. 이 두 가지를 파악하면 개별 팁을 암기하지 않고도 응용이 가능하다. 새로운 기능이 나와도 "이것은 컨텍스트의 어떤 문제를 해결하는가", "계획은 어디에 놓이는가"로 위치를 파악할 수 있다.

이 기사는 Claude Code를 "똑똑한 보완 도구"가 아니라 "개발 인프라에組み込む(組み込む, 내장하는) 자율 에이전트 기반"으로 운용하기 위한 설계를 공식 1차 정보를 바탕으로 정리한 것이다. 대상 독자는 기본적으로 사용할 줄 알지만 "왜 그렇게 해야 하는가"를 깊이 이해하고 싶은 중상급 개인 개발자다. 팀 통제나 MDM 배포 방식이 아닌, 혼자서 안전하게 자동화를 돌리는 관점에서 작성한다.

지난 1년간 일어난 일

Claude Code는 2025년부터 2026년에 걸쳐 기능을 급격히 쌓아 올렸다. 중요한 것은 각각이 "컨텍스트 유한"이라는 제약의 어떤 면을 해결했는가이다.

Anthropic은 자사에서 머지(Merge)하는 코드의 대부분을 Claude가 작성하고 있다고 공표했다. 다만 이 "80% 초과"는 논문 「When AI builds itself」(2026-06-04)의 자체 측정 결과이며, 저자 스스로가 "속성화 파이프라인은 불완전하며 보수적인 추정"이라고 주석을 달았다. 다른 추정(Redwood Research의 Greenblatt)에서는 "전사 평균은 약 50%, 일부 팀은 90%"라고 하며, 측정 정의에 따라 숫자는 크게 움직인다. 맹신할 숫자는 아니지만, "보완을 넘어선 사용법이 실제로 돌아가고 있다"는 방향성은 확실하다.

그리고 간과하기 쉬운 전제 변경이 있다. 2026년 6월 15일부터, Claude Code의 프로그래밍적 이용(claude -p / Agent SDK / GitHub Actions)이 대화적 이용과는 별도의 크레딧 범위로 과금된다. 자동화를 헤비하게 돌리는 사람일수록 여기서 비용 구조를 재검토할 필요가 생겼다(제5장).

제1장: 모든 기점은 "컨텍스트는 유한한 자원"이다

CLAUDE.md가 200행에서 효과가 없어지는 이유

공식은 "CLAUDE.md는 파일당 200행 미만을 기준으로 삼으라"고 적고 있다. 원문은 다음과 같다.

Target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. (CLAUDE.md는 파일당 200행 미만을 목표로 하세요. 파일이 길어지면 더 많은 컨텍스트를 소비하고 준수율을 떨어뜨립니다.)

여기서 멈추면 "경험칙이니까"라고 끝날 것이다. 하지만 공식 문서에는 그 배후의 구조가 적혀 있다.

CLAUDE.md content is delivered as a user message after the system prompt.

즉 CLAUDE.md는 시스템 프롬프트(System Prompt)가 아니다. 시스템 프롬프트 다음에 사용자 메시지(User Message)로서 주입된다. 따라서 처음부터 "절대적인 규칙"으로 취급될 보장이 없으며, 길어지면 다른 문맥에 파묻혀 규칙이 희석된다. 공식의 베스트 프랙티스(Best Practices)는 더 직설적이다.

Bloated CLAUDE.md files cause Claude to ignore your actual instructions!

규칙을 적었는데 지켜지지 않는다면, 파일이 너무 길어서 규칙이 가라앉았을 가능성이 높다. 가지치기 기준은 심플하다. "그 행을 삭제했을 때 Claude가 틀리는가?" 틀리지 않는다면 지운다.

컨텍스트를 절약하는 도구들

CLAUDE.md를 짧게 유지하면서 정보를 잃지 않기 위한 수단.

: CLAUDE.md 본체에는 요점만 적고, 상세 내용은 별도 파일로 분할할 수 있다. 단, import는 @path/to/file

import 구문은 기동 시에 전개되어 컨텍스트에 로드되므로, 토큰 자체는 절약되지 않는다 (어디까지나 정리를 위한 메커니즘이다). 정말로 지연 로딩 (Lazy Loading)을 하고 싶다면, 다음의 Just-in-time 획득이나 .claude/rules/의 paths 조건 로드, Skills, Auto Memory의 토픽 파일 (온디맨드 로딩)을 사용한다.

• HTML 주석: Claude는 이를 읽지 않으므로, 토큰을 소비하지 않고 유지보수 메모를 남길 수 있다. <!-- -->

• Just-in-time 획득: 사전에 전부 RAG로 채워 넣는 것이 아니라, glob / grep으로 파일을 동적으로 로드하게 한다. 컨텍스트에 로드되는 것은 "지금 필요한 만큼"뿐이게 된다.

• Auto Memory: MEMORY.md (~/.claude/projects/<project>/memory/MEMORY.md)는 기동 시에 처음 200행 또는 25KB (더 작은 쪽)만 읽히며, 토픽별 파일은 온디맨드로 열린다 (v2.1.59 이후, CLAUDE_CODE_DISABLE_AUTO_MEMORY=1로 무효화 가능). 무엇을 쓸지에 대한 판단 로직은 공식적으로 상세 내용이 비공개이며, 매 세션마다 작성하는 것은 아니다.

/compact ・ /clear ・ /rewind 의 구분 사용

긴 세션에서는 컨텍스트 청소가 곧 성능으로 이어진다.

• /compact: 오래된 도구 출력부터 먼저 지우고, 필요하다면 대화를 요약한다. 사용자의 요청과 주요 코드는 남지만, /compact를 사용하면 대화 초기의 세세한 지시는 유실될 수 있다. 따라서 중요한 제약 사항은 CLAUDE.md에 두어야 한다.

• /clear: 동일한 수정을 두 번 반복한다면 문맥이 오염되었다는 신호다. /clear를 하고 제대로 된 프롬프트로 다시 시작하는 것이 더 빠른 경우가 많다.

• /rewind: 체크포인트로 되돌리기. 단, 이것은 Claude의 변경 사항만을 추적하는 안전망이며, git의 대체재가 아니다.

/compact 이후의 재주입(Re-injection)에는 세세한 규칙이 있다. 프로젝트 루트의 CLAUDE.md는 디스크에서 다시 읽어오지만, 서브 디렉토리의 CLAUDE.md는 다음에 해당 디렉토리의 파일을 건드리기 전까지 재주입되지 않는다. 스킬(Skills) 목록은 컴팩트 이후에 재주입되지 않는 유일한 기동 시 컨텍스트다.

자동 컴팩트 임계값은 공식 문서 간에 차이가 있다

환경 변수 문서에서는 발화 임계값을 "약 95%"로 규정하지만, 소스 분석(GitHub issue #31806)에 따르면 "effectiveWindow − 13,000 ≒ 200k 모델에서 약 83.5%"이다. 어느 쪽이 현재의 정확한 값인지는 확정되지 않았다. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE는 내부의 Math.min 클램프(Clamp)로 인해 "임계값을 낮추는 방향"으로만 작동한다는 점에도 주의해야 한다.

제2장: CLAUDE.md는 "부탁", Hooks는 "CI"

제1장에서 보았듯이, CLAUDE.md의 지시는 **권고적 (advisory)**이다. ".env를 읽지 마"라고 써두어도 Claude는 가끔 이를 어긴다. 나중에 주입되는 사용자 메시지인 이상, 준수는 확률적으로만 이루어진다.

반면, Hooks는 **결정론적 (deterministic)**이다. .env에 대한 접근을 exit 2로 차단하면, Claude가 어떻게 판단하든 실행은 일어나지 않는다. CI가 "테스트가 실패하면 머지(Merge)시키지 않는다"와 같은 강제력으로 작동하며, 환각 (Hallucination)이 끼어들 여지가 없다. 이 "부탁 vs 강제"의 경계선이 안전하게 자율 실행을 시킬 수 있는지의 갈림길이 된다.

exit code의 의미

Hooks의 동작은 exit code로 결정된다.

• exit 2: 도구 실행을 차단하며, exit 2의 stderr 내용이 Claude에게 전달되는 피드백이 된다.

• exit 0: 통과시킨다. stdout의 취급은 이벤트에 따라 다르며, exit 0 SessionStart 등에서는 자동으로 컨텍스트에 들어간다 (후술).

• 그 외: 비차단(Non-blocking) 에러 취급.

중요한 제약 사항으로, 실행 전에 차단할 수 있는 것은 PreToolUse 훅뿐이다. PostToolUse는 도구 실행 "이후"에 호출되므로, exit 2를 내더라도 실행 자체를 멈출 수는 없다 (lint나 포맷팅 같은 후처리 작업에 적합).

우선 도입해야 할 최소 안전장치 세트

개인적으로 자율성을 높이려 한다면, 가장 먼저 도입해야 할 것은 이것뿐이다. .env의 보호와

위험한 명령이다. 흔히 발생하는 사고의 대부분은 이 두 가지에서 멈춘다.

rm 명령어를 .claude/settings.json의 block에 등록하면, 여러 머신 간에 동일한 안전장치를 재현할 수 있다. 아래의 JSON은 파일 보호(protect-files.sh)와 위험 명령 검사(pre_tool_use.py) 둘 다를 동일한 PreToolUse에 나란히 등록하는 형태다.

bash / uv run을 통해 호출하므로 실행 권한 부여(chmod)는 필요 없다.

{
"hooks": {
"PreToolUse": [
...

block 본체(공식 문서의 최소 형태). stdin으로부터 JSON을 받아 tool_input.file_path를 jq로 추출한다. 이 입출력 타입을 벗어나면 동작하지 않는다.

#!/bin/bash
# .claude/hooks/protect-files.sh
INPUT=$(cat)
...

이 매칭은 부분 일치이므로 .env.example이나 .env.sample도 포함된다. 템플릿 계열을 허용하려면 제외 조건을 추가해야 한다. 또한 file_path만 확인하기 때문에, cat .env와 같은 Bash를 통한 읽기는 막을 수 없다. 거기까지 방어하려면 permissions.deny(예: "Read(.env)" / "Read(.env.*)")를 병용한다.

rm -rf와 같은 위험한 명령까지 막으려면, Bash 명령어를 정규 표현식으로 검사한다. 아래는 커뮤니티 구현체(disler/claude-code-hooks-mastery)이며, 공식이 아니라는 점에 주의하라.

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.8"
...

편집 후 자동 포맷팅 (공식)

PostToolUse에서 Edit / Write에 매칭시켜, 편집된 파일에 Prettier를 적용한다. lint나 타입 체크도 동일한 방식으로 추가할 수 있다.

{
"hooks": {
"PostToolUse": [
...

같은 요령으로 SessionStart hook을 사용하면, 세션 시작 시 git 브랜치, 차이점(diff), 오픈된 GitHub Issue를 컨텍스트에 자동으로 주입할 수 있다(SessionStart의 stdout은 자동으로 컨텍스트에 들어간다). "지금 어떤 브랜치에서 무엇을 하고 있는지"를 Claude에게 매번 상기시켜야 하는 번거로움이 사라진다.

배치 스코프 (Placement Scope)

settings.json의 hook은 3단계 계층에 둘 수 있다.

• ~/.claude/settings.json: 사용자 전체
• .claude/settings.json: 리포지토리에 둘 수 있으므로, 여러 머신 간에 (필요하다면 팀 단위로도) 동일한 안전장치를 재현할 수 있음
• .claude/settings.local.json: 로컬 전용

동일한 이벤트에 여러 hook이 매칭되면 병렬로 실행되며, 단 하나라도 deny 판정이 있으면 deny가 승리한다 (가장 제한적인 판단이 우선된다). 안전장치를 가산(addition) 방식으로 겹쳐 쌓을 수 있는 설계다.

제3장: 병렬화는 "계획을 어디에 유지할 것인가"로 선택한다

서브 에이전트(Sub-agent), 에이전트 팀(Agent Team), 동적 워크플로우(Dynamic Workflow)——이름은 알고 있어도, 언제 무엇을 사용해야 하는지 한마디로 말할 수 있는 사람은 적다. 판단 기준은 사실 하나뿐이다. 중간 결과(계획)가 어디에 유지되는가. 이것을 알면, 단순(Simple) → 비교(Comparison) → 팬아웃(Fan-out) 규모에 따라 유일하게 선택할 수 있다.

이후의 각 절은 이 표의 각 행을 분해한 것이다.

서브 에이전트의 정의 (공식)

.claude/agents/<name>.md에 frontmatter + 본문으로 정의한다. 필수 항목은 name과 description뿐이다.

---
name: code-reviewer
description: 코드의 품질과 보안을 리뷰한다. 차이점이 발생하면 사용한다.
...

실무에서 유효한 포인트:

• isolation: worktree를 사용하면 임시 git worktree 내에서 실행할 수 있습니다. 병렬로 파일을 수정하더라도 충돌이 발생하지 않습니다 (변경 사항이 없으면 worktree는 자동으로 삭제됩니다).

• 모델의 해결 순서는 다음과 같습니다:
  CLAUDE_CODE_SUBAGENT_MODEL (환경 변수) > 호출 시 지정 > frontmatter > 부모 대화. 기본값은 inherit입니다.

• tools는 화이트리스트(whitelist)이며, disallowedTools는 블랙리스트(blacklist)입니다 (후자가 우선 적용됩니다). DB를 읽기 전용(read-only)으로 제한하는 등의 제어에 사용됩니다.

• 서브 에이전트(sub-agent)는 서브 에이전트를 생성(spawn)할 수 없습니다 (중첩 불가). 깊은 재귀(recursion)를 기대해서는 안 됩니다.

Dynamic Workflows (research preview)

10개를 초과하는 팬아웃(fan-out)에는 동적 워크플로우(Dynamic Workflows)가 적합합니다. 계획을 스크립트 변수로 외부화하므로 메인 컨텍스트(context)가 고갈되지 않습니다.

• v2.1.154 이후 및 모든 유료 플랜에서 사용 가능합니다 (Pro 플랜은 Config에서 활성화 필요).
• 병렬 상한은 동시 16개 에이전트 / 1회 실행 총합 1,000개입니다.
• 트리거는 ultracode입니다 (이전 명칭 workflow, v2.1.160 이후). /effort ultracode로 진입하며, 이는 순수한 모델의 추론 노력(reasoning effort) 값이 아니라, "xhigh 급의 사고 + 워크플로우 편성"을 한꺼번에 켜는 Claude Code 측의 설정입니다.
• 스크립트는 JavaScript (ESM)입니다. 결정론(determinism)을 유지하기 위해 시간이나 난수를 반환하는 비결정론적 API (Date / Math.random 계열)는 런타임 에러를 발생시킵니다 (타임스탬프는 인자로 전달해야 합니다).
• 비활성화하려면 CLAUDE_CODE_DISABLE_WORKFLOWS=1을 사용합니다.

Agent Teams (실험적)

팀원들끼리 공유된 태스크 리스트(task list)를 통해 직접 통신하는 메커니즘입니다. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1로 활성화하며, 최소 v2.1.32 이상, 권장 인원은 3~5명입니다. 단, 기본적으로 비활성화되어 있으며 GA(General Availability)에 도달하지 않았고, 알려진 제한 사항이 많습니다 (/resume · /rewind로 복구 불가, 1개 리드당 1개 팀, 중첩 불가, 생성 후 권한 모드(permission mode) 변경 불가 등). 개인 개발에서 상시 사용하는 단계는 아니라는 관점으로 접근하는 것이 정확합니다.

병렬화의 효과 (숫자 취급 주의)

Anthropic은 공식 블로그(2025-06-13)를 통해, 멀티 에이전트 구성이 단일 에이전트 대비 90.2%의 성능 향상을 보였으나, 토큰 소비는 약 15배에 달한다고 보고했습니다. 이는 자사의 내부 리서치 평가(약 20개 쿼리, LLM-as-judge 채점, 비교 대상은 단독 Opus 4) 결과이며, 일반적인 멀티 에이전트 지표로 독자적으로 해석해서는 안 됩니다. 해당 기사는 동일한 내부 평가에서 "토큰 사용량만으로 성능 분산의 약 80%를 설명할 수 있다"라고도 언급하고 있으므로, 성능과 비용은 세트로 읽는 것이 옳습니다.

제4장: 안전하게 손을 떼는 법 — auto mode · sandbox · 체크포인트

자율성을 높일 때 가장 큰 적은 "승인 피로(approval fatigue)"입니다. Anthropic의 사내 텔레메트리(telemetry)에 따르면, 사용자는 승인 프롬프트의 약 93%를 그대로 허용합니다 (측정 기간 및 대상 수는 미공개, 독립 검증 없음). 매번 나오는 Yes/No에 사람은 익숙해지며, 확인 절차는 형식적으로 변합니다. 반면 --dangerously-skip-permissions를 사용하여 모두 건너뛰면, 홈 디렉토리를 통째로 삭제하는 것과 같은 사고가 실제로 발생합니다.

Claude Code는 이 모순을 3단계 방어로 해결하려 합니다.

auto mode

--permission-mode auto는 입력층의 프로브(probe)와 출력층의 분류기(classifier)라는 2단계를 통해 조작의 위험도를 판정하고, 승인 필요 여부를 자동으로 결정합니다. Anthropic은 사내 실제 트래픽(n=10,000)에서 이 분류기의 **오탐률(FPR)이 0.4%**라고 보고했습니다. 다만 이는 "정상적인 조작을 실수로 차단하는 비율"이며, 같은 기사에서는 **위험한 조작을 놓칠 확률(FNR)이 17%**라고 병기했습니다 (둘 다 Anthropic의 사내 측정 결과이며, 독립 검증은 없습니다). 0.4%라는 수치만 따로 떼어 보지 마십시오. 안전한 방향으로 운용하려면 후속 단계인 샌드박스(sandbox)와 병용한다는 전제가 필요합니다. 참고로 --permission-mode auto

의 이용 가능 여부는 버전이나 플랜에 따라 다르므로(사용할 수 없는 환경도 있음), 자신의 환경에서 확인해야 한다.

sandboxing

/sandbox는 Linux에서는 bubblewrap, macOS에서는 seatbelt를 사용하여 OS 레벨의 격리(isolation)를 수행하며, 네트워크는 Unix 도메인 소켓(Unix domain socket) 프록시를 경유한다. Anthropic의 사내 측정에 따르면 승인 프롬프트(approval prompt)를 약 84% 감소시켰다고 한다(조건은 비공개이며, 독립적인 측정 결과는 없음. 또한 공식 문서의 sandboxing 페이지에는 이 84%라는 수치가 기재되어 있지 않으며, 엔지니어링 블로그에서 유래한 정보이다).

설계상의 비자명한(non-trivial) 원칙이 하나 있다. 공식적으로는 파일 시스템 격리와 네트워크 격리 모두를 필수 사항으로 규정하고 있다. 한쪽만으로는——예를 들어 네트워크가 열려 있다면, 쓰기 권한을 제한하더라도 외부에서 코드나 비밀 정보를 주고받을 수 있기 때문에——격리의 의미가 퇴색된다는 논리다.

체크포인트와 예산 상한

• 체크포인트: 변경 전 상태로 되돌리는 안전망. 추적하는 것은 Claude의 파일 편집 도구에 의한 변경뿐이며, Bash의 /rewind (Esc+Esc), rm, mv 또는 외부로부터의 변경은 되돌릴 수 없다. 앞서 언급했듯이 git의 대체재가 아니다.
• SDK의 예산 가드(budget guard): Agent SDK에서는 max_budget_usd (Python) / maxBudgetUsd (TS)로 USD 상한을, max_turns / maxTurns로 턴(turn) 상한을 설정할 수 있다. 자동화를 돌린다면 반드시 이것으로 폭주를 막아야 한다.
• 폭주 방지를 위해, 연속 또는 누적 일정 횟수만큼 차단되면 세션이 정지되는 메커니즘도 있다.

여기에서의 설계 사상은 "조직이 개인을 통제한다"가 아니라, **"자신이 자신의 폭주를 멈출 장치를 미리 만들어 둔다"**이다. 혼자서 안전하게 자동화를 돌리기 위한 기반 시설이다.

제5장: headless · CI · 비용 — Unix 파이프로 통합하기

Claude Code의 구조적인 강점은 claude -p를 통해 **stdin → stdout의 Unix 파이프(pipe)**로 동작할 수 있다는 점이다. GUI를 전제로 하는 도구에는 이러한 합성성(composability)이 없다.

# 차이점(diff)을 리뷰하게 하고 결과를 JSON으로 받기
git diff | claude -p "이 차이점을 리뷰하고, 중대한 문제만 지적해줘" \
--output-format json

꼭 알아두어야 할 플래그:

• --output-format json / stream-json, --json-schema를 통한 구조화된 출력(structured output). 후속 스크립트에서 파싱하기 쉽다.
• --bare: hooks/skills/MCP/CLAUDE.md의 탐지를 스킵하여 빠르고 재현성 있게 동작시킨다 (향후 기본값으로 설정될 예정임).
• --allowedTools 'Bash(git diff *)'의 접두사 매칭(prefix match)을 통해 허용할 명령어를 제한한다 (끝에 공백 유무에 따라 동작이 달라지는 점에 주의).
• 팬아웃(fan-out): 파일 단위의 대규모 변환을 쉘(shell)에서 실행한다 (공백이 포함된 경로에서도 깨지지 않는 형태로).

while IFS= read -r f; do
claude -p "다음 파일을 리뷰해줘: $f" < "$f"
done < files.txt

이 장의 핵심은 2026/6/15의 과금 분리

claude -p나 SDK로 자동화를 돌린다면, 실무에 가장 큰 영향을 미치는 것은 비용이다. 같은 Claude Code라도 인증 경로에 따라 크레딧 지갑이 두 개로 나뉜다.

• 분기는 UI의 외형이 아니라 인증 방식에 의해 결정된다. 핵심은 "구독 인증인가, API 키인가"이다.
• 인터랙티브한 구독 이용(터미널의 Claude Code, claude.ai의 각 클라이언트, Cowork)은 기존 구독 범위 내에 있으며 변경 사항이 없다. 터미널에서 대화만 하는 개인 개발자는 실질적인 영향을 받지 않는다.
• 구독 인증을 통한 프로그래밍적 이용(claude -p, Agent SDK, GitHub Actions)이 이번 변경의 본체다. 신설된 월간 "프로그래밍적 크레딧" (구독과 동일 금액: Pro=$20 / Max5x=$100 / Max20x=$200, 이월 불가)을 API의 종량제 단가로 소비한다.
• ANTHROPIC_API_KEY를 통한 이용은 원래 API 종량제(PAYG)로 구독과는 독립되어 있다. 이번 분리의 영향을 받지 않는다.

개인 개발자가 유의해야 할 점은 세 가지다.

• Pro의 $20는 자동화에는 적다. Sonnet 4.6 기준으로 1 세션당 500K~1M 토큰이 전형적이므로, claude -p를 일상적으로 실행하면 몇 시간 또는 수십 회 만에 고갈될 수 있다. 대화 작업과 CI/스크립트의 용도를 분리하는 것이 사실상의 전제 조건이 된다.
• overflow billing (Usage Credits)의 On/Off는 중단 리스크와 비용 무제한(unlimited) 리스크 사이의 트레이드오프(trade-off)다. 활성화되어 있으면 고갈 후에도 API 종량제 단가로 계속 진행되지만(중단되지는 않으나 비용이 무제한으로 발생 가능), 비활성화되어 있으면 월간 리셋까지 중단된다(상한선은 적용되지만 월중에 CI가 멈춤). 참고로 '기본값 비활성화'는 여러 서드파티(third-party) 기사의 기술 내용이며, 공식 문서에서 명시적인 확인은 되지 않았다.
• 비용 최소화는 세 가지 계층으로 생각한다.
  • Prompt Caching: 동일한 시스템 프롬프트(System Prompt)를 반복하는 에이전트(Agent) 루프에서 입력 비용을 최대 90% 절감 (공식에서 제시하는 상한값이며, 실제 효과는 캐시 히트율(cache hit rate)에 따라 다름. 5분 캐시는 1회 히트 시 수익성을 확보할 수 있음).
  • 모델 라우팅 (Model Routing): 단순 작업은 Haiku 4.5(Sonnet의 약 1/3 단가)로 보냄.
  • Batch API: 실시간성이 필요 없는 정형 체크는 모든 모델에서 50% 할인.

API 단가 기준(2026-06)은 Sonnet 4.6 = $3/$15, Opus 4.x = $5/$25, Haiku 4.5 = $1/$5 (per MTok)이다. Opus 4.7 이후는 새로운 토크나이저(tokenizer)를 사용하여 동일한 텍스트라도 최대 35% 더 많은 토큰을 소비할 수 있으므로(공식 토크나이저 변경 공지 기준), 견적에 이를 반영해야 한다. Opus 4.8에는 약 2.5배 빠른 Fast Mode($10/$50)도 있지만, Batch API와는 병행 사용할 수 없다.

스케줄 실행과 CI

GitHub Actions에는 claude-code-action@v1이 있어, on.schedule.cron이나 PR 이벤트로 실행할 수 있다. 나아가 Routines (research preview)를 사용하면 Scheduled / API / GitHub의 세 가지 트리거를 통해 Anthropic이 관리하는 클라우드 상에서 실행되므로, 로컬 PC의 전원이 꺼져 있어도 작동한다. API 트리거는 다음과 같은 형태다.

curl -X POST https://api.anthropic.com/v1/claude_code/routines/{trig_ID}/fire \
-H "Authorization: Bearer $ROUTINE_TOKEN" \
-H "anthropic-beta: experimental-cc-routine-2026-04-01" \
...

인증은 Anthropic API 키가 아니라, 라우팅마다 발행되는 Bearer 토큰을 사용한다 (research preview 단계이므로 상세 내용은 확인이 필요하다). 일일 실행 횟수 상한은 서드파티 보고에 따르면 Pro=5 / Max=15 등으로 알려져 있으나, 공식 문서에 숫자가 명시되어 있지는 않다.

제6장: 별도 카테고리로서의 위치 선정 (Cursor/Copilot 비교)

Claude Code를 'IDE 보완의 상위 호환'으로 비교하는 것은 논점에서 벗어난다. 이것은 선택하는 상황이 다른 별개의 카테고리다. 또한 정량적 비교는 출처가 모두 비대칭적(모델 차이, 이해관계 상충, 피어 리뷰 전)이므로, 숫자가 아닌 구조적 차이로 선택해야 한다.

이 장의 결론을 먼저 제시한다. 갈아타는 것이 아니라 병용하는 것이 현실적인 해답이며, 선정은 구조에 따라 결정한다.

구조적 차이:

• 터미널 네이티브 (Terminal Native): 전장에서 언급했듯이 셸 파이프(shell pipe) 및 스크립트로 합성할 수 있다. Cursor는 VS Code의 GUI 포크(fork)이며, Copilot 역시 GUI를 전제로 하기에 CI/cron/headless 파이프라인에 통합하기가 구조적으로 어렵다.
• 결정론적 훅 (Deterministic Hooks): 모델의 판단에 의존하지 않는 강제력 레이어 (제2장). 안전장치나 품질 게이트(quality gate)를 모델에 맡기지 않고 고정할 수 있다.
• 병렬 서브 에이전트 / 동적 워크플로우 (Parallel Sub-agents / Dynamic Workflow): 계획을 스크립트 변수로 외부화하여 동시에 병렬로 실행한다 (제3장).
• 안전망 (Safety Net): /rewind · 샌드박스(sandbox) · 분류기(classifier)의 다층 방어 (제4장).

일상적인 세밀한 편집은 IDE 통합(Cursor 등)이 빠르고, 복잡한 태스크, 병렬 조사, 자동화는 Claude Code가 적합하다. AI 생성 코드는 그에 상응하는 디버깅을 요하는 만큼, 어떤 도구를 사용하더라도 리뷰를 거친다는 전제는 변하지 않는다.

인용되는 정량적 비교의 출처와 그 할인율

• 토큰 효율 「Cursor 대비 5.5배 (188K vs 33K)」: Ian Nuttall 씨의 비공식적인 일회성 벤치마크로, Next.js + Tailwind + shadcn 구축 태스크에 대한 결과이다. Claude Code 측은 Opus를, Cursor 측은 GPT-5를 사용하여 모델이 다르기 때문에, 도구의 차이와 모델의 차이가 분리되지 않았다. 순수한 「5.5배」라는 수치로 사용하기에는 부적절하다.
• SWE-bench Verified 88.6% (Opus 4.8) / Pro 69.2%: System Card에서 기원하였으며, 여러 제3자(Third-party)가 일치하게 인용하고 있다. 신뢰도는 비교적 높으나, PDF 원문의 해당 부분은 직접 확인하지 않았다.
• 「AI 생성 변경 사항의 약 43%가 추가 디버깅을 요함」: Lightrun 사의 리포트 (2026-04, SRE/DevOps 200명 대상). 발주처가 AI 디버깅 도구 벤더로서 이해 상충(Conflict of Interest)의 소지가 있다. AI 코드는 리뷰가 필수적이라는 논지를 보강하는 용도로는 사용할 수 있다.
• 「코드베이스의 98.4%는 AI 추론이 아닌 운영 인프라(Operational Infrastructure)」: arXiv의 프리프린트 (Peer-review 전, 분류 정의는 비공개). 독립적인 사실로 사용하지 않고, 「에이전트의 대부분은 지루한 배관 작업(Plumbing)으로 이루어져 있다」는 정성적인 방증으로만 남겨둔다.

요약: 기능이 아니라, 하나의 제약과 하나의 축을 기억할 것

이 글에서 다룬 도구는 많지만, 척추는 단 두 개뿐이다.

• 모든 것은 컨텍스트(Context)가 유한한 자원이라는 점에 대한 대책이다. CLAUDE.md의 200행 제한도, /compact