Claude Code 2.0 완전 가이드: AI 코딩 에이전트를 마스터하는 여정

게시 2025/12/29 업데이트 2026/01/17

By BLUEBUG

135 분읽는 시간

A Guide to Claude Code 2.0 and getting better at using coding agents

프롤로그: 변화의 시대

2025년은 AI 코딩 도구의 역사에서 전환점이 된 해였다. OpenAI와 Anthropic이 2주마다 새로운 모델을 출시하며 치열한 경쟁을 펼쳤고, 중국의 오픈소스 진영(GLM-4.7, Kimi-K2, Minimax-2.1)도 빠르게 추격했다. 이러한 격변 속에서 Claude Code는 단순한 CLI 도구를 넘어 개발자 워크플로우를 근본적으로 재정의하는 제품으로 진화했다.

Andrej Karpathy가 트위터에서 “도구들이 너무 빠르게 변화해서 따라잡기 어렵다”며 토로했을 때, 이는 단순한 불평이 아니었다. 이는 기술 진화의 속도가 인간의 학습 능력을 앞지르기 시작한 시점을 상징적으로 보여주는 순간이었다. 하지만 그는 동시에 “이건 무서우면서도 흥미진진한 시대”라고 말했다. 이 문서는 바로 그 흥미진진함 속에서 길을 잃지 않고 Claude Code를 마스터하는 방법을 다룬다.

1부: 애증의 관계 - Anthropic과의 화해

1.1 Codex 시대: 이별의 서곡 (2025년 6-9월)

2025년 6월부터 9월 초까지, 필자는 Claude Code를 메인 드라이버로 사용했다. 그러나 9월 초, 월 100달러짜리 Claude Max 구독을 과감하게 취소하고 OpenAI Codex로 갈아탔다. 이 전환에는 두 가지 명확한 이유가 있었다.

첫째, Sonnet 4와 Opus 4가 기대에 미치지 못했다. GPT-5-codex가 Sonnet 4.5와 동등한 성능을 보이면서도 더 나은 코드를 작성했다. 더 심각한 문제는 Anthropic의 잦은 API 중단과 추론 버그로 인한 성능 저하였다. 이는 단지 개인적인 불만이 아니었다. 많은 개발자들이 비슷한 이유로 Codex나 Cursor의 GPT-5.1로 이동했다.

둘째, 비용 대비 가치의 문제였다. 9월에는 시스템 디자인과 사고 작업이 많았는데, Claude Max의 100달러는 이런 작업에 최적화되지 않았다. 반면 Codex는 월 20달러로 엄청난 가치를 제공했고, 속도 제한에도 거의 걸리지 않았다. Codex 개발자들이 버그를 푸시할 때마다 사용 제한을 리셋해주는 관대함도 한몫했다.

1.2 중간 지대: Sonnet 4.5의 슬롭 시대 (2025년 9-10월)

10월 말까지 필자는 Codex를 메인으로, Cursor를 보조로 사용했다. Claude Sonnet 4.5가 9월 29일 Claude Code 2.0과 함께 출시되었을 때, 호기심에 다른 이메일로 20달러 구독을 해서 시도해봤다. 하지만 GPT-5/GPT-5-codex가 전반적으로 더 우수했다.

Sonnet 4.5의 핵심 문제는 “슬롭(slop)” 생산이었다. 빠르고 능력은 있었지만, 무분별한 변경을 만들어 버그를 유발했다. 나중의 GPT-5.1/GPT-5.1-codex와 비교하면 많은 저품질 코드를 생산하는 것처럼 느껴졌다. 트위터에서 농담처럼 “Sonnet 4.5 슬롭 시대”라고 부를 정도였다.

1.3 귀환: Opus 4.5와의 재회 (2025년 11월)

10월 30일, Anthropic이 게임 체인저를 던졌다. 구독을 취소한 사용자들에게 월 200달러 맥스 플랜을 제안한 것이다. “28일 후 취소하라고 상기시켜줘”라고 농담하며 구독했지만, 곧 그럴 필요가 없음을 깨달았다.

11월 24일, Opus 4.5가 출시되었다. 5일간 미친 듯이 사용하며 업무를 처리하고, 매우 기술적인 블로그 글도 작성했다. 이 과정에서 Opus 4.5의 진정한 능력을 발견했다. 트위터에 올린 글에서 다음과 같이 평가했다:

“Opus 4.5로 전환한 이유: SWE-bench-verified와 Tau Bench에서 최고 수준, 빠른 속도, 동등한 코딩 능력, 협업에 뛰어남, 소통 능력 우수. 그냥 좋은 바이브를 가지고 있다.”

이 글은 GPT-5.1 전환 때보다 2배 많은 반응을 얻었다. 많은 사람들이 Opus 4.5에 공감하고 있었던 것이다.

1.4 Opus 4.5가 특별한 이유

현재 경험상 GPT-5.2-Codex가 코드 생성 능력에서 Opus 4.5를 작은 차이로 앞선다. 그럼에도 Opus 4.5가 메인 드라이버가 된 이유는 명확하다.

속도의 마법: Opus 4.5는 Codex보다 빠를 뿐 아니라, 비슷한 난이도의 작업을 훨씬 짧은 시간에 수행한다. 이것은 단순히 처리 속도만의 문제가 아니다. 더 빠른 피드백 루프는 진전을 더 실감나게 만든다. 미묘한 차이 같지만, 실제로 개발 경험에서는 엄청난 차이를 만든다.

커뮤니케이션의 예술: Opus 4.5는 탁월한 커뮤니케이터이자 페어 프로그래머다. Codex는 때때로 지시를 무시하고 제멋대로 변경을 가하는 반면, Opus 4.5는 의도를 정확히 감지하고 협업한다. 같은 프롬프트에 대해 Codex는 간결하지만, Claude는 기대에 부합한다. Codex는 항상 중첩된 불릿 포인트로 작성하지만, Claude는 대화적인 톤을 유지한다.

영혼이 있는 AI: 많은 사람들이 Opus 4.5의 “영혼”에 대해 이야기한다. 이는 과장이 아니다. Sonnet 3.7, Sonnet 4, Opus 4, Opus 4.1에서 다소 희석되었던 특성이 Opus 4.5에서 돌아왔다. Amanda Askell이 트위터에서 확인했듯이, 이는 실제 문서를 기반으로 훈련된 것이다. “Soul Document”를 통해 Claude에게 영혼을 후훈련시킨 것이다.

제품으로서의 완성도: 모델만 훌륭한 것이 아니다. Claude Code 제품 자체가 Codex보다 월등하다. UX/UI, 하네스, 프롬프트 엔지니어링이 어우러져 마법 같은 경험을 만든다. 개발자들이 Claude가 하네스에서 편안함을 느끼고 정확한 함수 호출을 할 수 있도록 쏟아부은 엔지니어링 노력은 감탄스러울 정도다.

1.5 이 글은 스폰서 받은 게 아니다

이전 글이 Hacker News 5위에 올랐을 때, “Anthropic이 스폰서한 거 아니냐”는 의혹을 받았다. 농담이 아니었다. 진지한 질문이었다.

하지만 필자는 Anthropic의 프롬프트 캐싱 가격을 비꼬고, 중단 사태를 조롱하고, Sonnet 4.5 슬롭을 신랄하게 비판했다. 느낀 대로 표현했고, 그것이 좋은 담론으로 이어졌다.

동시에 솔직히 말하면, Claude Code는 지금까지 경험한 제품 중 가장 즐거운 것 중 하나다. 이를 만든 엔지니어링과 리서치 팀에 깊은 존경심을 느낀다. 그것이 이 긴 글을 쓰는 이유다.

2부: Claude Code 2.0의 진화

2.1 품질 개선의 향연

7월 이후 Claude Code는 수많은 AI 기능과 품질 개선 사항을 추가했다. 주목할 만한 변화들을 살펴보자.

구문 강조 (Syntax Highlighting): 2.0.71에서 추가된 이 기능은 게임 체인저였다. 시간의 80%를 Claude Code CLI에서 보내는 필자에게 이는 기쁨 그 자체였다. 대부분의 코드를 Claude Code에서 검토하는 것을 좋아하는데, Opus 4.5의 우수함과 구문 강조가 결합되면서 코드 검토를 위해 Cursor를 여는 일이 완전히 사라졌다.

팁 시스템 (Tips): Claude가 생각하는 동안 표시되는 팁에서 많은 것을 배웠다. 비침습적이면서도 유용한 정보를 제공하는 이 접근 방식은 사용자 경험 디자인의 모범 사례다.

피드백 UI: 세션 중에 가끔씩 나타나는 피드백 요청은 우아하기 그지없다. 숫자 키로 빠르게 응답(1: 나쁨, 2: 괜찮음, 3: 좋음)하거나 0으로 무시할 수 있다. 사용자를 방해하지 않으면서도 피드백을 수집하는 완벽한 예시다.

질문 모드 옵션: “Claude에게 다르게 해야 할 것을 입력하세요”라는 세 번째 옵션이 특히 마음에 든다. 재미있는 사실: 이 모든 옵션들은 실제로 모델을 위한 프롬프트이며, 그 출력이 다른 도구 호출로 파싱되어 이런 형태로 표시된다.

울트라싱크 (Ultrathink): 어려운 작업이나 Opus 4.5가 더 엄격하기를 원할 때 울트라싱크를 많이 사용한다. 무언가를 설명하거나 변경 사항을 자체 검토할 때 특히 유용하다. 울트라싱크의 색상 디테일도 훌륭하다.

생각 토글: Tab으로 생각을 켜고 끄는 기능은 좋았지만, 최근에 Alt/Option + Tab으로 변경되었다. Mac에서 작동하지 않는 버그가 있지만, settings.json을 확인하면 CC는 기본적으로 생각을 항상 켜짐으로 설정한다.

2.2 체크포인팅: 시간을 되돌리는 힘

Esc + Esc 또는 /rewind 옵션은 이제 Cursor에서처럼 특정 체크포인트로 돌아갈 수 있게 한다. 코드와 대화를 모두 되감을 수 있다. 이것은 필자에게 주요 기능 요청이었고, 마침내 구현되었다.

체크포인팅은 단순한 실행 취소 기능이 아니다. 이는 실험의 자유를 준다. 위험한 변경을 시도하고, 잘못되면 되돌릴 수 있다는 확신은 더 대담한 시도를 가능하게 한다.

2.3 프롬프트 제안과 히스토리 검색

프롬프트 제안 (2.0.73): 최근 추가된 프롬프트 제안은 예측이 꽤 괜찮다. Claude Code는 이제 토큰을 대량으로 소비하는 기계가 되었다. 시스템 프롬프트 중 가장 단순한 것 중 하나지만 효과적이다.

프롬프트 히스토리 검색: Ctrl + R을 사용하여 터미널 역방향 검색처럼 프롬프트를 검색할 수 있다. 2.0.74 버전에 있으며, 프로젝트 전체 대화를 검색할 수 있다. Ctrl + R을 반복해서 누르면 결과를 순환한다. 이것은 이전 명령을 다시 찾을 때 엄청난 시간을 절약해준다.

2.4 기타 개선사항

커서 순환: 프롬프트의 처음/끝에 도달하면 아래/위를 눌러 순환한다. 작은 기능이지만 일상적인 사용에서 큰 편의를 제공한다.

메시지 큐 탐색: 대기 중인 메시지와 이미지 첨부 파일을 탐색할 수 있다(2.0.73). 이미지 첨부 파일을 표시할 수 있는지는 확실하지 않다.

퍼지 파일 검색: 파일 제안이 3배 빠르고 퍼지 검색을 지원한다(2.0.72). 정확한 파일명을 모를 때 유용하다.

