Claude Code의 설계 원칙: 모델을 상자에 가두지 않는다

핵심: 제품이 곧 모델이다

기존 AI 제품은 모델을 큰 프로그램 속 함수 하나로 다뤘다. Claude Code는 반대로 모델에게 최소한의 도구와 목표만 주고, 어떤 도구를 어떤 순서로 쓸지는 모델이 정하게 했다. 단계를 강제하는 워크플로나 오케스트레이터보다 도구와 목표만 주는 쪽이 거의 항상 낫다. 맥락도 미리 잔뜩 넣지 않고 필요한 맥락을 스스로 가져올 도구를 준다.

출발점은 첫 프로토타입이다. bash 도구 하나만 줬더니 모델이 AppleScript를 써서 「지금 듣는 음악」을 알아냈다. 모델은 도구를 쓰고 싶어 한다. 두 번째 도구가 파일 편집이었다. 그래서 핵심 설계는 「엔지니어가 터미널에서 할 수 있는 것은 Claude Code도 한다, 중간에 아무것도 없다」가 됐다.

설계 원칙

원칙	내용
6개월 뒤의 모델을 위해 만든다	지금 모델이 잘 못하는 경계에 건다. 모델이 따라잡을 때 제품이 바로 맞물린다. 처음 몇 달은 제품이 덜 맞는 불편을 감수한다. Claude Code가 쓴 코드 비율은 출시(2025-02) 때 10~20%였다가 2025-11 이후 사실상 100%가 됐다
Bitter lesson: 모델에 반하는 쪽에 걸지 않는다	더 일반적인 모델이 결국 특화 모델을 이긴다. 작은 모델·파인튜닝보다 범용 최상위 모델에 걸고, 가장 강한 모델에서 최고로 동작하는 것을 북극성으로 둔다
스캐폴딩은 기술 부채	모델 밖 코드는 성능을 10~20% 올리지만 다음 모델에서 대개 사라진다. 3개월 뒤 버리더라도 지금 이득이 크면 만들고, 버리게 되길 바란다. 시스템 프롬프트에서 약 2,000토큰을 지운 적이 있는데 새 모델에는 필요 없는 내용이었다
도구는 적게, 자주 넣고 뺀다	내장 도구는 십여 개이고 몇 주마다 추가·삭제한다. 전용 도구를 두는 이유는 둘뿐이다: 사람에게 결과를 더 잘 보여 주는 UX, 권한 강제. bash에서도 디렉터리 권한을 강제할 수 있게 되자 `ls` 전용 도구를 지웠다
이중 사용(dual use)	사람과 모델이 같은 도구를 쓴다. `!` bash 모드의 출력은 모델도 보고, 슬래시 명령은 사람도 모델도 부른다. 사람에게 우아한 설계가 모델에게도 통한다
모든 부분을 확장 가능하게	상태줄, 슬래시 명령, 훅, 그것들을 한 번에 들이는 플러그인. 제품을 해킹할 수 있어야 사람마다 다른 쓰임이 생긴다
어려운 과제로 모델을 본다	모델 차이는 쉬운 과제에선 안 보이고 한계까지 미는 과제에서 드러난다

처음에는 혼자라 UI를 만들 필요가 없는 가장 싼 선택이었다. 남은 이유는 모델이 너무 빨리 좋아져서 6개월 뒤에도 유효할 UI가 없다고 봤기 때문이다. 터미널 수명을 3개월로 예상했다가 빗나갔기에 다음 폼팩터 예측은 삼간다. 지금은 웹, 데스크톱 Code 탭, iOS·Android, Slack, GitHub, IDE 확장이 모두 같은 에이전트다. 80×100 글자, 256색, 마우스 없는 제약 속에서 UX 원칙을 다시 발견했고, 마우스 지원은 스크롤 가상화 비용 때문에 한 번 버렸다.

구조와 코드 수명

구조는 핵심 쿼리 루프 + 몇 개 도구 + TUI + 많은 보안 계층으로 단순하다. 6개월 전 코드가 거의 남아 있지 않고, 써 본 코드 대부분을 통계적으로 버린다. 스피너 문구 하나도 50~100번 고쳤다.

RAG 대신 에이전틱 검색

초기에는 로컬 벡터 DB와 임베딩으로 코드를 검색했지만 버렸다.

