시리즈를 시작하며 — 왜 “끝까지” 써봐야 하는가

Claude Code는 단순한 코드 자동완성 도구가 아닙니다. 터미널 안에서 파일을 읽고, 수정하고, 명령을 실행하고, 심지어 다른 에이전트에게 작업을 위임하기까지 하는 완전한 소프트웨어 엔지니어링 에이전트입니다. 그런데 대부분의 사용자는 “코드 짜줘”라고 말한 뒤 결과만 받아 보는 수준에서 멈춥니다. 이 시리즈는 그 벽을 넘기 위해 기획했습니다.

총 6편으로 구성된 “Claude Code, 끝까지 써보기” 시리즈의 로드맵은 다음과 같습니다.

• 1편(이번 글) — 코어 메커니즘: 모델 라인업, 권한 모드, 컨텍스트 운용, CLAUDE.md 계층
• 2편 — 슬래시 커맨드 30+종 치트시트와 세션 라이프사이클 마스터
• 3편 — 확장 생태계: MCP · Plugins · Skills 완전 정복
• 4편(상) — Hooks: 에이전트의 자율성과 통제의 경계선
• 4편(하) — Subagents: 멀티 에이전트 오케스트레이션
• 5편 — Remote Control · Cloud · 관측: 24/7 운영급으로 끌어올리기

각 편은 독립적으로 읽을 수 있지만, 순서대로 읽으면 Claude Code의 전체 그림이 머릿속에 완성됩니다. 자, 그럼 1편을 시작합니다.

1. 모델 라인업과 Effort 레벨 — 같은 도구, 다른 두뇌

Claude Code를 실행하면 내부적으로 Anthropic의 Claude 모델이 동작합니다. 2026년 4월 현재, Claude Code에서 사용할 수 있는 모델 패밀리는 Claude 4.5/4.6 세대입니다. 구체적으로 살펴보겠습니다.

1-1. 모델 패밀리 정리

• Claude Opus 4.6 (claude-opus-4-6) — 최상위 모델. 복잡한 아키텍처 설계, 대규모 리팩터링, 멀티파일 수정에 적합합니다. 1M 토큰 컨텍스트 윈도우를 완전히 활용할 수 있는 유일한 모델이기도 합니다.
• Claude Sonnet 4.6 (claude-sonnet-4-6) — 속도와 품질의 균형점. 일상적인 코딩 작업, 버그 수정, 단일 파일 수정에 가장 많이 쓰입니다.
• Claude Haiku 4.5 (claude-haiku-4-5-20251001) — 가장 빠른 응답. 간단한 질문, 파일 탐색, 빠른 검토 작업에 적합합니다.

모델 전환은 /model 슬래시 커맨드로 세션 중에도 가능합니다. 하지만 모델 선택보다 더 실질적으로 체감되는 것이 바로 Effort 레벨입니다.

1-2. Effort 레벨의 실제 동작 차이

Effort 레벨은 모델이 응답을 생성할 때 얼마나 깊이 생각할지를 제어하는 메커니즘입니다. /effort 커맨드로 조절하며, 총 4단계가 있습니다.

• low — 최소한의 추론. 단순 질문, “이 변수 이름 뭐야?” 수준의 작업에 적합합니다. 내부적으로 extended thinking이 비활성화되며, 토큰 소비가 가장 적습니다.
• medium — 기본적인 추론 체인을 활성화합니다. 단일 파일 버그 수정, 간단한 리팩터링에 충분합니다.
• high (기본값) — 깊은 추론 모드. 멀티파일 수정, 아키텍처 결정, 복잡한 디버깅에서 진가를 발휘합니다. extended thinking이 완전히 활성화됩니다.
• xhigh — 최대 추론 깊이. 모델이 응답 전에 가장 오래 “생각”합니다. 복잡한 알고리즘 설계, 보안 취약점 분석, 대규모 마이그레이션 계획 수립에 사용합니다.

실무 기준으로 effort 레벨 선택 가이드를 정리하면 다음과 같습니다.