LSP 지원: 최근 추가되었으며 플러그인을 통해 액세스한다. 이는 IDE 수준의 코드 인텔리전스를 CLI에 가져온다.

2.5 새로운 통합

Slack 통합, Claude Web(베타), Claude Chrome 확장 프로그램 등 새로운 통합도 추가되었다. 이들은 꽤 명확하므로 자세히 다루지 않겠지만, Claude Web은 iOS/Android에서도 작업을 시작할 수 있게 하므로 많은 사람들에게 흥미로울 것이다.

3부: 기능 심층 탐구

3.1 명령어 시스템의 힘

/를 사용하여 내장 슬래시 명령어에 액세스할 수 있다. 이것들은 특정 작업을 수행하는 사전 정의된 프롬프트다. 하지만 진정한 힘은 커스텀 명령어에 있다.

커스텀 명령어 만들기: 특정 작업에 대해 반복적으로 프롬프트를 작성하고 있고 지시사항이 정적/정확할 수 있다면, 커스텀 명령어를 만드는 것이 좋은 아이디어다. Claude에게 커스텀 명령어를 만들도록 요청할 수 있다. Claude는 방법을 알고 있거나 웹을 검색하고 claude-code-guide.md를 통해 알아낼 것이다.

실용적 예시 - /handoff: 컨텍스트 윈도우가 가득 차기 시작하면 /clear로 새 대화를 시작하고 싶다. Claude는 /compact를 제공하지만, 때로는 Claude가 현재 세션에서 일어난 일을 작성하게 한 후 종료하고 새로 시작하는 것을 선호한다. 이를 위해 /handoff 명령을 만들었다.

고급 활용 - bootstrap-repo: 필자는 bootstrap-repo라는 명령어를 가지고 있는데, 이것은 10개의 병렬 서브에이전트로 리포지토리를 검색하여 포괄적인 문서를 만든다. 요즘은 거의 사용하지 않으며, 너무 많은 병렬 서브에이전트는 Claude Code 깜박임 버그를 일으킨다.

명령어를 입력하면 그 프롬프트가 현재 대화/컨텍스트에 추가되고 메인 에이전트가 작업을 수행하기 시작한다. 명령어는 프로젝트 레벨(.claude/commands/)이나 글로벌 레벨(~/.claude/commands)로 만들 수 있다.

3.2 서브에이전트: 분신술의 예술

서브에이전트는 이전 포스팅 직후에 도입되었다. 이것들은 메인 에이전트가 자체 판단에 따라 또는 사용자가 지시할 때 생성하는 별도의 Claude 인스턴스다.

서브에이전트의 종류:

general-purpose: 복잡한 질문을 연구하고, 코드를 검색하고, 다단계 작업을 자율적으로 실행하는 범용 에이전트. 전체 컨텍스트를 상속하며 모든 도구에 액세스할 수 있다.
Explore: 코드베이스 탐색에 특화된 빠른 에이전트. 읽기 전용 파일 검색 전문가로, Glob, Grep, Read, 제한된 Bash 명령을 사용할 수 있지만 파일을 만들거나 수정하는 것은 엄격히 금지되어 있다.
Plan: 구현 계획을 설계하는 소프트웨어 아키텍트 에이전트. 작업에 대한 구현 전략을 계획해야 할 때 사용한다.
claude-code-guide: Claude Code, Claude Agent SDK, Claude API에 대한 질문에 답하는 문서 전문가.
statusline-setup: 사용자의 Claude Code 상태 표시줄 설정을 구성하는 에이전트.

커스텀 서브에이전트: .claude/agents/your-agent-name.md에 마크다운 파일을 만들어 커스텀 서브에이전트를 정의할 수 있다. 또는 /agents를 사용하여 자동으로 관리하고 만들 수 있다 - 권장되는 접근 방식이다.

3.3 Explore 에이전트: 읽기 전용 탐색의 달인

Explore 에이전트는 특히 흥미롭다. “Sonnet 4.5로 Explore 에이전트를 실행해”라고 말하면 Claude는 모델 매개변수를 Sonnet으로 설정하여 Task 도구를 호출한다.

Explore 프롬프트의 철학: Explore 에이전트 프롬프트는 읽기 전용 모드의 중요성을 강조한다. 새 파일 생성, 기존 파일 수정, 파일 삭제, 이동, 복사, 임시 파일 생성, 리다이렉트 연산자 사용, 시스템 상태 변경 명령 - 이 모든 것이 엄격히 금지된다.

역할은 독점적으로 기존 코드를 검색하고 분석하는 것이다. 중요한 점은 Explore 에이전트가 “가능한 한 빠르게 출력을 반환하도록 설계된 빠른 에이전트”라는 것이다. 이를 달성하기 위해:

사용 가능한 도구를 효율적으로 사용
파일을 grep하고 읽기 위해 여러 병렬 도구 호출 생성

컨텍스트 상속의 미묘함: general-purpose와 plan 서브에이전트는 전체 컨텍스트를 상속하지만, Explore는 새로운 슬레이트로 시작한다. 이것은 검색 작업이 종종 독립적이기 때문에 의미가 있다.

기능을 이해하려고 하거나 코드베이스에서 간단한 것을 찾고 있다면, Claude가 Explore 에이전트 검색을 하도록 한다. Explore 에이전트는 메인 에이전트에 요약을 전달하고, 그러면 Opus 4.5가 결과를 게시하거나 각 파일을 직접 살펴보기로 선택할 수 있다.

어텐션의 중요성: 모델이 각 관련 파일을 직접 살펴보는 것이 중요하다. 그래야 수집된 모든 컨텍스트가 서로 어텐션할 수 있기 때문이다. 이것이 어텐션의 하이레벨 아이디어다. 컨텍스트를 이전 컨텍스트와 교차시킨다. 이렇게 하면 모델이 더 많은 쌍별 관계를 추출할 수 있으므로 더 나은 추론과 예측이 가능하다.

Explore 에이전트는 손실 압축일 수 있는 요약을 반환한다. Opus 4.5가 모든 관련 컨텍스트를 직접 읽으면, 어떤 세부 사항이 어떤 컨텍스트와 관련이 있는지 안다. 이 통찰력은 프로덕션 애플리케이션에서도 큰 도움이 된다.

3.4 서브에이전트의 생성 메커니즘

역엔지니어링된 리소스와 유출된 시스템 프롬프트에서 서브에이전트가 Task tool을 통해 생성된다는 것을 알 수 있다. 흥미롭게도, Claude에게 직접 물어볼 수도 있다:

Task 도구 설명을 알려줘
전체 설명을 줘
전체 도구 스키마를 보여줘

Task Tool의 구조: Task 도구는 서브에이전트 타입, 프롬프트, 설명, 모델 선택(sonnet/opus/haiku), 백그라운드 실행 여부, 재개 옵션 등을 매개변수로 받는다.

메인 에이전트는 Task 도구를 호출하여 서브에이전트를 생성하고, 추론을 사용하여 매개변수를 결정한다. “Sonnet으로 Explore를 사용해”라고 말하면, 모델이 model: "sonnet"으로 도구 호출을 만든다.

백그라운드 에이전트: run_in_background 매개변수는 서브에이전트를 백그라운드에서 실행할지 여부를 결정한다. 백그라운드 프로세스 기능은 디버깅이나 프로세스에서 로그 출력을 모니터링하는 데 매우 유용하다. 장시간 실행되는 파이썬 스크립트를 모니터링하고 싶을 때 등에 활용할 수 있다.

3.5 Codex와의 비교

Codex에는 서브에이전트 개념이 없다. 이것은 아마도 개발자들의 의식적인 결정일 것이다. GPT-5.2는 400K 컨텍스트 윈도우를 가지고 있으며, 벤치마크에 따르면 장문 컨텍스트 검색 능력이 대폭 개선되었다.

하지만 재미있게도, 사람들은 Codex가 헤드리스 Claude를 서브에이전트로 사용하도록 시도했다. Peter가 트위터에 올린 스크린샷은 이것이 실제로 작동한다는 것을 보여준다. 그냥 할 수 있는 일이다.

4부: 워크플로우의 예술

4.1 설정: 도구의 조합

필자의 워크플로우는 꽤 단순하고 작업 기반이다:

Claude Code: 메인 드라이버
Codex: 검토 및 어려운 작업용
Cursor: 코드 읽기 및 수동 편집용

플랜 모드는 거의 사용하지 않는다. 대신 요구사항이 충분히 명확해지면 관련 파일을 직접 찾기 위해 코드베이스를 탐색한다.

사용하는 것: 몇 가지 커스텀 명령, CLAUDE.md와 스크래치패드를 광범위하게 사용, 필요 시 MCP(문서, Playwright, Figma MCP), 간단한 작업을 위한 훅, 관찰성 목적의 백그라운드 에이전트.

사용하지 않는 것: 커스텀 서브에이전트(아직), Git worktrees(거의), 스킬/플러그인(정기적으로는 아직), MCP(일반적으로는 팬이 아님).

4.2 탐색과 실행: 질문 주도 개발

Opus 4.5는 설명에 놀랍고 뛰어난 ASCII 다이어그램을 만든다. 5월 지식 컷오프도 여기서 도움이 된다. 따라서 탐색은 많은 질문을 하는 것을 포함한다:

요구사항 명확화
어디서/어떻게/왜 변경해야 하는지 이해
아키텍처적 함의 파악
잠재적 부작용 식별

플랜 모드보다 효율적이지 않을 수 있지만 이 접근 방식을 좋아한다. 충분한 컨텍스트를 가지면 /ultrathink를 많이 사용하고 어떤 변경이 필요한지 묻는다. 괜찮아 보이면 변경 사항을 밀접하게 모니터링하면서 실행을 시작한다 - 기본적으로 마이크로 매니징한다. 때때로 여기서 Codex의 두 번째 의견을 묻기도 한다.

4.3 일회용 초안 접근법: 테넷 스타일

어려운 새로운 기능의 경우, “일회용 초안” 접근법을 사용한다. 어떤 변경이 필요한지 이해하면, 새 브랜치를 만들고 Claude가 관찰하는 동안 처음부터 끝까지 기능을 작성하게 한다.

그런 다음 출력을 요구사항에 얼마나 가까웠는지에 대한 정신적 모델과 비교한다:

어디서 벗어났는가?
어떤 결정을 내렸는가?
어떤 편향을 보였는가?

이 프로세스는 Claude의 오류와 가지고 있던 컨텍스트를 기반으로 내린 결정/편향을 드러낸다. 이러한 사후 지식의 이점으로 또 다른 반복을 실행하는데, 이번에는 첫 번째 패스에서 배운 것으로 알게 된 더 날카로운 프롬프트로 진행한다. 영화 테넷(Tenet)과 비슷한 개념이다.

백엔드 중심 또는 복잡한 기능의 경우 특히, 때때로 Codex xhigh에게 대신 계획을 생성하도록 요청한다.

4.4 검토: Codex의 예리한 눈

코드를 검토하고 버그를 찾는 데는 GPT-5.2-Codex가 우수하다고 생각한다. 그냥 /review를 사용하면 된다. 코드 리뷰 제품보다 낫다.

버그를 찾고 P1, P2와 같은 심각도를 언급할 수 있다. Claude에 비해 위양성을 보고할 가능성이 적고 혼란스러운 변경사항에 대해 더 신뢰할 수 있다. 실행은 Claude로, 검토/버그는 GPT/o-시리즈 모델로 하는 이 역학은 아마도 1년 동안 꽤 일정했다.

트위터에 올린 스크린샷처럼 “Opus 4.5 변경사항을 GPT-5.1-Codex-Max high로 검토받기” - 이것이 필자의 워크플로우다.

4.5 하네스의 마법