문제	내용
동기화	방금 만든 함수가 아직 색인되지 않는다. 코드가 바뀔 때마다 재색인해야 한다
보안	색인 접근을 어떻게 정책화하고 내부자 열람을 막을지. 기업 도입 시 노출면이 넓다
결과	glob·grep을 쓰는 에이전틱 검색이 같은 정확도에 이르렀고 배포가 훨씬 깔끔하다

의미 검색이 필요하면 직접 색인을 관리하고 MCP 도구로 노출하면 된다.

안전: 스위스 치즈 모델

완벽한 단일 장치는 없으니 층을 쌓는다. 프롬프트 인젝션에는 (1) 인젝션에 강하게 훈련된 모델 (2) 의심 요청을 막는 런타임 분류기 (3) 웹 결과를 서브에이전트가 요약해 본 에이전트에 돌려주기의 세 층을 둔다. 권한은 읽기 전용 유닉스 명령만 기본 허용하는데, find·sed처럼 임의 코드 실행 경로가 있는 명령이 많아 보수적으로 둔다. 「에이전트의 bash 실행은 안전하게 풀 수 없다」는 반대에 대한 답이 「모르면 사람에게 묻는다」였고, 그것이 1회·세션·전역 허용 프롬프트가 됐다. 샌드박스는 다른 에이전트도 쓸 수 있게 오픈소스로 냈다.

계획 모드의 정체

시스템 프롬프트에 「아직 코드를 쓰지 말라」는 한 문장을 넣을 뿐이다. 직접 그렇게 말해도 된다. 모델이 의도에서 계획이 필요한지 읽게 되면 없어질 기능으로 본다.

제품 철학

원칙	내용
잠재 수요(latent demand)	사람은 이미 하고 있는 일만 한다. 새 행동을 시킬 수는 없고 하려는 일을 쉽게 만들 뿐이다. 제품을 해킹할 수 있게 열어 두고 「남용」을 보고 다음 것을 만든다. 사용자가 마크다운 메모를 모델에게 읽히던 습관이 CLAUDE.md가, 「코드는 아직 쓰지 말고 계획만」 요청이 계획 모드가, 비개발자가 터미널을 설치해 가며 쓰던 현상이 Cowork가 됐다
모델의 잠재 수요	사용자뿐 아니라 모델이 하고 싶어 하는 일(on distribution)을 보고 그걸 쉽게 만든다
훅은 통합 대신	「권한 요청이 떴는데 커피 마시러 가서 몰랐다, Slack으로 알려 달라」는 요청에 통합 기능을 만들지 않고 훅을 노출했다
걷어 내기(unshipping)	빨리 만들 수 있을수록 지우는 게 중요하다. 무언가를 없애면 그 의도를 더 잘 채우는 것을 내놓는다. 기능 이름만 들어도 이해되는 추상화를 유지한다
온보딩 없는 제품	그냥 들어와도 동작해야 한다. `?` 팁, 작업 중 팁, 하단 알림, 그리고 훅·플러그인처럼 생태계에서 이미 통하는 이름을 쓴다. `Ctrl+O` 원문 기록 같은 것은 필요할 때만 안내한다
상호작용 재사용	`Shift+Tab` 하나가 자동 수락에서 계획 모드까지 「얼마나 에이전틱하게」를 정하는 축이 됐다. 같은 상호작용을 여러 기능이 쓰면 멘탈 모델이 단단해진다
문서보다 데모, PRD보다 프로토타입	「15초만 보여 줘」. 할 일 목록 UI는 하루 반 동안 인터랙티브 시제품 15~20개를, 계획 모드는 세 번 만들고 버렸다. 만드는 비용은 낮고 과녁은 모르니 많이 쏴 본다. 아이디어의 절반은 틀리고 어느 절반인지는 해 봐야 안다
일찍 내놓는다	직관은 자주 틀리고, AI로 무엇을 할 수 있을지 미리 알기 어렵다. 처음엔 Windows도 안 됐다
경쟁사보다 사용자	경쟁 제품을 거의 쓰지 않는다. 피드백에 몇 분 안에 고쳐 응답하면 피드백이 더 온다
일부러 자원을 적게	한 프로젝트에 한 명만 두면 빨리 내고 싶은 동기 때문에 자동화하게 된다. 토큰은 처음에 아끼지 않고, 규모가 커지면 그때 작은 모델로 내린다
평균 엔지니어 기준	만든 사람이 일부러 평범한 설정을 유지해(Vim 안 씀) Vim·tmux·SSH를 몰라도 쓰이는 도구를 만든다