• “이 파일에서 함수 이름 바꿔줘” → low 또는 medium
• “이 테스트가 왜 실패하는지 찾아서 고쳐줘” → high
• “이 레거시 시스템을 마이크로서비스로 분리하는 설계를 해줘” → xhigh

핵심은 effort가 높을수록 토큰 소비량과 응답 시간이 비례해서 증가한다는 점입니다. xhigh로 모든 작업을 처리하면 비용이 급증하고, low로만 쓰면 복잡한 작업에서 품질이 떨어집니다. 상황에 맞게 슬라이더를 조절하는 것이 Claude Code 활용의 첫 번째 노하우입니다.

1-3. Fast 모드의 진실

Claude Code에는 /fast 토글이 있습니다. 많은 분이 “더 저렴한 모델로 바뀌는 거 아냐?”라고 오해하시는데, Fast 모드는 같은 Claude Opus 4.6 모델을 사용하되 출력 속도를 최적화한 모드입니다. 모델 자체가 바뀌는 것이 아니라, 출력 생성 파이프라인의 처리 방식이 달라지는 것입니다. 따라서 품질 저하 없이 체감 속도를 높일 수 있습니다.

2. 권한 모드 — 에이전트의 자유도를 설계하다

Claude Code가 다른 AI 코딩 도구와 가장 크게 구별되는 지점이 바로 권한 모드 시스템입니다. 에이전트가 파일을 수정하고, 셸 명령을 실행하고, 외부 서비스에 접근하는 모든 행위에 대해 세밀한 통제 체계가 존재합니다.

2-1. 네 가지 권한 모드

Claude Code는 네 가지 권한 모드를 제공합니다. 각 모드는 에이전트의 자율성 수준을 결정합니다.

• Default 모드 — 가장 보수적입니다. 파일 읽기와 같은 안전한 작업은 자동으로 허용되지만, 파일 수정이나 셸 명령 실행은 매번 사용자에게 승인을 요청합니다. 처음 Claude Code를 사용할 때 기본으로 적용되는 모드이며, 에이전트의 동작을 하나하나 확인하고 싶을 때 적합합니다.
• Plan 모드 — 실행 없이 계획만 세우는 모드입니다. 코드를 읽고 분석하지만, 실제로 파일을 수정하거나 명령을 실행하지는 않습니다. 대규모 리팩터링이나 마이그레이션을 시작하기 전에 “어떤 파일을 어떻게 바꿀 건지” 계획서를 먼저 받아보고 싶을 때 사용합니다. Plan 모드에서 계획을 확인한 뒤 Auto 모드로 전환해서 실행하는 패턴이 실무에서 매우 효과적입니다.
• Auto 모드 — 허용된 도구에 대해서는 사용자 확인 없이 자동으로 실행합니다. settings.json에서 허용할 도구와 명령을 미리 정의해두면, 에이전트가 해당 범위 내에서 자율적으로 작업합니다. 반복적인 작업이나 잘 정의된 작업에서 생산성이 크게 향상됩니다.
• –dangerously-skip-permissions — 이름 그대로, 모든 권한 검사를 건너뜁니다. CI/CD 파이프라인이나 완전히 격리된 샌드박스 환경에서만 사용해야 합니다. 개발 머신에서 이 옵션을 켜는 것은 매우 위험하며, 에이전트가 시스템 파일을 수정하거나 의도치 않은 명령을 실행할 수 있습니다.

2-2. 입력·출력 이중 분류기의 동작 원리

Claude Code의 권한 시스템 내부에는 이중 분류기(Dual Classifier)가 작동합니다. 이것은 보안의 핵심입니다.

입력 분류기(Input Classifier)는 사용자의 프롬프트와 도구 호출 요청을 분석합니다. 예를 들어 사용자가 “시스템의 모든 파일을 삭제해줘”라고 요청하면, 입력 분류기가 이를 위험한 요청으로 분류하고 실행을 차단합니다. 이 분류기는 다음을 검사합니다.