하네스가 너무나 철저하게 엔지니어링되어 있어서 Claude는 어떤 서브에이전트를 생성할지, 어떤 명령/도구 호출/스킬을 실행할지, 무엇을 비동기 방식으로 실행할지 안다. 에이전트 루프를 크게 운반할 수 있어서 주요 작업은 판단력을 사용하고 올바른 방향으로 프롬프트하는 것이다.

다음 세대 모델은 더 나아질 것이고, 관련 스캐폴딩은 기존 기능에 대해서는 줄어들고 새로운 기능에 대해서는 증가할 것이다. (이것은 Karpathy의 최신 트윗과 대조된다)

기능을 깊이 알 필요는 전혀 없다. 하지만 작동 방식을 아는 것은 Explore 에이전트에게 Sonnet을 사용하라고 말하는 것처럼 모델을 더 잘 조종하는 데 도움이 될 수 있다.

5부: 컨텍스트 엔지니어링 - 메모리의 예술

5.1 에이전트는 토큰 소비의 거물

하네스의 에이전트는 코드베이스를 읽고, 편집하고, 쓰기를 만들기 위해 많은 도구 호출을 능동적으로 수행할 수 있다. 이 과정에서 엄청난 양의 데이터가 생성되어 실행 중인 대화, 즉 컨텍스트 윈도우에 추가된다.

도구 호출의 컨텍스트 축적: 커피숍 랜딩 페이지를 만드는 간단한 예를 들어보자:

사용자: "내 커피숍을 위한 랜딩 페이지를 만들어줘"
↓
웹 검색 결과: ~1.5K 토큰
↓
브랜드 가이드라인 읽기: ~4K 토큰
↓
HTML 파일 생성: ~50 토큰
↓
이미지 생성: ~30 토큰
↓
HTML 편집: ~300 토큰
────────────────────────
총계: 한 작업에 ~6K+ 토큰

도구 호출과 도구 호출 출력이 모두 컨텍스트에 추가된다. 이는 LLM이 결과를 알 수 있도록 하기 위함이다. LLM은 stateless다 - 컨텍스트 윈도우 밖에는 메모리가 없다.

대화에 n개의 메시지가 있다고 가정하자. 다음 메시지를 보내면 요청은 LLM에서 n + 1개의 메시지를 다시 처리한다 ~ 단일 컨텍스트 윈도우. 도구 호출 결과는 컨텍스트를 빠르게 채울 수 있으며 이것이 에이전트가 매우 비쌀 수 있는 이유이기도 하다.

5.2 컨텍스트 엔지니어링의 정의

Anthropic의 공식 정의를 인용하면:

컨텍스트는 대규모 언어 모델(LLM)에서 샘플링할 때 포함되는 토큰 세트를 의미한다. 당면한 엔지니어링 문제는 일관되게 원하는 결과를 달성하기 위해 LLM의 고유한 제약에 대해 이러한 토큰의 유용성을 최적화하는 것이다.
컨텍스트 엔지니어링은 “어떤 컨텍스트 구성이 모델의 원하는 동작을 생성할 가능성이 가장 높은가?”라는 질문에 답하는 것이다.

지금까지 논의한 모든 것 - 서브에이전트, 스크래치패드 사용, 컴팩션 - 이 모든 것이 컨텍스트 엔지니어링에 해당된다.

5.3 컨텍스트 부패: 주의력의 한계

제한된 컨텍스트 윈도우: LLM의 컨텍스트 검색 성능은 새로운 토큰이 도입될 때마다 저하된다. 컨텍스트를 제한된 “어텐션 예산”으로 생각하라. 이것은 어텐션 메커니즘 자체의 결과로, 쌍별 관계를 모델링하기가 어려워진다.

모델별 컨텍스트 윈도우:

GPT-5.2: 400K 입력 토큰
Opus 4.5: 200K
Gemini 3 Pro: 1M

하지만 길이만이 중요한 것은 아니다. 이러한 컨텍스트 윈도우의 효과는 다를 수 있다. Chroma의 컨텍스트 부패 논문은 작업 난이도가 아닌 길이에 따른 성능 저하를 보여주는 실험을 깊이 다룬다.

실용적 결론: 효과적인 컨텍스트 윈도우는 아마도 50-60% 또는 그 이하일 것이다. 대화의 중간쯤에 복잡한 작업을 시작하지 마라. 컴팩션을 하거나 새로운 것을 시작하라.

프롬프트와 코드에서 수행되는 모든 것은 다음을 위한 것이었다:

가장 관련성 높은 컨텍스트 연결
컨텍스트 비대화/무관한 컨텍스트 감소
적고 충돌하지 않는 지시사항 제공
리마인더와 런타임 주입을 통해 도구 호출 개선

5.4 MCP와 코드 실행

MCP 서버는 기계나 인터넷에서 원격으로 호스팅될 수 있는 서버다. 파일시스템, 도구, CRM, Google Drive와 같은 통합을 노출할 수 있다. 본질적으로 모델이 외부 도구와 서비스에 연결하는 방법이다.

문제점: 도구 정의는 호스트의 컨텍스트 윈도우에 미리 로드되어 비대화시킨다. MCP 사용이 확대됨에 따라:

도구 정의가 컨텍스트 윈도우를 과부하시킨다
중간 도구 결과가 추가 토큰을 소비한다

해결책 - MCP Code exec: 직접 도구 호출 대신 코드 API를 노출하고 Claude에게 파일시스템이 있는 샌드박스 실행 환경을 제공한다. 그런 다음 도구 호출을 만들기 위한 코드를 작성하게 한다. 우아한 아이디어이며 “온디맨드 프롬프트”라는 점에서 스킬과 꽤 유사하다.

5.5 시스템 리마인더: 암송을 통한 어텐션 조작

컨텍스트 저하를 방지하는 한 가지 기법은 컨텍스트에 목표를 반복적으로 주입하는 것이다. Manus의 접근 방식을 살펴보자:

Manus는 복잡한 작업을 처리할 때 todo.md 파일을 만들고 작업이 진행됨에 따라 단계별로 업데이트한다. 이것은 귀여운 행동이 아니라 어텐션을 조작하기 위한 의도적인 메커니즘이다.

일반적인 작업은 평균적으로 약 50번의 도구 호출을 필요로 한다. 긴 루프다. todo 목록을 지속적으로 다시 작성함으로써 Manus는 컨텍스트 끝에 목표를 암송하고 있다. 이것은 글로벌 계획을 모델의 최근 어텐션 범위로 밀어넣어 “중간에 잃어버린” 문제를 피하고 목표 불일치를 줄인다.

Claude Code도 todo 목록을 가지고 있다. 이제 그것의 논리 일부를 안다.

5.6 리마인더 태그의 전략적 활용

Claude Code는 사용자 메시지와 도구 결과에 <system-reminder> 태그를 연결하여 유사한 것을 시도한다. 일부는 도구 설명에 언급되고, 다른 리마인더는 코드를 통해 런타임에 추가된다.

Claude에게 물어보면 답한다:

사용자 메시지에 추가되는 리마인더 (예: CLAUDE.md 내용)
도구 결과에 첨부되는 리마인더
특정 모드가 활성화되었을 때의 리마인더 (예: Plan Mode)

CC 2.0.56의 이전 버전에는 plan-mode-is-active 같은 상세한 리마인더가 있었다. Armin Ronacher는 자신의 포스트에서 “에이전트에게 상기시키는 반복 프롬프트”를 언급할 때 이것에 대해 이야기한다.

유출된 프롬프트를 보면 플랜 모드에 대해 2-3개의 프롬프트와 ENTRY_PLAN_MODE_TOOL, EXIT_PLAN_MODE_TOOL과 같은 도구 스키마가 있다. 출력은 /plan을 통해 액세스할 수 있는 마크다운 파일에 작성된다. 모든 것이 마크다운이다.

5.7 스킬: Matrix의 Neo처럼

Anthropic은 최근 Agent Skills를 도입했고, Codex도 채택했다. 스킬은 SKILL.md 파일, 기타 참조 가능한 파일, 그리고 사용자 정의 작업을 수행하는 코드 스크립트를 포함하는 폴더다.

작동 원리: SKILL.md는 LLM이 어떤 스킬이 사용 가능한지 알 수 있는 메타데이터를 포함한다(메타데이터는 시스템 프롬프트에 추가됨). Claude가 스킬이 관련이 있다고 느끼면 스킬의 내용을 읽기 위해 도구 호출을 수행하고 Matrix 1999의 Neo처럼 도메인 전문지식을 다운로드한다.

장점: 일반적으로 도메인 전문지식을 가르치려면 시스템 프롬프트에 모든 정보를 작성해야 한다. 스킬을 사용하면 모델이 온디맨드로 로드하기 때문에 그렇게 할 필요가 없다. 이것은 특히 항상 해당 지시사항이 필요한지 확실하지 않을 때 유용하다.

인기 있는 frontend-design 플러그인은 실제로 단지 스킬이다.

5.8 플러그인: 기능의 패키징

플러그인은 스킬, 슬래시 명령, 서브에이전트, 훅, MCP 서버를 단일 배포 가능한 단위로 번들링하는 패키징 메커니즘이다. /plugins를 통해 설치할 수 있으며 충돌을 피하기 위해 네임스페이스가 지정된다.

.claude/의 독립 실행형 구성은 개인/프로젝트별 사용에 좋지만, 플러그인은 프로젝트와 팀 간에 기능을 쉽게 공유할 수 있게 한다.

5.9 훅: 라이프사이클의 관찰자

훅은 Claude Code와 Cursor에서 사용 가능하다(Codex는 아직 구현하지 않았다). 에이전트 루프 라이프사이클의 특정 단계가 시작하거나 끝날 때 관찰하고 이전이나 이후에 bash 스크립트를 실행하여 에이전트 루프를 변경할 수 있게 한다.

훅의 종류:

Stop: Claude가 응답을 마친 후 실행
UserPromptSubmit: 사용자가 프롬프트를 제출할 때 Claude가 처리하기 전에 실행

실용적 사용 예:

첫 번째로 만든 훅: Claude가 응답을 멈췄을 때 애니메이션 알림 소리 재생
재미있는 사용 사례: Stop 훅을 통해 “더 해” 프롬프트를 실행하여 Claude를 몇 시간 동안 실행

5.10 고급 통합: 훅 + 스킬 + 리마인더

연구 중 Reddit에서 흥미로운 포스트를 발견했다. 한 사용자가 훅, 스킬, 리마인더를 아름답게 결합했다. 모델에게 스킬을 상기시키기 위해 훅을 사용하는 것이다.

Anthropic은 skill.md를 500줄 이하로 유지할 것을 권장한다. 그래서 이 사용자는:

지시사항을 별도의 스킬 파일로 나눔
훅과 결합
CLAUDE.md의 크기를 대폭 감소

유틸리티/요구사항이 발생하면 많은 커스터마이징 공간이 있다. 그런 무거운 커스터마이징이 필요하지 않을 수 있지만 적어도 영감을 받을 수 있다.

6부: 기술적으로 가벼운 사람들을 위한 개념

6.1 핵심 개념 설명

컨텍스트와 컨텍스트 윈도우: 컨텍스트는 LLM에 제공되는 입력을 의미한다. 보통 텍스트지만 요즘 모델은 이미지, 오디오, 비디오를 지원한다. 더 구체적으로 컨텍스트는 입력 토큰이다.

컨텍스트 윈도우는 LLM이 대화 중 한 번에 볼 수 있고 처리할 수 있는 최대 토큰 양을 의미한다. 모델의 작업 메모리와 같다. Opus 4.5는 200K 컨텍스트 윈도우를 가지고 있으며 이는 약 150,000 단어다.

