클로드 코드를 뜯어봤더니, 비밀은 "단순함"이었어요

클로드 코드를 뜯어봤더니, 비밀은 "단순함"이었어요

AI 코딩 도구 중에서 요즘 가장 화제인 게 뭐냐고 물으면, 열에 아홉은 "클로드 코드(Claude Code)"를 말해요.

YC 대표 Gary Tan부터 실리콘밸리 스타트업 개발자들까지, 다들 클로드 코드에 빠져 있거든요. 근데 한 가지 궁금한 게 있었어요. 도대체 이걸 어떻게 만들었길래 이렇게 잘 되는 걸까?

MinusX라는 팀이 실제로 클로드 코드의 내부 구조를 분석한 글을 냈는데요. 읽어보니 정말 의외의 결론이 나오더라고요. 오늘은 그 분석을 하나하나 풀어볼게요.

한 줄 요약부터 할게요

클로드 코드가 잘 작동하는 이유는 "Keep Things Simple, Dummy" 때문이에요.

한마디로, 극단적인 단순함.

요즘 AI 에이전트 만든다고 하면 다들 멀티 에이전트 아키텍처니, 복잡한 오케스트레이션이니, 그래프 기반 워크플로우니 하잖아요. LangGraph 쓰고, CrewAI 쓰고, AutoGen으로 에이전트 여러 개 조합하고...

근데 클로드 코드는 정반대 방향을 택했어요. 그리고 그게 먹혔어요. 제대로요.

이게 왜 중요하냐면요, 우리가 AI 에이전트를 직접 만들 때도 똑같은 교훈이 적용되거든요. 하나씩 뜯어볼게요.

1. 메인 루프는 딱 하나만 돌려요

클로드 코드의 가장 핵심적인 설계 원칙이에요. 그리고 솔직히 가장 의외인 부분이기도 해요.

메인 스레드 하나. 메시지 히스토리 하나. 최대 분기는 하나.

끝이에요. 복잡한 멀티 에이전트 시스템 같은 거 안 써요.

요즘 AI 에이전트 프레임워크들이 뭘 강조하는지 생각해보세요. "매니저 에이전트가 작업을 분배하고, 리서처 에이전트가 정보를 모으고, 코더 에이전트가 코드를 짜고, 리뷰어 에이전트가 검토하고..." 이런 구조를 많이 제안하잖아요.

클로드 코드는 이런 거 안 해요.

대신 "서브에이전트"라는 개념이 있긴 한데요, 이게 되게 재밌어요. 서브에이전트는 결국 자기 자신의 복제본이에요. 동일한 모델, 동일한 프롬프트, 동일한 도구를 가진 복제본이 하나 더 생기는 거예요.

단, 중요한 제한이 하나 있어요. 서브에이전트는 또 다른 서브에이전트를 만들 수 없어요. 자기 복제의 복제는 안 되는 거죠.

이게 왜 영리한 설계냐면요:

첫째, 디버깅이 엄청 쉬워져요. 멀티 에이전트 시스템에서 뭔가 잘못되면, 어느 에이전트가 어떤 시점에 잘못된 판단을 했는지 찾는 게 정말 악몽이거든요. 에이전트 A가 에이전트 B에게 잘못된 정보를 전달했고, 에이전트 B가 그걸 기반으로 에이전트 C에게 지시했고... 이런 디버깅 지옥이요. 단일 루프에서는 그냥 메시지 히스토리를 쭉 읽으면 돼요.

둘째, 시스템이 예측 가능해요. 메인 루프 하나가 모든 판단을 내리니까, 어떤 상황에서 어떤 행동을 할지 예상할 수 있어요. 복잡한 멀티 에이전트 시스템은 에이전트 간 상호작용에서 예상 못한 행동이 나올 수 있는데, 단일 루프에서는 그런 일이 없어요.

셋째, 개선이 쉬워요. 프롬프트 하나만 고치면 전체 시스템의 행동이 바뀌니까요. 멀티 에이전트 시스템에서는 한 에이전트의 프롬프트를 바꾸면 다른 에이전트와의 상호작용이 어떻게 변할지 예측하기 어렵잖아요.

핵심: 복잡한 멀티 에이전트 구조 대신, 단일 루프 + 제한된 서브에이전트로 안정성, 디버깅 용이성, 관찰 가능성을 모두 확보했어요.