• 요청된 작업의 가역성(reversibility) — 되돌릴 수 있는 작업인가?
• 작업의 영향 범위(blast radius) — 로컬에만 영향을 미치는가, 외부 시스템에도 영향을 미치는가?
• 파괴적 패턴 매칭 — rm -rf, force push, DROP TABLE 같은 위험 패턴을 포함하는가?

출력 분류기(Output Classifier)는 모델이 생성한 응답을 실행하기 전에 한 번 더 검증합니다. 모델이 의도치 않게 위험한 명령을 생성했거나, 프롬프트 인젝션 공격에 의해 조작된 응답을 만들었을 때 이를 잡아냅니다. 구체적으로는 다음을 검사합니다.

• 도구 호출 파라미터에 인젝션 패턴이 포함되어 있는지
• 파일 수정 내용이 보안 취약점(OWASP Top 10)을 도입하는지
• 셸 명령이 허용된 범위를 벗어나는지

이 이중 분류기 덕분에 Auto 모드에서도 기본적인 안전망이 유지됩니다. 하지만 --dangerously-skip-permissions는 이 분류기까지 우회하므로, 격리 환경이 아닌 곳에서는 절대 사용하지 말아야 합니다.

2-3. 권한 설정의 계층 구조

권한은 여러 레벨에서 설정할 수 있으며, 아래로 갈수록 우선순위가 높습니다.

• 시스템 기본값 — Claude Code가 내장하고 있는 기본 권한 규칙
• 글로벌 설정 (~/.claude/settings.json) — 모든 프로젝트에 적용
• 프로젝트 설정 (.claude/settings.json) — 해당 프로젝트에만 적용
• 로컬 설정 (.claude/settings.local.json) — 개인 환경에만 적용 (git에 커밋하지 않음)
• 런타임 플래그 — 실행 시 명령줄 옵션으로 지정

예를 들어 팀 프로젝트에서는 프로젝트 설정에 npm test와 npm run build를 허용 명령으로 등록해두고, 개인 로컬 설정에서 추가로 docker compose up을 허용하는 식으로 계층적 관리가 가능합니다.

3. 1M 컨텍스트 시대의 컨텍스트 운용

Opus 4.6 GA와 함께 Claude Code는 1백만 토큰(약 100만 자)의 컨텍스트 윈도우를 사용할 수 있게 되었습니다. 이론적으로는 수만 줄의 코드를 한 번에 읽고 이해할 수 있다는 뜻입니다. 하지만 실전에서는 “다 넣으면 된다”가 아니라 “어떻게 효율적으로 운용할 것인가”가 관건입니다.

3-1. 컨텍스트 윈도우의 실체

1M 토큰이라고 해서 무한정 대화를 이어갈 수 있는 것은 아닙니다. 컨텍스트 윈도우에는 다음이 모두 포함됩니다.

• 시스템 프롬프트 — CLAUDE.md 파일들, 도구 정의, 권한 규칙 등
• 대화 히스토리 — 이전 메시지와 응답 전체
• 도구 호출 결과 — 파일 내용, 검색 결과, 명령 실행 출력 등
• 현재 프롬프트 — 지금 사용자가 입력한 내용

대규모 코드베이스를 다루다 보면 파일 몇 개만 읽어도 수만 토큰이 소비됩니다. 따라서 컨텍스트를 의식적으로 관리하는 것이 장시간 세션에서 품질을 유지하는 핵심입니다.

3-2. Prompt Caching — 비용과 속도의 최적화

Claude Code는 내부적으로 Prompt Caching을 활용합니다. 이것은 시스템 프롬프트나 CLAUDE.md처럼 세션 동안 변하지 않는 부분을 캐싱해서, 매 요청마다 다시 처리하지 않도록 하는 기술입니다.

Prompt Caching의 동작을 이해하면 비용 최적화에 직접적인 도움이 됩니다.