도구 호출: LLM이 텍스트를 생성할 수 있다는 것은 알고 있지만 작업을 수행하게 하려면 어떻게 할까? 예를 들어 이메일 초안을 작성하거나, 날씨를 조회하거나, 구글 검색을 하게 하려면? 여기서 도구가 등장한다.

도구는 엔지니어가 정의한 함수로 정확히 그런 일을 한다. 도구를 정의하고 시스템 프롬프트에서 LLM에게 알려주면 대화 중에 어떤 도구를 호출할지 결정할 수 있다. 도구 호출(작업)이 수행되면 결과가 LLM에게 다시 전달된다.

에이전트: 가장 간단한 정의는 목표를 달성하기 위해 능동적으로 도구를 실행할 수 있는 LLM이다. 더 정교한 정의로는 Anthropic의 것이 있다: “에이전트는 LLM이 자신의 프로세스와 도구 사용을 동적으로 지시하고, 작업을 수행하는 방법에 대한 제어를 유지하는 시스템이다.”

“Agentic”: 모델의 도구 호출 능력 - 얼마나 능동적인지, 도구 호출이 얼마나 정확한지(사용자의 의도를 감지하여 작업 수행, 올바른 도구 선택, 언제 멈출지 아는 것)를 의미한다.

하네스/스캐폴딩: Sonnet 4.5/Opus 4.5는 모델이다. 반자율적으로 작동하게 하려면 많은 “스캐폴딩”/코드 레이어, 프롬프트, 도구 호출, 소프트웨어 패키징/환경을 제공해야 한다. Claude Code는 하네스가 아니라 제품이다(TUI, 통합 등을 생각하라). Claude Code는 하네스를 가지고 있다.

6.2 학습 곡선 극복하기

기술적으로 가벼운 사람들도 Claude Code를 사용할 수 있다. 실제로 CC는 범용 에이전트에 가깝다 - 코딩뿐만 아니라 Excel 송장 만들기, 데이터 분석, 기계에서 심부름 등 다른 작업에도 사용할 수 있다.

Twitter의 한 사용자가 말했듯이: “Claude Code를 처음 사용하는데, 공식적으로 이력서에 ‘기술적으로 가벼운’을 넣을 수 있게 되었다.”

에필로그: 변화 속에서 길 찾기

따라잡기에 대한 새로운 관점

Karpathy의 “따라잡기 어렵다” 트윗은 많은 담론을 불러일으켰다. 하지만 “따라잡기”라는 관점 대신, 더 나은 프레이밍은 “이 도구들로 어떻게 자신을 향상시킬 수 있는가” 즉 증강이다.

자신을 증강하는 3가지 요소:

도구링 업데이트 유지: 이 도구들을 정기적으로 사용하고 릴리즈를 따라가라. 힘들 수 있지만 즐거운 과정이고 업무에 도움이 된다. 기술적으로 가벼운 사람들에게는 주간/월간 업데이트도 도움이 될 것이다.
도메인 역량 강화: 수직적으로(도메인 깊이)와 수평적으로(인접 영역) 확장하기 좋은 시기다. 더 많이 알수록 더 잘 프롬프트할 수 있다 - 알려지지 않은 미지수를 알려진 미지수로 변환한다. 경험은 판단력과 취향을 만든다 - 이것이 전문 개발자를 바이브 코더와 구별하는 것이다.
구현이 훨씬 빠르므로 이제 취향 개선에 더 많은 시간을 쓸 수 있다.
소프트웨어 엔지니어링 분야에서는 좋은 관행, 시스템 디자인, 계획 - 더 많은 사고가 필요한 곳에서 더 나아지는 것을 의미할 수 있다. 더 많은 질문을 하고, 더 많은 실험을 실행하고(빠르게 반복할 수 있으므로), 요구사항 이해에 더 많은 시간을 쓰라.
더 많이 놀고 열린 마음 갖기: 더 많은 모델, 특히 최첨단 모델을 시도하라. 인색하게 굴지 마라. 질문하고, 모델에게 작업을 시키고, 할 수 없다고 생각하는 것도 시도하라. 놀랄 것이다. 이것을 충분히 하면 직관이 생긴다.

워크플로우의 미래

Claude Code는 올해 CLI 코딩 제품 경험을 지배했으며, Codex, OpenCode, Amp CLI, Vibe CLI 심지어 Cursor와 같은 모든 CLI 제품들이 이로부터 큰 영감을 받았다. 이것은 Claude Code에서 작동하는 방식을 배우는 것이 개인 사용과 프로덕션 급 엔지니어어링 측면 모두에서 다른 도구로 직접 전환된다는 것을 의미한다.

현재 경험이 좋지만, 때때로 거의 배경 에이전트가 된 것 같다고 느낀다. 그런 다음 모델이 특정 버그를 해결할 수 없을 때 똑똑함을 느낀다.

트위터에 농담처럼 올렸다: “내가 배경 에이전트라는 것을 깨달았을 때 Claude와 Codex가 나를 보는 모습.”

앞으로의 전망

새로운 릴리즈를 더 이상 기대하지 않는다. 어차피 계속 일어나기 때문이다(OpenAI를 향한 외침). Deepseek과 Kimi K3가 대기 중이다.

2026년에는 다음을 기대한다:

RL 훈련의 개선
새로운 어텐션 아키텍처를 통한 장문 컨텍스트 효과 개선
더 높은 처리량 모델
환각이 적은 모델
o1/o3 수준의 추론 돌파구 또는 지속적 학습의 무언가

이것들을 기대하지만 동시에 무섭다. 더 중요한 능력 잠금 해제는 세상을 예측 불가능하게 만들 것이기 때문이다.

Dario Amodei의 사진과 함께: “현재로서는 Dario가 하늘의 명령을 가지고 있다.”

최종 조언

이 엄청나게 긴 글에서 많은 것을 배웠기를 바라며, 학습한 내용을 CC뿐만 아니라 다른 도구에도 적용하기를 바란다. 조금 이상하게 들리지만 우리는 변혁적인 시대를 겪고 있다.

이 글이 유용했다면 오늘 이 글에서 새로운 기능 하나를 시도해보라. 즐거운 빌딩을!

참고 자료

Anthropic 공식 자료

Claude Code 문서