이건 사실 소프트웨어 공학에서 오래된 교훈이기도 해요. "작동하는 복잡한 시스템은 항상 작동하는 단순한 시스템에서 진화한다." (Gall's Law) 클로드 코드가 바로 이걸 증명한 거예요.

2. LLM 호출의 절반 이상이 "작은 모델"이에요

이거 좀 놀라운 사실인데요.

클로드 코드의 LLM 호출 중 50% 이상이 Claude 3.5 Haiku(작은 모델)로 처리돼요.

네, 여러분이 클로드 코드를 쓸 때 돌아가는 LLM 호출의 절반 이상이 "작은 모델"이라는 거예요. 파일 읽기, 웹 페이지 파싱, Git 히스토리 처리, 대화 요약 같은 작업은 굳이 비싼 대형 모델을 쓸 필요가 없거든요.

이렇게 하면 비용이 70~80% 절감되면서도 사용자가 느끼는 품질은 유지돼요.

이걸 비유하자면 이래요. 회사에서 모든 의사결정을 CEO가 하지 않잖아요. 커피 주문은 인턴이 해도 되고, 미팅룸 예약은 어시스턴트가 해도 되고, CEO는 정말 중요한 전략적 판단만 하면 돼요. 클로드 코드도 마찬가지예요.

진짜 어려운 판단 — "이 코드를 어떻게 리팩토링할까?", "이 버그의 근본 원인이 뭘까?", "어떤 아키텍처 패턴을 적용할까?" — 이런 건 가장 똑똑한 모델(Sonnet이나 Opus)이 담당해요.

단순 반복 작업 — "이 파일 내용 읽어와", "이 웹페이지 내용 요약해줘", "Git 커밋 히스토리 정리해줘" — 이런 건 Haiku가 처리해요.

이 전략이 영리한 이유가 또 있어요. 응답 속도도 빨라져요. 작은 모델은 큰 모델보다 추론 속도가 훨씬 빠르거든요. 파일 읽기 같은 간단한 작업을 할 때 큰 모델이 "음... 이 파일의 컨텍스트를 분석해보면..." 하면서 시간 쓸 필요 없이, 작은 모델이 빠르게 처리하고 넘어가는 거예요.

핵심: 모든 작업에 최고 성능 모델을 쓰는 건 낭비예요. 작업의 난이도에 맞게 모델을 배분하면 비용도 줄고, 속도도 빨라져요.

3. 프롬프트 엔지니어링이 진짜 미친 수준이에요

자, 이제 가장 흥미로운 부분이에요.

클로드 코드의 시스템 프롬프트는 약 2,800토큰이에요. 그리고 도구(tool) 설명에 9,400토큰이 추가로 들어가요. 합치면 12,000토큰이 넘는 지시문이 매번 모델에 전달되는 거예요.

이게 그냥 "코드를 잘 짜줘" 수준이 아니에요. 구체적인 휴리스틱과 예시가 가득해요.

좋은 예시 vs 나쁜 예시

클로드 코드가 쓰는 독특한 패턴이 있어요. "good-example"과 "bad-example"이라는 태그를 써서, 이런 식으로 모델에게 알려줘요:

좋은 예시: pytest /foo/bar/tests 나쁜 예시: cd /foo/bar && pytest tests

"테스트를 실행할 때는 절대경로를 쓰고, cd로 디렉토리를 옮기지 마" 라고 말로 설명하는 것보다, 좋은 예시와 나쁜 예시를 대비해서 보여주는 게 모델 입장에서 훨씬 이해하기 쉽거든요.

사람한테 뭔가 가르칠 때도 "이렇게 하면 되고, 이렇게 하면 안 돼"를 보여주는 게 제일 효과적이잖아요. LLM한테도 마찬가지예요.

대문자 지시어의 힘

원문에서 재밌는 고백이 나와요. **"IMPORTANT, VERY IMPORTANT, NEVER, ALWAYS 같은 대문자 강조가 모델을 위험한 행동에서 벗어나게 하는 가장 좋은 방법인 것 같다"**고요.

우아하진 않아요. 솔직히 좀 무식해 보이기도 하죠. 근데 현실적으로 가장 잘 작동하는 방법이래요.

프롬프트 엔지니어링의 현실이 이래요. 학술적으로 세련된 방법보다, "야 이거 절대 하지 마!!!"가 더 잘 먹힐 때가 있는 거예요.

claude.md 컨텍스트 파일

그리고 claude.md라는 컨텍스트 파일(보통 1,000~2,000토큰)이 있어요. 이건 사용자의 프로젝트 규칙, 코딩 컨벤션, 선호도 같은 걸 담는 파일인데요, 매 요청마다 시스템 프롬프트에 같이 포함돼요.

이게 왜 강력하냐면, 사용자가 매번 "나는 TypeScript를 쓰고, 2칸 들여쓰기를 선호하고, 함수형 프로그래밍 스타일을 좋아해" 같은 걸 반복할 필요 없이, 한 번 설정해두면 계속 적용되니까요. 팀원한테 우리 팀 컨벤션 문서를 공유하는 것과 비슷하다고 보면 돼요.

핵심: 프롬프트에 "지시문"이 아니라 **"알고리즘"**을 심어둔 거예요. 산발적인 "이거 해, 저거 하지 마"가 아니라, 판단 기준 + 좋은 예시 + 나쁜 예시를 체계적으로 조합한 의사결정 트리.

4. RAG를 안 써요. 대신 LLM이 직접 검색해요.

이게 아마 이 글에서 가장 논쟁적인 부분일 거예요.

보통 AI 코딩 도구들은 RAG(Retrieval Augmented Generation) 방식을 쓰잖아요. 코드베이스를 벡터 임베딩으로 변환해서 벡터 DB에 저장하고, 사용자 질문이 들어오면 관련 코드 조각을 검색해서 프롬프트에 넣어주는 방식이요.

Cursor가 이 방식을 쓰고, GitHub Copilot도 비슷한 방식을 쓰고, 대부분의 AI 코딩 도구들이 이 패턴을 따르고 있어요.

근데 클로드 코드는 완전히 다른 접근을 택했어요.

LLM이 직접 ripgrep이나 jq 같은 커맨드라인 도구를 써서 코드를 검색하게 만든 거예요.

이게 왜 더 나을 수 있냐면요:

RAG의 숨겨진 문제들:

이런 문제들이 다 **"숨겨진 실패 모드"**가 돼요. RAG가 잘못된 코드를 가져오면, 모델은 그게 잘못된 건지 모르고 그냥 그 코드를 기반으로 답변을 생성하거든요.

LLM 네이티브 검색의 장점:

도구의 3단계 계층

클로드 코드의 도구는 3단계로 나눠져 있어요:

저수준 도구 — Bash(쉘 명령 실행), Read(파일 읽기), Write(파일 쓰기)

중수준 도구 — Edit(파일의 특정 부분 수정, 가장 많이 쓰이는 도구!), Grep(코드 검색), Glob(파일 패턴 매칭)

고수준 도구 — Task(서브에이전트에게 복잡한 작업 위임), WebFetch(웹 콘텐츠 가져오기)

이 중에서 가장 많이 쓰이는 도구가 뭔지 아세요? Edit이에요. 코드 편집이요. 그 다음이 Read, 그 다음이 Todo 관리.

이 순서가 의미하는 게 있어요. 클로드 코드는 코드를 "읽고 → 수정하고 → 진행 상황을 관리하는" 패턴으로 작동한다는 거예요. 검색해서 답변 주는 패턴이 아니라, 능동적으로 코드를 만져가는 패턴이에요.

핵심: RAG의 블랙박스 검색 대신, LLM이 직접 도구를 써서 검색하게 하면 실패가 투명하고, 모델이 스스로 검색 전략을 조정할 수 있어요.

5. 할 일 목록을 스스로 관리해요

AI 에이전트를 써본 분들이라면 다 겪어봤을 문제가 있어요. "컨텍스트 드리프트(Context Drift)".

대화가 길어지면 원래 뭘 하려고 했는지 까먹는 거예요. "아, 로그인 기능 구현해달라고 했는데, 중간에 DB 스키마 질문하다가, 그 다음에 에러 핸들링 얘기하다가... 지금 뭐 하고 있는 거지?"

이거 사람도 마찬가지잖아요. 회의 시간에 "오늘 논의할 안건이 3개입니다"로 시작했는데, 1번 안건에서 옆길로 새다가 결국 시간 다 써버리는 거요.

클로드 코드는 이걸 자체 투두 리스트로 해결해요.

에이전트가 스스로 할 일 목록을 만들어요:

그리고 작업을 진행하면서 이 목록을 업데이트해요. "1번 완료, 2번 진행 중, 3번 대기 중..."

이게 단순해 보이지만 엄청 강력한 이유가 있어요.

유연성과 집중력의 균형이에요.

중간에 사용자가 "아, 그리고 비밀번호 리셋 기능도 추가해줘"라고 하면, 투두 리스트에 5번을 추가하면 돼요. 기존 작업의 맥락을 잃지 않으면서요.

여기에 확장 사고(Extended Thinking) 기능이 더해져요. 클로드 코드는 작업 중간중간에 "지금까지 뭘 했고, 다음에 뭘 해야 하지?"를 스스로 생각하면서 계획을 동적으로 조정해요. 단순히 목록을 따라가는 게 아니라, 상황에 맞게 계획 자체를 바꿀 수 있는 거예요.

마치 경험 많은 개발자가 코딩하면서 머릿속으로 "음, 이거 하다 보니까 저것도 수정해야겠는데... 투두에 추가해두자"하는 것과 똑같아요.

핵심: 투두 리스트라는 단순한 도구 하나가, AI 에이전트의 고질적인 문제인 컨텍스트 드리프트를 잡아줘요. 고급 메모리 시스템이 아니라, 그냥 할 일 목록이요.

6. 톤 앤 매너도 프롬프트로 잡았어요

클로드 코드를 써보면 느끼는 게 있어요. 쓸데없는 말이 없다는 거.

다른 AI 도구들은 이런 식이잖아요:

"안녕하세요! 좋은 질문이네요. 로그인 기능을 구현하는 것은 매우 중요한 작업입니다. 이를 위해 여러 가지 접근 방법이 있는데, 하나하나 살펴보겠습니다..."

클로드 코드는 이래요:

"로그인 API를 만들겠습니다." → 바로 코드 작성 시작.

이것도 다 프롬프트에 명시적으로 지시한 거예요:

그리고 "system-reminder"라는 태그를 사용해서 중요한 제약 조건을 대화 중간중간에 반복적으로 상기시켜요. 대화가 길어지면 초기 지시사항을 잊어버릴 수 있으니까, 주기적으로 "잊지 마, 이건 절대 하면 안 돼!"를 리마인드하는 거예요.

이것도 사실 되게 인간적인 접근이에요. 우리도 중요한 일할 때 포스트잇 붙여놓잖아요. "절대 main 브랜치에 직접 푸시하지 말 것!" 이런 거요.

그래서 이걸 어떻게 써먹을 수 있을까요?

여기서 끝내면 아쉬우니까, 이 분석에서 우리가 직접 활용할 수 있는 교훈 6가지를 정리해볼게요.

교훈 1: 멀티 에이전트보다 단일 루프가 낫다

AI 에이전트를 만들 때, 무조건 복잡한 멀티 에이전트 프레임워크를 쓸 필요 없어요. 단일 메인 루프 + 필요할 때만 서브에이전트를 쓰는 구조가 더 안정적이고, 디버깅도 쉽고, 유지보수도 쉬워요.

교훈 2: 작은 모델을 전략적으로 섞어 써라

모든 작업에 GPT-4o나 Claude Opus를 쓸 필요 없어요. 단순 작업은 Haiku나 GPT-4o-mini로 처리하고, 비용을 절약하세요. 사용자 경험은 거의 차이가 없어요.

교훈 3: 프롬프트에 "알고리즘"을 넣어라

"잘 해줘"가 아니라, 판단 기준 + 좋은 예시 + 나쁜 예시를 체계적으로 제공하세요. 모델이 의사결정을 내릴 수 있는 프레임워크를 프롬프트 안에 설계하는 거예요.

교훈 4: RAG가 항상 정답은 아니다

코드 검색 같은 경우, 모델이 직접 검색 도구를 쓰게 하는 게 RAG보다 나을 수 있어요. 특히 검색 품질이 중요하고, 실패를 투명하게 드러내야 하는 경우에요.

교훈 5: 에이전트에게 자기 관리 도구를 줘라

투두 리스트 하나만 줘도 컨텍스트 드리프트 문제가 크게 줄어요. 비싼 메모리 시스템이 아니라, 단순한 할 일 목록이면 충분해요.

교훈 6: 톤 앤 매너를 방치하지 마라

AI의 응답 스타일은 프롬프트로 잡아야 해요. 그냥 놔두면 장황하고 공손한 기본 모드로 돌아가거든요. 명확한 스타일 가이드를 프롬프트에 포함시키세요.

이 분석이 말하는 더 큰 그림

마지막으로 한 발 물러서서 큰 그림을 볼게요.

AI 에이전트 분야가 지금 엄청나게 빠르게 발전하고 있잖아요. 매주 새로운 프레임워크, 새로운 아키텍처, 새로운 패러다임이 나와요.

근데 클로드 코드가 증명한 건 뭐냐면요.

파운데이션 모델이 충분히 똑똑하면, 복잡한 스캐폴딩이 필요 없다는 거예요.

과도한 스캐폴딩은 오히려 독이 돼요. 디버깅이 어려워지고, 시스템이 깨지기 쉬워지고, 개선하기도 힘들어져요. 복잡한 프레임워크에 갇혀서 모델의 능력을 충분히 활용 못하는 상황이 되는 거예요.

클로드 코드의 접근법은 모델이 잘하는 걸 모델에게 맡기고, 우리는 그 모델이 잘 작동할 수 있는 환경만 만들어주는 거예요. 단순한 루프, 좋은 프롬프트, 적절한 도구, 가끔 필요한 투두 리스트. 이게 전부예요.

결국 가장 중요한 메시지는 이거예요.

"트렌디한 복잡함"보다 "지루한 단순함"이 이겨요.

AI 에이전트를 만들고 있다면, 복잡한 아키텍처를 쌓기 전에 이 질문부터 해보세요.

"이거, 단일 루프로 안 되나?"

원문 보기: Decoding Claude Code - MinusX

이런 정보와 실전 AI 팁과 코드를 얻고 싶다면?

AI 인사이더 클럽에 들어와 주세요!