• 캐시 가능한 영역: 시스템 프롬프트, CLAUDE.md 내용, 도구 정의 → 세션 시작 시 한 번만 처리되고 이후 요청에서는 캐시된 결과를 재사용
• 캐시 불가능한 영역: 사용자 메시지, 도구 호출 결과, 모델 응답 → 매 요청마다 새로 처리
• 비용 효과: 캐시 히트 시 해당 토큰의 처리 비용이 대폭 절감됨. 긴 시스템 프롬프트를 사용하는 프로젝트에서 특히 효과적

실무 팁으로, CLAUDE.md를 잘 정리해두면 매 요청의 캐시 히트율이 높아져서 비용 효율이 좋아집니다. 반대로 CLAUDE.md를 매번 수정하면 캐시가 무효화되어 비용이 증가할 수 있습니다.

3-3. /compact — 컨텍스트 압축의 기술

/compact는 Claude Code에서 가장 중요한 컨텍스트 관리 도구입니다. 이 명령을 실행하면 현재까지의 대화 히스토리를 요약·압축해서 컨텍스트 사용량을 줄입니다.

/compact가 하는 일을 구체적으로 살펴보면 다음과 같습니다.

• 이전 대화의 핵심 내용(수정한 파일, 내린 결정, 현재 상태)을 요약
• 도구 호출의 상세 결과를 핵심만 남기고 압축
• 반복되거나 불필요한 정보를 제거

언제 /compact를 사용해야 할까요?

• 장시간 세션에서 응답 품질이 떨어지기 시작할 때
• 컨텍스트 사용량이 70% 이상에 도달했을 때
• 작업의 방향이 크게 전환될 때 (이전 맥락이 더 이상 필요 없을 때)
• 도구 호출 결과로 대량의 데이터가 컨텍스트에 누적되었을 때

또한 /compact에 커스텀 지시를 함께 전달할 수 있습니다. 예를 들어 /compact 현재 진행 중인 마이그레이션 작업의 상태만 유지해줘처럼 어떤 정보를 보존할지 명시하면 더 효과적입니다.

참고로 Claude Code는 컨텍스트가 한계에 가까워지면 자동으로 이전 메시지를 압축합니다. 시스템이 “Prior messages compressed”라는 알림을 보내면, 이전 대화의 일부가 자동으로 요약된 것입니다. 이 자동 압축에 의존하기보다는, 적절한 시점에 직접 /compact를 실행하는 것이 컨텍스트 품질 면에서 더 낫습니다.

3-4. Focus 모드와 Brief 모드

Focus 모드는 특정 파일이나 디렉터리에 에이전트의 주의를 집중시키는 기능입니다. 대규모 모노레포에서 작업할 때, 관련 없는 파일까지 탐색하느라 컨텍스트를 낭비하는 것을 방지합니다.

Brief 모드는 에이전트의 응답 길이를 줄이는 모드입니다. 코드 수정 작업에서 불필요한 설명을 생략하고 핵심만 출력하도록 합니다. 이는 컨텍스트 소비를 줄이는 동시에, 작업 흐름을 빠르게 만들어줍니다.

이 두 모드를 조합하면 컨텍스트 효율이 극대화됩니다. 예를 들어 src/auth/ 디렉터리의 인증 모듈만 리팩터링할 때, Focus를 해당 디렉터리로 설정하고 Brief 모드를 켜면, 에이전트가 집중적이고 간결하게 작업을 수행합니다.

3-5. 컨텍스트 운용 실전 전략

1M 컨텍스트를 효과적으로 활용하기 위한 실전 전략을 정리합니다.

• “필요할 때 읽기” 원칙 — 프로젝트의 모든 파일을 미리 읽어두지 마세요. 에이전트가 필요한 시점에 필요한 파일만 읽도록 하는 것이 효율적입니다. Claude Code는 Glob과 Grep 도구로 필요한 파일을 정확히 찾아 읽을 수 있습니다.
• 세션 분리 — 서로 다른 작업(버그 수정 vs 새 기능 개발)은 별도의 세션으로 분리하세요. 하나의 세션에 모든 작업을 몰아넣으면 컨텍스트가 혼잡해지고 품질이 떨어집니다.
• 중간 정리 — 작업 단계가 완료될 때마다 /compact로 정리하세요. “파일 3개 수정 완료 → compact → 다음 단계” 패턴이 효과적입니다.
• Subagent 활용 — 탐색적 작업(“이 버그의 원인이 될 수 있는 파일 찾아줘”)은 서브에이전트에 위임하면 메인 컨텍스트를 보호할 수 있습니다. 이 부분은 4편(하)에서 자세히 다룹니다.