Claude Code Changelog
Checkpointing](https://code.claude.com/docs/en/checkpointing)
Agent Skills](https://code.claude.com/docs/en/skills)

연구 자료

Context Rot - Chroma의 컨텍스트 저하 연구
Context Engineering for AI Agents: Lessons from Building Manus
Claude Code System Prompts - 역엔지니어링된 프롬프트

커뮤니티 리소스

awesome-claude-code - 명령어, 훅, 스킬 모음
Claude Code is a beast - tips from 6 months of usage - Reddit 포스트

작성 일자: 2025-12-29

Claude Code의 진화: 2025년 한 해의 여정 #

2025년은 AI 코딩 에이전트의 격동의 해였다. Claude Code는 단순한 CLI 도구를 넘어서 개발자들의 일상적인 워크플로우를 근본적으로 변화시키는 제품으로 발전했다. 이 문서에서는 Claude Code가 어떻게 진화해왔는지, 그리고 왜 현재 CLI 코딩 제품 경험의 정점에 서 있는지를 탐구한다.

2025년 프론티어 모델 릴리즈 타임라인

2025년은 OpenAI와 Anthropic의 치열한 경쟁이 펼쳐진 해였다. 특히 주목할 만한 점은 OpenAI가 코드 생성 능력, 인텔리전스, 컨텍스트 윈도우 효율성, 명령어 준수 및 의도 감지에서 Anthropic을 따라잡았다는 것이다.

주요 릴리즈 일정

연초부터 2주마다 새로운 OpenAI 릴리즈가 쏟아졌다
Opus 4.5 출시 이후 45일도 채 지나지 않았다 (문서 작성 시점 기준)
중국의 오픈소스 경쟁자들(GLM-4.7, Kimi-K2, Minimax-2.1)이 등장했다

경쟁이 치열했지만 Anthropic과 OpenAI는 여전히 중국 프론티어 모델들을 앞서고 있다. 다만 후자는 DeepSeek R1 논문이나 연초의 Kimi K2 논문처럼 기술 오픈소싱에서 더 많은 기여를 했다.

Claude와의 사랑과 미움: 개인적인 여정

Codex 시대의 시작 (2025년 6월-9월)

늦은 6월부터 9월 초까지 Claude Code를 메인 드라이버로 사용했던 필자는 9월 초에 Claude Max 구독(월 100달러)을 취소하고 OpenAI Codex로 전환했다. 전환의 주요 이유는 두 가지였다:

첫째, Sonnet 4/Opus 4가 특별히 마음에 들지 않았고, GPT-5-codex가 Sonnet 4.5와 동등하게 작동하면서 훨씬 더 나은 코드를 작성했다. 둘째, Anthropic에는 수많은 API 중단이 있었고, 한때는 추론 버그로 인한 성능 저하가 있었다. 이것도 많은 사람들이 Codex나 Cursor의 GPT-5.1로 이동하게 된 주요 원인이었다.

더불어 9월에는 시스템 디자인과 사고 작업이 많아서 Claude Max 플랜이 좋은 거래가 아니었다. Codex는 월 20달러 구독으로 엄청난 가치를 제공했고 거의 속도 제한에 걸리지 않았다.

Anthropic의 귀환 (2025년 10월-11월)

10월 말까지 Codex(메인 드라이버)와 Cursor(구독 유지)를 사용했다. Claude Sonnet 4.5가 9월 29일에 Claude Code 2.0과 함께 출시되었고, 다른 이메일 계정으로 20달러 구독을 해서 시도해봤지만 GPT-5/GPT-5-codex가 전반적으로 더 나았다.

Sonnet 4.5의 문제는 빠르고 좋았지만 많은 무분별한 변경을 만들어 버그를 유발한다는 것이었다. 즉, 나중의 GPT-5.1/GPT-5.1-codex에 비해 많은 “슬롭(slop)”을 생산하는 것처럼 느껴졌다.

10월 30일경 Anthropic이 구독을 취소한 사용자들에게 200달러 맥스 플랜을 제공한다는 이메일을 보냈고, 당연히 받아들였다. 11월 24일 Opus 4.5가 출시되었고, 5일 동안 미친 듯이 사용했다. 업무에 사용하고 매우 기술적인 블로그 글도 작성하면서 여러 능력을 발견했다.

Opus 4.5가 특별한 이유

Opus 4.5는 코드 생성 능력에서 GPT-5.1-Codex-Max와 거의 동등했다. 현재 경험상 GPT-5.2-Codex가 작은 차이로 Opus 4.5를 능가한다고 생각하지만, Opus 4.5는 출시 이후 메인 드라이버가 되었다.

첫 번째 이유는 더 빠르고 Codex보다 훨씬 적은 시간에 비슷한 난이도의 작업을 수행할 수 있다는 것이다. 또한 전반적으로 Codex보다 훨씬 더 나은 커뮤니케이터이자 페어 프로그래머다. Codex는 때때로 지시를 무시하고 변경을 가할 수 있다. Opus는 의도 감지도 더 뛰어나다.

같은 프롬프트에 대해 Codex는 여전히 조금 더 간결하지만 Claude는 기대에 부합한다. Codex는 항상 중첩된 불릿으로 작성하는 반면, Claude는 더 대화적인 톤을 가지고 있다.

더 빠르다는 것은 작업 수행에 필요한 사고 시간이 적을 뿐만 아니라 처리량 면에서도 더 빠르다는 의미이며, 이는 작업에 대해 훨씬 더 빠른 피드백 루프를 열어준다. 이것은 11월에 GPT-5.1/Codex가 능력 면에서 동등했음에도 불구하고 진전이 더 실감나게 느껴지게 만든다.

Opus 4.5는 훌륭한 작가이며 인간에 가장 가까워서 프롬프트를 커스터마이징하는 데 항상 Claude 모델을 선호해왔다. 많은 사람들이 Opus 4.5의 개성과 말하는 방식을 사랑하며, 일부는 Opus 4.5가 “영혼”을 가지고 있다고 언급한다. 이 특성은 Sonnet 3.7, Sonnet 4, Opus 4, Opus 4.1에서는 다소 덜했지만 Opus 4.5에서 돌아왔다. Amanda Askell이 “영혼”을 Claude에 후훈련시켰다.

Claude Code 2.0의 품질 개선 사항

Claude Code는 제품으로서 Codex보다 훨씬 앞서 있다. 하네스, 프롬프트, 그리고 모델이 마법 같은 경험을 만들어낸다. 모델은 놀랍지만, 맛있게 엔지니어링된 UX/UI와 Claude가 하네스에서 편안함을 느끼고 함수 호출을 정확하게 할 수 있도록 하는 코드/프롬프트가 엄청나게 많다.

주요 기능 업데이트

1. 구문 강조 (Syntax Highlighting)

2.0.71에서 최근 추가되었다. 시간의 80%를 Claude Code CLI에서 보내기 때문에 이 변경 사항은 기쁨이었다. 대부분의 것을 Claude Code에서 한 번 검토하는 것을 좋아한다. Opus 4.5가 정말 좋다는 점 외에도 이 기능 덕분에 코드를 검토하기 위해 Cursor를 전혀 열지 않게 되었다.

2. 팁 (Tips)

Claude가 생각할 때 표시되는 팁에서 많은 것을 배웠다. 비침습적인 방식으로 유용한 정보를 제공한다.

3. 피드백 UI

이런 피드백 요청 방식은 꽤 우아하다. 가끔씩 나타나며 숫자 키로 빠르게 응답할 수 있다(1: 나쁨, 2: 괜찮음, 3: 좋음) 또는 0으로 무시할 수 있다.

4. 질문 모드 옵션

옵션 3을 좋아한다 - “Claude에게 다르게 해야 할 것을 입력하세요”. 재미있는 사실: 이것들은 모두 모델을 위한 프롬프트이며, 그 출력은 다른 도구 호출로 파싱되어 이런 식으로 표시된다.

5. 울트라싱크 (Ultrathink)

어려운 작업이나 Opus 4.5가 더 엄격하기를 원할 때, 예를 들어 무언가를 설명하거나 변경 사항을 자체 검토할 때 울트라싱크를 많이 사용한다.

6. 생각 토글 (Thinking Toggle)

Tab으로 생각을 켜고 끄는 것은 좋은 기능이었다. 최근에 Alt/Option + Tab으로 변경되었지만 Mac에서 작동하지 않는 버그가 있다. 어쨌든 settings.json을 확인하면 CC는 기본적으로 생각을 항상 켜짐으로 설정한다.

7. `/context` 명령

현재 컨텍스트 사용량을 보려면 /context를 사용한다. 꽤 자주 사용하는 편이다. 복잡한 것을 구축할 때 총 60%에 도달하면 핸드오프나 컴팩트를 수행한다.

8. `/usage`와 `/stats`

사용량을 보려면 /usage를, 통계를 보려면 /stats를 사용한다. 이것들은 자주 사용하지 않는다.

9. 체크포인팅 (Checkpointing)

Esc + Esc 또는 /rewind 옵션은 이제 Cursor에서 할 수 있는 것처럼 특정 체크포인트로 돌아갈 수 있게 한다. 코드와 대화를 모두 되감을 수 있다. 이것은 필자에게 주요 기능 요청이었다.

10. 프롬프트 제안 (Prompt Suggestions)

2.0.73에서 최근 추가되었으며 예측이 꽤 괜찮다. Claude Code는 이제 토큰을 대량으로 소비하는 기계가 되었다.

11. 프롬프트 히스토리 검색

Ctrl + R을 사용하여 프롬프트를 검색한다(터미널 역방향 검색과 유사). 2.0.74에 있다. 프로젝트 전체 대화에서 검색할 수 있다. Ctrl + R을 반복해서 누르면 결과를 순환한다.

12. 커서 순환 (Cursor Cycling)

프롬프트의 처음/끝에 도달하면 아래/위를 눌러 순환한다.

13. 메시지 큐 탐색

이제 대기 중인 메시지와 이미지 첨부 파일을 탐색할 수 있다(2.0.73).

14. 퍼지 파일 검색

파일 제안이 3배 빠르고 퍼지 검색을 지원한다(2.0.72).

15. LSP 지원

최근 추가되었다. 플러그인을 통해 액세스한다.

제품으로서의 Claude Code

제품으로서 Claude Code는 Codex보다 QoL 기능에서 한참 앞서 있다. 하네스, 프롬프트, 그리고 모델이 마법 같은 경험을 만들어낸다. 모델은 놀랍지만, Claude가 하네스에서 편안함을 느끼고 함수 호출을 정확하게 만들 수 있도록 UX/UI와 코드/프롬프트에 들어간 맛있는 엔지니어링이 엄청나게 많다.

Claude Code는 올해 CLI 코딩 제품 경험을 지배했으며, Codex, OpenCode, Amp CLI, Vibe CLI 심지어 Cursor와 같은 모든 CLI 제품들이 이로부터 큰 영감을 받았다. 이것은 Claude Code에서 작동하는 방식을 배우는 것이 개인 사용과 프로덕션 급 엔지니어링 측면 모두에서 다른 도구로 직접 전환된다는 것을 의미한다.

마치며

Claude Code는 단순한 코딩 도구가 아니라 개발자 경험의 새로운 패러다임을 제시하는 제품으로 진화했다. Opus 4.5의 놀라운 능력과 결합되어 2025년 말 현재 가장 즐거운 제품 경험 중 하나를 제공한다. 앞으로도 계속해서 진화할 이 도구가 개발자들의 워크플로우를 어떻게 변화시킬지 기대된다.

작성 일자: 2025-12-29

Claude Code 기능 심층 분석: 명령어, 서브에이전트, 그리고 그 너머 #

Claude Code는 표면적으로는 단순한 CLI 도구처럼 보이지만, 그 내부에는 정교하게 설계된 기능들이 층층이 쌓여 있다. 이 문서에서는 Claude Code의 핵심 기능들을 깊이 있게 탐구하고, 이들이 어떻게 작동하며 왜 그렇게 설계되었는지를 살펴본다.

명령어 시스템 (Commands)

내장 명령어와 커스텀 명령어

/를 사용하여 내장 슬래시 명령어에 액세스할 수 있다. 이것들은 특정 작업을 수행하는 사전 정의된 프롬프트다.

만약 이것들이 원하는 특정 작업을 다루지 않는다면, 커스텀 명령어를 만들 수 있다. 명령어를 입력하면 그 프롬프트가 현재 대화/컨텍스트에 추가되고 메인 에이전트가 작업을 수행하기 시작한다.

명령어는 프로젝트 레벨이나 글로벌 레벨로 만들 수 있다. 프로젝트 레벨은 .claude/commands/에, 글로벌은 ~/.claude/commands에 위치한다.

실용적인 활용 예시

컨텍스트 윈도우가 가득 차기 시작하거나 모델이 복잡한 작업에 어려움을 겪는다고 느껴지면, 종종 /clear를 사용하여 새 대화를 시작하고 싶어진다. Claude는 CC 2.0에서 더 빠르게 실행되는 /compact를 제공하지만, 때로는 Claude가 현재 세션에서 일어난 일을 작성하게 한 후(특정 사항과 함께) 종료하고 새로 시작하는 것을 선호한다. 이를 위해 /handoff 명령을 만들었다.

어떤 것에 대해 반복적으로 프롬프트를 작성하고 있고 지시사항이 정적/정확할 수 있다면, 커스텀 명령어를 만드는 것이 좋은 아이디어다. Claude에게 커스텀 명령어를 만들도록 요청할 수 있다. Claude는 방법을 알고 있거나(또는 웹을 검색하고 claude-code-guide.md를 통해 알아낼 것이다) 당신을 위해 만들어줄 것이다.

고급 명령어 활용

bootstrap-repo라는 명령어를 가지고 있는데, 이것은 10개의 병렬 서브에이전트로 리포지토리를 검색하여 포괄적인 문서를 만든다. 요즘은 거의 사용하지 않으며, 너무 많은 병렬 서브에이전트는 Claude Code 깜박임 버그를 일으킨다.

“Explore” 서브에이전트가 병렬로 실행되고 “백그라운드에서 실행 중” 상태를 확인할 수 있다.

서브에이전트 (Sub-agents)

서브에이전트란?

서브에이전트는 이전 포스팅 직후에 도입되었다. 이것들은 메인 에이전트가 자체 판단에 따라 또는 사용자가 지시할 때 생성하는 별도의 Claude 인스턴스다. 이러한 능력은 이미 시스템 프롬프트에 있다(적어도 Explore와 같은 사전 정의된 것들의 경우). 때로는 Claude에게 사용하도록 넛지만 주면 된다. 어떻게 작동하는지 이해하면 마이크로 매니징이 필요할 때 도움이 된다.

커스텀 서브에이전트를 정의할 수도 있다. 만들려면:

.claude/agents/your-agent-name.md에 마크다운 파일을 만든다
에이전트의 이름, 지시사항, 허용된 도구를 지정한다

또는 /agents를 사용하여 서브에이전트를 자동으로 관리하고 만들 수 있다 - 권장되는 접근 방식이다.

Explore 에이전트

“Explore”는 서브에이전트다. Sonnet 4.5를 사용하고 싶다면 “Sonnet 4.5로 Explore 에이전트를 실행해”라고 Claude에게 말할 수 있다(이것을 시도해보면서 발견했지만 어떻게 작동하는지 볼 것이다).

Explore 에이전트는 읽기 전용 파일 검색 전문가다. Glob, Grep, Read, 그리고 제한된 Bash 명령을 사용하여 코드베이스를 탐색할 수 있지만 파일을 만들거나 수정하는 것은 엄격히 금지되어 있다.

프롬프트가 언제 어떤 도구 호출을 사용할지 지정하는 데 얼마나 철저한지 알아차릴 것이다. 음, 대부분의 사람들은 도구 호출을 정확하게 작동시키는 것이 얼마나 어려운지 과소평가한다.

Explore 에이전트 프롬프트의 핵심

프롬프트는 다음과 같은 핵심 지침을 포함한다:

읽기 전용 모드의 중요성: 이것은 읽기 전용 탐색 작업이다. 다음을 엄격히 금지한다:

새 파일 생성 (Write, touch, 또는 어떤 형태의 파일 생성도)
기존 파일 수정 (Edit 작업 없음)
파일 삭제 (rm 또는 삭제 없음)
파일 이동 또는 복사 (mv 또는 cp 없음)
/tmp를 포함한 어디에도 임시 파일 생성 없음
리다이렉트 연산자(>, », ) 또는 heredocs를 사용하여 파일에 쓰기
시스템 상태를 변경하는 어떤 명령도 실행

역할은 독점적으로 기존 코드를 검색하고 분석하는 것이다.

강점:

Glob 패턴을 사용한 빠른 파일 찾기
강력한 정규식 패턴으로 코드와 텍스트 검색
파일 내용 읽기 및 분석

가이드라인:

광범위한 파일 패턴 매칭에는 Glob을 사용
정규식으로 파일 내용을 검색하려면 Grep을 사용
읽어야 할 특정 파일 경로를 알 때는 Read를 사용
Bash는 읽기 전용 작업(ls, git status, git log, git diff, find, cat, head, tail)에만 사용
호출자가 지정한 철저함 수준에 따라 검색 접근 방식을 조정
최종 응답에서 파일 경로를 절대 경로로 반환
명확한 커뮤니케이션을 위해 이모지 사용 피하기
최종 보고서를 일반 메시지로 직접 커뮤니케이션 - 파일 생성 시도 금지

중요 사항: 가능한 한 빠르게 출력을 반환하도록 설계된 빠른 에이전트다. 이를 달성하려면:

사용 가능한 도구를 효율적으로 사용: 파일과 구현을 검색하는 방법에 대해 현명하게 행동
가능한 한 파일을 grep하고 읽기 위해 여러 병렬 도구 호출을 생성하려고 시도

서브에이전트의 컨텍스트 상속

general-purpose와 plan 서브에이전트는 전체 컨텍스트를 상속하지만, Explore는 새로운 슬레이트로 시작한다. 이것은 검색 작업이 종종 독립적이기 때문에 의미가 있다. 많은 작업은 관련된 것을 필터링하기 위해 대량의 코드를 검색하는 것을 포함하며, 개별 부분은 이전 대화 컨텍스트가 필요하지 않다.

기능을 이해하려고 하거나 코드베이스에서 간단한 것을 찾고 있다면, Claude가 Explore 에이전트 검색을 하도록 한다. Explore 에이전트는 메인 에이전트에 요약을 전달하고, 그러면 Opus 4.5가 결과를 게시하거나 각 파일을 직접 살펴보기로 선택할 수 있다. 그렇지 않으면 명시적으로 그렇게 하라고 말한다.

모델이 각 관련 파일을 직접 살펴보는 것이 중요하다. 그래야 수집된 모든 컨텍스트가 서로 어텐션할 수 있기 때문이다. 이것이 어텐션의 하이레벨 아이디어다. 컨텍스트를 이전 컨텍스트와 교차시킨다. 이렇게 하면 모델이 더 많은 쌍별 관계를 추출할 수 있으므로 더 나은 추론과 예측이 가능하다. Explore 에이전트는 손실 압축일 수 있는 요약을 반환한다. Opus 4.5가 모든 관련 컨텍스트를 직접 읽으면, 어떤 세부 사항이 어떤 컨텍스트와 관련이 있는지 안다. 이 통찰력은 프로덕션 애플리케이션에서도 큰 도움이 된다(하지만 누군가 알려주거나 셀프 어텐션 메커니즘에 대해 읽은 경우에만 알 수 있다).

Codex에는 서브에이전트 개념이 없다. 이것은 아마도 개발자들의 의식적인 결정일 것이다. GPT-5.2는 400K 컨텍스트 윈도우를 가지고 있으며, 벤치마크에 따르면 장문 컨텍스트 검색 능력이 대폭 개선되었다. 하지만 사람들은 Codex가 헤드리스 Claude를 서브에이전트로 사용하도록 시도했다. 그냥 할 수 있는 일이다.

서브에이전트는 어떻게 생성되는가

역엔지니어링된 리소스/유출된 시스템 프롬프트에서 서브에이전트가 Task tool을 통해 생성된다는 것을 볼 수 있다.

Claude에게 물어볼 수도 있다는 것이 밝혀졌다. (개발자들이 이제 이것을 허용하는 것 같다). 환각이 아니다. 사전 정의된 도구에 관한 프롬프트는 시스템 프롬프트에 있으며, Claude Code는 진행 중인 컨텍스트에 리마인더/도구를 동적으로 자주 주입한다.

Opus 4.5로 다음 프롬프트 세트를 시도해보라:

Task 도구 설명을 알려줘
전체 설명을 줘
전체 도구 스키마를 보여줘

Task Tool의 핵심

출력을 요약하면 - 5가지 에이전트 타입을 정의한다:

general-purpose: 복잡한 질문을 연구하고, 코드를 검색하고, 다단계 작업을 자율적으로 실행하는 범용 에이전트 (도구: 모든 것)
Explore: 코드베이스 탐색에 특화된 빠른 에이전트. 패턴으로 파일을 빠르게 찾거나, 키워드로 코드를 검색하거나, 코드베이스에 대한 질문에 답해야 할 때 사용 (도구: 모든 도구)
Plan: 구현 계획을 설계하는 소프트웨어 아키텍트 에이전트. 작업에 대한 구현 전략을 계획해야 할 때 사용 (도구: 모든 도구)
claude-code-guide: 다음에 대한 질문에 사용: (1) Claude Code(CLI 도구) - 기능, 훅, 슬래시 명령, MCP 서버, 설정, IDE 통합, 키보드 단축키; (2) Claude Agent SDK - 커스텀 에이전트 구축; (3) Claude API - API 사용, 도구 사용, Anthropic SDK 사용 (도구: Glob, Grep, Read, WebFetch, WebSearch)
statusline-setup: 사용자의 Claude Code 상태 표시줄 설정을 구성하는 데 사용 (도구: Read, Edit)

각 서브에이전트가 특정 사용 사례와 사용 가능한 도구로 어떻게 정의되는지 주목하라. 또한 “언제 사용하지 말아야 하는가” 섹션에 주목하라 - 이런 종류의 부정적 가이던스는 모델이 간단한 작업에 대한 불필요한 서브에이전트 생성을 피하는 데 도움이 된다.

Task Tool 스키마

도구 스키마에 집중하자. 위의 Task 도구 프롬프트는 시스템 프롬프트에 있는 도구 사용 방법에 대한 자세한 가이던스다. 도구 스키마는 도구 또는 함수를 정의한다.

주요 필드:

description: 작업의 짧은(3-5단어) 설명
prompt: 에이전트가 수행할 작업
subagent_type: 이 작업에 사용할 특화된 에이전트 타입
model: “sonnet”, “opus”, 또는 “haiku” 중 선택 - 기본값은 부모 모델
resume: 이전 실행에서 계속할 에이전트 ID (선택 사항)
run_in_background: 에이전트를 백그라운드에서 실행하려면 true로 설정 (선택 사항)

메인 에이전트는 Task 도구를 호출하여 서브에이전트를 생성하고, 추론을 사용하여 매개변수를 결정한다. model 매개변수를 주목하라 - “Sonnet으로 Explore를 사용해”라고 말하면, 모델이 model: "sonnet"으로 도구 호출을 만든다.

8월경까지 Claude Code는 TUI에서 Task 도구가 작업을 수행하는 것을 보여줬지만, 이제 TUI는 대신 서브에이전트 이름을 표시한다.

백그라운드 에이전트 활용

run_in_background 매개변수를 주목하라. 이것은 서브에이전트를 백그라운드에서 실행할지 여부를 결정한다. 백그라운드 프로세스 기능을 좋아한다 - 디버깅이나 프로세스에서 로그 출력을 모니터링하는 데 매우 유용하다. 때때로 모니터링하고 싶은 장시간 실행되는 파이썬 스크립트가 있다.

모델은 일반적으로 프로세스를 백그라운드에 넣을지 자동으로 결정하지만 명시적으로 그렇게 하라고 말할 수 있다. “백그라운드 작업”은 다르다는 점에 유의하라. &를 사용하여 작업을 Claude Web에 보낸다(Claude Cloud라고 이름을 지었어야 했다). 이것을 제대로 작동시키는 것은 아직 못했다.

마치며

Claude Code의 기능들은 단순히 편의를 위한 것이 아니라, 컨텍스트 관리, 효율적인 도구 호출, 그리고 정확한 에이전트 동작을 위해 정교하게 설계된 시스템의 일부다. 명령어와 서브에이전트를 이해하고 활용하면, Claude Code의 진정한 힘을 발휘할 수 있다.

작성 일자: 2025-12-29

Claude Code 워크플로우: 효율적인 개발을 위한 실전 가이드 #

도구는 훌륭하지만, 진정한 마법은 그것을 어떻게 사용하느냐에 있다. 이 문서는 Claude Code를 실제 개발 워크플로우에 통합하는 방법과, 수많은 시행착오를 통해 얻은 실용적인 인사이트를 공유한다.

기본 설정 (Setup)

도구 스택 구성

꽤 단순하고 작업 기반의 워크플로우를 가지고 있다:

Claude Code: 메인 드라이버
Codex: 검토 및 어려운 작업용
Cursor: 코드 읽기 및 수동 편집용

플랜 모드는 거의 사용하지 않는다. 대신 요구사항이 충분히 명확해지면 관련 파일을 직접 찾기 위해 코드베이스를 탐색한다.

커스텀 도구 활용

몇 가지 커스텀 명령을 유지하고, CLAUDE.md와 스크래치패드를 광범위하게 사용한다. 커스텀 서브에이전트는 없다. 필요할 때 가끔 MCP를 사용한다(예: 문서용. 지금까지 Playwright와 Figma MCP를 시도해봤다) 하지만 일반적으로는 팬이 아니다. 과거에 간단한 것들에 훅을 사용했고 필요에 따라 사용한다. 스킬/플러그인은 아직 정기적으로 사용해야 할 것이다. 관찰성(로그/오류 모니터링) 목적으로 백그라운드 에이전트를 자주 사용한다. Git worktrees는 거의 사용하지 않는다.

하네스가 너무나 철저하게 엔지니어링되어 있어서 Claude는 어떤 서브에이전트를 생성할지, 어떤 명령/도구 호출/스킬을 실행할지, 무엇을 비동기 방식으로 실행할지 안다. 에이전트 루프를 크게 운반할 수 있어서 주요 작업은 판단력을 사용하고 올바른 방향으로 프롬프트하는 것이다. 다음 세대 모델은 더 나아질 것이고, 관련 스캐폴딩은 기존 기능에 대해서는 줄어들고 새로운 기능에 대해서는 증가할 것이다.

탐색 및 실행 (Exploration and Execution)

탐색 단계: 대화를 통한 이해

Opus 4.5는 설명에 놀랍고 뛰어난 ASCII 다이어그램을 만든다. 5월 지식 컷오프도 여기서 도움이 된다. 따라서 탐색은 많은 질문을 하는 것을 포함한다 - 요구사항 명확화, 어디서/어떻게/왜 변경해야 하는지 이해하기. 플랜 모드보다 효율적이지 않을 수 있지만 이 접근 방식을 좋아한다.

충분한 컨텍스트를 가지면 /ultrathink를 많이 사용하고 어떤 변경이 필요한지 묻는다. 그런 다음 괜찮아 보이면 변경 사항을 밀접하게 모니터링하면서 실행을 시작한다 - 기본적으로 마이크로 매니징한다. 때때로 여기서 Codex의 두 번째 의견을 묻기도 한다.

“일회용 초안” 접근법

어려운 새로운 기능의 경우, 때때로 “일회용 초안” 접근법을 사용한다. 어떤 변경이 필요한지 이해하면, 새 브랜치를 만들고 Claude가 관찰하는 동안 처음부터 끝까지 기능을 작성하게 한다. 그런 다음 출력을 요구사항에 얼마나 가까웠는지에 대한 정신적 모델과 비교한다. 어디서 벗어났는가?

백엔드 중심 또는 복잡한 기능의 경우 특히, 때때로 Codex xhigh에게 대신 계획을 생성하도록 요청한다.

무엇을 사용하고 사용하지 않는가 (What I Use and Don’t)

사용하는 것

몇 가지 커스텀 명령
CLAUDE.md와 스크래치패드를 광범위하게 사용
관찰성(로그/오류 모니터링) 목적의 백그라운드 에이전트
필요 시 MCP (문서, Playwright, Figma MCP)
간단한 작업을 위한 훅

사용하지 않는 것

커스텀 서브에이전트 (아직)
Git worktrees (거의)
스킬/플러그인 (정기적으로는 아직)
MCP (일반적으로는 팬이 아님, 필요 시에만)

판단의 중요성

하네스가 너무 철저하게 엔지니어링되어 있어서 Claude가 대부분의 작업을 자동으로 처리한다. 주요 작업은 판단력을 사용하고 올바른 방향으로 프롬프트하는 것이다. 기능을 깊이 알 필요는 없지만, 작동 방식을 이해하면 모델을 더 잘 조종할 수 있다.

검토 단계 (Review)

Codex를 활용한 코드 리뷰

코드를 검토하고 버그를 찾는 데는 GPT-5.2-Codex가 우수하다고 생각한다. 그냥 /review를 사용하면 된다. 코드 리뷰 제품보다 낫다.

검토 프로세스

Opus 4.5로 변경 사항 구현
GPT-5.2-Codex로 코드 검토 수행
발견된 버그와 개선 사항 확인
필요한 경우 수정 반복

컨텍스트 관리

컨텍스트 모니터링

/context를 사용하여 현재 컨텍스트 사용량을 자주 확인한다. 복잡한 것을 구축할 때 총 60%에 도달하면 핸드오프나 컴팩트를 수행한다.

컨텍스트 최적화 전략

컨텍스트가 50-60%에 도달하면: 새로운 대화를 시작하거나 /compact 실행
복잡한 작업 시작 전: 항상 컨텍스트 상태 확인
핸드오프 명령 사용: 현재 세션의 중요한 정보를 요약하고 새 세션으로 전환

실용적인 팁

울트라싱크 활용

어려운 작업이나 Opus 4.5가 더 엄격하기를 원할 때 울트라싱크를 많이 사용한다. 예를 들어:

복잡한 개념 설명이 필요할 때
변경 사항을 자체 검토할 때
아키텍처 결정이 필요한 경우

질문 주도 개발

Claude와 대화하면서 개발하는 접근법:

요구사항에 대해 질문
코드베이스 구조 이해
변경이 필요한 위치와 방법 파악
구현 전략 검증
단계별 실행

이 방법은 플랜 모드보다 덜 효율적일 수 있지만, 더 깊은 이해와 더 나은 결과를 제공한다.

다른 도구와의 통합

Claude Code + Codex + Cursor

세 가지 도구를 조합하여 사용하는 이유:

Claude Code: 빠른 반복, 우수한 커뮤니케이션, 메인 개발
Codex: 깊은 검토, 버그 발견, 복잡한 작업 계획
Cursor: 코드 읽기, 빠른 수동 편집

각 도구의 강점을 활용하여 최상의 결과를 얻는다.

워크플로우 진화

지속적인 학습

도구와 모델은 계속 진화한다. 다음 세대 모델은 더 나아질 것이고:

기존 기능에 대한 스캐폴딩은 줄어들 것
새로운 기능에 대한 스캐폴딩은 증가할 것
판단력과 프롬프팅의 중요성은 계속될 것

실험 정신

새로운 기능이나 접근법을 시도하는 것을 두려워하지 마라. Claude Code는 안전하게 실험할 수 있는 환경을 제공한다:

체크포인팅으로 쉽게 되돌릴 수 있음
서브에이전트로 병렬 탐색 가능
백그라운드 에이전트로 장시간 작업 모니터링

마치며

효율적인 워크플로우는 도구의 기능을 이해하고, 각 도구의 강점을 활용하며, 지속적으로 배우고 실험하는 것에서 나온다. Claude Code는 강력한 하네스와 프롬프트로 대부분의 무거운 작업을 수행하므로, 개발자는 판단력과 전략에 집중할 수 있다.

가장 중요한 것은 완벽한 워크플로우를 찾으려고 하지 말고, 자신의 작업 스타일과 프로젝트 요구사항에 맞는 워크플로우를 만들어가는 것이다. 도구는 계속 진화하고, 우리의 워크플로우도 함께 진화해야 한다.

작성 일자: 2025-12-29

컨텍스트 엔지니어링: AI 에이전트의 메모리 관리 예술 #

컨텍스트 엔지니어링은 AI 에이전트의 효율성을 결정짓는 가장 중요한 요소 중 하나다. 이 문서에서는 컨텍스트가 무엇인지, 왜 중요한지, 그리고 Claude Code가 어떻게 정교한 컨텍스트 관리 시스템을 구축했는지 탐구한다.

에이전트는 토큰 소비의 거물

도구 호출과 컨텍스트 축적

하네스의 에이전트는 코드베이스를 읽고, 편집하고, 쓰기를 만들기 위해 많은 도구 호출을 능동적으로 수행할 수 있다. 이 과정에서 엄청난 양의 데이터가 생성되어 실행 중인 대화, 즉 컨텍스트 윈도우에 추가된다. Anthropic은 이 정보에서 제한된 컨텍스트 윈도우에 무엇을 넣을지 큐레이션하는 이 기술과 과학을 컨텍스트 엔지니어링이라고 부른다.

도구 호출이 토큰을 추가하는 방법

도구 호출이 어떻게 컨텍스트 윈도우에 토큰을 추가하는지 의문이 들 수 있다. 플로우는 다음과 같이 작동한다:

컨텍스트 윈도우:
├─ 사용자: "내 커피숍을 위한 랜딩 페이지를 만들어줘"
│
├─ 어시스턴트: [tool_call: web_search("모던 커피숍 랜딩 페이지 디자인")]
├─ 도구 결과: [스니펫, URL이 포함된 10개 결과]           ← ~1.5K 토큰
│
├─ 어시스턴트: [tool_call: read_file("브랜드-가이드라인.pdf")]
├─ 도구 결과: [추출된 텍스트, 색상, 폰트]  ← ~4K 토큰
│  (여기에 있어야 함, 모델은 stateless)
│
├─ 어시스턴트: "당신의 브랜드 색상을 사용한 따뜻하고 미니멀한 디자인을 만들겠습니다..."
├─ 어시스턴트: [tool_call: create_file("landing-page.html")]
├─ 도구 결과: [성공, 140줄]                       ← ~50 토큰
│
├─ 어시스턴트: [tool_call: generate_image("아늑한 커피숍 인테리어")]
├─ 도구 결과: [반환된 이미지 URL]                       ← ~30 토큰
│
├─ 어시스턴트: [tool_call: edit_file("landing-page.html")]
├─ 도구 결과: [diff: 히어로 이미지 + 메뉴 섹션 추가]    ← ~300 토큰
│
└─ 어시스턴트: "완료! 히어로, 메뉴, 연락처 섹션이 있는 랜딩 페이지입니다."

총계: 한 작업에 ~6K+ 토큰. 모든 것이 컨텍스트에 남아 있음.

여기서 주목해야 할 핵심은 도구 호출과 도구 호출 출력이 모두 컨텍스트에 추가된다는 것이다. 이는 LLM이 결과를 알 수 있도록 하기 위함이다. LLM은 stateless다 - 컨텍스트 윈도우 밖에는 메모리가 없다. 대화에 n개의 메시지가 있다고 가정하자. 다음 메시지를 보내면 요청은 LLM에서 n + 1개의 메시지를 다시 처리한다 ~ 단일 컨텍스트 윈도우.

선택한 도구 호출에 대한 정보를 추가하지 않으면 LLM은 알 수 없고, 출력을 연결하지 않으면 결과를 알 수 없다. 도구 호출 결과는 컨텍스트를 빠르게 채울 수 있으며 이것이 에이전트가 매우 비쌀 수 있는 이유이기도 하다.

컨텍스트 엔지니어링의 정의

Anthropic의 effective-context-engineering-for-ai-agents에서 직접 인용:

컨텍스트는 대규모 언어 모델(LLM)에서 샘플링할 때 포함되는 토큰 세트를 의미한다. 당면한 엔지니어링 문제는 일관되게 원하는 결과를 달성하기 위해 LLM의 고유한 제약에 대해 이러한 토큰의 유용성을 최적화하는 것이다. LLM을 효과적으로 다루려면 종종 컨텍스트로 생각해야 한다 - 다시 말해서: 주어진 시간에 LLM이 사용할 수 있는 전체적인 상태와 그 상태가 어떤 잠재적 행동을 유발할 수 있는지 고려해야 한다.
컨텍스트 엔지니어링은 “어떤 컨텍스트 구성이 모델의 원하는 동작을 생성할 가능성이 가장 높은가?”라는 질문에 답하는 것이다.

지금까지 논의한 모든 것이 컨텍스트 엔지니어링에 해당된다. 서브에이전트, 스크래치패드 사용, 컴팩션은 Claude Code에서 사용되는 컨텍스트 관리 방법의 명백한 예다.

컨텍스트 부패/저하

제한된 컨텍스트 윈도우 - LLM의 컨텍스트 검색 성능은 새로운 토큰이 도입될 때마다 저하된다. 위 블로그를 의역하면 - 컨텍스트를 제한된 “어텐션 예산”으로 생각하라. 이것은 어텐션 메커니즘 자체의 결과로, 쌍별 관계를 모델링하기가 어려워진다 - 멀리 떨어진 것들에 집중하기가 어려워지는 것처럼 생각하면 된다.

GPT-5.2는 400K 입력 토큰의 컨텍스트 윈도우를 가지고 있다. Opus 4.5는 200K다. Gemini 3 Pro는 1M 컨텍스트 윈도우 길이를 가지고 있다. 이제 이러한 컨텍스트 윈도우의 효과는 다를 수 있으며, 길이만이 중요한 것은 아니다. 그렇긴 하지만 900K 길이의 입력에서 무언가를 묻고 싶다면 Gemini 3 Pro로만 가장 안정적으로 할 수 있을 것이다.

Chroma의 컨텍스트 부패 논문은 작업 난이도가 아닌 길이에 따른 성능 저하를 보여주는 일부 실험을 깊이 다룬다.

대략적으로 도출할 수 있는 결론은 효과적인 컨텍스트 윈도우는 아마도 50-60% 또는 그 이하일 것이다. 대화의 중간쯤에 복잡한 작업을 시작하지 마라. 컴팩션을 하거나 새로운 것을 시작하라.

프롬프트와 지금까지 본 코드에서 수행되는 모든 것은 다음을 위한 것이었다:

가장 관련성 높은 컨텍스트 연결
컨텍스트 비대화/무관한 컨텍스트 감소
모델이 따르기 쉽도록 적고 충돌하지 않는 지시사항 제공
리마인더와 런타임 주입을 통해 도구 호출이 더 잘 작동하도록 만들기

컨텍스트 관리 기법

MCP 서버와 코드 실행

MCP 서버는 필자의 주력은 아니지만 다룰 가치가 있다. MCP 서버는 기계나 인터넷에서 원격으로 호스팅될 수 있는 서버다. 이것들은 파일시스템, 도구, CRM, Google Drive와 같은 통합을 노출할 수 있다. 본질적으로 모델이 외부 도구와 서비스에 연결하는 방법이다.

MCP 서버에 연결하려면 MCP 클라이언트를 수용할 수 있는 호스트(Claude)가 필요하다. MCP 클라이언트는 프로토콜을 호출하여 연결할 수 있다. 연결되면 MCP 클라이언트는 서버가 제공하는 도구, 리소스, 프롬프트를 노출한다.

도구 정의는 호스트의 컨텍스트 윈도우에 미리 로드되어 비대화시킨다.

MCP를 활용한 코드 실행

코드 실행 with MCP의 아이디어가 마음에 든다. 비록 더 많은 토큰 소비를 위한 선전이긴 하지만.

Code execution with MCP에서 인용:

MCP 사용이 확대됨에 따라 에이전트 비용과 지연을 증가시킬 수 있는 두 가지 일반적인 패턴이 있다:
도구 정의가 컨텍스트 윈도우를 과부하시킨다;
중간 도구 결과가 추가 토큰을 소비한다.

더 많은 MCP 서버는 컨텍스트를 비대화시키는 더 많은 도구 정의를 의미한다.

MCP Code exec은 직접 도구 호출 대신 도구 호출 정의보다는 코드 API를 노출하고 Claude에게 파일시스템이 있는 샌드박스 실행 환경을 제공할 것을 제안한다. 그런 다음 도구 호출을 만들기 위한 코드를 작성하게 한다. 우아한 아이디어이며 “온디맨드 프롬프트”라는 점에서 스킬과 꽤 유사하다.

시스템 리마인더의 역할

컨텍스트 저하를 방지하는 한 가지 기법은 컨텍스트에 목표를 반복적으로 주입하는 것이다. Manus는 Context Engineering 블로그에서 그들의 접근 방식을 공유했다:

암송을 통한 어텐션 조작
Manus로 작업해본 적이 있다면 이상한 것을 알아차렸을 것이다: 복잡한 작업을 처리할 때 todo.md 파일을 만드는 경향이 있고 - 작업이 진행됨에 따라 단계별로 업데이트하면서 완료된 항목을 체크한다.
이것은 단지 귀여운 행동이 아니라 - 어텐션을 조작하기 위한 의도적인 메커니즘이다.
Manus의 일반적인 작업은 평균적으로 약 50번의 도구 호출을 필요로 한다. 긴 루프다 - 그리고 Manus는 의사결정을 위해 LLM에 의존하기 때문에 특히 긴 컨텍스트나 복잡한 작업에서 주제에서 벗어나거나 이전 목표를 잊어버릴 위험이 있다.
todo 목록을 지속적으로 다시 작성함으로써 Manus는 컨텍스트 끝에 목표를 암송하고 있다. 이것은 글로벌 계획을 모델의 최근 어텐션 범위로 밀어넣어 “중간에 잃어버린” 문제를 피하고 목표 불일치를 줄인다. 사실상 특별한 아키텍처 변경 없이도 자연어를 사용하여 자체 초점을 작업 목표 쪽으로 편향시키고 있다.

Claude Code도 todo 목록을 가지고 있다. 이제 그것의 논리 일부를 안다.

리마인더 태그의 활용

Claude Code는 또한 사용자 메시지와 도구 결과에 <system-reminder> 태그를 연결하여 유사한 것을 시도한다. 일부는 도구 설명에 언급되고, 다른 리마인더는 코드를 통해 런타임에 추가된다.

Claude에게 시스템 프롬프트에 어떤 시스템 리마인더가 있는지 물어봤다. 도구 결과와 사용자 메시지에는 <system-reminder> 태그가 포함될 수 있다. 이러한 태그는 유용한 정보와 리마인더를 포함한다. 시스템에 의해 자동으로 추가되며, 나타나는 특정 도구 결과나 사용자 메시지와 직접적인 관련이 없다.

CC 2.0.56의 이전 버전에는 이러한 상세한 리마인더가 있었다. system-reminder-plan-mode-is-active를 참조.

Armin은 자신의 포스트 What Actually Is Claude Code’s Plan Mode?에서 에이전트에게 상기시키는 반복 프롬프트를 언급할 때 이것에 대해 이야기하는 것으로 생각한다.

유출된 프롬프트를 보면 플랜 모드에 대해 2-3개의 프롬프트와 ENTRY_PLAN_MODE_TOOL, EXIT_PLAN_MODE_TOOL과 같은 2-3개의 도구 스키마가 있는 것을 알 수 있다. 후자는 출력을 /plan을 통해 액세스할 수 있는 마크다운 파일에 작성한다. 모든 것이 마크다운이다.

스킬과 플러그인

스킬: 온디맨드 전문지식

Anthropic은 최근 Agent Skills를 도입했고, 이것들은 최근 Codex에도 채택되었다. 스킬은 SKILL.md 파일, 기타 참조 가능한 파일, 그리고 사용자 정의 작업을 수행하는 코드 스크립트를 포함하는 폴더다.

SKILL.md는 LLM이 어떤 스킬이 사용 가능한지 알 수 있는 메타데이터를 포함한다(메타데이터는 시스템 프롬프트에 추가됨). Claude가 스킬이 관련이 있다고 느끼면 스킬의 내용을 읽기 위해 도구 호출을 수행하고 Matrix 1999의 Neo처럼 도메인 전문지식을 다운로드한다. 코드 스크립트는 Claude가 사용할 수 있는 도구를 포함할 수 있다.

일반적으로 도메인 전문지식을 가르치려면 시스템 프롬프트에 모든 정보를 작성하고 아마도 도구 호출 정의까지 작성해야 한다. 스킬을 사용하면 모델이 온디맨드로 로드하기 때문에 그렇게 할 필요가 없다. 이것은 특히 항상 해당 지시사항이 필요한지 확실하지 않을 때 유용하다.

플러그인: 패키징 메커니즘

플러그인은 스킬, 슬래시 명령, 서브에이전트, 훅, MCP 서버를 단일 배포 가능한 단위로 번들링하는 패키징 메커니즘이다. /plugins를 통해 설치할 수 있으며 충돌을 피하기 위해 네임스페이스가 지정된다(예: /my-plugin:hello). .claude/의 독립 실행형 구성은 개인/프로젝트별 사용에 좋지만, 플러그인은 프로젝트와 팀 간에 기능을 쉽게 공유할 수 있게 한다.

인기 있는 frontend-design 플러그인은 실제로 단지 스킬이다.

훅 (Hooks)

에이전트 라이프사이클 관찰

훅은 Claude Code와 Cursor에서 사용 가능하다(Codex는 아직 구현하지 않았다). 이것들은 에이전트 루프 라이프사이클의 특정 단계가 시작하거나 끝날 때 관찰하고 이전이나 이후에 bash 스크립트를 실행하여 에이전트 루프를 변경할 수 있게 한다.

Stop, UserPromptSubmit 등과 같은 훅이 있다. 예를 들어 Stop 훅은 Claude가 응답을 마친 후에 실행되고 UserPromptSubmit 훅은 Claude가 처리하기 전에 사용자가 프롬프트를 제출할 때 실행된다.

실용적인 훅 사용 예

첫 번째로 만든 훅은 Claude가 응답을 멈췄을 때 애니메이션 알림 소리를 재생하는 것이었다. 분명히 Cursor의 알림 소리에서 영감을 받았다.

한 가지 재미있는 사용 사례는 Stop 훅을 통해 Claude가 현재 작업을 마치면 “더 해” 프롬프트를 실행하여 Claude를 몇 시간 동안 실행하게 하는 것이다.

훅, 스킬, 리마인더의 결합

연구 중 흥미로운 포스트를 발견했다. 이 사람은 지금까지 논의한 개념과 기능을 아름답게 결합했다. 모델에게 스킬을 상기시키기 위해 훅을 사용한다. 유틸리티/요구사항이 발생하면 많은 커스터마이징 공간이 있다. 그런 무거운 커스터마이징이 필요하지 않을 수 있지만 적어도 영감을 받을 수 있다.

Anthropic은 skill.md를 500줄 이하로 유지할 것을 권장하므로 별도의 파일로 나누고 훅과 결합하여 CLAUDE.md의 크기를 줄였다. 지시사항을 스킬 파일로 나누어 CLAUDE.md 크기를 줄이는 전략이다.

마치며

컨텍스트 엔지니어링은 단순히 토큰을 관리하는 것이 아니라, AI 에이전트가 효율적이고 정확하게 작동할 수 있도록 정보를 전략적으로 구성하는 것이다. Claude Code는 서브에이전트, 리마인더, 스킬, 훅 등 다양한 기법을 통해 정교한 컨텍스트 관리 시스템을 구축했다.

이러한 기법들을 이해하고 활용하면:

더 효율적인 토큰 사용
더 정확한 에이전트 동작
더 안정적인 장기 작업 수행
더 나은 전반적인 개발 경험

을 달성할 수 있다.

앞으로 모델이 발전하면서 일부 스캐폴딩은 줄어들 것이지만, 컨텍스트 엔지니어링의 핵심 원칙은 계속해서 중요할 것이다. 제한된 어텐션 예산을 최대한 활용하는 것은 여전히 AI 에이전트 개발의 핵심 과제로 남을 것이다.

작성 일자: 2025-12-29

AI, Claude Code

AI Developer vibe-coding claude-code coding-agents Guide Claude.write

프롤로그: 변화의 시대

1부: 애증의 관계 - Anthropic과의 화해

1.1 Codex 시대: 이별의 서곡 (2025년 6-9월)

1.2 중간 지대: Sonnet 4.5의 슬롭 시대 (2025년 9-10월)

1.3 귀환: Opus 4.5와의 재회 (2025년 11월)

1.4 Opus 4.5가 특별한 이유

1.5 이 글은 스폰서 받은 게 아니다

2부: Claude Code 2.0의 진화

2.1 품질 개선의 향연

2.2 체크포인팅: 시간을 되돌리는 힘

2.3 프롬프트 제안과 히스토리 검색

2.4 기타 개선사항

2.5 새로운 통합

3부: 기능 심층 탐구

3.1 명령어 시스템의 힘

3.2 서브에이전트: 분신술의 예술

3.3 Explore 에이전트: 읽기 전용 탐색의 달인

3.4 서브에이전트의 생성 메커니즘

3.5 Codex와의 비교

4부: 워크플로우의 예술

4.1 설정: 도구의 조합

4.2 탐색과 실행: 질문 주도 개발

4.3 일회용 초안 접근법: 테넷 스타일

4.4 검토: Codex의 예리한 눈

4.5 하네스의 마법

5부: 컨텍스트 엔지니어링 - 메모리의 예술

5.1 에이전트는 토큰 소비의 거물

5.2 컨텍스트 엔지니어링의 정의

5.3 컨텍스트 부패: 주의력의 한계

5.4 MCP와 코드 실행

5.5 시스템 리마인더: 암송을 통한 어텐션 조작

5.6 리마인더 태그의 전략적 활용

5.7 스킬: Matrix의 Neo처럼

5.8 플러그인: 기능의 패키징

5.9 훅: 라이프사이클의 관찰자

5.10 고급 통합: 훅 + 스킬 + 리마인더

6부: 기술적으로 가벼운 사람들을 위한 개념

6.1 핵심 개념 설명

6.2 학습 곡선 극복하기

에필로그: 변화 속에서 길 찾기

따라잡기에 대한 새로운 관점

워크플로우의 미래

앞으로의 전망

최종 조언

참고 자료

Anthropic 공식 자료

Claude Code 문서

연구 자료

커뮤니티 리소스

Claude Code의 진화: 2025년 한 해의 여정 #

2025년 프론티어 모델 릴리즈 타임라인

주요 릴리즈 일정

Claude와의 사랑과 미움: 개인적인 여정

Codex 시대의 시작 (2025년 6월-9월)

Anthropic의 귀환 (2025년 10월-11월)

Opus 4.5가 특별한 이유

Claude Code 2.0의 품질 개선 사항

주요 기능 업데이트

1. 구문 강조 (Syntax Highlighting)

2. 팁 (Tips)

3. 피드백 UI

4. 질문 모드 옵션

5. 울트라싱크 (Ultrathink)

6. 생각 토글 (Thinking Toggle)

7. /context 명령

8. /usage와 /stats

9. 체크포인팅 (Checkpointing)

10. 프롬프트 제안 (Prompt Suggestions)

11. 프롬프트 히스토리 검색

12. 커서 순환 (Cursor Cycling)

13. 메시지 큐 탐색

14. 퍼지 파일 검색

15. LSP 지원

제품으로서의 Claude Code

마치며

Claude Code 기능 심층 분석: 명령어, 서브에이전트, 그리고 그 너머 #

명령어 시스템 (Commands)

내장 명령어와 커스텀 명령어

실용적인 활용 예시

고급 명령어 활용

7. `/context` 명령

8. `/usage`와 `/stats`