Agent SDK라는 이름도 잠재 수요에서 나왔다. 이름을 바꿀 즈음 이미 수천 개 회사가 쓰고 있었고 상당수가 건강 비서, 재무 분석, 법률 보조, 시장 조사처럼 코딩 밖 용도였다. 오래 도는 에이전트 루프 + 인터넷 접근 + 코드 작성·실행이면 거의 무엇이든 만든다. Cowork는 같은 SDK를 쓰는 데스크톱 래퍼이고, 복잡성 대부분은 비개발자용 안전장치(가상 머신, 삭제 보호, 분류기)에 있다.

앞으로의 형태

큰 흐름은 자율 실행 시간의 증가다. 15~~30초면 궤도를 벗어나던 모델이 이제 평균 10~~30분, 길게는 며칠을 돈다. 그러면 노트북을 닫아도 도는 컨테이너, Claude가 Claude를 감독하는 구조, 사람이 들여다볼 수 있으면서 에이전트 사이 대역폭에 최적화된 형태가 문제가 된다. 지금 도는 에이전트 대부분은 사람이 아니라 상위 Claude가 띄운 서브에이전트다. 사용 요령 같은 마이크로 기술은 모델마다 사라지므로 만드는 쪽도 겸손해야 한다.

팀과 역할

관찰	내용
생산성	엔지니어당 생산성(PR 수, 커밋 수명으로 교차 확인)이 팀이 커지는 동안 약 70%에서 200%까지 늘었다. 예전 대기업에서는 수백 명이 1년 일해 몇 %를 올리던 지표다
확산	회사 코드의 약 80%를 Claude Code가 쓰고, 기술직은 사실상 모두 매일 쓴다. 강제하지 않았다
모두가 코드를 쓴다	PM, 디자이너, 데이터 과학자, 재무 담당까지 코드를 쓴다. 역할 간 겹침이 약 50%이고 모든 직군에 기술 면접이 있다. 직함은 모두 Member of Technical Staff
코드 품질	코드 품질이 생산성에 두 자릿수 %를 기여한다. 반쯤 마이그레이션된 코드베이스는 사람도 모델도 잘못된 쪽을 고르게 하므로 끝까지 옮긴다
규모 추정	20~~30명이 2년 걸린 재작성이 약 5명 6개월로 준다. 범위 추정은 30분~~몇 시간으로 시간 상자를 두고 Claude에게 관련 시스템을 나열시킨다

엔지니어의 일은 지루한 부분(코드 세부, git)이 사라지고 무엇을 만들지, 사용자, 큰 시스템 설계가 남는 쪽으로 옮겨 간다. 15세기 필경사가 인쇄기 이후 사라지지 않고 작가·저자라는 범주를 낳은 것과 비슷하다. 단기적으로는 고통스러운 사람이 많다.

덜 중요해지는 것	더 중요해지는 것
코드 스타일·언어·프레임워크에 대한 강한 의견	가설 중심의 과학적 사고, 제1원리
언어 세부 암기	초심자의 마음: 예전 모델에서 안 되던 아이디어를 몇 달마다 다시 시도하기
깊은 몰입 한 번	여러 Claude 사이의 맥락 전환
한 분야만 깊이	제너럴리스트(제품+인프라, 엔지니어링+비즈니스)와 극단적 전문가의 양극화

채용에서는 「틀렸던 경험을 말해 달라」로 실수를 돌아보고 배웠는지 본다. AI 시대 개발자의 역할 전반은 AI 시대 개발자의 역할에 있다.

정리

모델에게 최소한의 도구와 목표를 주고 나머지는 모델이 정하게 한다. 스캐폴딩은 다음 모델이 흡수할 부채다.
6개월 뒤의 모델에 걸고, 가장 강한 모델 기준으로 만든다.
사용자와 모델이 이미 하려는 일(잠재 수요)을 보고 쉽게 만들고, 쓰이지 않는 것은 걷어 낸다.
문서보다 프로토타입을 많이 만들고, 안전은 층을 쌓아 확보한다.

버그 제보