4. CLAUDE.md 계층 구조 — 에이전트의 운영 매뉴얼

CLAUDE.md는 Claude Code에게 “이 프로젝트에서는 이렇게 행동해”라고 알려주는 지시서입니다. 단순한 README가 아닙니다. Claude Code는 세션을 시작할 때 CLAUDE.md를 시스템 프롬프트의 일부로 로드하며, 여기에 적힌 지시사항을 최우선으로 따릅니다.

4-1. 세 가지 계층

CLAUDE.md는 세 가지 레벨에서 존재할 수 있습니다.

① 루트 CLAUDE.md — 프로젝트 루트에 위치하는 메인 지시서입니다. 프로젝트 전반에 적용되는 규칙을 담습니다.

• 프로젝트 아키텍처 설명
• 코딩 컨벤션 (네이밍, 포맷팅, 패턴)
• 빌드/테스트/배포 명령어
• 금지 사항 (“절대 main 브랜치에 직접 푸시하지 마”)
• 외부 서비스 접근 정보

② 서브디렉터리 CLAUDE.md — 특정 디렉터리에 위치하며, 해당 디렉터리와 하위 디렉터리에서 작업할 때만 활성화됩니다.

• src/api/CLAUDE.md → API 관련 작업 시에만 로드
• tests/CLAUDE.md → 테스트 관련 작업 시에만 로드
• docs/CLAUDE.md → 문서 작업 시에만 로드

서브디렉터리 CLAUDE.md는 루트 CLAUDE.md를 보완합니다. 충돌하는 지시가 있을 경우, 서브디렉터리의 지시가 우선합니다. 이를 통해 “전체 프로젝트에서는 이렇게 하되, 이 디렉터리에서만은 저렇게 해”라는 세밀한 제어가 가능합니다.

③ 개인 글로벌 CLAUDE.md — ~/.claude/CLAUDE.md에 위치하며, 모든 프로젝트에서 공통으로 적용됩니다.

• 개인 코딩 스타일 선호도
• 자주 사용하는 도구나 워크플로우
• 언어 선호 (“항상 한국어로 응답해줘”)
• 공통 금지 사항 (“절대 자동으로 커밋하지 마”)

4-2. 우선순위 규칙

여러 CLAUDE.md가 동시에 존재할 때, 지시사항의 우선순위는 다음과 같습니다 (높은 순서).

• 1순위: 현재 작업 중인 서브디렉터리의 CLAUDE.md
• 2순위: 상위 디렉터리의 CLAUDE.md (루트까지 체인)
• 3순위: 프로젝트 루트의 CLAUDE.md
• 4순위: 개인 글로벌 ~/.claude/CLAUDE.md

이 우선순위는 CSS의 캐스케이딩과 비슷합니다. 더 구체적인(가까운) 지시가 더 일반적인(먼) 지시를 덮어씁니다.

4-3. 효과적인 CLAUDE.md 작성 패턴

CLAUDE.md를 잘 작성하면 Claude Code의 행동이 극적으로 개선됩니다. 실전에서 검증된 패턴들을 소개합니다.

패턴 1: 명확한 금지 사항 먼저

Claude Code는 “~하지 마”라는 지시를 매우 잘 따릅니다. 프로젝트에서 자주 발생하는 실수를 금지 사항으로 명시하면 효과적입니다.

• “절대 console.log를 커밋하지 마. 디버깅용이면 logger.debug를 사용해.”
• “any 타입을 사용하지 마. 반드시 구체적인 타입을 정의해.”
• “직접 SQL 쿼리를 작성하지 마. 반드시 ORM을 사용해.”

