Claude Code 소스 유출이 AI 코딩을 바꾸는 이유
핵심 요약
- Claude Code 하네스 설계가 통째로 드러났다.
- Claude.md로 팀 규칙을 매 턴 강제할 수 있다.
- 병렬 에이전트와 프롬프트 캐시로 거의 무비용 병렬 처리가 가능하다.
- 권한 팝업은 설정 실패, Auto 모드가 기본값이어야 한다.
- 컨텍스트 압축과 /compact가 긴 세션 품질을 좌우한다.
- Claude Code 소스 유출이 AI 코딩을 바꾸는 이유
npm 레지스트리의 맵(map) 파일 하나에서 출발한 실수가, 결과적으로 AI 코딩 에이전트 역사에서 가장 깊숙한 ‘내부 설계 공개’ 사건이 됐다. Anthropic의 Claude Code 전체 소스코드(약 2,300개 파일, 50만 줄)가 유출되면서, 이 도구가 단순한 코드 어시스턴트를 넘어 ‘에이전트 하네스(Agent Harness)’ 수준으로 동작한다는 사실이 그대로 드러났다.
Related: 하네스 엔지니어링으로 LLM 코드 품질 멱등성 확보하기 | 실전 AX 가이드
Related: AI 네이티브 조직 구축 사례: 오픈클로 뽀짝이 커뮤니티 자동화 가이드
Related: 팔란티어 AI 에이전트와 온톨로지: 진짜 엔터프라이즈 AI 아키텍처 가이드
Related: AI 네이티브와 지능 배분 전략: 에이전틱 AI 시대 비즈니스 가이드
Related: 하네스 엔지니어링으로 AI 에이전트 품질·보안 높이는 설계법 | 실전 가이드
이런 규모의 실전 코드베이스를 뜯어보면 마케팅 문서에서는 절대 안 보이는 설계 철학과 시행착오가 고스란히 나온다. 이번 유출을 통해 Claude.md 제어 파일, 병렬 서브 에이전트 구조, 스마트 권한 시스템, 컨텍스트 압축(Compaction) 전략, Hooks·툴 시스템까지, Claude Code를 실제로 강하게 만들어 준 핵심 원리가 공개됐다. 영상 없이도 이해할 수 있도록 그 내용을 정리한다.
Claude Code 소스 유출이란 무엇인가?
Claude Code 소스 유출이란 Anthropic의 AI 코딩 에이전트 Claude Code 전체 소스가 npm 맵 파일을 통해 외부에 공개된 보안 사고를 말한다. 단순한 코드 노출을 넘어, 상용 최고 수준 에이전트 하네스의 설계 청사진을 통째로 드러냈다는 점에서 상징적인 사건으로 평가된다.
- npm 레지스트리 맵 파일 실수로 전체 소스가 노출됐다.
- 약 2,300개 파일, 50만 줄 규모의 코드베이스가 포함됐다.
- X(트위터)에서 24시간 내 2,200만 뷰를 기록했다.
- 커뮤니티가 Python 재작성 버전을 만들어 합법적으로 배포 중이다.
출발점은 배포한 npm 패키지에 소스 맵(map) 파일을 실수로 포함한 것이다. 트위터 유저 Fried Rice가 이를 발견해 전체 코드를 ZIP으로 공유했고, 24시간도 안 되어 뷰 수가 2,200만 회를 넘기며 AI 개발 커뮤니티를 뒤흔들었다.
코드베이스를 보면 단순한 “채팅 + 코드 실행” 수준이 아니라, 정교한 에이전트 실행 프레임워크(Agent Harness)임이 분명하다. DMCA 조치가 예상됐지만 누군가 전체 코드를 Python으로 재작성해 공개했고, 이 재작성본은 기존 저작권과 별개로 취급되어 합법적으로 다운로드·실행이 가능한 상태가 됐다.
“Claude Code는 놀라운 하네스입니다. 이 하네스 덕분에 대형 언어 모델이 훨씬 잘 작동합니다.”
Anthropic은 평소 폐쇄적인 정책으로 알려져 있어서, 이 사건은 아이러니하게도 “가장 오픈소스 친화적인” 이벤트가 됐다. Elon Musk가 “Anthropic이 이제 공식적으로 OpenAI보다 더 오픈소스에 가깝다”고 비꼰 것도 같은 맥락이다.
Claude Code 하네스란 무엇이며 왜 중요한가?
Claude Code 하네스란 대형 언어 모델(LLM)이 실제 개발 작업을 수행하도록 감싸는 실행 프레임워크로, 모델의 능력을 최대한 끌어올리는 구조적 레이어다. 소스 분석을 통해 명확해진 건, Claude Code의 진짜 경쟁력이 Claude 모델 자체가 아니라 이 하네스 설계에 있다는 점이다.
- Claude Code는 단순한 모델 래퍼가 아니라 정교한 에이전트 프레임워크다.
- 하네스는 프롬프트 설계, 권한 관리, 컨텍스트 관리, 병렬 실행을 통합한다.
- Claude 패밀리 모델에 강하게 최적화되어 있어, 단순 모델 교체로는 같은 품질이 나오지 않는다.
- 오픈소스 프로젝트는 이 하네스 아이디어를 가져와 자체 에이전트를 향상시킬 수 있다.
트위터 유저 Alfred Versa는 Claude Code의 비밀을 “Claude Code 하네스 + Claude 모델 패밀리의 조합”이라고 요약했다. 이 하네스에 다른 오픈소스 LLM이나 OpenAI, Gemini 모델을 단순 연결하면 기대한 만큼의 성능이 안 나올 가능성이 크다.
성능의 절반 이상은 ‘포장(하네스)’에서 나온다는 뜻이다.
비슷한 모델을 써도 “프롬프트 구조, 툴 호출 전략, 파일·권한 관리 방식”에 따라 체감 품질이 완전히 달라지는 건 직접 써보면 바로 느껴진다. 이번 유출은 그 구체적인 설계 원칙을 코드 수준에서 공개한 셈이고, Open Code 같은 오픈소스 대안이 바로 따라 할 수 있는 실질적인 청사진이 됐다.
경쟁사 입장에서 이제 구체적으로 연구할 수 있는 것들:
- Claude 모델 패밀리와 최적 궁합을 내는 프롬프트·시스템 메시지 구조
- 다중 AI 서브 에이전트(Sub-Agent)를 어떻게 체이닝하고 조율하는지
- 파일·터미널 권한을 사용자 경험을 해치지 않으면서 안전하게 관리하는 방식
Claude.md란 무엇이며 어떻게 활용해야 할까?
Claude.md란 Claude Code 세션에서 매 턴(turn)마다 로드되는 제어용 설정 파일로, 팀의 코딩 규칙과 프로젝트 문맥을 지속적으로 주입하는 핵심 메커니즘이다. 제대로 활용하면 에이전트가 긴 세션 동안에도 일관된 스타일과 아키텍처를 유지하도록 강제할 수 있다.
- Claude.md는 모든 턴마다 재주입되는 ‘숨겨진 시스템 프롬프트’다.
- 최대 40,000자를 쓸 수 있어 팀 규칙과 아키텍처 설명을 충분히 담을 수 있다.
- 코딩 표준, 아키텍처 다이어그램 설명, 금지 패턴 등을 구체적으로 명시할 수 있다.
- 이 파일을 비워두면 Claude Code의 잠재력을 상당 부분 버리는 셈이다.
Claude.md에 담을 수 있는 대표적인 내용:
- 팀의 코딩 스타일 가이드(네이밍 규칙, 테스트 관습, 예외 처리 정책 등)
- 현재 프로젝트의 아키텍처 개요(레이어 구조, 주요 모듈 책임, 의존성 규칙)
- 팀이 합의한 베스트 프랙티스와 반드시 피해야 할 패턴
- 살펴봐야 할 핵심 파일·디렉터리 경로 목록
“Claude.md에는 Claude Code가 여러분이 어떻게 일하길 원하는지 정확히 알려줄 수 있는 40,000자를 쓸 수 있습니다.”
한 번 읽고 잊는 설정이 아니라, 모든 프롬프트에 반복적으로 주입된다는 게 핵심이다. 발표자도 “나는 이 파일을 거의 건드리지 않았는데, 이제 반드시 업데이트해야겠다고 깨달았다”고 말할 정도로, 실제 사용자 상당수가 이 기능을 과소평가하고 있었다.
직접 팀 프로젝트에 적용해보면, Claude.md에 코딩 패턴과 금지 규칙을 꼼꼼히 적어 넣었을 때 코드 리뷰에서 반복적으로 지적되던 실수가 눈에 띄게 줄어드는 걸 확인할 수 있다. 여러 개발자가 섞인 프로젝트에서 일관성 유지 장치로 특히 유용하다.
병렬 에이전트 실행이란 무엇인가?
병렬 에이전트 실행이란 Claude Code가 여러 서브 에이전트(Sub-Agent)를 동시에 띄워 서로 다른 작업을 병렬로 진행하게 하되, 프롬프트 캐시(Prompt Cache)를 공유해 추가 비용 없이 속도를 극대화하는 실행 구조다. 단일 에이전트 구조의 한계를 넘기 위한 핵심 아키텍처다.
- Claude Code는 한 번에 여러 서브 에이전트를 띄워 병렬로 작업한다.
- 서브 에이전트들은 프롬프트 캐시를 공유해 중복 비용 없이 빠르게 동작한다.
- Git worktree를 이용해 에이전트별 브랜치를 분리해 충돌을 예방한다.
- 읽기·분석 작업은 병렬, 파일 쓰기 작업은 직렬로 안전하게 처리한다.
소스코드에서 드러난 서브 에이전트 실행 모델은 3가지다.
- Fork
- 부모 컨텍스트(대화·상태)를 상속받아 새로운 에이전트를 띄운다.
- 프롬프트 캐시를 공유해 이전 계산 결과를 재사용한다.
-
동일한 베이스 컨텍스트에서 다양한 아이디어 브랜치를 만들 때 적합하다.
-
Teammate
tmux나iTerm의 별도 창에서 독립적으로 실행되는 에이전트다.- 파일 기반 메일박스(mailbox)로 서로 메시지를 주고받는다.
-
실제 팀원처럼 병렬로 다른 서브태스크를 진행할 수 있다.
-
Work Tree
- 각 에이전트에 독립된 Git 워크트리와 격리된 브랜치를 할당한다.
- 서로 다른 브랜치에서 수정하므로 작업 충돌을 근본적으로 줄인다.
- 대규모 기능 개발을 여러 에이전트가 나눠 맡는 시나리오에 적합하다.
“단일 에이전트로만 작업하는 것은 Claude Code의 설계 의도에 반하며 비효율적입니다.”
툴 실행 구조도 병렬성을 고려해 설계돼 있다.
- 읽기 전용 작업(코드 읽기, 검색 등) → 동시 실행 툴(Concurrent Tools)로 병렬 처리
- 변경 작업(파일 쓰기, 코드 수정, Bash 명령 등) → 직렬 실행 툴(Serialized Tools)로 순차 처리
예를 들어, 10개의 서브 에이전트가 코드베이스의 서로 다른 부분을 한꺼번에 읽고 분석하도록 설정하면 사람이 순차적으로 코드를 따라가는 것과 비교해 속도 차이가 체감될 정도다.
실무적으로는 Git worktree를 적극 활용해 에이전트별 브랜치를 분리하고, 상호 충돌 가능성이 낮은 태스크 단위로 에이전트를 병렬로 띄우는 것이 Claude Code의 본래 의도에 가장 가까운 사용법이다.
권한 관리 시스템은 어떻게 작동하나?
Claude Code의 권한 관리 시스템이란 작업 실행 전마다 사용자에게 물어보는 대신, 사전 설정과 LLM 분류기를 활용해 ‘물어볼 필요가 없는 상태’를 만드는 구조다. 이 설계 덕분에 번거로운 팝업 없이도 안전한 자동화를 구현한다.
- 권한 팝업이 뜨는 순간은 곧 설정 실패를 의미한다.
- Anthropic은 대부분의 사용자가 결국 ‘허용’을 누른다는 패턴을 반영했다.
- LLM 분류기가 작업의 위험도를 예측해 자동 허용·차단을 결정한다.
- 구식
--dangerously-skip-permissions플래그는 사실상 필요가 없어졌다.
“무언가를 허용할지 물어보는 메시지를 볼 때마다, 그것은 설정 실패입니다. 기본적으로 그런 메시지를 보지 않아야 합니다.”
현재 Claude Code에는 3가지 권한 모드가 있다.
- Bypass 모드
- 모든 권한 검사를 건너뛴다.
- 가장 빠르지만 실수나 악성 프롬프트에 취약하다.
-
실험용·샌드박스 환경이 아니라면 권장하지 않는다.
-
Allow Edits 모드
- 작업 디렉토리 내 파일 편집을 자동 허용한다.
- 디렉토리 밖으로 나가는 위험한 작업은 여전히 제어한다.
-
로컬 개발용으로 무난한 절충안이다.
-
Auto 모드
- Claude Code를 실행할 때 LLM 분류기가 각 작업을 분석한다.
- 안전하다고 판단되는 작업은 자동 허용, 위험 작업은 자동 차단한다.
- 실무 환경에서 가장 권장하는 기본값이다.
settings.json 파일에 허용할 명령과 차단할 명령을 미리 정의해두면 대부분의 경우 추가 권한 요청 없이 매끄러운 개발 플로우를 유지할 수 있다. 이 설정을 제대로 잡아두면 “권한 팝업 때문에 작업 흐름이 끊기는 일”이 거의 사라진다.
컨텍스트 압축(Compaction)이란 무엇인가?
컨텍스트 압축이란 긴 대화 세션에서 중요 정보는 남기고 불필요한 내용을 구조적으로 삭제·요약하는 메커니즘으로, Claude Code에서 응답 품질과 집중도를 유지하는 핵심 기술이다. AI에서 무엇을 기억하느냐보다 무엇을 잊을지를 똑똑하게 결정하는 것이 더 중요하다는 철학이 이 설계에 반영돼 있다.
- 긴 세션에서 중요한 정보만 남기고 나머지를 요약·삭제하는 기능이다.
- Claude Code는 5가지 압축 전략을 조합해 컨텍스트를 관리한다.
- 기본 컨텍스트 윈도우는 200,000 토큰, 옵션으로 1,000,000 토큰까지 확장 가능하다.
- /compact 명령을 선제적으로 쓰는 것이 품질·비용 면에서 중요하다.
“모델이 무엇을 기억하느냐보다, 무엇을 잊느냐가 더 중요합니다. 무엇을 잊을지 알면 중요한 것을 훨씬 더 정확히 기억할 수 있습니다.”
Claude Code에서 확인된 5가지 압축 방식:
-
Micro Compact: 오래된 툴 결과를 시간 기준으로 삭제한다. 세부 툴 로그를 무한정 쌓지 않아 메모리 사용을 줄인다.
-
Context Collapse: 대화의 일부 구간을 요약하는 손실 압축이다. 세부 정보 일부는 사라지지만 핵심 흐름을 유지한다.
-
Session Memory: 핵심 컨텍스트를 별도 파일로 추출·저장한다. 추후 세션 재개 시 중요한 정보만 빠르게 불러올 수 있다.
-
Full Compact: 전체 대화 히스토리를 요약한다. 세션이 너무 길어졌을 때 전반을 리셋에 가깝게 정리한다.
-
PTL Truncation: 가장 오래된 메시지 그룹을 단순 삭제한다. 최후의 수단에 가까운 절단 방식이다.
/compact 명령은 비디오 게임의 ‘저장하기’다. 컨텍스트가 200,000 토큰에 가까워지거나 대화 흐름이 복잡해지면 수동으로 실행하는 습관을 들이는 게 좋다. 200,000 토큰을 넘어가면 품질이 조금씩 떨어지지만, 그래도 경쟁 도구 대비 높은 수준을 유지하는 건 사실이다.
특히 다음 정보는 Session Memory로 구조화되어 저장된다.
- 작업 명세
- 파일 목록과 현재 워크플로우 상태
- 발생한 오류와 해결 전략
- 세션에서 배운 교훈
그래서 새 세션을 여는 것보다 기존 세션을 --continue 또는 --resume으로 재개하는 편이 훨씬 효율적이다.
실무에서 한 가지 더 챙겨야 할 사실: 대용량 파일을 붙여넣어도 실제로는 8KB 미리보기만 모델에 전달된다. 거대한 파일 전체를 인식한다고 가정하면 안 되고, 핵심 부분만 선택해 입력하는 편이 낫다. 모든 대화는 JSONL로 저장되므로, 세션 지속성(Session Persistence)은 기본으로 탑재돼 있다.
Hooks와 내장 툴 시스템은 어떻게 구성돼 있나?
Hooks 시스템이란 Claude Code가 에이전트 실행 중 특정 이벤트 시점에 자동으로 커스텀 동작을 수행하게 만드는 확장 메커니즘이다. 여기에 66개의 내장 툴이 결합되면서, 반복 작업을 거의 완전 자동화하는 파워 유저용 워크플로우를 만들 수 있다.
- Hooks는 특정 이벤트(세션 시작·툴 실행 전후 등)에 자동 동작을 연결하는 기능이다.
- 이벤트 타입은 Pre-tool, Post-tool, User prompt, Session start/end 등이다.
- Hook는 Command, Prompt, Agent, HTTP, Function 다섯 방식으로 구현할 수 있다.
- Claude Code에는 66개의 내장 툴이 있으며 읽기용은 병렬, 쓰기용은 직렬 처리된다.
사용 가능한 Hook 이벤트:
Pre-tool use: 툴 실행 직전에 트리거Post-tool use: 툴 실행 직후 트리거User prompt submit: 사용자가 프롬프트를 입력할 때Session start: 세션이 시작될 때Session end: 세션이 종료될 때
Hook의 구현 타입:
- Command: 쉘 명령을 실행
- Prompt: 특정 프롬프트를 에이전트에 자동 전송
- Agent: 또 다른 에이전트를 호출
- HTTP: 외부 API 호출
- Function: 사용자 정의 함수 실행
예를 들어 “새 코드가 커밋될 때마다 문서를 자동 업데이트”하는 워크플로우도, Post-tool use 훅에 문서 업데이트 명령을 연결하면 된다. git commit 이후 문서 수정이 자동으로 트리거되니 매번 “문서도 업데이트해줘”라고 말할 필요가 없어진다. 한 번 써보면 이게 얼마나 편한지 바로 느낀다.
스트리밍 아키텍처 덕분에 실행 중인 에이전트를 저비용으로 즉시 중단할 수 있습니다. 잘못된 방향이라 느껴지면 바로 끊고 이전 상태에서 재개해도 토큰을 추가로 낭비하지 않습니다.
내장 툴 66개는 크게 둘로 나뉜다.
- 동시 실행 툴(Concurrent Tools): 읽기 전용 → 병렬 처리
- 직렬 실행 툴(Serialized Tools): 파일 수정, 명령 실행 등 변경 작업 → 순차 처리
“에이전트가 약간 이상한 방향으로 간다”고 느껴질 때 즉시 중단하고 직전 상태에서 방향을 수정해 재개하는 전략이 토큰·시간 모두에서 이득이다.
오픈소스 생태계와 보안에는 어떤 의미가 있을까?
이번 유출의 오픈소스 파급 효과란 Claude Code 수준의 상용 에이전트 설계가 공개되면서 AI 에이전트 개발 생태계 전체에 생기는 영향을 말한다. 보안 관점에서는 역설적으로 그리 나쁘지 않은 ‘선택적 피해’라는 평가도 나온다.
- 오픈소스 프로젝트들이 Claude Code의 설계 패턴을 직접 참고할 수 있게 됐다.
- 프롬프트 설계, 권한 처리, 멀티 에이전트 체이닝, 컨텍스트 압축 전략 등이 공개 지식이 됐다.
- 고객 데이터·API 키 등 민감 정보는 유출되지 않아 피해는 제한적이다.
- 더 많은 눈이 코드를 검토하면서 보안 취약점이 더 빨리 드러날 수 있다.
Alfred Versa의 분석처럼, 이제 경쟁사와 독립 개발자들은 다음을 직접 연구할 수 있다.
- Claude Code의 정확한 프롬프트 구조와 에이전트 구성법
- 권한 시스템, 멀티 서브 에이전트 체이닝, 컨텍스트 압축 전략 등 구현 디테일
- 이 아이디어들을 오픈소스 프로젝트(예: Open Code)에 통합하는 구체적인 방법
보안 측면에서 중요한 지점도 있다.
- 유출된 것은 하네스의 작동 방식과 코드 구조뿐이다.
- 고객 데이터, API 키, 내부 기밀은 노출되지 않았다.
- 다양한 개발자와 보안 연구자가 코드를 살펴보며 잠재 취약점을 찾고 공유할 수 있다.
결과적으로, 이 유출은 ‘leak 스펙트럼’에서 그리 나쁘지 않은 편에 속한다는 평가가 설득력을 얻고 있습니다.
가장 흥미로운 가능성은 Claude Code를 ‘메타 하네스(Meta Harness)’에 통합하는 실험이다. 메타 하네스란 에이전트 하네스 자체를 자기 개선(Self-improvement) 할 수 있게 만드는 상위 프레임워크다. Claude Code 소스가 사실상 오픈된 만큼, 이를 메타 하네스에 연결해 재귀적 자기 개선(Recursive Self-improvement) 을 실험하는 프로젝트들이 등장할 토대가 마련됐다.
Claude Code 하네스 vs 단순 LLM 래퍼: 무엇이 더 적합할까?
Claude Code 하네스와 단순 LLM 래퍼란 각각 에이전트 중심의 복합 실행 프레임워크와 단일 프롬프트-응답 기반의 간단한 래핑 도구를 의미한다. 둘 중 무엇이 적합한지는 프로젝트 규모, 복잡도, 자동화 수준에 따라 다르다.
- Claude Code 하네스는 병렬 에이전트, 권한·컨텍스트 관리, 툴 시스템이 통합된 구조다.
- 단순 LLM 래퍼는 API 호출과 결과 표시 정도만 담당하는 얇은 레이어다.
- 대규모·장기 개발 프로젝트에는 하네스형이 압도적으로 유리하다.
- 간단한 스크립트나 실험에는 가벼운 래퍼가 더 효율적일 수 있다.
| 항목 | Claude Code 하네스 | 단순 LLM 래퍼 |
|---|---|---|
| 구조 복잡도 | 높음: 에이전트, 툴, 권한, 컨텍스트가 통합 | 낮음: 요청–응답 중심 |
| 병렬 처리 | 지원: 서브 에이전트·프롬프트 캐시 기반 | 제한적 또는 미지원 |
| 권한 관리 | LLM 기반 Auto 모드, 설정 파일로 제어 | 대부분 수동 확인 또는 무제한 허용 |
| 컨텍스트 관리 | 5단계 Compaction, Session Memory 내장 | 보통 단순 히스토리 또는 없음 |
| 적합한 경우 | 팀 개발, 대규모 코드베이스, 장기 세션 | 간단 질의응답, 작은 스크립트 |
개인적으로는 “도구를 만들어서 개발 문화를 바꾸고 싶다면 하네스형, 그냥 답변을 조금 더 똑똑하게 만들고 싶다면 단순 래퍼형”으로 구분하는 게 실무감에 가장 가깝다고 생각한다. 이번 유출로 하네스형의 구체적인 구현 예시가 공개됐으니, 단순 래퍼에서 하네스 구조로 옮겨가는 팀이 늘어날 가능성이 크다.
자주 묻는 질문 (FAQ)
Q: 유출된 Claude Code를 그대로 써도 되나요?
A: 원본 소스는 저작권 이슈가 있을 수 있지만, 커뮤니티가 Python으로 재작성한 버전은 법적으로 별도 저작물로 취급되어 합법 다운로드·실행이 가능한 상태로 알려져 있다. 실제 사용 시 각 저장소의 라이선스와 업데이트 상황은 반드시 확인하는 게 좋다.
Q: Claude.md에는 무엇을 얼마나 적는 게 좋을까요?
A: 최대 40,000자까지 쓸 수 있지만, 장문 설명보다는 규칙·패턴·예시 코드 위주로 구조화하는 편이 낫다. 코딩 스타일, 아키텍처 규칙, 금지 패턴, 주요 디렉터리 설명 등을 구체적으로 적어두면 Claude Code가 세션 내내 이 기준을 일관되게 따른다.
Q: /compact는 언제 사용하는 것이 적절한가요?
A: 컨텍스트가 200,000 토큰에 가까워지거나, 대화 흐름이 복잡해졌다고 느낄 때 수동으로 /compact를 실행하는 게 좋다. 큰 변곡점(기능 설계 완료, 주요 리팩터링 직후 등)마다 ‘세이브 포인트’를 찍는다는 느낌으로 쓰는 전략이 유용하다.
Q: 권한 팝업이 계속 뜨는데, 어떻게 줄일 수 있나요?
A: 팝업이 반복된다면 설정 실패다. settings.json에서 허용할 명령과 차단할 명령을 명확히 정의하고, 권한 모드를 Auto로 설정하면 LLM 분류기가 안전 작업을 자동 허용해 팝업 빈도가 크게 줄어든다. Bypass 모드는 테스트 환경이 아니면 피하는 게 안전하다.
Q: 병렬 서브 에이전트를 쓰면 코드 충돌 위험이 크지 않나요?
A: 이 문제를 해결하려고 Claude Code는 Git worktree와 격리된 브랜치 전략을 내장했다. 각 에이전트를 다른 워크트리·브랜치에 배치하면 수정 위치가 물리적으로 분리되어 충돌 가능성을 크게 줄일 수 있다. 이후 필요한 변경만 선택적으로 머지하는 패턴을 권장한다.
지금 당장 무엇부터 할까?
-
Claude.md 점검·작성
현재 프로젝트에 Claude.md가 없다면 새로 만들거나, 있다면 팀 규칙과 아키텍처 설명으로 채운다. -
권한 모드를 Auto로 설정
settings.json에서 권한 모드를Auto로 바꾸고, 허용·차단할 명령 목록을 구체적으로 정의해 권한 팝업을 최소화한다. -
Git worktree 기반 병렬 환경 준비
Git 저장소에 worktree를 설정하고, 서브 에이전트별로 분리된 브랜치를 쓰는 실험 환경을 구성한다. -
/compact 사용 습관 들이기
장기 세션에서 주요 단계마다/compact를 실행해 세션 메모리를 관리하고, 필요할 때--resume으로 이어가는 워크플로우를 익힌다. -
Hooks 한 가지부터 도입
Post-tool use나Session end같은 간단한 Hook 하나를 정의해, “코드 변경 시 자동 테스트 실행” 또는 “세션 종료 시 요약 저장” 같은 작은 자동화를 구현해본다. -
Python 재작성 버전 코드 읽기
커뮤니티가 공개한 Claude Code Python 포트를 로컬에 받아, 병렬 에이전트 실행·권한 관리·Compaction 관련 부분을 중심으로 설계를 직접 확인한다. -
자신만의 미니 하네스 설계
위에서 얻은 인사이트를 바탕으로, 사용하는 LLM과 스택에 맞춘 간단한 하네스(프롬프트 구조·툴 호출·권한 관리)를 정의해 단순 래퍼에서 한 단계 진화한 에이전트 기반 워크플로우를 시도해본다.
참고 링크
- Anthropic 공식 문서: https://docs.anthropic.com
- Git 공식 문서 (worktree): https://git-scm.com/docs/git-worktree
- npm 공식 문서 (패키지·맵 파일 이해): https://docs.npmjs.com
- JSON Lines 포맷 설명: https://jsonlines.org
- LLM 보안·프롬프트 공격 개요 (NIST): https://csrc.nist.gov/publications/detail/ai/100-4/draft
- AI 에이전트 아키텍처 개요 (Stanford CRFM): https://crfm.stanford.edu
Found this article helpful?
Get more tech insights delivered to you.
댓글 남기기