패턴 2: 빌드/테스트 명령어 명시

Claude Code가 코드를 수정한 후 자동으로 테스트를 실행할 수 있도록, 빌드와 테스트 명령어를 CLAUDE.md에 명시합니다.

• “코드 수정 후 반드시 npm test를 실행해서 테스트가 통과하는지 확인해.”
• “빌드: npm run build, 테스트: npm test, 린트: npm run lint“

패턴 3: 아키텍처 의사결정 기록

프로젝트의 주요 아키텍처 결정을 CLAUDE.md에 기록하면, 에이전트가 그 맥락을 이해하고 일관된 코드를 생성합니다.

• “이 프로젝트는 클린 아키텍처를 따른다. domain → usecase → adapter → infrastructure 레이어 구분을 준수해.”
• “상태 관리는 Zustand만 사용한다. Redux나 Context API는 사용하지 마.”

패턴 4: 간결하게 유지

CLAUDE.md가 너무 길면 두 가지 문제가 생깁니다. 첫째, 컨텍스트 윈도우를 많이 소비합니다. 둘째, 지시사항 간 충돌 가능성이 높아집니다. 핵심만 간결하게, 200줄 이내로 유지하는 것이 좋습니다.

4-4. 메모리 시스템과의 관계

Claude Code에는 CLAUDE.md 외에도 자동 메모리 시스템이 있습니다. 이 시스템은 ~/.claude/projects/ 디렉터리에 프로젝트별 메모리 파일을 저장합니다.

CLAUDE.md와 메모리 시스템의 역할 분담은 다음과 같습니다.

• CLAUDE.md — 팀 전체가 공유하는 공식 지시서. git에 커밋하여 버전 관리. “이 프로젝트에서는 이렇게 해”
• 메모리 시스템 — 개인적인 학습 기록. 세션 간에 학습한 내용을 자동으로 축적. “이 프로젝트에서 이전에 이런 패턴을 발견했어”

우선순위는 CLAUDE.md가 메모리보다 높습니다. CLAUDE.md의 지시와 메모리의 내용이 충돌하면, CLAUDE.md를 따릅니다. 이는 팀의 공식 규칙이 개인의 학습 기록보다 우선한다는 합리적인 설계입니다.

메모리 시스템의 세부 구조는 다음과 같습니다.

• MEMORY.md — 항상 컨텍스트에 로드되는 핵심 메모리 파일. 200줄 제한이 있으므로 가장 중요한 정보만 담아야 합니다.
• 주제별 파일 (예: debugging.md, patterns.md) — 상세한 메모를 분리 저장. MEMORY.md에서 링크로 참조.

사용자가 “이것을 기억해줘”라고 명시적으로 요청하면 메모리에 즉시 저장됩니다. 또한 여러 세션에 걸쳐 반복 확인된 패턴은 자동으로 메모리에 축적됩니다.

5. 도구 시스템의 내부 동작

Claude Code가 실제로 작업을 수행하는 것은 도구(Tool)를 통해서입니다. 모델이 “이 파일을 읽어야겠다”고 판단하면 Read 도구를 호출하고, “이 파일을 수정해야겠다”고 판단하면 Edit 도구를 호출합니다. 이 도구 시스템의 내부 동작을 이해하면, Claude Code를 더 효과적으로 활용할 수 있습니다.

5-1. 핵심 내장 도구

Claude Code에는 다음과 같은 핵심 도구가 내장되어 있습니다.

• Read — 파일 읽기. cat이나 head 대신 이 도구를 사용하면 구조화된 결과를 얻습니다.
• Edit — 파일의 특정 부분 수정. sed나 awk 대신 이 도구를 사용하면 정확한 위치에 정확한 수정이 가능합니다.
• Write — 새 파일 생성. 기존 파일이 있다면 Edit를 우선 사용합니다.
• Glob — 파일 패턴 검색. find 대신 사용합니다.
• Grep — 파일 내용 검색. grep이나 rg 대신 사용합니다.
• Bash — 셸 명령 실행. 위의 전용 도구로 해결할 수 없는 경우에만 사용합니다.
• Agent — 서브에이전트에게 작업을 위임합니다.
• TodoWrite — 작업 계획을 세우고 진행 상황을 추적합니다.

도구 호출은 다음과 같은 흐름으로 처리됩니다.

• 모델의 판단 → 도구 호출 결정
• 입력 분류기 → 요청의 안전성 검증
• 권한 검사 → 현재 권한 모드에서 허용되는 작업인지 확인
• 사용자 승인 → (필요한 경우) 사용자에게 승인 요청
• 도구 실행 → 실제 작업 수행
• 출력 분류기 → 결과의 안전성 검증
• 결과 반환 → 모델에게 결과 전달

5-2. 병렬 도구 호출

Claude Code는 독립적인 도구 호출을 병렬로 실행할 수 있습니다. 예를 들어 세 개의 파일을 읽어야 할 때, 순차적으로 읽는 대신 세 개의 Read 도구를 동시에 호출합니다. 이는 체감 속도를 크게 향상시킵니다.

하지만 의존성이 있는 도구 호출은 순차적으로 실행됩니다. “파일을 읽고 → 내용을 분석한 뒤 → 수정”하는 작업에서는 각 단계가 이전 단계의 결과에 의존하므로, 반드시 순서대로 실행됩니다.

5-3. 도구와 Bash의 경계

많은 사용자가 Bash 도구로 모든 것을 처리하려 합니다. 하지만 Claude Code의 설계 철학은 “전용 도구가 있으면 전용 도구를 사용하라”입니다. 그 이유는 다음과 같습니다.

• 안전성 — 전용 도구는 내부적으로 추가 검증을 수행합니다. Bash는 임의의 명령을 실행하므로 위험성이 높습니다.
• 구조화 — 전용 도구의 결과는 구조화되어 있어 모델이 더 정확하게 해석합니다.
• 추적성 — 전용 도구 호출은 로그에 명확히 기록되어, 사용자가 에이전트의 행동을 추적하기 쉽습니다.

Bash 도구는 빌드 실행, 서버 시작/중지, 패키지 설치 등 셸 환경에서만 가능한 작업에 한정하여 사용하는 것이 좋습니다.

6. 에이전트의 행동 원칙 — “신중하게, 안전하게”

Claude Code의 코어 메커니즘을 이해하는 데 있어 빼놓을 수 없는 것이 내장된 행동 원칙입니다. 이 원칙들은 단순한 가이드라인이 아니라, 모델의 의사결정에 직접 영향을 미치는 핵심 규칙입니다.

6-1. 가역성과 영향 범위 평가

Claude Code는 모든 작업을 실행하기 전에 두 가지를 평가합니다.

• 가역성(Reversibility) — 이 작업을 되돌릴 수 있는가? 파일 수정은 git으로 되돌릴 수 있으므로 비교적 안전합니다. 하지만 git push –force나 데이터베이스 DROP은 되돌리기 어렵습니다.
• 영향 범위(Blast Radius) — 이 작업이 영향을 미치는 범위는 어디까지인가? 로컬 파일 수정은 나에게만 영향을 미칩니다. 하지만 PR 생성이나 Slack 메시지 전송은 다른 사람에게도 영향을 미칩니다.

이 두 축을 기준으로 Claude Code는 작업을 네 가지로 분류합니다.

• 안전(로컬 + 가역): 파일 읽기, 로컬 파일 수정, 테스트 실행 → 자동 실행 가능
• 주의(로컬 + 비가역): 파일 삭제, git reset –hard → 사용자 확인 후 실행
• 주의(외부 + 가역): PR 생성, 이슈 코멘트 → 사용자 확인 후 실행
• 위험(외부 + 비가역): force push, 프로덕션 배포 → 반드시 사용자 확인 후 실행

6-2. “과도하게 하지 않기” 원칙

Claude Code에는 Over-engineering 방지 원칙이 내장되어 있습니다. 이것은 많은 AI 코딩 도구가 빠지는 함정 — 요청한 것보다 훨씬 많은 것을 수정하는 — 을 방지합니다.

• 버그 수정을 요청하면 해당 버그만 고칩니다. 주변 코드를 “개선”하지 않습니다.
• 기능 추가를 요청하면 요청한 기능만 구현합니다. 불필요한 추상화, 에러 핸들링, 설정 옵션을 추가하지 않습니다.
• 비슷한 코드 세 줄이 있어도, 한 번만 사용될 것이라면 헬퍼 함수로 추출하지 않습니다.

이 원칙은 실무에서 매우 중요합니다. 에이전트가 “더 좋은 코드”를 만들겠다고 불필요한 변경을 가하면, 리뷰어가 실제 변경 사항을 파악하기 어려워지고, 의도치 않은 버그가 발생할 수 있습니다.

7. 코어 메커니즘을 활용한 실전 워크플로우

지금까지 다룬 코어 메커니즘을 조합하여, 실전에서 활용할 수 있는 워크플로우를 구성해보겠습니다.

7-1. 새 프로젝트 시작 워크플로우

• Step 1: 루트 CLAUDE.md 작성 — 프로젝트 아키텍처, 코딩 컨벤션, 빌드/테스트 명령어, 금지 사항을 명시합니다.
• Step 2: 권한 설정 — 프로젝트 settings.json에 자주 사용하는 명령어(npm test, npm run build 등)를 허용 목록에 추가합니다.
• Step 3: Effort 레벨 설정 — 프로젝트 초기 아키텍처 설계는 xhigh, 이후 구현 작업은 high가 적절합니다.
• Step 4: Plan 모드로 시작 — 전체 구조를 먼저 계획하고, 확인 후 Auto 모드로 전환하여 구현합니다.

7-2. 대규모 리팩터링 워크플로우

• Step 1: Plan 모드에서 영향 범위 분석 — “이 리팩터링이 영향을 미치는 파일을 모두 찾아줘”
• Step 2: Effort xhigh로 리팩터링 계획 수립 — “각 파일에 어떤 변경이 필요한지 계획을 세워줘”
• Step 3: 계획 검토 후 Auto 모드 전환 — Effort를 high로 낮추고 실행
• Step 4: 중간 중간 /compact — 파일 그룹별로 수정 완료 시마다 컨텍스트 정리
• Step 5: 전체 테스트 실행 — 모든 수정 완료 후 테스트 스위트 실행

7-3. 디버깅 워크플로우

• Step 1: Effort high로 시작 — 버그 재현 및 원인 분석
• Step 2: Subagent로 관련 코드 탐색 — 메인 컨텍스트를 보호하면서 넓은 범위 탐색
• Step 3: 원인 파악 후 Effort medium으로 수정 — 단순 수정은 높은 effort가 불필요
• Step 4: 테스트 작성 및 실행 — 같은 버그가 재발하지 않도록 테스트 추가

마무리 — 다음 편 예고

이번 편에서는 Claude Code의 코어 메커니즘을 깊이 있게 살펴보았습니다. 모델 라인업과 Effort 레벨, 네 가지 권한 모드와 이중 분류기, 1M 컨텍스트 시대의 운용 전략, CLAUDE.md 계층 구조와 메모리 시스템, 도구 시스템의 내부 동작, 그리고 에이전트의 행동 원칙까지.

이 기초를 이해하고 나면, Claude Code와의 상호작용이 “AI에게 코드 짜달라고 하기”에서 “에이전트를 설계하고 운용하기”로 레벨업됩니다.

다음 2편에서는 슬래시 커맨드 30+종을 체계적으로 정리하고, 세션 라이프사이클을 마스터하는 방법을 다룹니다. /resume, /fork, /recap 같은 커맨드로 작업의 연속성을 유지하는 실전 테크닉을 기대해주세요.

이미지는 Leonardo AI 로 생성되었습니다.

이미지는 Claude AI 로 생성되었습니다.

---